CommunityEscrita e Ediçãogithub.com

Safe Migrations

Identifica migrações de banco de dados que podem bloquear tabelas e as reescreve em etapas seguras e sem tempo de inatividade. Suporta PostgreSQL e MySQL, em qualquer framework.

O que é Safe Migrations?

Safe Migrations é uma skill para agentes de IA (como Claude Code, Cursor, Codex) que automatiza a revisão de migrações de banco de dados, detectando operações que causam bloqueios ou reescritas completas de tabelas — as principais causas de quedas em produção. A skill analisa cada migração, classifica as operações em inseguras (🔴), condicionais (🟡) ou seguras (🟢), e fornece uma reescrita pronta para uso em SQL ou código idiomático do framework (Rails, Django, etc.). Também detalha a sequência de deploy necessária para mudanças não compatíveis com versões anteriores, seguindo o padrão Expand/Contract. Suporta PostgreSQL e MySQL/MariaDB, com arquivos de referência que incluem locks, versões, DDL online e padrões como backfill em lote e lock_timeout. O resultado é um relatório claro que o desenvolvedor pode copiar e executar imediatamente.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add windchillscalanthes-ship-it/safe-migrations

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Migrações Seguras

Identifique as alterações de esquema que silenciosamente bloqueiam uma tabela ou a reescrevem em disco — e transforme-as em migrações seguras e sem tempo de inatividade antes de chegarem à produção.

Uma única linha aparentemente inofensiva (SET NOT NULL, CREATE INDEX, ADD FOREIGN KEY, uma coluna com DEFAULT) pode adquirir um lock ACCESS EXCLUSIVE ou forçar uma reescrita completa da tabela. Em uma tabela grande e ocupada, isso significa que toda leitura e escrita ficam enfileiradas atrás da migração — uma queda de serviço. Esta skill revisa uma migração, explica exatamente o que bloquearia e por que, e produz uma reescrita segura.

Quando usar

  • Você está escrevendo uma nova migração e quer verificá-la antes do commit.
  • Você está revisando uma migração em um PR/diff.
  • Você está prestes a executar uma migração em uma tabela que já possui linhas.
  • Alguém pergunta "esta migração é segura?", "isso vai bloquear a tabela?" ou "como faço isso com zero downtime?".

Se a tabela alvo estiver vazia ou for minúscula (uma tabela nova criada na mesma migração, uma tabela de configuração com poucas linhas), a maioria desses riscos não se aplica — informe isso e não complique demais.

Fluxo de trabalho

  1. Estabeleça o contexto. Identifique o motor (PostgreSQL vs MySQL/MariaDB e, se possível, a versão principal) e o framework. A versão é importante: várias operações são seguras no Postgres 11/12+ mas não antes. Se a versão for desconhecida, sinalize as operações cuja segurança depende da versão.

  2. Localize as operações. Leia cada arquivo de migração e liste todas as operações de esquema ou dados que ele executa. Uma migração frequentemente agrupa várias.

  3. Classifique cada operação de acordo com o catálogo de riscos abaixo. Atribua uma severidade:

    • 🔴 Inseguro — adquirirá um lock bloqueante, reescreverá a tabela ou quebrará uma versão em execução do app. Deve ser reescrito.
    • 🟡 Cuidado — seguro apenas sob condições (tabela pequena, versão específica do motor, baixo tráfego, configurações corretas). Destaque a condição.
    • 🟢 Seguro — apenas metadados ou sem bloqueio. Nenhuma alteração necessária.
  4. Reescreva os inseguros. Para cada 🔴/🟡, forneça:

    • o risco concreto (qual lock, o que ele bloqueia, impacto aproximado),
    • uma reescrita segura como etapas executáveis (SQL e, quando um framework estiver em uso, o código idiomático do framework), e
    • a sequência de deploy quando o código do app precisar mudar em sincronia (veja Expandir / Contrair abaixo).
  5. Relate usando o template de saída no final. Comece pelos itens inseguros.

Para profundidade específica de motor e framework, carregue os arquivos de referência sob demanda:

  • reference/postgres.md — Locks, versões e reescritas seguras do PostgreSQL (o mais detalhado).
  • reference/mysql.md — DDL online do MySQL/MariaDB, ALGORITHM/LOCK, gh-ost.
  • reference/patterns.md — Padrões independentes de motor: expandir/contrair, backfill em lote, lock_timeout, compatibilidade N-1.
  • reference/frameworks.md — Como expressar índices concorrentes, desabilitar a transação DDL e separar estado vs. esquema em cada framework.

Leia o arquivo de referência relevante para a migração à sua frente, em vez de adivinhar o comportamento específico da versão.

Catálogo de riscos (os mais frequentes)

Focado no Postgres; diferenças do MySQL estão em reference/mysql.md. "Reescrever" = a tabela inteira é copiada em disco; "escanear" = leitura completa da tabela; ambos ocorrem sob um lock que bloqueia tráfego concorrente.

