db-migration-helper

DB Migration Helper

モデルの変更を分析し、安全なデータベース移行 SQL を生成します。

概要

コード内のエンティティ／モデル定義と現在のデータベーススキーマを比較し、構造の変更（テーブルの追加、列の追加・削除、型の変更）を検出して、前方互換性のある移行 SQL を生成します。MySQL、PostgreSQL、SQLite に対応しています。

使用するタイミング

• ユーザーがデータベース移行を作成したい場合
• ユーザーがモデル／エンティティの定義を変更した場合
• ユーザーが migration、schema change、sync に言及した場合
• ユーザーが「移行を生成」／「create migration」と言った場合
• ユーザーが /db-migration-helper を入力した場合

使用しないタイミング：

• ユーザーがデータベース構造の確認だけを希望している場合
• ユーザーがデータ移行（スキーマではなくデータ）を希望している場合
• ユーザーが ORM の自動移行を使用している場合
• ユーザーがシードデータの生成を希望している場合
• ユーザーがデータベースのバックアップ／復元を希望している場合

基本的な流れ

ステップ 1：プロジェクトの種類と ORM を検出する

検出ファイル	ORM／フレームワーク	移行方法
prisma/schema.prisma	Prisma	SQL diff を生成
alembic/	SQLAlchemy + Alembic	Alembic migration を生成
migrations/	汎用	既存の移行をスキャンして推定
*.entity.ts / *.model.ts	TypeORM / Sequelize	デコレーターから抽出
schema.rb / db/migrate/	Rails	Rails migration

ステップ 2：現在のスキーマを抽出する

# Prisma (v2.18+，旧命令 introspect 已更名为 db pull，统一用 db pull)
npx prisma db pull 2>/dev/null

# 通用 — 从代码提取
grep -r "CREATE TABLE\|@Entity\|@Table\|model " --include="*.ts" --include="*.py" --include="*.go" -l

抽出する内容：

• テーブル名と列定義
• 列の型、制約（NOT NULL、DEFAULT、UNIQUE）
• インデックスと外部キー

ステップ 3：変更を比較する

コード内のモデル定義と既存のスキーマ（または前回の移行）を比較し、次の変更を検出します。

変更の種類	リスクレベル	説明
テーブルの追加	低	そのまま CREATE TABLE を実行
列の追加（DEFAULT あり）	低	ALTER TABLE ADD COLUMN
列の追加（DEFAULT なし）	中	既存データの処理が必要
列の削除	高	データが失われる可能性があるため、確認が必要
列の型の変更	高	互換性がない可能性あり
インデックスの追加	低	CREATE INDEX
インデックスの削除	低	DROP INDEX

ステップ 4：移行ファイルを生成する

templates/migration.sql テンプレートを使用して、次を生成します。

1. Up 移行 — 正方向の変更 SQL
2. Down ロールバック — 逆方向のロールバック SQL
3. リスク評価 — 高リスクの操作に印を付ける

-- Migration: 20260603_add_user_avatar
-- Risk: LOW

-- Up
ALTER TABLE users ADD COLUMN avatar_url VARCHAR(500);
CREATE INDEX idx_users_email ON users(email);

-- Down
DROP INDEX idx_users_email;
ALTER TABLE users DROP COLUMN avatar_url;

クイックリファレンス

/db-migration-helper                    # 检测变更，生成迁移
/db-migration-helper --dry-run          # 只预览 SQL 不执行
/db-migration-helper --name add_user    # 指定迁移名称

パラメーター	説明	デフォルト値
--dry-run	実行せずにプレビューのみ	false
--name	移行ファイル名	自動生成
--output	出力ディレクトリ	./migrations/

よくある間違い

間違い	正しい方法	理由
down ロールバックを生成しない	常にロールバック SQL を生成する	問題が発生した場合に元に戻す必要があるため
列を削除する前にバックアップしない	データをバックアップしてから列を削除する	データを失うと復元できないため
型の変更に ALTER COLUMN を使う	PostgreSQL では ALTER COLUMN ... TYPE ... USING を直接使用できます。MySQL では列の新規作成 → データの移行 → 古い列の削除を行います	MySQL で型を直接変更するとデータが失われる可能性があり、PG の USING はアトミックに変換するため
インデックスを追加しない	クエリで使用するフィールドにインデックスを追加する	クエリのパフォーマンスに影響するため
移行ファイルに名前を付けない	説明的な名前を付ける	チームでの共同作業や変更履歴の確認が容易になるため
外部キーの依存関係を確認しない	先にテーブル間の関係を確認する	参照されている列を削除すると失敗するため