データベースマイグレーションヘルパー は何をしますか?
このスキルは、プロジェクトのORM規約と命名パターンに従ったデータベースマイグレーションファイルを作成するのに役立ちます。
このスキルを使用するタイミング
- ユーザーがデータベースマイグレーションの作成をリクエストしたとき
- 新しいテーブルやカラムをデータベースに追加するとき
- 既存のデータベーススキーマを変更するとき
- インデックス、制約、リレーションシップを作成するとき
- ユーザーが「マイグレーション」「スキーマ変更」「データベース更新」に言及したとき
手順
1. ORM/マイグレーションツールの検出
まず、プロジェクトが使用しているORMまたはマイグレーションツールを特定します。
- Prisma:
prisma/schema.prismaまたは package.json 内の@prisma/clientを確認 - Sequelize:
.sequelizercまたは package.json 内のsequelize-cliを確認 - Knex:
knexfile.jsまたは package.json 内のknexを確認 - TypeORM:
ormconfig.jsonまたは package.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関数、forwards/rollbackなど)
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/Rollbackの両方を含める
サポートされている場合は、常に両方向を提供します。
- Up/Upgrade/Forward: スキーマ変更を適用
- Down/Downgrade/Rollback: スキーマ変更を元に戻す
Railsや一部のSequelizeのようにリバーシブル操作を使用するORMの場合は、単一の 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マイグレーションの例
ベストプラクティス
- マイグレーションは1つの目的に: 無関係な変更を混在させない
- 説明的な名前: 名前がそのマイグレーションの内容を説明するように
- タイムスタンプ: 順序付けのためにORMのタイムスタンプ形式を使用
- 可能な限り冪等性: 複数回実行しても安全
- ロールバックのテスト: down/rollbackが正しく動作することを確認
- 複雑なロジックの文書化: 明白でない操作にはコメントを追加
- 大規模操作のバッチ処理: 多数の行に影響するデータマイグレーションの場合
- トランザクションの使用: サポートされている場合は操作をトランザクションでラップ
サポートファイル
templates/: 様々なORM向けのマイグレーションテンプレートreference.md: 命名規則とマイグレーションパターン