database-migration

Visão geral da skill database-migration

O que a skill database-migration ajuda você a fazer

A skill database-migration foi feita para planejar e gerar trabalho de migração de schema e de dados em fluxos comuns com ORM e SQL, com atenção especial à segurança de rollback e a releases sem downtime. Ela é mais útil quando você precisa de algo além de um prompt genérico do tipo “escreva uma migration”: por exemplo, quando a mudança afeta dados reais de produção, exige deploy em fases ou precisa funcionar dentro de um framework específico de migração, como Sequelize ou TypeORM.

Quem deve usar esta skill database-migration

Os usuários com melhor aderência são times de Database Engineering, engenheiros de backend, engenheiros de plataforma e desenvolvedores que usam IA e precisam de uma saída de migração com consciência operacional, não apenas sintaticamente correta. Se você vai alterar tabelas, fazer backfill de dados, renomear colunas com segurança ou migrar entre padrões de ORM, esta skill dá ao modelo um ponto de partida muito mais forte do que um prompt em branco.

Para qual job-to-be-done ela funciona melhor

Use a skill database-migration quando a tarefa real for produzir um plano de migração que possa de fato ser executado: arquivos de migration, etapas de rollout em fases, caminhos de rollback e considerações sobre transformação de dados. O valor central não está só em gerar código. Está em reduzir a adivinhação em torno da ordem das operações, das janelas de compatibilidade e da recuperação em caso de falha.

Principais diferenciais em relação a um prompt normal de programação

Em comparação com um prompt comum, a skill database-migration tem uma abordagem opinativa em torno de:

• exemplos de migration com consciência de ORM
• padrões explícitos de up e down
• raciocínio voltado a zero-downtime
• fluxos que combinam mudança de schema com mudança de dados
• procedimentos de rollback como requisito de primeira classe

Isso faz dela uma opção melhor para mudanças em produção do que um pedido genérico para “gerar SQL”.

O que está dentro do escopo — e o que não está

O conteúdo atual da skill é mais forte em padrões de migration e estruturas de exemplo, especialmente para Sequelize e TypeORM. Ela é mais limitada em automação específica de repositório, scripts de validação e regras de decisão, porque a pasta da skill expõe apenas SKILL.md. Na prática, isso significa que ela orienta bem e rascunha migrations com qualidade, mas você ainda deve fornecer os detalhes da sua stack, suas restrições e seu modelo de deploy para obter uma saída confiável.

Como usar a skill database-migration

Contexto de instalação da skill database-migration

Se você usa o sistema de Skills deste repositório, instale a skill a partir do repo e depois invoque-a em uma sessão do agente que já tenha acesso ao seu codebase e ao contexto do schema. Uma instalação típica é assim:

npx skills add https://github.com/wshobson/agents --skill database-migration

Como esta skill é entregue principalmente como um único SKILL.md, o valor dela depende bastante de como você formula o pedido e de quanto contexto de schema você fornece.

Leia este arquivo primeiro antes de usar

Comece por:

• plugins/framework-migration/skills/database-migration/SKILL.md

Como não há rules/, resources/ ou scripts de suporte visíveis para esta skill, você não precisa passar por uma fase longa de leitura do repositório. O caminho prático é simples: inspecione SKILL.md e depois vá rapidamente para os seus próprios arquivos de schema, configuração do ORM e histórico de migrations existente.

Quais entradas a skill precisa para funcionar bem

A skill database-migration funciona muito melhor quando você informa:

• ORM ou ferramenta de migração atual: Sequelize, TypeORM, Prisma, SQL puro etc.
• schema atual ou definições dos modelos
• mudança de schema desejada
• se será necessário fazer backfill de dados
• tamanho das tabelas ou sensibilidade a tráfego
• tolerância a downtime
• expectativa de rollback
• engine de banco de dados alvo: PostgreSQL, MySQL etc.
• estilo de deploy: one-shot, em fases, blue/green, canary

Sem esses detalhes, o modelo pode devolver uma migration com aparência válida, mas insegura para produção.

Como transformar um objetivo vago em um bom prompt para database-migration

