# Migration sem downtime no PostgreSQL: como alterar tabelas de 50 milhões de linhas sem derrubar a aplicação

- **Marca:** SeQueLa (https://reserva.ink/usesequela)
- **URL Canônica:** https://blog.usesequela.com.br/post/migration-sem-downtime-postgresql/
- **Categoria:** Banco de Dados
- **Palavra-chave alvo:** migration sem downtime postgresql
- **Autor:** Senior Dev Esgotado (SQL //sequela) (Staff Engineer & Sobrevivente de Produção)
- **Publicado em:** 2026-11-16 | **Atualizado em:** 2026-11-16

## Resposta Direta

Para rodar migrations no PostgreSQL sem causar downtime em tabelas grandes, elimine comandos que seguram locks longos de leitura ou escrita. Utilize CREATE INDEX CONCURRENTLY fora de blocos de transação, adicione constraints com NOT VALID seguido de VALIDATE CONSTRAINT (lock SHARE UPDATE EXCLUSIVE que não bloqueia SELECT/INSERT/UPDATE/DELETE) e configure SET lock_timeout curto no início do script.

## Pontos-Chave

- CREATE INDEX padrão trava escritas na tabela durante toda a construção; use sempre CREATE INDEX CONCURRENTLY fora de transações.
- CHECK e FOREIGN KEY com NOT VALID gravam no catálogo em milissegundos e validam o legado depois sem bloquear tráfego.
- Defina SET lock_timeout = "2s" em toda migration para falhar rápido antes que uma query lenta enfileire o pool inteiro atrás dela.

## O efeito dominó do AccessExclusiveLock em produção

Em homologação com 200 registros, qualquer ALTER TABLE roda em três milissegundos e ninguém percebe. Em produção com dezenas de milhões de linhas e relatórios rodando em paralelo, o comando precisa esperar uma consulta aberta terminar para adquirir AccessExclusiveLock — e enquanto espera, coloca toda nova requisição da API numa fila imóvel até o pool de conexões explodir.

Resolver isso não exige reescrever o sistema inteiro. Exige quebrar operações destrutivas em etapas curtas que respeitem as regras reais de travamento do PostgreSQL.

## As 3 receitas SQL que salvam sua sexta-feira

Sempre que precisar indexar, restringir nulos ou adicionar chaves estrangeiras em tabelas quentes, aplique os padrões abaixo:

- 1. Índices concorrentes fora de BEGIN/COMMIT: CREATE INDEX CONCURRENTLY permite leituras e escritas normais enquanto o índice constrói em segundo plano.
- 2. Constraint em duas etapas: adicione com NOT VALID (instantâneo para linhas novas) e rode VALIDATE CONSTRAINT depois usando SHARE UPDATE EXCLUSIVE, que permite tráfego concorrente.
- 3. Timeout defensivo obrigatório: inicie scripts com SET lock_timeout = "2s" para abortar a migration antes que ela sufoque o servidor web.

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

-- 1. Índice sem travar escrita (executar fora de bloco de transação)
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_pedidos_cliente ON pedidos (cliente_id);

-- 2. NOT NULL sem scan bloqueante na tabela inteira
ALTER TABLE usuarios ADD CONSTRAINT usuarios_email_nn CHECK (email IS NOT NULL) NOT VALID;
ALTER TABLE usuarios VALIDATE CONSTRAINT usuarios_email_nn;
ALTER TABLE usuarios ALTER COLUMN email SET NOT NULL;
ALTER TABLE usuarios DROP CONSTRAINT usuarios_email_nn;
```

### Renomeando ou removendo colunas sem quebrar containers antigos

Durante um deploy com rolling update, containers da versão V1 e da versão V2 convivem por minutos lendo o mesmo banco. Nunca faça RENAME COLUMN nem DROP COLUMN no mesmo deploy do código novo: crie a coluna nova, escreva nas duas (expand), migre a leitura e remova a coluna velha apenas no release seguinte (contract).

## Operação Ingênua vs. Padrão Zero-Downtime no PostgreSQL

| Necessidade | Comando que Trava Produção | Alternativa Segura | Impacto no Tráfego |
| --- | --- | --- | --- |
| Criar índice | CREATE INDEX idx ON tabela(col); | CREATE INDEX CONCURRENTLY idx ... | Zero bloqueio de leitura/escrita |
| Adicionar CHECK / FK | ALTER TABLE ADD CONSTRAINT ...; | ADD CONSTRAINT ... NOT VALID + VALIDATE | Permite SELECT/INSERT/UPDATE/DELETE |
| Tornar coluna NOT NULL | ALTER COLUMN c SET NOT NULL; | CHECK (c IS NOT NULL) NOT VALID + VALIDATE | Lock mínimo apenas no catálogo |
| Proteger fila de locks | Rodar sem lock_timeout | SET lock_timeout = "2s"; | Falha limpa sem derrubar API |

## Perguntas Frequentes (FAQ)

### Por que meu ORM (Prisma/TypeORM/Django) dá erro ao rodar CREATE INDEX CONCURRENTLY?

Porque a maioria dos migrators envolve cada arquivo SQL num bloco BEGIN ... COMMIT automático, e o PostgreSQL proíbe CONCURRENTLY dentro de transações explícitas. É preciso desativar a transação automática naquele arquivo específico.

### O que fazer se o CREATE INDEX CONCURRENTLY falhar no meio por deadlock ou erro?

Ele deixa um índice marcado como inválido no catálogo, consumindo espaço e escrita sem servir consultas. Rode DROP INDEX CONCURRENTLY nome_do_indice antes de tentar recriá-lo.

### Em PostgreSQL mais novo existe atalho nativo para NOT NULL NOT VALID?

Sim, versões recentes como o PostgreSQL 18 introduziram suporte direto a SET NOT NULL NOT VALID seguido de VALIDATE NOT NULL, mantendo a mesma lógica em duas fases.

## Leituras Relacionadas no Cluster

- [Por que o código perfeito em homologação quebra na sexta às 17h59](https://blog.usesequela.com.br/post/por-que-codigo-perfeito-em-homologacao-quebra-em-producao-sexta-17h59/) — Veja como locks de migration se somam ao cache zumbi e ao drift de ambiente.
- [Calculadora de Risco de Deploy na Sexta-Feira](https://blog.usesequela.com.br/ferramentas/calculadora-risco-deploy-sexta/) — Simule quanto uma migration bloqueante multiplica o risco de incidente.

## Fontes e Referências

- [PostgreSQL Documentation — Building Indexes Concurrently & Explicit Locking (PostgreSQL Global Development Group)](https://www.postgresql.org/docs/current/sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY)

---

**Se alguém rodar ALTER TABLE sem lock_timeout às 17h55, pelo menos vista o luto certo**
Peças em dark mode pensadas para quem já viu o pool de conexões bater 100% em menos de cinco segundos.
[Ver catálogo // usesequela](https://reserva.ink/usesequela?utm_source=blog&utm_medium=organic&utm_campaign=migration-sem-downtime-postgresql&utm_content=markdown_cta)