---
title: Guia de atualização
icon: arrow-up-right-dots
---

## Diretrizes gerais

**Sempre faça backup do seu banco de dados antes de iniciar o processo de atualização** executando:

```bash
docker exec -it {db_container_name_or_id} pg_dumpall -U {postgres_user} > databases_backup.sql
```

Para restaurar a partir de um backup:

```bash
cat databases_backup.sql | docker exec -i {db_container_name_or_id} psql -U {postgres_user}
```

Se você usa o Docker Compose, siga estas etapas:

1. Pare o Twenty: `docker compose down`
2. Altere o valor de `TAG` no arquivo `.env` que está no mesmo diretório do seu `docker-compose.yml`
3. Inicie o Twenty: `docker compose up -d`

O servidor executa automaticamente todas as migrações de atualização necessárias na inicialização. Nenhum comando manual é necessário.

## Atualizações entre versões (v1.22+)

A partir da **v1.22**, o Twenty oferece suporte a atualizações entre versões. Você pode pular diretamente de qualquer versão compatível para a versão mais recente sem passar por cada versão intermediária.

Por exemplo, a atualização da v1.22 diretamente para a v2.0 é totalmente suportada.

## Atualizando para a v2.5+ — envelope de criptografia em repouso

A partir da **v2.5**, Twenty armazena segredos em repouso (tokens OAuth, variáveis de aplicação, chaves privadas de chaves de assinatura, valores de configuração sigilosos, segredos TOTP) dentro de um envelope versionado `enc:v2:` criptografado com `ENCRYPTION_KEY` (ou `APP_SECRET` se `ENCRYPTION_KEY` não estiver definido).

A primeira inicialização na v2.5 executa comandos de atualização lentos que **preenchem retroativamente** as linhas existentes no novo envelope. Eles são idempotentes — interromper e reiniciar o servidor retoma do ponto em que parou —, mas podem demorar em bancos de dados grandes. Você pode monitorar o progresso com `upgrade:status`.

Você deve definir uma `ENCRYPTION_KEY` dedicada **antes** da atualização para a v2.5, para que o preenchimento retroativo grave as linhas sob ela desde o início. Trocar as chaves após o preenchimento retroativo exige uma [rotação](/l/pt/developers/self-host/capabilities/key-rotation).

## Rotação de segredos e chaves de assinatura

Para tarefas operacionais do dia a dia, como rotacionar a `ENCRYPTION_KEY`, rotacionar a chave de assinatura JWT ou revogar uma chave de assinatura vazada, consulte o [guia de rotação de chaves](/l/pt/developers/self-host/capabilities/key-rotation) dedicado.

## Verificando o status da atualização

O comando `upgrade:status` permite inspecionar o estado atual da sua instância e das migrações dos espaços de trabalho. É útil para depurar problemas de atualização ou ao abrir uma solicitação de suporte.

Execute-o a partir do contêiner do servidor:

```bash
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status
```

Exemplo de saída:

```sh
APP_VERSION: v1.23.0

Instance
    Inferred version: 1.23.0
    Latest command:   1.23.0_DropWorkspaceVersionColumnFastInstanceCommand_1785000000000
    Status:           Up to date
    Executed by:      v1.23.0
    At:               2026-04-16T11:43:58.823Z

Workspace
  Apple (20202020-1c25-4d02-bf25-6aeccf7ea419)
      Inferred version: 1.23.0
      Latest command:   1.23.0_UpdateGlobalObjectContextCommandMenuItemsCommand_1780000005000
      Status:           Up to date
      Executed by:      v1.23.0
      At:               2026-04-16T11:44:09.361Z

Summary
    Instance: Up to date
    Workspaces: 1 up to date, 0 behind, 0 failed (1 total)
```

### Opções

| Opção                     | Descrição                                                                                            |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `-w, --workspace-id <id>` | Restringe a um espaço de trabalho específico. Pode ser passada várias vezes.                         |
| `-f, --failed-only`       | Oculta os espaços de trabalho atualizados; mostra apenas os que estão desatualizados e os com falha. |

## Resolução de Problemas

Se a atualização falhar em alguns espaços de trabalho, o servidor não avançará além da etapa com falha. Reiniciar o servidor (`docker compose up -d`) tentará novamente a atualização a partir de onde parou.

Para identificar rapidamente os problemas, execute:

```bash
docker exec -it {server_container_name_or_id} yarn command:prod upgrade:status --failed-only
```

Isso mostra apenas os espaços de trabalho que estão desatualizados ou com falha, juntamente com a mensagem de erro de cada falha.

## Antes da v1.22

Se a sua instância for anterior à v1.22, você deve atualizar incrementalmente por cada versão principal marcada (da v1.6 para a v1.7, depois da v1.7 para a v1.8 e assim por diante) até chegar à v1.22. A partir daí, você pode pular diretamente para a versão mais recente.