Prompt fraco:

Create a migration to rename a column.

Prompt mais forte:

Use the database-migration skill. We use TypeORM with PostgreSQL.
Current table: users(id, full_name, created_at).
Goal: replace full_name with first_name and last_name.
Constraints: production table has 20M rows, cannot block writes, rollout must be zero-downtime, app and migration may be deployed separately.
Need:
1. phased migration plan
2. TypeORM migration files
3. data backfill strategy
4. rollback plan
5. application compatibility notes during transition

A segunda versão dá à skill o que ela precisa para escolher uma abordagem mais segura de expand-migrate-contract, em vez de um rename direto e arriscado.

Melhor fluxo de trabalho para tarefas reais de migration

Um fluxo prático de database-migration usage é:

1. Peça primeiro a estratégia de migração.
2. Revise riscos, comportamento de locks e premissas de rollback.
3. Depois peça o arquivo de migration no seu framework.
4. Se o rollout for em fases, peça também as mudanças de compatibilidade na camada de aplicação.
5. Peça queries de verificação e passos de rollback.
6. Execute em staging com formato de dados parecido com o de produção antes de confiar na saída.

Essa sequência importa porque código de migration gerado cedo demais costuma embutir o modelo de rollout errado.

Padrões de ORM em que a skill é mais forte

As evidências no repositório mostram exemplos explícitos para:

• migrations com Sequelize
• migrations com TypeORM

A descrição também menciona uso mais amplo para migrações em ORMs e plataformas, mas os exemplos visíveis são mais fortes nesses dois ecossistemas. Se você usa outra stack, peça ao modelo para traduzir a mesma intenção de migration para a sua toolchain em vez de presumir profundidade nativa.

Quando pedir orientação de zero-downtime explicitamente

Não presuma que o modelo sempre vai otimizar para segurança de migração online. Diga isso de forma explícita quando qualquer um destes pontos for verdadeiro:

• tabelas grandes
• alto volume de escrita
• deploys independentes entre app e banco
• renome de colunas ou mudanças de tipo
• backfills em caminhos quentes
• mudanças de constraint sob tráfego de produção

Para database-migration voltado a times de Database Engineering, isso costuma ser a diferença entre uma resposta de brinquedo e uma resposta pronta para deploy.

Quais saídas pedir da skill

Para usar a skill database-migration com mais confiança, peça um pacote completo, não só um arquivo:

• código da migration
• sequência de rollout
• sequência de rollback
• lógica de backfill de dados
• premissas e riscos
• checklist de validação
• etapas de limpeza pós-migração

Isso evita que trabalho operacional importante fique implícito ou seja omitido.

Alerta prático sobre mudanças destrutivas diretas

A skill funciona melhor quando usada para evitar mudanças inseguras em uma única etapa, como:

• remover colunas antigas imediatamente
• renomear colunas quentes in-place sem compatibilidade
• mudar tipos sem estratégia de conversão
• adicionar constraints not null antes do backfill
• reescrever tabelas grandes sem planejar o impacto de locks

Se a primeira saída fizer qualquer uma dessas coisas em um caminho de produção, peça uma alternativa em fases.

FAQ da skill database-migration

Esta skill database-migration serve apenas para migrations com ORM?

Não. A skill é estruturada em torno de migrações de schema e de dados em ORMs e plataformas diversas. Na prática, os exemplos visíveis são orientados a ORM, especialmente Sequelize e TypeORM, então você terá os melhores resultados ao declarar sua stack exata e pedir SQL ou adaptação para o framework quando necessário.

A skill database-migration é boa para iniciantes?

Sim, com ressalvas. Ela é acessível porque os exemplos são concretos, mas pressupõe que você consiga avaliar se uma migration é operacionalmente segura. Iniciantes podem usá-la para rascunhar arquivos de migration e planos de rollout, mas não devem tratar a primeira resposta como pronta para produção sem revisão.

Quando eu não devo usar database-migration?