#OperaçãoPor que é perigosaAbordagem segura
1Adicionar coluna com DEFAULTUm default volátil (ex: gen_random_uuid(), random()) reescreve a tabela sob ACCESS EXCLUSIVE. Qualquer default reescreve no Postgres < 11.Adicione a coluna nullable sem default → ALTER … SET DEFAULT (apenas novas linhas) → faça backfill das linhas existentes em lotes → adicione NOT NULL (linha 2).
2SET NOT NULL em uma coluna existenteEscaneia a tabela inteira sob ACCESS EXCLUSIVE para verificar nulos — bloqueia leituras e escritas.Adicione CHECK (col IS NOT NULL) NOT VALID → VALIDATE CONSTRAINT (sem bloqueio) → SET NOT NULL (Postgres 12+ reutiliza o check validado e pula o escaneamento) → opcionalmente remova o check.
3CREATE INDEX (não concorrente)Adquire um lock SHARE que bloqueia escritas durante toda a construção.CREATE INDEX CONCURRENTLY — deve executar fora de uma transação; pode deixar um índice INVALID se falhar (remova e tente novamente).
4DROP INDEXACCESS EXCLUSIVE na tabela.DROP INDEX CONCURRENTLY (Postgres 9.2+).
5Adicionar FOREIGN KEYBloqueia ambas as tabelas e escaneia a tabela filha para validar linhas existentes.Adicione a constraint NOT VALID (rápido, sem escaneamento) → VALIDATE CONSTRAINT em uma etapa separada (adquire apenas SHARE UPDATE EXCLUSIVE).
6Adicionar constraint UNIQUEConstrói um índice único sob um lock bloqueante.CREATE UNIQUE INDEX CONCURRENTLY → ALTER TABLE … ADD CONSTRAINT … UNIQUE USING INDEX <nome> (anexa o índice existente, rápido).
7Adicionar constraint CHECKEscaneia a tabela sob ACCESS EXCLUSIVE.ADD CONSTRAINT … CHECK (…) NOT VALID → VALIDATE CONSTRAINT.
8ALTER COLUMN … TYPEGeralmente reescreve a tabela e seus índices sob ACCESS EXCLUSIVE. (Exceções: aumentar/remover um limite de tamanho varchar é apenas metadados.)Expandir/contrair: adicione uma nova coluna, gravação dupla + backfill, troque as leituras, remova a coluna antiga.
9RENAME coluna/tabelaO DDL é instantâneo, mas quebra a versão atual do app no momento em que confirma.Nunca renomeie no local em um app ativo. Expandir/contrair: adicione novo nome, gravação dupla, backfill, troque as leituras, remova o antigo — em dois deploys.
10DROP COLUMNCódigo do app ainda referenciando-a (incluindo SELECT *) quebra; os dados desaparecem (difícil de reverter).Apenas fase de contração: primeiro envie o código do app que para de usar a coluna, depois remova em uma migração posterior.
11Backfill em um único UPDATE grandeTransação de longa duração → contenção de lock, inchaço da tabela, atraso de replicação.Agrupe por faixas de chave primária com um commit entre os lotes; mantenha cada lote curto. Faça fora da migração de esquema.
12Sem lock_timeout / statement_timeoutMesmo um DDL instantâneo precisa de um lock ACCESS EXCLUSIVE breve. Se ele enfileirar atrás de uma consulta longa, bloqueará todas as consultas que chegarem depois — uma paralisação em cascata.Defina um lock_timeout baixo (e statement_timeout) antes do DDL para que a migração falhe rapidamente em vez de derrubar o site.

Princípios orientadores

  • Expandir / contrair (mudança paralela). Qualquer alteração que não seja compatível com versões anteriores deve ser dividida para que o banco seja simultaneamente compatível com as versões antiga e nova do app durante uma implantação. Expandir (adicionar, compatível com versões anteriores) → migrar dados / gravação dupla → contrair (remover) — geralmente em dois ou mais deploys. Esta é a base para renomeações, alterações de tipo, divisões e mesclagens.
  • Uma alteração lógica por migração. Mais fácil de revisar, entender e reverter. Nunca misture uma alteração de esquema com um grande backfill de dados na mesma transação.
  • Compatibilidade N-1. Durante uma implantação, ambas as versões do app são executadas ao mesmo tempo. O esquema deve atender a ambas.
  • Separe esquema de dados. DDL estrutural e backfills de linhas pertencem a etapas diferentes (e frequentemente a deploys diferentes).
  • Ajuste o conselho ao contexto. Tabelas vazias/minúsculas/novas em folha não precisam de nada disso. Não transforme uma alteração de duas linhas em uma dança de cinco etapas quando a tabela tem 12 linhas.

Template de saída

## Revisão de Segurança da Migração

**Motor:** <ex: PostgreSQL 14>  ·  **Framework:** <ex: Rails>  ·  **Arquivos revisados:** <n>

### 🔴 <arquivo> — INSEGURO
**Operação:** <o que faz>
**Risco:** <qual lock / reescrita, o que bloqueia>
**Impacto provável:** <ex: "lock global em `users` durante um escaneamento completo; em uma tabela com 40M de linhas, segundos a minutos de tráfego bloqueado">
**Reescrita segura:**
<etapas executáveis — SQL e/ou código do framework>
**Sequência de deploy:** <apenas se o código do app precisar mudar em sincronia>

### 🟡 <arquivo> — CUIDADO
**Operação / Risco / Condição / Recomendação**

### 🟢 <arquivo> — SEGURO
<uma linha: por que é seguro, nenhuma ação necessária>

---
**Resumo:** <n inseguros, n cuidados, n seguros.> <linha final resumida.>

Sempre mostre a reescrita segura como algo que o usuário possa copiar e executar — não apenas uma descrição do que fazer.

Habilidades Relacionadas