0Pricing
SQL Academy · Aula

Migrações on-line: por que ALTER TABLE bloqueia

Entenda quais formas de ALTER TABLE obtêm um bloqueio ACCESS EXCLUSIVE e reescrevem a tabela, e quais alteram apenas os metadados.

Migrações on-line: por que ALTER TABLE bloqueia é uma aula grátis de SQL Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de SQL Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de SQL Academy inclui 4 aulas no total.

O problema das migrações em produção

Em um banco de dados pequeno, ALTER TABLE é instantâneo. Em uma tabela ativa de 500GB, o mesmo comando pode bloquear as gravações por 20 minutos. É essencial saber quais comandos ALTER são seguros e quais não são.

Níveis de bloqueio

Os bloqueios do PostgreSQL têm níveis:

  • ACCESS SHARE — seleções
  • ROW EXCLUSIVE — gravações
  • SHARE / SHARE ROW EXCLUSIVE — DDL coexistindo com leituras
  • EXCLUSIVE — bloqueia seleções
  • ACCESS EXCLUSIVE — bloqueia EVERYTHING

O que ALTER TABLE exige

A maioria das variantes de ALTER obtém ACCESS EXCLUSIVE — elas bloqueiam leitores e escritores até serem concluídas.

ALTERs rápidos (somente metadados)

Alguns comandos ALTER apenas alteram o catálogo e são concluídos em milissegundos, mesmo em tabelas enormes:

ALTER TABLE t RENAME COLUMN a TO b;
ALTER TABLE t ALTER COLUMN a SET DEFAULT ...;
ALTER TABLE t ADD COLUMN x INT;             -- nullable, no default: metadata only (PG 11+)
ALTER TABLE t ADD COLUMN x INT NOT NULL DEFAULT 0;  -- metadata only PG 11+ if default is constant

ALTERs lentos (com reescrita)

Eles reescrevem a tabela inteira:

ALTER TABLE t ALTER COLUMN x TYPE BIGINT;     -- when types not binary-compatible
ALTER TABLE t SET LOGGED;
CLUSTER t USING idx;                          -- physically reorders rows
VACUUM FULL t;                                -- rewrites whole table

Adicionando NOT NULL com segurança

Em uma tabela grande:

-- BAD: full table scan + ACCESS EXCLUSIVE lock
ALTER TABLE t ALTER COLUMN x SET NOT NULL;

-- BETTER:
ALTER TABLE t ADD CONSTRAINT x_not_null CHECK (x IS NOT NULL) NOT VALID;
ALTER TABLE t VALIDATE CONSTRAINT x_not_null;     -- scans without exclusive lock
-- then drop the CHECK and add NOT NULL (still cheap because already validated):
ALTER TABLE t ALTER COLUMN x SET NOT NULL;
ALTER TABLE t DROP CONSTRAINT x_not_null;

Adicionando chaves estrangeiras sem interrupção

A mesma técnica de NOT VALID:

ALTER TABLE orders
  ADD CONSTRAINT orders_user_fk FOREIGN KEY (user_id) REFERENCES users(id) NOT VALID;
ALTER TABLE orders VALIDATE CONSTRAINT orders_user_fk;

Problemas de espera por bloqueios

Um ALTER aguardando um bloqueio ACCESS EXCLUSIVE ficará na fila atrás de todas as transações de longa duração. As transações mais novas também ficarão na fila atrás do ALTER — uma cadeia de consultas bloqueadas.

lock_timeout

Não permita que as migrações fiquem pendentes indefinidamente:

SET lock_timeout = '5s';
ALTER TABLE t ...;
-- ERROR if it can't get the lock in 5s — retry.

Laços de repetição

As migrações devem tentar novamente quando ocorrer lock_timeout:

for (let i = 0; i < 20; i++) {
  try {
    await client.query('SET lock_timeout = 5000');
    await client.query('ALTER TABLE ...');
    break;
  } catch (e) {
    if (e.code === '55P03') continue;     // lock_not_available
    throw e;
  }
}

statement_timeout para segurança

Limite por quanto tempo uma única instrução pode ser executada dentro de uma migração:

SET statement_timeout = '30s';

Ferramentas úteis

  • strong_migrations (Rails)
  • django-migrate-zero-downtime
  • pg-osc (Alteração de esquema on-line do PostgreSQL)
  • pgRoll

Resumo

As migrações sem interrupção exigem atenção a:

  • Quais comandos ALTER alteram somente metadados e quais reescrevem a tabela
  • Usar NOT VALID + VALIDATE para restrições
  • Definir lock_timeout e tentar novamente
  • Evitar transações de longa duração que bloqueiem as migrações

Verificação rápida

Você adiciona uma restrição NOT NULL a uma tabela de 500GB em um único ALTER TABLE — o que acontece com as gravações?

Perguntas Frequentes

A aula “Migrações on-line: por que ALTER TABLE bloqueia” é grátis?

Sim — o texto completo de “Migrações on-line: por que ALTER TABLE bloqueia” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de SQL Academy, atualize para CoddyKit PRO. O curso de SQL Academy inclui 4 aulas no total.

O que vou aprender em “Migrações on-line: por que ALTER TABLE bloqueia”?

Entenda quais formas de ALTER TABLE obtêm um bloqueio ACCESS EXCLUSIVE e reescrevem a tabela, e quais alteram apenas os metadados. Você pratica SQL Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar SQL Academy?

Nenhuma experiência prévia é necessária. SQL Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Migrações on-line: por que ALTER TABLE bloqueia”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de SQL Academy?

Sim. Cada aula de SQL Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Migrações on-line: por que ALTER TABLE bloqueia
  2. Índices concorrentes (CREATE INDEX CONCURRENTLY)
  3. Renomeação de colunas sem indisponibilidade
  4. Ferramentas: Flyway, Liquibase, Sqitch
← Voltar para SQL Academy