数据库迁移助手 是做什么的?
此技能可帮助您创建符合项目 ORM 约定和命名模式的数据库迁移文件。
何时使用此技能
- 用户请求创建数据库迁移
- 向数据库添加新表或新列
- 修改现有数据库架构
- 创建索引、约束或关系
- 用户提及“迁移”、“架构更改”或“数据库更新”
操作说明
1. 检测 ORM/迁移工具
首先,识别项目使用哪个 ORM 或迁移工具:
- Prisma:在 package.json 中查找
prisma/schema.prisma或@prisma/client - Sequelize:在 package.json 中查找
.sequelizerc或sequelize-cli - Knex:在 package.json 中查找
knexfile.js或knex - TypeORM:查找
ormconfig.json或typeorm - Alembic(Python):查找
alembic.ini或alembic/目录 - Django:查找
manage.py以及*/migrations/中的 Django 迁移 - Active Record(Rails):查找
db/migrate/目录 - Flyway:查找
flyway.conf或db/migration/ - Liquibase:查找
liquibase.properties或变更日志文件
使用 Glob 搜索这些指示文件。
2. 检查现有迁移
阅读现有迁移文件以了解:
- 命名约定(时间戳格式、描述格式)
- 目录结构
- 迁移文件格式(SQL、JavaScript、TypeScript、Python 等)
- 编码模式(up/down 函数、forward/rollback 等)
使用 Grep 查找最近的迁移:在常见目录中查找,例如:
prisma/migrations/db/migrate/migrations/或database/migrations/alembic/versions/
3. 生成迁移文件
根据检测到的 ORM,创建适当的迁移文件:
Prisma
- 运行
npx prisma migrate dev --name <description>或者 - 手动在
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. 同时包含 Up 和 Down/回滚
在支持的情况下始终提供两个方向:
- Up/Upgrade/Forward:应用架构更改
- Down/Downgrade/Rollback:还原架构更改
对于使用可逆操作的 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:命名约定和迁移模式