database-migration

database-migrationスキルの概要

database-migrationスキルでできること

database-migration スキルは、一般的な ORM や SQL ワークフローにまたがるデータベースのスキーマ変更・データ移行を計画し、実装案まで作るためのスキルです。特に、ロールバックの安全性とゼロダウンタイムリリースを強く意識した設計に向いています。単に「migration を書いて」と頼むだけでは足りない場面、たとえば本番データに直接影響する変更、段階的なデプロイが必要な変更、Sequelize や TypeORM など特定の migration フレームワーク前提で進めたいケースで特に有効です。

このdatabase-migrationスキルを使うべき人

特に相性がよいのは、Database Engineering チーム、バックエンドエンジニア、プラットフォームエンジニア、そして AI 支援で migration を進めたい開発者です。求めているのが「文法的に正しい migration」ではなく、「運用まで見据えた migration 出力」であれば、このスキルは空のプロンプトよりずっと適した出発点になります。テーブル変更、データ backfill、安全なカラム名変更、ORM パターン移行などを扱うときに効果的です。

このスキルが最も得意なジョブ

database-migration スキルを使うべきなのは、実際に実行できる migration 計画を作りたいときです。たとえば migration ファイル、段階的な rollout 手順、rollback 経路、データ変換時の考慮事項まで含めて設計したいケースです。価値の中心は単なるコード生成ではありません。実行順序、互換性を保つ期間、障害発生時の復旧といった論点で、migration の“勘頼み”を減らせる点にあります。

通常のコーディングプロンプトとの主な違い

通常のプロンプトと比べると、この database-migration スキルは次の観点を明確に重視しています。

• ORM を踏まえた migration 例
• 明示的な up / down パターン
• ゼロダウンタイム前提の考え方
• スキーマ変更とデータ変更をまたぐワークフロー
• rollback 手順を必須要件として扱うこと

そのため、単なる「SQL を生成して」という依頼よりも、本番変更にははるかに適しています。

対象範囲と対象外

現在のスキル内容は、migration パターンと実装例の構成に強みがあり、特に Sequelize と TypeORM での活用がしやすくなっています。一方で、リポジトリ固有の自動化、検証スクリプト、判断ルールについては比較的薄めです。公開されているスキルフォルダにあるのが SKILL.md のみだからです。つまり、このスキルは migration 作業の方針づけや下書き生成には十分役立ちますが、安定した出力を得るには、自分のスタック詳細、制約、デプロイ方式をあわせて渡す必要があります。

database-migrationスキルの使い方

database-migrationスキルの導入コンテキスト

このリポジトリの Skills システムを使う場合は、repo からスキルを追加し、そのうえで自分のコードベースやスキーマ情報にアクセスできる agent セッション内で呼び出します。導入例は次のとおりです。

npx skills add https://github.com/wshobson/agents --skill database-migration

このスキルは実質的に単一の SKILL.md を中心に提供されているため、価値の大半は「どう依頼を組み立てるか」と「どれだけスキーマ文脈を渡せるか」で決まります。

使う前にまず読むべきファイル

最初に確認するのは以下です。

• plugins/framework-migration/skills/database-migration/SKILL.md

このスキルには、見える範囲に rules/、resources/、スクリプト類がありません。そのため、長い repo 読み込みフェーズは不要です。実務的には、まず SKILL.md を確認し、その後すぐに自分のスキーマ定義、ORM 設定、既存 migration 履歴を見る流れが最短です。

このスキルがうまく機能するために必要な入力

database-migration スキルは、次の情報があると出力品質が大きく上がります。

• 現在使っている ORM または migration ツール: Sequelize、TypeORM、Prisma、raw SQL など
• 現在のスキーマまたはモデル定義
• 目標とするスキーマ変更
• データ backfill が必要かどうか
• テーブルサイズやトラフィック感度
• 許容できるダウンタイム
• rollback に関する期待値
• 対象 DB エンジン: PostgreSQL、MySQL など
• デプロイ方式: one-shot、phased、blue/green、canary

これらがないと、見た目は正しくても本番では危険な migration を返してくることがあります。

粗い要件を強いdatabase-migrationプロンプトに変える

