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

NecessidadeComando que Trava ProduçãoAlternativa SeguraImpacto no Tráfego
Criar índiceCREATE INDEX idx ON tabela(col);CREATE INDEX CONCURRENTLY idx ...Zero bloqueio de leitura/escrita
Adicionar CHECK / FKALTER TABLE ADD CONSTRAINT ...;ADD CONSTRAINT ... NOT VALID + VALIDATEPermite SELECT/INSERT/UPDATE/DELETE
Tornar coluna NOT NULLALTER COLUMN c SET NOT NULL;CHECK (c IS NOT NULL) NOT VALID + VALIDATELock mínimo apenas no catálogo
Proteger fila de locksRodar sem lock_timeoutSET 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.

Referências e Fontes

Sobre a Autoria

Senior Dev Esgotado (SQL //sequela)

Staff Engineer & Sobrevivente de Produção

Engenheiro sênior movido a café frio e post-mortems das 23h. Documenta falhas reais de infraestrutura, rituais corporativos inúteis e a ergonomia duvidosa de quem mantém sistemas críticos no ar.

  • 12+ anos apagando incêndios em produção às sextas-feiras
  • Especialista em Sistemas Distribuídos, Post-Mortems e Sobrevivência a Dailies