name: database-migration-helper description: 创建遵循项目约定的数据库迁移文件，适用于Prisma、Sequelize、Alembic、Knex、TypeORM等ORM。在添加表格、修改架构或用户提及数据库变更时使用。 allowed-tools: 读取，搜索，全局搜索，写入，Bash
数据库迁移助手
此技能帮助您创建遵循项目ORM约定和命名模式的数据库迁移文件。
何时使用此技能
- 用户请求创建数据库迁移
- 向数据库添加新表格或列
- 修改现有数据库架构
- 创建索引、约束或关系
- 用户提及"迁移"、“架构变更"或"数据库更新”
指令
1. 检测ORM/迁移工具
首先，确定项目使用的ORM或迁移工具：
- Prisma：查找
prisma/schema.prisma或@prisma/client在package.json中 - Sequelize：查找
.sequelizerc或sequelize-cli在package.json中 - Knex：查找
knexfile.js或knex在package.json中 - TypeORM：查找
ormconfig.json或typeorm在package.json中 - Alembic（Python）：查找
alembic.ini或alembic/目录 - Django：查找
manage.py和Django迁移在*/migrations/ - Active Record（Rails）：查找
db/migrate/目录 - Flyway：查找
flyway.conf或db/migration/ - Liquibase：查找
liquibase.properties或变更日志文件
使用全局搜索来查找这些指示文件。
2. 检查现有迁移
阅读现有迁移文件以了解：
- 命名约定（时间戳格式、描述格式）
- 目录结构
- 迁移文件格式（SQL、JavaScript、TypeScript、Python等）
- 编码模式（up/down函数、forwards/rollback等）
使用搜索查找最近的迁移：在常见目录中查找，如：
prisma/migrations/db/migrate/migrations/或database/migrations/alembic/versions/
3. 生成迁移文件
根据检测到的ORM，创建适当的迁移文件：
Prisma
- 运行
npx prisma migrate dev --name <description>OR - 手动在
prisma/migrations/<timestamp>_<name>/migration.sql中创建迁移SQL
Sequelize
- 生成：
npx sequelize-cli migration:generate --name <description> - 然后填写up/down函数以进行架构更改
Knex
- 生成：
npx knex migrate:make <description> - 填写exports.up和exports.down函数
TypeORM
- 生成：
npm run typeorm migration:create src/migrations/<Name> - 实现up()和down()方法
Alembic
- 生成：
alembic revision -m "<description>" - 填写upgrade()和downgrade()函数
Django
- 运行：
python manage.py makemigrations - 或手动在
<app>/migrations/中创建迁移
Rails
- 生成：
rails generate migration <ClassName> - 填写change方法（或对于复杂迁移的up/down）
4. 遵循命名约定
使用一致的、描述性的名称：
- 好：
add_user_email_index，create_products_table，add_payment_status_to_orders - 不好：
migration1，update，fix
根据项目模式格式化：
- 时间戳前缀：
20231215120000_add_email_to_users - 序列：
001_create_users，002_add_indexes
5. 包含上和下/回滚
始终提供两个方向（如果支持）：
- 上/升级/向前：应用架构更改
- 下/降级/回滚：撤销架构更改
对于使用可逆操作的ORM（Rails、部分Sequelize），单个change方法可能足够。
6. 迁移内容指南
创建表格：
- 定义所有列及其适当类型
- 在适当的地方设置NOT NULL约束
- 添加主键
- 如果项目使用，则包括时间戳（created_at，updated_at）
- 在同一迁移中添加外键和索引，或者如果项目更倾向于分开，则单独添加
修改表格：
- 具体说明：
ADD COLUMN，DROP COLUMN，MODIFY COLUMN - 适当处理现有数据（默认值，回填）
- 考虑向后兼容性
添加索引：
- 清晰命名索引：
idx_users_email，idx_orders_user_id_created_at - 使用适当的索引类型（B-tree、Hash、GIN等）
- 对于大型表格考虑部分索引
数据迁移：
- 如果可能，将架构迁移与数据迁移分开
- 对于大型数据集要小心（批量操作）
- 用现实数据量测试回滚
7. 验证迁移安全性
在最终确定之前检查：
- 可逆性：迁移可以回滚吗？
- 数据丢失：会丢失任何数据吗？警告用户！
- 停机时间：这会锁定表格吗？考虑大型表格的在线迁移
- 依赖性：是否有必须首先运行的依赖迁移？
8. 测试建议
建议用户：
- 首先在开发数据库上运行迁移
- 测试回滚功能
- 对于生产：在暂存环境中测试
- 查看生成的SQL（对于自动生成SQL的ORM）
ORM特定模板
参考templates/目录中的模板：
prisma-migration.sql- Prisma迁移示例sequelize-migration.js- Sequelize迁移示例knex-migration.js- Knex迁移示例typeorm-migration.ts- TypeORM迁移示例alembic-migration.py- Alembic迁移示例rails-migration.rb- Rails迁移示例
最佳实践
- 每个迁移一个目的：不要混合不相关的更改
- 描述性名称：名称应解释迁移的作用
- 时间戳：使用ORM的时间戳格式进行排序
- 尽可能幂等：安全地多次运行
- 测试回滚：确保down/rollback正确工作
- 为复杂逻辑添加文档：为非明显操作添加注释
- 批量大型操作：对于影响多行的数据迁移
- 使用事务：在支持时将操作包装在事务中
支持文件
templates/：各种ORM的迁移模板reference.md：命名约定和迁移模式