Evite esta skill quando sua tarefa for puramente conceitual e não envolver execução real de mudança de schema ou dados. Ela também não é a melhor escolha se você espera validação completa e específica do ambiente apenas a partir do repositório, porque esta skill não inclui scripts extras, regras ou test harnesses na pasta exposta.

Como isso é melhor do que pedir para uma IA escrever SQL?

O valor do database-migration guide está em enquadrar a tarefa em torno do ciclo de vida da migração, e não apenas da sintaxe. Um prompt simples de SQL costuma deixar de fora rollback, janelas de compatibilidade, backfills em fases e convenções de migration de ORM. Esta skill é melhor quando a segurança do deploy importa tanto quanto a correção do código.

Ela dá suporte a deploys zero-downtime?

Sim, esse é um dos casos de uso claramente visados. Ainda assim, você precisa especificar o que zero-downtime significa no seu ambiente. A expressão sozinha é ampla demais; o modelo precisa entender sua ordem de deploy, o perfil de tráfego de leitura e escrita e as restrições de compatibilidade.

Como melhorar a skill database-migration

Forneça à skill o diff de schema junto com as restrições operacionais

A forma mais rápida de melhorar a qualidade da saída de database-migration é fornecer ao mesmo tempo a mudança de schema e as restrições de runtime. Por exemplo:

Current: orders.status VARCHAR nullable
Target: orders.status ENUM not null
DB: PostgreSQL
Rows: 80M
Traffic: constant writes
Requirement: no downtime, rollback available, deploy app separately

Isso empurra o modelo para um desenho de migração em fases, em vez de um alter simplista.

Peça expand-migrate-contract quando segurança for prioridade

Se o primeiro rascunho parecer destrutivo demais, peça explicitamente um plano de expand-migrate-contract. Isso normalmente melhora os resultados para:

• renames
• conversões de tipo
• introdução de not null
• split de tabelas
• mudanças de desnormalização ou normalização

Essa é uma das formas mais confiáveis de obter melhor database-migration usage com a skill.

Exija validação e rollback já na primeira resposta

Um modo comum de falha é receber uma migration up correta com um down fraco ou irrealista. Para melhorar isso, peça:

• condições de rollback
• alertas de perda de dados
• queries de verificação
• critérios de sucesso após cada fase

Isso força o modelo a pensar em reversibilidade desde cedo.

Forneça o estilo de migration já usado no seu repositório

Se o seu projeto já tem convenções de migration, cole um ou dois arquivos representativos e peça para a skill segui-los. Isso melhora de forma concreta a nomenclatura, o tratamento de transações, o estilo de timestamps e os idioms do framework. Isso é especialmente útil em Sequelize e TypeORM, em que os times costumam ter padrões locais além do default do framework.

Itere sobre risco de lock, não apenas sobre correção de código

Depois da primeira saída, faça perguntas de acompanhamento como:

• Quais etapas podem bloquear a tabela?
• Quais etapas podem rodar enquanto as escritas continuam?
• O que deve ser separado em deploys distintos?
• Que parte se torna irreversível depois do backfill?
• Que monitoramento devemos observar durante o rollout?

É nesse ponto que a skill database-migration costuma se tornar realmente valiosa para trabalho de Database Engineering, em vez de apenas gerar boilerplate.

Fique atento a estes modos de falha comuns

Tenha cautela se a migration gerada:

• assume tabelas pequenas
• omite rollback
• remove campos antigos cedo demais
• combina mudança de schema e backfill massivo em um único passo arriscado
• ignora compatibilidade da aplicação durante a transição
• usa sintaxe de framework que não corresponde à sua versão

Esses são motivos normais para refinar o prompt, não sinais de que a skill seja inutilizável.

Melhor forma de melhorar os resultados após o primeiro rascunho

Trate a primeira resposta como uma proposta de migration, não como artefato final. Depois, peça à skill para revisar com base em:

• o tamanho real das suas tabelas
• a situação dos índices
• a ordem de deploy esperada
• achados de canary ou staging
• qualquer premissa que tenha falhado na revisão

Esse ciclo de feedback é a forma mais prática de extrair valor em nível de produção do fluxo de database-migration install e uso da skill.