資料庫遷移助手
這項技能可協助你建立符合專案 ORM 慣例與命名模式的資料庫遷移檔案。
使用時機
- 用戶要求建立資料庫遷移
- 在資料庫中新增資料表或資料行
- 修改現有資料庫綱要
- 建立索引、約束條件或關聯
- 用戶提及「migration」、「schema change」或「database update」
操作說明
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在 package.json 中 - Alembic (Python):尋找
alembic.ini或alembic/目錄 - Django:尋找
manage.py及*/migrations/中的 Django 遷移 - Active Record (Rails):尋找
db/migrate/目錄 - Flyway:尋找
flyway.conf或db/migration/ - Liquibase:尋找
liquibase.properties或 changelog 檔案
使用 Glob 搜尋這些指示檔案。
2. 檢查現有遷移
讀取現有遷移檔案以了解:
- 命名慣例(時間戳格式、描述格式)
- 目錄結構
- 遷移檔案格式(SQL、JavaScript、TypeScript、Python 等)
- 編碼模式(up/down 函數、向前/回滾等)
使用 Grep 尋找最近的遷移:查看常見目錄,例如:
prisma/migrations/db/migrate/migrations/或database/migrations/alembic/versions/
3. 產生遷移檔案
根據偵測到的 ORM,建立適當的遷移檔案:
Prisma
- 執行
npx prisma migrate dev --name <描述>或 - 在
prisma/migrations/<時間戳>_<名稱>/migration.sql中手動建立遷移 SQL
Sequelize
- 產生:
npx sequelize-cli migration:generate --name <描述> - 然後在 up/down 函數中填入綱要變更
Knex
- 產生:
npx knex migrate:make <描述> - 填入 exports.up 和 exports.down 函數
TypeORM
- 產生:
npm run typeorm migration:create src/migrations/<名稱> - 實作 up() 和 down() 方法
Alembic
- 產生:
alembic revision -m "<描述>" - 填入 upgrade() 和 downgrade() 函數
Django
- 執行:
python manage.py makemigrations - 或在
<應用程式>/migrations/中手動建立遷移
Rails
- 產生:
rails generate migration <類別名稱> - 填入 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(對於自動產生的 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:命名慣例與遷移模式