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.
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 |
Leia também
- Por que o código perfeito em homologação quebra na sexta às 17h59
Veja como locks de migration se somam ao cache zumbi e ao drift de ambiente.
- Calculadora de Risco de Deploy na Sexta-Feira
Simule quanto uma migration bloqueante multiplica o risco de incidente.
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.
Referências e Fontes
- PostgreSQL Documentation — Building Indexes Concurrently & Explicit Locking — PostgreSQL Global Development Group