弱いプロンプト:

Create a migration to rename a column.

より強いプロンプト:

Use the database-migration skill. We use TypeORM with PostgreSQL.
Current table: users(id, full_name, created_at).
Goal: replace full_name with first_name and last_name.
Constraints: production table has 20M rows, cannot block writes, rollout must be zero-downtime, app and migration may be deployed separately.
Need:
1. phased migration plan
2. TypeORM migration files
3. data backfill strategy
4. rollback plan
5. application compatibility notes during transition

後者のように書くと、このスキルは危険な直接 rename ではなく、より安全な expand-migrate-contract の進め方を選びやすくなります。

実運用の migration タスクでおすすめの進め方

実践的な database-migration usage の流れは次のとおりです。

1. まず migration 戦略を出させる
2. リスク、lock の挙動、rollback 前提をレビューする
3. その後で自分のフレームワーク向け migration ファイルを出させる
4. 段階的 rollout ならアプリ側の互換対応も出させる
5. 検証クエリと rollback 手順も要求する
6. 本番に近いデータ形状の staging で検証してから信用する

この順番は重要です。早い段階で migration コードだけ生成させると、rollout モデル自体が間違ったまま固まりやすくなります。

このスキルが特に強い ORM パターン

リポジトリ上で明示的な例が確認できるのは次の 2 つです。

• Sequelize migrations
• TypeORM migrations

説明文ではより広い ORM / プラットフォームでの migration も想定されていますが、見えている実例としてはこの 2 つが最も厚めです。別のスタックを使う場合は、そのまま深いネイティブ対応を期待するより、同じ migration 意図を自分のツールチェーン向けに変換するよう明示して依頼するのが安全です。

ゼロダウンタイム guidance を明示的に求めるべきタイミング

モデルが常にオンライン migration の安全性を最優先してくれるとは限りません。次のどれかに当てはまるなら、ゼロダウンタイム前提を明言してください。

• 大規模テーブル
• 書き込み量が多い
• アプリと DB を別々にデプロイする
• カラム rename や型変更がある
• hot path 上で backfill が走る
• 本番トラフィック下で制約変更を行う

Database Engineering チーム向けの database-migration では、ここをはっきり指定するだけで、サンプル止まりの回答と実際に投入できる回答の差が出ます。

スキルに要求すべき出力

高い確度で使いたいなら、database-migration スキルには単一ファイルではなく、ひとまとまりの成果物を返すよう依頼するのがおすすめです。

• migration code
• rollout sequence
• rollback sequence
• data backfill logic
• assumptions and risks
• validation checklist
• post-migration cleanup steps

こうしておくと、運用上必要なのに見落とされがちな作業を落としにくくなります。

直接的で破壊的な変更に関する実務上の注意

このスキルは、次のような危険な一発変更を避けるために使うのが向いています。

• 古いカラムを即座に削除する
• 互換性を確保せず hot なカラムをその場で rename する
• 変換戦略なしで型を変更する
• backfill 前に non-null 制約を追加する
• lock 影響を計画せず大規模テーブルを書き換える

もし最初の出力が本番導線でこれらをやっているなら、段階的な代替案を求めるべきです。

database-migrationスキル FAQ

このdatabase-migrationスキルは ORM migration 専用ですか

いいえ。このスキルは、ORM や各種プラットフォームをまたぐデータベースのスキーマ変更・データ migration を前提に設計されています。実際には、見えている例は ORM 寄りで、とくに Sequelize と TypeORM が中心です。そのため、最も良い結果を得るには、自分のスタックを明示し、必要に応じて SQL あるいは対象フレームワーク向けに変換するよう頼むのが有効です。

database-migrationスキルは初心者にも向いていますか

はい、ただし限界はあります。例が具体的なので入りやすい一方で、その migration が運用上安全かを自分で判断できる前提があります。初心者でも migration ファイルや rollout 計画の下書きには使えますが、最初の回答をレビューなしでそのまま本番投入できるものとして扱うべきではありません。

どんなときは database-migration を使わないほうがよいですか

