> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Atualizar o MongoDB

<Info>
  Cada nova versão do Server CE/Server Pro indicará qualquer alteração na versão suportada do MongoDB nas suas [notas de versão](https://docs.overleaf.com/on-premises/release-notes).
</Info>

### Devo atualizar o MongoDB?

Você **só** deve considerar atualizar a sua versão do MongoDB se estiver planejando atualizar a sua instância do Server CE/Server Pro.

Se estiver executando uma versão do MongoDB mais recente do que a recomendada para a sua versão atual (ou de destino), não é necessário fazer nenhuma alteração.

<Warning>
  Nunca deve fazer downgrade da sua versão do MongoDB.
</Warning>

Se você tiver um problema específico que acredite estar relacionado com a sua versão atual do MongoDB, fique à vontade para [abrir uma issue](https://github.com/overleaf/overleaf/issues) se for usuário do Server CE, ou contatar o suporte do Overleaf se for usuário do Server Pro.

### Verificar a sua versão do MongoDB

Abrir o shell `mongo` deverá exibir imediatamente a versão atual.

Usuários do Overleaf Toolkit:

```bash theme={null}
bin/docker-compose exec mongo mongod --version
db version v5.0.24
Build Info: {
    "version": "5.0.24",
    "gitVersion": "f034f0c51b3dffef4b8c9452d77ede9888f28f66",
    "openSSLVersion": "OpenSSL 1.1.1f  31 Mar 2020",
    "modules": [],
    "allocator": "tcmalloc",
    "environment": {
        "distmod": "ubuntu2004",
        "distarch": "x86_64",
        "target_arch": "x86_64"
    }
}
```

Usuários do Docker Compose:

```bash theme={null}
docker compose exec mongo mongod --version
db version v5.0.24
Build Info: {
    "version": "5.0.24",
    "gitVersion": "f034f0c51b3dffef4b8c9452d77ede9888f28f66",
    "openSSLVersion": "OpenSSL 1.1.1f  31 Mar 2020",
    "modules": [],
    "allocator": "tcmalloc",
    "environment": {
        "distmod": "ubuntu2004",
        "distarch": "x86_64",
        "target_arch": "x86_64"
    }
}

```

### Processo de atualização

A atualização da versão do MongoDB durante uma atualização da sua instância do Server CE/Server Pro é feita da seguinte forma:

1. Decida para qual versão do Server CE/Server Pro pretende atualizar.
2. Encontre a versão do MongoDB recomendada por essa versão específica do Overleaf Server CE/Server Pro.
3. Siga as instruções para atualizar o MongoDB para a versão de destino.
4. Atualize a versão da imagem do Server CE/Server Pro e reinicie a instância.

A nossa recomendação é atualizar sempre o **Server CE/Server Pro** para a versão mais recente disponível, pois o seu suporte é sempre garantido (apenas para usuários do Server Pro).

<Danger>
  Ao atualizar o Server CE/Pro, recomendamos atualizar para a versão mais recente da versão principal implantada **antes** de atualizar para a versão mais recente da versão principal **seguinte**. Se a sua implantação estiver mais de uma versão principal atrás da mais recente, será necessário realizar uma atualização em várias etapas.

  Por exemplo, se estiver executando a 3.5.10, precisará atualizar para a 3.5.13 -> realizar a migração para o Full Project History -> 4.2.9 -> 5.5.4.

  Você **nunca** deve pular versões principais (3.5.10 -> 5.5.4). Se estiver usando o Toolkit e estiver mais de uma versão principal atrás da mais recente, **não** deve usar o script `bin/upgrade`, pois precisará realizar uma atualização manual em várias etapas.
</Danger>

<Warning>
  É importante garantir que você faça um [backup consistente](/pt/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) **antes** de cada atualização de versão principal, para que possa reverter se necessário.
</Warning>

#### Informações de suporte de versões

Caso decida usar uma versão anterior, esta tabela mostra a versão recomendada do MongoDB para versões anteriores do Server CE/Server Pro, mas você **nunca** deve fazer downgrade da sua versão do MongoDB.

<div style={{ overflowX: "auto" }}><table style={{ display: "table", width: "100%" }}><thead><tr><th width="175">Server CE/Server Pro</th><th width="139" style={{ textAlign: "center" }}>Versão do MongoDB</th><th style={{ textAlign: "center" }}>Versão mínima de compatibilidade de recursos</th><th style={{ textAlign: "center" }}>Versão máxima suportada pelo driver Node.js</th></tr></thead><tbody><tr><td>2.0.x</td><td style={{ textAlign: "center" }}>3.4</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>2.1.x a 2.4.x</td><td style={{ textAlign: "center" }}>3.6</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=2.5.0</td><td style={{ textAlign: "center" }}>4.0</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=3.1.0</td><td style={{ textAlign: "center" }}>4.2</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=3.2.0</td><td style={{ textAlign: "center" }}>4.4</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=4.2.0</td><td style={{ textAlign: "center" }}>5.0</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=5.1.0</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=5.3.1</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>5.0</td><td style={{ textAlign: "center" }}>8.0</td></tr><tr><td>>=5.5.0</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>8.0</td></tr><tr><td>6.0.0</td><td style={{ textAlign: "center" }}>8.0</td><td style={{ textAlign: "center" }}>8.0</td><td style={{ textAlign: "center" }}>8.0</td></tr></tbody></table></div>

<Danger>
  A versão mínima de compatibilidade de recursos acima baseia-se na versão do MongoDB correspondente recomendada para uso com a versão do Overleaf indicada. Se pretender usar uma versão superior, o MongoDB terá o seu próprio requisito mínimo.
</Danger>

Você pode ver a tabela de compatibilidade que especifica as versões suportadas do driver Node.js do MongoDB para uso com o MongoDB [aqui](https://www.mongodb.com/docs/drivers/node/current/reference/compatibility/).

Você pode ver o status de fim de vida de cada versão do MongoDB [aqui](https://endoflife.date/mongodb).

#### Atualizar o MongoDB

O MongoDB exige **atualizações passo a passo**. Isso significa que não é possível passar diretamente, digamos, da `4.0` para a `5.0`. É necessário primeiro atualizar da `4.2` para a `4.4` e depois para a `5.0`.

<Info>
  O MongoDB usa números pares para as suas versões estáveis.
</Info>

#### **Instruções de atualização ao executar o MongoDB fora do Docker**

Aqui estão os links para as instruções de atualização do mongodb.com ao atualizar o MongoDB.

* [Notas de versão do MongoDB - atualizar o MongoDB da `4.2` para a `4.4`](https://www.mongodb.com/docs/v4.4/release-notes/4.4-upgrade-standalone/)
* [Notas de versão do MongoDB - atualizar o MongoDB da `4.4` para a `5.0`](https://www.mongodb.com/docs/v5.0/release-notes/5.0-upgrade-replica-set/)
* [Notas de versão do MongoDB - atualizar o MongoDB da `5.0` para a `6.0`](https://www.mongodb.com/docs/v6.0/release-notes/6.0-upgrade-replica-set/)
* [Notas de versão do MongoDB - atualizar o MongoDB da `6.0` para a `7.0`](https://www.mongodb.com/docs/manual/release-notes/7.0-upgrade-replica-set/#std-label-7.0-upgrade-replica-set)
* [Notas de versão do MongoDB - atualizar o MongoDB da `7.0` para a `8.0`](https://www.mongodb.com/docs/manual/release-notes/8.0-upgrade-replica-set/#std-label-8.0-upgrade-replica-set)

<Info>
  As instruções para a `5.0` e superiores referem-se a uma instalação em replica set, em vez de standalone. Como o Server Pro/CE 4.0.1+ usa transações, o MongoDB precisa ser executado como replica set.
</Info>

<Warning>
  A documentação do MongoDB 3.2 a 4.2 está agora disponível em [https://www.mongodb.com/docs/legacy/](https://www.mongodb.com/docs/legacy/)
</Warning>

**Instruções básicas**

Na maioria dos casos, a atualização exige definir um flag de compatibilidade antes de atualizar efetivamente a versão do mongo. As etapas são as seguintes:

1. Defina o flag de compatibilidade conforme descrito nas notas de versão do MongoDB (veja os exemplos abaixo).
2. Em seguida, atualize a imagem do mongo:
   1. **Usuários do Toolkit:** atualize `MONGO_VERSION`, por exemplo `MONGO_VERSION=6.0`
   2. **Usuários do Docker Compose:** atualize a versão da tag da imagem `mongo`,\
      por exemplo `services -> mongo -> image: mongo:6.0`;

**Exemplo: atualizar o MongoDB da `5.0` para a `6.0`**

Vamos começar por garantir que estamos executando o MongoDB `6.0`:

Usuários do Overleaf Toolkit:

```bash theme={null}
bin/docker-compose exec mongo mongod --version
# db version v5.0.24
```

Usuários do Docker Compose:

```bash theme={null}
docker compose exec mongo mongod --version
# db version v5.0.24
```

De acordo com as [instruções de atualização](https://docs.mongodb.com/manual/release-notes/3.6-upgrade-standalone/#upgrade-version-path), o único requisito é ter `featureCompatibilityVersion` definido como `5.0`. Fazemos isso abrindo um shell do MongoDB e executando o comando indicado:

Usuários do Overleaf Toolkit:

```bash theme={null}
bin/mongo
# MongoDB shell version v5.0.24
# ...
# overleaf:PRIMARY> db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )
# { 
# "ok" : 1,
# ...
# }
overleaf:PRIMARY> exit
# bye
```

<Info>
  Os usuários do Docker Compose podem executar `docker compose exec mongo mongosh` para obter um shell e executar os mesmos comandos que os usuários do Toolkit.
</Info>

Usuários do Overleaf Toolkit:

Em seguida, paramos as instâncias do Server CE/Server Pro e do MongoDB usando o comando `bin/stop`, definimos `MONGO_VERSION=6.0` em `config/overleaf.rc` e reiniciamos o serviço `mongo` usando `bin/up mongo`) para verificar se a atualização correu bem.

Por fim, atualizamos a versão da imagem do Server CE/Server Pro para a nossa versão de destino e recriamos todos os serviços usando o comando `bin/up -d`.

Usuários do Docker Compose:

Em seguida, paramos as instâncias do Server CE/Server Pro e do MongoDB usando o comando `docker compose stop`, atualizamos o arquivo [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) para usar `image: mongo:6.0` e reiniciamos o serviço `mongo` usando o comando `docker compose up mongo` para verificar se a atualização correu bem.

Por fim, atualizamos a versão da imagem do Server CE/Server Pro para a nossa versão de destino e recriamos todos os serviços usando o comando `docker compose up`.

<strong>Exemplo: atualizar o MongoDB da `6.0` para a `7.0` (usuários do Toolkit)</strong>

Comece por garantir que está executando o MongoDB `6.0` usando os comandos `mongod --version` acima.

De acordo com as [instruções de atualização](https://www.mongodb.com/docs/manual/release-notes/7.0-upgrade-replica-set/#std-label-7.0-upgrade-replica-set), o único requisito é ter `featureCompatibilityVersion` definido como `6.0`. Fazemos isso abrindo um shell do MongoDB e executando o comando `db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })` .

Usuários do Overleaf Toolkit:

```bash theme={null}
bin/mongo
# ...
# overleaf:PRIMARY> db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )
# { 
# "ok" : 1,
# ...
# }
overleaf:PRIMARY> exit
# bye
```

Em seguida, paramos as instâncias do Server CE/Server Pro e do MongoDB usando o comando `bin/stop`, definimos `MONGO_VERSION=7.0` em `config/overleaf.rc` e reiniciamos o serviço `mongo` usando `bin/up mongo`) para verificar se a atualização correu bem.

Por fim, atualizamos a versão da imagem do Server CE/Server Pro para a nossa versão de destino e recriamos todos os serviços usando o comando `bin/up -d`.

<strong>Exemplo: atualizar o MongoDB da `7.0` para a `8.0` (usuários do Toolkit)</strong>

Comece por garantir que está executando o MongoDB `7.0` usando os comandos `mongod --version` acima.

De acordo com as [instruções de atualização](https://www.mongodb.com/docs/manual/release-notes/8.0-upgrade-replica-set/#std-label-8.0-upgrade-replica-set), o único requisito é ter `featureCompatibilityVersion` definido como `7.0`. Fazemos isso abrindo um shell do MongoDB e executando o comando `db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true })`. Observe que agora é necessário um parâmetro adicional `confirm: true`.

```bash theme={null}
bin/mongo
# ...
# overleaf:PRIMARY> db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true } )
# { 
# "ok" : 1,
# ...
# }
overleaf:PRIMARY> exit
# bye
```

Em seguida, paramos as instâncias do Server CE/Server Pro e do MongoDB usando o comando `bin/stop`, definimos `MONGO_VERSION=8.0` em `config/overleaf.rc` e reiniciamos o serviço `mongo` usando `bin/up mongo`) para verificar se a atualização correu bem.

Por fim, atualizamos a versão da imagem do Server CE/Server Pro para a nossa versão de destino e recriamos todos os serviços usando o comando `bin/up -d`.

#### Comandos equivalentes para usuários do Docker Compose

Para usuários do Docker Compose, os comandos equivalentes são:

* `docker compose exec mongo mongod --version` para exibir a versão do mongo
* `docker compose exec mongo mongosh` para iniciar um shell do mongo para comandos de administração
* o comando `docker compose stop` para parar o servidor
* Editar o arquivo [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) para usar `image: mongo:6.0` e atualizar a versão do mongo
* `docker compose up mongo` para reiniciar o serviço mongo e verificar se a atualização correu bem
* Editar o arquivo [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) para usar `image: sharelatex:VERSION` e atualizar a versão da imagem
* `docker compose up` para recriar todos os serviços.

### Criar uma função personalizada

Na versão `5.5.1`, introduzimos uma verificação na inicialização para confirmar a versão de compatibilidade de recursos do MongoDB. Se o seu banco de dados MongoDB usar autenticação (por exemplo, autenticação básica), o contêiner `sharelatex` poderá não iniciar, exibindo um erro de permissão "*not authorized on admin to execute command*".

Para resolver isso, você pode criar uma nova função (role) no MongoDB e atribuí-la à conta de usuário usada para acessar o banco de dados seguindo as instruções abaixo, ou definir `ALLOW_MONGO_ADMIN_CHECK_FAILURES=true` para permitir que a verificação falhe sem impedir o início da implantação.

<Check>
  Esta nova função concede **apenas** permissão para ler parâmetros do servidor MongoDB em todo o cluster e pode ser reutilizada para fins de monitoramento,
</Check>

```bash wrap theme={null}
# Toolkit users
$ bin/docker-compose exec -it mongo mongosh -u {{YOUR-ADMIN-USERNAME}} -p

# Switch to the "admin" database using
overleaf [direct: primary] sharelatex> use admin
switched to db admin
overleaf [direct: primary] admin> 

# Create a new role with permission to use "getParamter". Copy and paste the function below into the shell and press the return key

db.createRole(
  {
    role: "clusterParameterReader",
    privileges: [
      {
        resource: { cluster: true },
        actions: ["getParameter"]    
      }
    ],
    roles: [] 
  }
);

# Switch back to the "sharelatex" database 
use sharelatex
switched to db sharelatex
overleaf [direct: primary] sharelatex> 

# Assign the new "clusterParameterReader" role to your database user by copy and pasting the function below into the shell and press the return key 
db.grantRolesToUser(
  "{{YOUR-DATABASE-USER}}",
  [
    { role: "clusterParameterReader", db: "admin" }
  ]
);

# Type exit then return to exit the MongoDB shell
# Run bin/up -d to start the deployment stack
$ bin/up -d
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.