Claude Codeでデータベースのマイグレーションをする方法！スキーマ変更を安全に管理する手順｜ブログ

はじめに

「マイグレーションファイルの書き方がわからない」

「本番データベースのスキーマ変更が怖くて進められない」

「マイグレーションが失敗したときのロールバック手順がわからない」

データベースのスキーマ変更はアプリケーション開発の中でもリスクの高い作業の一つです。Claude Codeを使えば、安全なマイグレーション計画の立案から実行・検証まで自律的にサポートしてくれます。

Claude Codeでのマイグレーション管理の基本
マイグレーションファイルの自動生成
安全なマイグレーションの設計
ロールバック戦略の実装
本番環境への適用手順
データマイグレーションの実装
よく使うマイグレーションパターン
まとめ

1. Claude Codeでのマイグレーション管理の基本

対応しているマイグレーションツール

Claude Codeは主要なマイグレーションツールすべてに対応しています。

ツール	主な使用言語	特徴
Alembic	Python（SQLAlchemy）	柔軟な自動生成
Prisma Migrate	Node.js	スキーマファースト
Flyway	Java/任意	SQL直接記述
Liquibase	Java/任意	XML/YAML/JSON対応
Rails Migrations	Ruby	フレームワーク統合
Django migrations	Python	ORM統合

マイグレーション作業の全体像

スキーマ変更の要件が決まる
    ↓
Claude Codeに変更内容を伝える
    ↓
マイグレーションファイルを自動生成
    ↓
ロールバック手順の確認
    ↓
開発環境で適用・検証
    ↓
ステージング環境で適用・検証
    ↓
本番環境への適用

2. マイグレーションファイルの自動生成

Alembicのマイグレーション生成

> usersテーブルに以下の変更を加えるAlembicのマイグレーションを作成してください：

  追加するカラム：
  - last_login_at: TIMESTAMP WITH TIME ZONE, nullable
  - login_count: INTEGER, NOT NULL DEFAULT 0
  - is_email_verified: BOOLEAN, NOT NULL DEFAULT FALSE

  インデックス：
  - last_login_atにインデックスを追加（検索パフォーマンス向上のため）

  アップグレードとダウングレードの両方を実装してください。

Prismaのマイグレーション生成

> 以下のPrismaスキーマの変更に対するマイグレーションを作成してください：

  変更内容：
  - Postモデルにtagsフィールド（文字列配列）を追加
  - UserモデルのnameフィールドをfirstNameとlastNameに分割
  - Commentモデルを新規追加

  既存データの移行ロジックも含めてください。
  nameフィールドのデータは「名 姓」の形式でfirstNameとlastNameに分割してください。

3. 安全なマイグレーションの設計

ゼロダウンタイムマイグレーション

本番環境でサービスを停止せずにスキーマを変更するための設計です。

> usersテーブルのemail_addressカラムをemailにリネームする
  ゼロダウンタイムマイグレーションを設計してください。

  制約：
  - サービスを停止せずに実行する
  - 旧カラム名で動作するコードと新カラム名で動作するコードの
    両方が混在する過渡期を考慮する

  フェーズごとの手順を詳しく説明してください。

Claude Codeが以下のような段階的な計画を提案します。

Phase 1：新カラムを追加する（既存カラムは維持）
  ALTER TABLE users ADD COLUMN email VARCHAR(255);

Phase 2：既存データを新カラムにコピー（トリガーまたはバッチ処理）

Phase 3：アプリケーションを新カラムを使うように更新

Phase 4：古いカラムを削除する
  ALTER TABLE users DROP COLUMN email_address;

インデックス追加のオンライン実行

> 本番環境でテーブルをロックせずにインデックスを追加する
  マイグレーションを作成してください。

  対象：ordersテーブルのcreated_atカラム
  PostgreSQL の CONCURRENTLY オプションを使ってください。
  Alembicで実行する場合のコードも含めてください。

4. ロールバック戦略の実装

ダウングレードスクリプトの作成

> このマイグレーションのダウングレードスクリプトを作成してください。
  特に以下のケースを考慮してください：

  - データが失われる操作（カラム削除）がある場合は
    事前にバックアップテーブルを作成する
  - NOT NULL制約を追加した場合のロールバック
  - インデックスの削除

  [マイグレーションファイルを貼り付け]

