O que Ajudante de Migração de Banco de Dados faz?
Esta habilidade ajuda você a criar arquivos de migração de banco de dados que seguem as convenções e padrões de nomenclatura do seu projeto.
Quando Usar Esta Habilidade
- O usuário solicita a criação de uma migração de banco de dados
- Adicionar novas tabelas ou colunas ao banco de dados
- Modificar o esquema do banco de dados existente
- Criar índices, restrições ou relacionamentos
- O usuário menciona "migração", "alteração de esquema" ou "atualização de banco de dados"
Instruções
1. Detectar a Ferramenta ORM/Migração
Primeiro, identifique qual ferramenta ORM ou migração o projeto utiliza:
- Prisma: Procure por
prisma/schema.prismaou@prisma/clientno package.json - Sequelize: Procure por
.sequelizercousequelize-clino package.json - Knex: Procure por
knexfile.jsouknexno package.json - TypeORM: Procure por
ormconfig.jsonoutypeormno package.json - Alembic (Python): Procure por
alembic.iniou diretórioalembic/ - Django: Procure por
manage.pye migrações Django em*/migrations/ - Active Record (Rails): Procure pelo diretório
db/migrate/ - Flyway: Procure por
flyway.confoudb/migration/ - Liquibase: Procure por
liquibase.propertiesou arquivos changelog
Use Glob para pesquisar esses arquivos indicadores.
2. Examinar Migrações Existentes
Leia os arquivos de migração existentes para entender:
- Convenções de nomenclatura (formato de timestamp, formato de descrição)
- Estrutura de diretórios
- Formato do arquivo de migração (SQL, JavaScript, TypeScript, Python, etc.)
- Padrões de código (funções up/down, forwards/rollback, etc.)
Use Grep para encontrar migrações recentes: procure em diretórios comuns como:
prisma/migrations/db/migrate/migrations/oudatabase/migrations/alembic/versions/
3. Gerar Arquivo de Migração
Com base no ORM detectado, crie um arquivo de migração apropriado:
Prisma
- Execute
npx prisma migrate dev --name <descricao>OU - Crie manualmente o SQL da migração em
prisma/migrations/<timestamp>_<nome>/migration.sql
Sequelize
- Gere:
npx sequelize-cli migration:generate --name <descricao> - Em seguida, preencha as funções up/down com as alterações de esquema
Knex
- Gere:
npx knex migrate:make <descricao> - Preencha as funções exports.up e exports.down
TypeORM
- Gere:
npm run typeorm migration:create src/migrations/<Nome> - Implemente os métodos up() e down()
Alembic
- Gere:
alembic revision -m "<descricao>" - Preencha as funções upgrade() e downgrade()
Django
- Execute:
python manage.py makemigrations - Ou crie manualmente a migração em
<app>/migrations/
Rails
- Gere:
rails generate migration <NomeClasse> - Preencha o método change (ou up/down para migrações complexas)
4. Seguir Convenções de Nomenclatura
Use nomes consistentes e descritivos:
- Bom:
add_user_email_index,create_products_table,add_payment_status_to_orders - Ruim:
migration1,update,fix
Formate com base nos padrões do projeto:
- Prefixo timestamp:
20231215120000_add_email_to_users - Sequencial:
001_create_users,002_add_indexes
5. Incluir Tanto Up/Upgrade quanto Down/Downgrade
Sempre forneça ambas as direções quando suportado:
- Up/Upgrade/Forward: Aplica a alteração de esquema
- Down/Downgrade/Rollback: Reverte a alteração de esquema
Para ORMs que usam operações reversíveis (Rails, alguns Sequelize), um único método change pode ser suficiente.
6. Diretrizes de Conteúdo da Migração
Criando Tabelas:
- Defina todas as colunas com tipos apropriados
- Defina restrições NOT NULL quando apropriado
- Adicione chaves primárias
- Inclua timestamps (created_at, updated_at) se o projeto os usar
- Adicione chaves estrangeiras e índices na mesma migração ou separadamente, conforme preferência do projeto
Alterando Tabelas:
- Seja específico:
ADD COLUMN,DROP COLUMN,MODIFY COLUMN - Lide com dados existentes adequadamente (valores padrão, backfills)
- Considere a compatibilidade com versões anteriores
Adicionando Índices:
- Nomeie os índices claramente:
idx_users_email,idx_orders_user_id_created_at - Use tipos de índice apropriados (B-tree, Hash, GIN, etc.)
- Considere índices parciais para tabelas grandes
Migrações de Dados:
- Separe migrações de esquema de migrações de dados, se possível
- Seja cauteloso com grandes conjuntos de dados (operações em lote)
- Teste a reversão com volumes de dados realistas
7. Validar Segurança da Migração
Antes de finalizar, verifique:
- Reversibilidade: A migração pode ser revertida?
- Perda de dados: Algum dado será perdido? Avise o usuário!
- Tempo de inatividade: Isso bloqueará tabelas? Considere migrações online para tabelas grandes
- Dependências: Existem migrações dependentes que devem ser executadas primeiro?
8. Recomendações de Teste
Sugira ao usuário:
- Execute a migração em um banco de dados de desenvolvimento primeiro
- Teste a funcionalidade de reversão
- Para produção: teste em um ambiente de staging
- Revise o SQL gerado (para ORMs que geram automaticamente)
Modelos Específicos por ORM
Consulte os modelos no diretório templates/:
prisma-migration.sql- Exemplo de migração Prismasequelize-migration.js- Exemplo de migração Sequelizeknex-migration.js- Exemplo de migração Knextypeorm-migration.ts- Exemplo de migração TypeORMalembic-migration.py- Exemplo de migração Alembicrails-migration.rb- Exemplo de migração Rails
Melhores Práticas
- Um propósito por migração: Não misture alterações não relacionadas
- Nomes descritivos: Os nomes devem explicar o que a migração faz
- Timestamps: Use o formato de timestamp do ORM para ordenação
- Idempotente quando possível: Seguro executar várias vezes
- Teste reversões: Garanta que down/rollback funciona corretamente
- Documente lógica complexa: Adicione comentários para operações não óbvias
- Lote de operações grandes: Para migrações de dados que afetam muitas linhas
- Use transações: Envolvam operações em transações quando suportado
Arquivos de Suporte
templates/: Modelos de migração para vários ORMsreference.md: Convenções de nomenclatura e padrões de migração