# Migrações de banco de dados no deploy

As migrações de banco de dados no deploy rodam uma vez, antes de a versão nova receber tráfego. Um rollback de código não desfaz o schema.

Canonical URL: https://unbroker.cloud/pt/blog/database-migrations-on-deploy
Published: 2026-11-03
Reviewed: 2026-11-13
Author: Timoteo Borgobello

## A resposta curta

As migrações de banco de dados no deploy são um único passo de release. Elas rodam uma vez, antes de a versão nova receber tráfego. Não fazem parte do build da imagem, e não fazem parte da subida de cada réplica.

Um rollback desse código não desfaz o schema. Não existe um comando que devolva o banco. A mudança se desenha para o release anterior continuar funcionando: expandir, copiar os dados e depois contrair. Na Unbroker esse passo é o comando pre-deploy, e os comandos de migração exigem o Pro.

Onde o banco roda é outra decisão: um contêiner que você opera, ou um cluster gerenciado. Esse mapa está em [Docker Compose em produção](https://unbroker.cloud/pt/blog/docker-compose-to-production) e em [Postgres gerenciado](https://unbroker.cloud/managed-databases/postgres). Operar o servidor está em [Postgres em produção](https://unbroker.cloud/pt/blog/postgres-in-production).

## Três lugares para as migrações de banco de dados no deploy

A migração roda em um de três lugares. Dois deles quebram quando existe mais de um build, ou mais de uma cópia do app.

### Migrações no build do Docker

O Dockerfile roda a migração enquanto a imagem é construída. Isso acontece em todo build, não uma vez para o release que está prestes a ir ao ar.

O [guia de Django](https://docs.unbroker.cloud/guides/deploy-django) diz para rodar as migrações uma vez, como um passo de release controlado, com as credenciais de runtime. Diz para evitar colocá-las no build da imagem. O [guia de FastAPI](https://docs.unbroker.cloud/guides/deploy-fastapi) diz para não rodar migrações durante o build da imagem.

### Na subida de cada réplica

O processo migra e depois serve. Cada cópia faz isso. Essas cópias podem rodar ao mesmo tempo e competem pela mesma mudança de schema. O guia de Django diz para evitar rodar migrações concorrentes em cada processo web.

### Uma vez, antes de a versão nova receber tráfego

Um comando, a partir da imagem nova, antes de o tráfego chegar. Esse é o passo de release. O caminho é rodar as migrations antes do deploy, não depois de o código novo já estar servindo. Na Unbroker esse comando é o [pre-deploy](https://unbroker.cloud/changelog/2026-08-01-jobs-terminal-pre-deploy). No Heroku esse passo é a linha `release` do Procfile. O mapa de cada linha está em [Procfile do Heroku, linha a linha](https://unbroker.cloud/pt/blog/heroku-procfile-to-services).

## O que o comando pre-deploy precisa fazer

O comando aplica o schema uma vez e termina. Escreva para uma segunda execução não fazer nada quando o schema já está nessa versão. Um release posterior pode chamá-lo quando não há nada novo para aplicar.

Defina `lock_timeout` na sessão que roda a migração, para uma espera de lock terminar em vez de ficar em cima da tabela. Não coloque isso no `postgresql.conf`. O PostgreSQL diz que isso afetaria todas as sessões. O default é 0, o que desliga o timeout. Se você omitir a unidade, o número é em milissegundos. O `'1s'` abaixo ilustra a sintaxe. Não é um default do PostgreSQL nem um valor da Unbroker.

```sql
SET lock_timeout = '1s';
```

Se a migração falha, o comando precisa sair com um código diferente de zero. Imprima qual migração rodou e o erro. Não imprima o connection string. Depois leia o log desse deployment. A documentação e o changelog não dizem o que um pre-deploy que falhou faz com a versão que já está no ar.

Segredos ficam em variáveis de ambiente, não no texto do comando. A [seção de post-deploy na documentação de deployments](https://docs.unbroker.cloud/cli/deployments) escreve essa regra para o comando post-deploy, e diz que o comando em si não é impresso no log. Use o mesmo hábito no pre-deploy. O exemplo do changelog é `npm run db:migrate`.

## Um rollback não desfaz a migração

`ubctl apps rollback` promove um deployment conhecido. Ele não reconstrói o commit de origem. A [documentação de deployments](https://docs.unbroker.cloud/cli/deployments) mostra o comando com um id de serviço e um id de deployment:

```bash
ubctl apps rollback svc_123 dep_previous
```

Esses dois argumentos são o serviço e o deployment que você está promovendo. Rollbacks não rodam de novo o comando pre-deploy, então a migração precisa continuar compatível com o código anterior. Isso está no [changelog de 1 de agosto](https://unbroker.cloud/changelog/2026-08-01-jobs-terminal-pre-deploy).

Voltar para uma imagem anterior não desfaz mudanças de configuração, escritas no banco, dados de um volume nem efeitos externos. A [documentação de infrastructure as code](https://docs.unbroker.cloud/cli/infrastructure-as-code) diz para manter o rollback separado das migrações. Um restore que você já rodou continua sendo o caminho de volta para as linhas antigas. Essa checagem está em [Postgres em produção](https://unbroker.cloud/pt/blog/postgres-in-production).

## Expand and contract, um release de cada vez

O caso comum é um rename. Você quer que `name` vire `full_name`. Se a mudança de código e o drop vão no mesmo release, um rollback sobe o código antigo contra uma coluna que já não existe.

Esse é o padrão de [parallel change](https://martinfowler.com/bliki/ParallelChange.html), também chamado expand and contract. Uma migração expand and contract parte a mudança em três fases: expandir, migrar e contrair. Cada release precisa funcionar com o anterior.

1. **Expandir.** Adicione `full_name`. O código novo escreve as duas colunas e continua lendo `name`. O código antigo só conhece `name`, então um rollback continua rodando.

```sql
ALTER TABLE users ADD COLUMN full_name text;
```

Adicionar uma coluna com um default não volátil guarda esse valor nos metadados da tabela e não a reescreve. Sem default, o PostgreSQL usa NULL e também pula a reescrita. Um default volátil, como `clock_timestamp()`, reescreve a tabela e os índices dela. A maior parte das formas de `ALTER TABLE` pega um lock `ACCESS EXCLUSIVE`, a menos que a documentação anote um mais fraco. O lock está na seção abaixo.

2. **Migrar.** Copie as linhas existentes em lotes, com um comando avulso ou um job agendado, não dentro de cada request. O código novo lê `full_name` e continua escrevendo `name`, então um rollback para o release de expand ainda vê as escritas novas em `name`.

```sql
UPDATE users
SET full_name = name
WHERE id IN (
  SELECT id FROM users
  WHERE full_name IS NULL
  LIMIT 1000
);
```

O `1000` é o tamanho do lote no exemplo. Não é uma configuração do PostgreSQL. Repita até não sobrar linha com `full_name` nulo.

3. **Contrair.** O código novo lê e escreve só `full_name`. Deixe `name` no lugar. Remova a coluna num release posterior, quando você não for mais voltar para um release que ainda a lê ou a escreve.

```sql
ALTER TABLE users DROP COLUMN name;
```

`DROP COLUMN` torna a coluna invisível para o SQL. Não encolhe a tabela em disco na hora. Atualizações posteriores recuperam esse espaço quando reescrevem as linhas. A fonte do comportamento da coluna e do drop é [ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html).

## Operações do Postgres que pegam lock

Um `ALTER TABLE` pega um lock `ACCESS EXCLUSIVE`, a menos que a forma que você usa diga outra coisa. Vários subcomandos na mesma sentença pegam o lock mais estrito que qualquer um deles exija.

`ADD FOREIGN KEY` é uma exceção: pega `SHARE ROW EXCLUSIVE` na tabela que você altera e na tabela referenciada. Adicionar um check ou um not-null varre a tabela, e as outras atualizações esperam até essa sentença fazer commit. `NOT VALID` pula essa varredura. Um `VALIDATE CONSTRAINT` posterior pega `SHARE UPDATE EXCLUSIVE` e não bloqueia atualizações concorrentes. A fonte é [ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html).

Um `CREATE INDEX` normal bloqueia escritas, e não leituras, até o build terminar. `CREATE INDEX CONCURRENTLY` não pega locks que bloqueiem inserts, updates ou deletes. Demora mais, porque o PostgreSQL varre a tabela duas vezes e espera as transações que ainda poderiam usar o índice. Não pode rodar dentro de um bloco de transação. Um `CREATE INDEX` comum pode. Um runner de migrações que embrulha o arquivo numa transação não pode colocar `CREATE INDEX CONCURRENTLY` dentro dessa transação.

```sql
CREATE INDEX CONCURRENTLY users_full_name_idx ON users (full_name);
```

Se o build concorrente falha, o PostgreSQL pode deixar um índice inválido. Esse índice é ignorado nas queries e continua adicionando trabalho em cada update. A recuperação que a documentação indica é apagá-lo e rodar `CREATE INDEX CONCURRENTLY` de novo, ou reconstruí-lo com `REINDEX INDEX CONCURRENTLY`. Só pode haver um build concorrente de índice por tabela de cada vez. Builds concorrentes numa tabela particionada não são suportados. Você pode construir o índice de forma concorrente em cada partição e depois criar o índice pai sem `CONCURRENTLY`. Esse passo do pai é só metadata. A fonte é [CREATE INDEX](https://www.postgresql.org/docs/current/sql-createindex.html).

`lock_timeout` aborta uma sentença que espera mais do que o limite enquanto tenta pegar um lock. O limite vale separado para cada tentativa. Vale para locks explícitos e para os que a sentença pega sozinha. Diferente de `statement_timeout`, ele só dispara enquanto espera um lock. Se `statement_timeout` está definido e é menor ou igual, ele dispara primeiro, então um `lock_timeout` mais longo não ajuda. Não defina `lock_timeout` no `postgresql.conf`. A fonte é [client connection defaults](https://www.postgresql.org/docs/current/runtime-config-client.html).

## O backfill de dados fica separado

Adicionar uma coluna e copiar todas as linhas existentes são trabalhos diferentes. A coluna fica no passo de release. A cópia fica num comando avulso ou num job agendado, em lotes, para uma sentença não ser uma transação longa.

Uma transação que fica aberta mantém visíveis as versões antigas das linhas, e o vacuum ainda não pode tratá-las como lixo. Essa é a checagem de transação longa em [Postgres em produção](https://unbroker.cloud/pt/blog/postgres-in-production). Uma migração também é outro cliente contra `max_connections`. Conte isso junto com os outros clientes nessa nota.

## Pre-deploy e post-deploy

Use o comando pre-deploy para a migração. Ele roda uma vez a partir da imagem nova, antes de essa versão ir ao ar. Rollbacks não rodam esse comando de novo.

Use o comando post-deploy para um trabalho que pode esperar a versão nova já estar servindo, como limpar um cache ou enviar uma notificação. Ele roda numa cópia avulsa da imagem nova, com as variáveis de ambiente desse serviço, por no máximo 10 minutos. A saída é acrescentada ao log do deployment.

Se o comando post-deploy falha, o deployment continua `live` e nada é revertido. A falha fica no log do deployment. O comando não roda quando o próprio deploy falha. Ele não monta um volume persistente. Exige um plano pago, e não está disponível para serviços de imagem. Coloque segredos em variáveis, não no texto do comando. As fontes são a [documentação de deployments](https://docs.unbroker.cloud/cli/deployments) e o [changelog de 26 de outubro](https://unbroker.cloud/changelog/2026-10-26-post-deploy-command).

Uma migração não entra aí. O código novo já estaria recebendo tráfego, e um comando que falhou deixaria esse release no ar.

## Testar a migração antes da produção

Teste a migração numa cópia descartável antes de aplicá-la em produção. O [guia de Django](https://docs.unbroker.cloud/guides/deploy-django) diz isso.

Um preview de pull request serve para isso, apontado para um banco que você pode jogar fora. A Unbroker não documenta um banco criado para cada preview. Você escolhe o banco com uma variável de escopo Preview. Uma migração contra um banco de staging compartilhado muda esse schema para todos os outros previews. Uma migração contra produção muda a produção. A nota longa é [ambientes de preview de pull request](https://unbroker.cloud/pt/blog/pull-request-preview-environments).

## Como funciona na Unbroker

Em Settings, um serviço pode definir um comando pre-deploy como `npm run db:migrate`. Ele roda uma vez a partir da imagem nova, antes de essa versão ir ao ar. Rollbacks não rodam esse comando de novo, então mantenha a migração compatível com o código anterior. O [changelog de 1 de agosto](https://unbroker.cloud/changelog/2026-08-01-jobs-terminal-pre-deploy) é esse release. Em 8 de outubro o terminal interativo foi removido. Comandos avulsos e jobs agendados continuaram. Um comando avulso roda uma vez, com a imagem e as variáveis do serviço. Um job agendado tem um nome, um cron, um comando e um fuso horário. A saída de cada execução fica em Executions. Como escolher entre um worker, esse job e um comando avulso está em [Workers e cron](https://unbroker.cloud/pt/blog/background-workers-cron-jobs).

`@unbroker/iac` v0.2.0 mapeia `preDeploy`. Mudar o comando pre-deploy é um rebuild do commit que está no ar, então um apply que só mexe em config não publica um HEAD mais novo do branch. O post-deploy não faz parte desse schema. Defina `postDeployCommand` no dashboard, ou com `PATCH /apps/services/:id`. Mudar o comando post-deploy marca o serviço para redeploy. A fonte é a [documentação de infrastructure as code](https://docs.unbroker.cloud/cli/infrastructure-as-code) e a de [deployments](https://docs.unbroker.cloud/cli/deployments).

Os comandos pre-deploy e post-deploy compartilham o isolamento de ambiente do serviço e podem alcançar os bancos privados dele. Essa frase está em [tipos de serviço](https://docs.unbroker.cloud/apps/services).

A [página de planos](https://docs.unbroker.cloud/billing/plans) lista comandos de migração, comandos avulsos e jobs agendados como indisponíveis no Free e disponíveis no Pro. O Pro custa $25 por mês, com $25 de crédito de uso. O crédito reinicia a cada ciclo e não acumula. Se o uso elegível ficar abaixo do crédito, a cobrança do mês continua sendo o preço do plano. Os preços estão em [preços](https://unbroker.cloud/pt/precos).

<aside class="plan-box">
<p><strong>Na Unbroker.</strong> O comando pre-deploy é o passo de release. Comandos de migração exigem o Pro. Um rollback promove o deployment anterior e não roda esse comando de novo.</p>
</aside>

## Checklist

1. Rode a migração uma vez, antes de a versão nova receber tráfego.
2. Deixe-a fora do build da imagem Docker. Os guias de Django e de FastAPI dizem isso.
3. Deixe-a fora do comando de subida de cada réplica.
4. Garanta que uma segunda execução não faça nada quando o schema já está em dia.
5. Defina `lock_timeout` nessa sessão. Não mexa no `postgresql.conf`.
6. Coloque os segredos em variáveis, não no comando. Não imprima o connection string.
7. Expanda, copie linhas em lotes e depois contraia. Remova a coluna antiga só quando você não for voltar para um código que precisa dela.
8. Coloque um backfill grande num comando avulso ou num job agendado.
9. Teste numa cópia descartável. Aponte os previews para um banco que não seja produção.
10. Trate um rollback como um deployment anterior, não como um schema anterior. Guarde um restore que você já rodou.
11. Na Unbroker, comandos de migração exigem o Pro. O caminho do Django é [Deploy de Django](https://unbroker.cloud/deploy/django). O que muda depois do `runserver` está em [Django em produção](https://unbroker.cloud/pt/blog/django-in-production).

## Perguntas frequentes

### Devo rodar as migrações no Dockerfile?

Não. O [guia de Django](https://docs.unbroker.cloud/guides/deploy-django) diz para evitar colocar migrações no build da imagem. O [guia de FastAPI](https://docs.unbroker.cloud/guides/deploy-fastapi) diz para não rodar migrações durante o build da imagem. Rode uma vez, como passo de release, com as credenciais de runtime, antes de a versão nova receber tráfego.

### Um rollback reverte a migração do banco?

Não. `ubctl apps rollback` promove um deployment conhecido e não reconstrói o commit. Rollbacks não rodam de novo o comando pre-deploy. Voltar para uma imagem anterior não desfaz mudanças de configuração, escritas no banco, dados de um volume nem efeitos externos.

### O que acontece se a migração do pre-deploy falhar?

Leia o log desse deployment. A documentação e o changelog não dizem o que um pre-deploy que falhou faz com a versão que já está no ar. Escreva o comando para uma migração que falhou sair com código diferente de zero, para a falha aparecer nesse log.

### Posso rodar migrações no plano Free?

Não. A [página de planos](https://docs.unbroker.cloud/billing/plans) lista comandos de migração como indisponíveis no Free e disponíveis no Pro. Comandos avulsos e jobs agendados seguem a mesma regra. O Pro custa $25 por mês, com $25 de crédito de uso. Veja [preços](https://unbroker.cloud/pt/precos).

### As migrações vão no pre-deploy ou no post-deploy?

No pre-deploy. Ele roda uma vez a partir da imagem nova, antes de essa versão ir ao ar. O post-deploy roda depois que a versão já está servindo tráfego. Se o comando post-deploy falha, o deployment continua live e nada é revertido.

## Related reading

- [Postgres em produção](https://unbroker.cloud/pt/blog/postgres-in-production)
- [Postgres gerenciado](https://unbroker.cloud/managed-databases/postgres)
- [Ambientes de preview de pull request](https://unbroker.cloud/pt/blog/pull-request-preview-environments)
- [Docker Compose em produção](https://unbroker.cloud/pt/blog/docker-compose-to-production)
- [Deploy de Django](https://unbroker.cloud/deploy/django)
- [Django em produção](https://unbroker.cloud/pt/blog/django-in-production)
- [Preços](https://unbroker.cloud/pt/precos)
- [Comando pre-deploy](https://unbroker.cloud/changelog/2026-08-01-jobs-terminal-pre-deploy)
- [Procfile do Heroku, linha a linha](https://unbroker.cloud/pt/blog/heroku-procfile-to-services)