マイグレーション失敗時の復旧手順

> 本番環境でのマイグレーション失敗に備えた緊急復旧手順書を作成してください。

  含める内容：
  - マイグレーション実行前のバックアップ手順
  - マイグレーション失敗の検知方法
  - ロールバックの実行手順（コマンドレベルで詳細に）
  - データ整合性の検証方法
  - サービスの再起動手順

5. 本番環境への適用手順

適用前チェックリスト

> このマイグレーションを本番環境に適用する前のチェックリストを作成してください。

  確認項目：
  - マイグレーションによるテーブルロック時間の見積もり
  - インデックス再構築が必要なテーブルサイズ
  - テーブルが大きい場合のパーティション分割の必要性
  - アプリケーションの後方互換性
  - ロールバック可能かどうか

ドライランの実行

> このマイグレーションのドライランを実行して、
  実際に変更を加えずに何が起こるかを確認してください。

  確認したいこと：
  - 実行されるSQLの内容
  - 影響を受けるテーブルとレコード数
  - 推定実行時間
  - 必要なディスク容量

6. データマイグレーションの実装

既存データの変換

> 既存のfull_nameカラムのデータをfirst_nameとlast_nameに分割する
  データマイグレーションスクリプトを作成してください。

  考慮事項：
  - 名前が1語の場合の処理
  - 名前が3語以上の場合の処理
  - 空白・null値の処理
  - 大量データの場合のバッチ処理（10,000件ずつ処理）
  - 処理の進捗ログ
  - エラー時の処理と再実行可能な設計

大量データの安全なマイグレーション

> 100万件以上のレコードがあるordersテーブルに
  新しいカラムを追加してデータを埋めるマイグレーションを
  サービスに影響を与えずに実行してください。

  方針：
  - バックグラウンドジョブで少しずつ処理
  - 処理済みフラグで再実行に対応
  - 進捗の監視方法
  - 完了の確認方法

7. よく使うマイグレーションパターン

パターン① 外部キー制約の安全な追加

> ordersテーブルにuser_idの外部キー制約を追加してください。
  既存データで外部キー違反があるレコードを事前にチェックして、
  問題がある場合は報告してください。

パターン② カラムのデータ型変更

> usersテーブルのage（VARCHAR）をage（INTEGER）に変更してください。
  データ型変換できない不正なデータがある場合の処理も含めてください。

パターン③ テーブルのパーティショニング

> logsテーブルを月次パーティションに変換するマイグレーションを作成してください。
  既存データの移行手順と、アプリケーションへの影響も説明してください。

8. まとめ

Claude Codeでのマイグレーション管理のポイント：

マイグレーションファイルの自動生成でヒューマンエラーを削減
ゼロダウンタイムマイグレーションの設計を相談できる
ロールバック戦略を事前に立案・実装できる
大量データの安全な移行スクリプトを自動生成できる

本番環境への適用で守るべき原則：

必ずバックアップを取ってから実行する
ステージング環境で先に検証する
ゼロダウンタイムかどうかを事前に確認する
ロールバック手順を事前に準備する

次回の第24回：CLIツールを作成する方法では、コマンドラインツールをClaude Codeで自動生成する方法を解説します。

よくある質問（FAQ）

Q. マイグレーションのロックでサービスが止まるリスクはどう回避しますか？

A. Claude Codeに「このマイグレーションでテーブルロックは発生しますか？ゼロダウンタイムで実行する方法を教えてください」と相談することで、ロック回避の方法を提案してくれます。

Q. 複数の開発者が同時にマイグレーションを作成した場合の競合は？

A. マイグレーションファイルのタイムスタンプ衝突や順序の問題をClaude Codeに相談することで、解決策を提案してくれます。

この記事はClaude Code入門シリーズ（第3部）の第23回です。← 第22回：API設計・実装｜第24回：CLIツール作成 →

ご質問はお問い合わせページからお気軽にどうぞ。

Claude Codeでデータベースのマイグレーションをする方法！スキーマ変更を安全に管理する手順