タスクが純粋に概念整理だけで、実際のスキーマ変更やデータ変更の実行計画に関係しないなら、このスキルは優先度が下がります。また、リポジトリだけで環境固有の完全な検証まで期待している場合も相性はよくありません。このスキルの公開フォルダには、追加のスクリプト、ルール、テストハーネスが含まれていないためです。

AI に SQL を書かせるのと比べて何が良いですか

database-migration guide としての価値は、タスクを単なる SQL 構文ではなく、migration のライフサイクル全体で捉えさせる点にあります。普通の SQL プロンプトでは、rollback、互換性を保つ移行期間、段階的 backfill、ORM の migration 慣習が抜けがちです。コードの正しさと同じくらいデプロイ安全性が重要なら、このスキルのほうが適しています。

ゼロダウンタイムデプロイに対応していますか

はい。これは明確に想定されているユースケースのひとつです。ただし、あなたの環境でゼロダウンタイムが何を意味するかは具体的に伝える必要があります。この言葉だけでは広すぎます。モデルには、デプロイ順序、読み書きトラフィックの形、互換性制約が必要です。

database-migrationスキルを改善する方法

スキーマ差分と運用制約をセットで渡す

database-migration の出力品質を最も早く上げる方法は、スキーマ変更内容と実行時制約を一緒に渡すことです。たとえば次のように書きます。

Current: orders.status VARCHAR nullable
Target: orders.status ENUM not null
DB: PostgreSQL
Rows: 80M
Traffic: constant writes
Requirement: no downtime, rollback available, deploy app separately

こうすると、単純な alter 文ではなく、段階的 migration 設計に寄りやすくなります。

安全性が重要なら expand-migrate-contract を指定する

最初のドラフトが破壊的すぎる場合は、expand-migrate-contract プランを明示的に要求してください。特に次のようなケースで改善しやすくなります。

• rename
• type conversion
• non-null 導入
• table split
• denormalization または normalization の変更

これは、スキルからより良い database-migration usage を引き出すための、最も再現性の高い方法のひとつです。

最初の回答から validation と rollback を必須にする

よくある失敗は、up migration は正しくても down が弱い、あるいは現実的でないことです。これを防ぐには、最初から次の項目を要求します。

• rollback conditions
• data loss warnings
• verification queries
• success criteria after each phase

こうすることで、モデルに早い段階から可逆性を考えさせられます。

リポジトリ内の既存 migration スタイルを渡す

プロジェクトにすでに migration の書き方の慣習があるなら、代表的なファイルを 1〜2 個貼って、それに合わせるよう依頼してください。これだけで、命名、transaction の扱い、timestamp の流儀、フレームワークの慣用表現がかなり揃います。Sequelize や TypeORM では、フレームワーク標準とは別にチーム固有の流儀があることが多く、特に効果的です。

コードの正しさだけでなく lock リスクを掘る

最初の出力のあとには、コードの正しさだけで終わらせず、次のような追質問を入れてください。

• Which steps may lock the table?
• Which steps can run while writes continue?
• What should be split into separate deploys?
• Which part is irreversible after backfill?
• What monitoring should we watch during rollout?

database-migration スキルが、単なる boilerplate 生成ではなく、Database Engineering の実務に本当に役立つ段階に入るのはここからです。

よくある失敗パターンを見抜く

生成された migration に次の傾向がある場合は注意が必要です。

• 小さなテーブル前提で話が進んでいる
• rollback が省かれている
• 古いフィールドを早すぎる段階で削除している
• スキーマ変更と大規模 backfill を一つの危険な手順にまとめている
• 移行期間中のアプリ互換性を無視している
• フレームワーク構文が自分のバージョンと合っていない

これらは「スキルが使えない」というより、プロンプトを詰め直すべき典型例です。

初稿のあとに結果を改善する最良の方法

最初の回答は完成品ではなく、migration proposal として扱うのが基本です。そのうえで、次の実情報をもとに修正を依頼してください。

• 実際のテーブルサイズ
• index の状況
• 想定している deploy 順序
• canary や staging で得た結果
• レビューで判明した誤った前提

このフィードバックループこそが、database-migration install と活用フローから本番水準の価値を引き出す、いちばん現実的なやり方です。