schema-migration-planner

スキーマ移行プランナー

ソースマッピング：Kotlin_Spring_Developer_Pipeline.md（SK-11）から派生した Tier 3 の専門スキルです。

ミッション

稼働中のトラフィック、デプロイ順序、ロールバックの安全性を損なわずにスキーマを変更します。 スキーマの進化は、単一の DDL 文ではなく、複数段階にわたる互換性の検討として扱います。

最初に確認すること

• 現在のスキーマと、目標とする構造。
• 現在のコードパス、目標とするコードパス、デプロイモデル。
• テーブルサイズ、トラフィックパターン、ロックへの感度、レプリケーションや CDC の制約。
• 実際に使用している移行ツールと SQL 方言。
• バックフィルの実行能力、ロールアウトの時間枠、ロールバックへの期待。

計画ワークフロー

1. 変更が追加、破壊的、意味的、またはデータ移動を伴うものかを特定します。
2. 旧バージョンと新バージョンのアプリケーションを共存させる必要があるかを判断します。
3. ロールアウトを次のフェーズに分けて計画します。
   • 拡張
   • デュアルライトまたは互換性レイヤー
   • バックフィル
   • 読み取りの切り替え
   • 縮小
4. ロールバックが現実的か、それともロールフォワードのほうが運用上安全かを判断します。
5. スモークチェック、検証クエリ、移行に関する可観測性を定義します。

移行の基本ルール

• 削除する前に追加します。
• 新しいコードで必須にする前に、古いコードが新しいスキーマに対応できるようにします。
• 可能な限り、レイテンシーに敏感なリクエストパスとは別にバックフィルを実行します。
• インデックスと制約は後付けではなく、移行設計の一部として明示的に扱います。
• ツールの想定に従い、移行スクリプトを決定的かつ再実行可能に保ちます。

高度な移行における落とし穴

• データベースやバージョンによっては、デフォルト値を指定して NOT NULL 列を追加すると、大きなテーブルが書き換えられたりロックされたりすることがあります。小さな DDL でも、運用上のコストが高くなる場合があります。
• 一意制約、インデックスの構築、外部キーの検証は、列の追加よりも大きな影響を及ぼすことがあります。
• プライマリの書き込みレイテンシーに問題がなくても、バックフィルによってレプリカ、キューワーカー、キャッシュ、下流の CDC コンシューマーが飽和することがあります。
• ローリングデプロイでは、しばらくの間、旧コードと新コードの両方が書き込みを行う可能性があります。デュアルライトの互換性を明示的に設計してください。
• 名前の変更は、通常、追加・コピー・切り替え・削除の計画を別の形で表したものです。そのように扱ってください。
• 破壊的なクリーンアップは、旧形式に依存する古い読み取り側、書き込み側、レポートがないと確認してから行います。
• トリガーベースの互換性シムは役立つことがありますが、運用の複雑さと隠れた結合を増やします。理解したうえで使用してください。
• ツール上で移行が冪等であっても、業務上の安全性が自動的に保証されるわけではありません。バックフィルスクリプトやデータ修正には、個別の冪等性設計が必要です。

データ進化に関する注意点

• 数値型の拡張、タイムゾーンの再解釈、列挙型の再構成、JSON 構造の進化といった型の変更は、単純な追加や削除より危険な場合があります。
• NOT NULL と一意性の適用では、多くの場合、違反の検出、データのクリーンアップ、制約の検証、厳格な適用という段階的な手順が必要です。
• 大規模テーブルでは、バックフィルのチャンクサイズ、順序、一時停止・再開の動作、チェックポイントも移行設計の一部です。
• データ変換ロジックが単純でない場合、読み取りをすぐに切り替えるより、デュアルリードやシャドーリードのフェーズを設けるほうが安全な場合があります。
• 通常の DDL に伴うロックがワークロードに対して高コストすぎる場合、オンラインスキーマ変更ツールやシャドーテーブル方式が必要になることがあります。
• プライマリデータベースのメトリクスに問題がなくても、バックフィル中はレプリケーションラグや CDC の下流コンシューマーが実際のボトルネックになることがあります。

方言とツールに関する注意点

• オンラインでのインデックス作成、並行インデックス構築、ロックの動作はベンダーごとに異なります。一般的な SQL の知識だけに頼らず、方言に合わせて計画してください。
• Flyway と Liquibase は、ロールバックのモデル化、チェックサムの処理、ブランチ運用において、それぞれ異なる強みがあります。すでに使用しているツールに計画を合わせてください。
• スキーマツールによっては、チェックサムの不一致や適用済み履歴の編集を厳しく扱います。適用済みの移行を書き換えることは、安易に行わないでください。
• パーティションテーブル、シャーディングシステム、CDC パイプラインでは、DDL の構文だけでなく、トポロジーも考慮した移行計画が必要です。

エキスパートの経験則

• 本番環境ですでにデータの形が変わっている場合は、ロールバックという幻想に頼るより、前進する設計を優先してください。
• テーブルが大規模またはビジネス上重要な場合は、互換性の変更、データ移行、クリーンアップを別々のリリースに分けてください。
• マイグレーションによってクエリの形が変わる場合は、スキーマの正しさだけでなく、マイグレーションの一環として実行計画も検証してください。
• ゼロダウンタイムが重要な場合は、隣接するデプロイバージョン間の互換性を明示的に実証してください。
• クリーンアップは初期ロールアウト計画の脚注にせず、明確な証明基準を設けた別のプロジェクト工程として扱ってください。
• スキーマ制約を適用できると決めつける前に、実際の本番環境に即したデータで制約を検証してください。
• データの正確性がリリース速度より重要な場合は、強引にクリーンアップするよりも、より長い共存期間を優先してください。
• マイグレーションを可観測にしてください。危険な工程を開始する前に、バックフィル済み行数、遅延、再試行、検証失敗、切り替え準備状況のカウンターを用意してください。

出力仕様

以下のセクションを返してください。

• スキーマ変更の種類：追加、破壊的、意味的、またはデータ移動。
• 段階的なマイグレーション計画：拡張／縮小の正確な手順。
• 互換性の方針：旧コードと新コードを安全に共存させる方法。
• 運用上のリスク：ロック、バックフィル負荷、レプリケーション、CDC、インデックス作成のリスク。
• 検証：SQL チェック、スモークチェック、ロールアウトのチェックポイント。
• クリーンアップ段階：後で削除できるものと、そのために必要な証明。

ガードレール

• 段階的な計画なしに、本番稼働中のシステムに対する破壊的な DDL を直接推奨しないでください。
• データ変換後もロールバックが安全だと決めつけないでください。
• 他に選択肢がない場合を除き、大規模なバックフィルによってリクエストのレイテンシが左右される構成にしないでください。
• 過去に適用済みのマイグレーションを安易に編集しないでください。

品質基準

このスキルを適切に実行すると、チームは運用面のリスクを考慮した、デプロイ可能で互換性を安全に保つマイグレーション手順を得られます。 不適切な実行では、正しい SQL を書けても、本番環境で実行するには依然として危険なものになります。