Migrações de esquema

O problema: mudar a tabela com o sistema no ar

O código muda a cada deploy, e o banco precisa acompanhar: uma coluna nova, um índice, uma tabela. Fazer isso à mão, direto no banco de produção, não escala: ninguém sabe o que foi aplicado onde, e o ambiente de testes fica diferente do de produção.

A migração de esquema resolve a organização. Cada mudança vira um arquivo versionado no repositório, aplicado em ordem, uma vez só, em todos os ambientes. Uma tabela no próprio banco registra quais migrações já rodaram:

migracoes/
  0001_cria_clientes.sql
  0002_cria_pedidos.sql
  0003_adiciona_canal_em_pedidos.sql

Ferramentas como Flyway, Alembic, golang-migrate, EF Core Migrations e Prisma Migrate fazem esse controle. A parte difícil não é a organização: é que a migração roda com o sistema atendendo pedidos, contra tabelas com milhões de linhas.

Nem toda mudança custa o mesmo

Medimos, num PostgreSQL 18 com uma tabela de 3 milhões de pedidos, quanto tempo cada mudança levou. Durante esse tempo, a maioria delas segura uma trava exclusiva que impede leituras e escritas na tabela:

A diferença está em reescrever ou não a tabela. Desde o PostgreSQL 11, um valor padrão constante é guardado só no catálogo, e as linhas antigas o recebem na leitura. Um valor que muda a cada linha, ou uma troca de tipo, obriga o banco a reescrever as 3 milhões de linhas, com a tabela travada. Numa tabela dez vezes maior, os 3 segundos viram 30.

O SET NOT NULL não reescreve, mas lê a tabela inteira para conferir que não há nulos, também com a trava exclusiva. Há um caminho sem bloquear:

A restrição NOT VALID vale para as linhas novas na hora. A validação das antigas acontece depois, com uma trava mais fraca, que deixa a aplicação ler e escrever. E o SET NOT NULL usa a restrição validada para pular a leitura da tabela.

A fila de travas: a migração que derruba o sistema

Mesmo uma mudança instantânea pode parar o sistema. Para acrescentar uma coluna, o banco precisa de uma trava exclusiva por um instante, e espera todas as transações que estão usando a tabela terminarem. Enquanto espera, todos os pedidos que chegam depois ficam na fila atrás dela, inclusive as leituras mais simples.

Testamos com três sessões: um relatório que lê a tabela por 6 segundos, uma migração que acrescenta uma coluna meio segundo depois e uma leitura simples por chave primária logo em seguida.

Sem o limite, a leitura de 1 milissegundo esperou mais de 5 segundos. Num sistema real, são todos os pedidos que tocam a tabela, por todo esse tempo: na prática, uma queda. Com lock_timeout, a migração desiste e libera a fila. Na Implementação, um executor que desiste e tenta de novo aplicou a migração na terceira tentativa, nas cinco linguagens, e nenhuma leitura esperou mais de 1 segundo.

Índices sem parar as escritas

CREATE INDEX lê a tabela inteira e, enquanto isso, bloqueia as escritas. CREATE INDEX CONCURRENTLY constrói o índice em etapas, sem bloquear. Medimos com inserções contínuas na tabela de 3 milhões de linhas:

O CONCURRENTLY é um pouco mais lento e tem regras: não roda dentro de uma transação, e, se falhar no meio, deixa um índice marcado como inválido, que precisa ser apagado e criado de novo. Muitas ferramentas de migração envolvem cada arquivo numa transação, e é preciso desligar isso para esse comando.

O código antigo continua rodando

Durante um deploy, a versão nova e a antiga do código rodam ao mesmo tempo por alguns minutos, e a migração roda antes, ou no meio. Toda migração precisa funcionar com as duas versões do código.

Renomear a coluna obs para observacao quebra a versão antiga, que continua lendo obs. A saída é dividir a mudança em etapas, no padrão expandir e contrair:

1. Expandir: criar observacao, e fazer o código novo gravar nas duas colunas.
2. Migrar: copiar os dados antigos de obs para observacao, em lotes.
3. Trocar a leitura: o código passa a ler só observacao.
4. Contrair: num deploy posterior, quando nenhum código usa mais obs, apagá-la.

São quatro deploys para uma renomeação. É o preço de não ter janela de manutenção.

Por que isso importa quando a IA escreve o código

Um assistente que gera uma migração costuma escrever o SQL que funciona num banco vazio:

• Nenhum lock_timeout, e a migração forma a fila que derruba o sistema.
• CREATE INDEX sem CONCURRENTLY em tabelas grandes.
• Coluna nova com valor padrão calculado, ou troca de tipo, reescrevendo a tabela sob trava.
• SET NOT NULL direto, em vez de CHECK ... NOT VALID e validação.
• Renomear ou remover colunas num único deploy, quebrando a versão antiga do código.
• Atualizar milhões de linhas num único UPDATE, numa transação gigante.

O próximo nível compara as formas de organizar e aplicar migrações, e as receitas para cada tipo de mudança.