migrate

/migrate

概要

3 種類の変更に対応する単一の移行ワークフローです。主なフローは EF Core スキーマ移行です。

1. EF Core スキーマ — 保留中のモデル変更を確認し、内容を説明する名前の移行を生成し、データ損失やロックのリスクについて SQL を確認し、ロールバック手順を記録したうえで適用します。
2. .NET バージョンのアップグレード — 各フェーズで検証を行いながら、段階的に TFM／SDK／パッケージをアップグレードします。
3. NuGet の更新 — 破損の原因を常に特定できるよう、パッケージを 1 つずつ段階的に更新します。

共通原則：適用前に検証すること、常にロールバック計画を用意すること、各ステップの後にテストすること、移行ごとに論理的な変更を 1 つだけ含めること。

タイミング

• エンティティクラス、DbContext の設定、またはリレーションシップを変更した後
• 「add migration」、「update database」、「create migration」、「new table」、「rename column」
• DBA による確認用の SQL スクリプトを生成するとき
• 「upgrade to .NET 10」、「version upgrade」、「.NET upgrade」
• 「upgrade nuget」、「update packages」、「dependency update」、脆弱なパッケージに関するアラート

方法

まず、リクエストを分類します。スキーマ変更ならフロー A、フレームワークのアップグレードならフロー B、パッケージの更新ならフロー C に進みます。その後、該当するフローを最初から最後まで実行します。

フロー A：EF Core スキーマ移行（主なフロー）

ステップ 1：現在の状態を評価する

dotnet ef migrations list --project <InfraProject> --startup-project <ApiProject>

保留中の移行と、取り込まれていないモデル変更がないか確認します。

ステップ 2：モデル変更を確認する

ファイル全体を読むのではなく、MCP ツールを使用します。

find_symbol(name: entity or DbSet)        -- locate the changed entity
get_type_hierarchy(typeName: entity)      -- check TPH/TPT/TPC inheritance changes
find_references(symbolName: property)     -- assess downstream query impact

変更が論理的に 1 つの単位であることを確認します。そうでない場合は、複数の移行に分割します。複数の変更が混在した移行では、すべてを一度にロールバックすることになります。

ステップ 3：移行を生成する

名前にはエンティティではなく変更内容を記述します。Add|Remove|Rename|Modify + WhatChanged とします。

# GOOD
dotnet ef migrations add AddOrderShippingAddress --project <Infra> --startup-project <Api>
# BAD — names the entity, not the change
dotnet ef migrations add Order

ステップ 4：生成された SQL を確認する

database update にはドライラン用のフラグがありません。冪等スクリプトを生成して内容を読むことで、事前に確認します。

dotnet ef migrations script --idempotent --project <Infra> --startup-project <Api>

次の点を報告します。

• DROP COLUMN / DROP TABLE — データ損失が意図したものか確認します
• ALTER COLUMN による型の変更 — 精度の損失や切り捨てがないか確認します
• 大きなテーブルに対する ALTER — ロックの継続時間について警告します
• 新しい NOT NULL 列 — 既存の行に値を設定するためのデフォルト値が必要です

名前変更や型変更の際にデータを保持する必要がある場合は、生 SQL を使った複数ステップの移行を使用します。

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.AddColumn<string>("ContactEmail", "Customers", nullable: true);
    migrationBuilder.Sql("UPDATE \"Customers\" SET \"ContactEmail\" = \"Email\"");
    migrationBuilder.AlterColumn<string>("ContactEmail", "Customers", nullable: false);
    migrationBuilder.DropColumn("Email", "Customers");
}

ステップ 5：適用して検証する

dotnet ef database update --project <Infra> --startup-project <Api>
dotnet build && dotnet test   # integration tests catch schema mismatches

ステップ 6：ロールバック手順を記録する

dotnet ef database update <PreviousMigrationName> --project <Infra> --startup-project <Api>
dotnet ef migrations remove --project <Infra> --startup-project <Api>   # if unapplying from code

すでに適用された移行は変更しないでください。新しい移行を作成します。

フロー B：.NET バージョンのアップグレード

1. 評価 — get_project_graph で、すべての TFM を一覧表示します。バージョンが混在している場合は指摘します。
2. 事前確認 — すべてのテストが成功していること、保留中の EF 移行がないこと、依存関係がアップグレード先のバージョンと互換性があるか確認済みであること、専用ブランチを作成済みであることを確認します（ブランチがロールバック計画になります）。
3. global.json を更新 — SDK のバージョンに "rollForward": "latestMinor" を指定します。
4. TFM を更新 — .csproj または Directory.Build.props の <TargetFramework>net10.0</TargetFramework> と <LangVersion>14</LangVersion> を更新します。
5. パッケージを更新 — dotnet outdated --upgrade Major --include Microsoft.* を実行し、その後ビルドして問題を修正します。
6. 新機能を取り入れる — knowledge/dotnet-whats-new.md に従い、TimeProvider、HybridCache、プライマリコンストラクター、コレクション式を採用します。
7. 検証 — dotnet build、dotnet test、dotnet format --verify-no-changes を実行します。

フロー C：NuGet パッケージの更新

1. 監査 — dotnet list package --outdated と dotnet list package --vulnerable を実行します。脆弱なパッケージは緊急対応が必要です。更新し、テストして、デプロイします。
2. 分類 — パッチ（まとめて更新しても安全）、マイナー（1 つずつ）、メジャー（リリースノートを先に読み、1 つずつ）。
3. 段階的に更新 — パッケージを 1 つ更新するごとに、次の更新に進む前に dotnet build && dotnet test を実行します。まとめて更新すると、失敗の原因を特定できなくなります。
4. 適合性を確認 — 新しいパッケージを追加する前に knowledge/package-recommendations.md を確認し、.NET に組み込まれている代替手段を優先します。MediatR（v13 以降は商用ライセンス）から移行する場合は、knowledge/mediatr-to-mediator-migration.md の手順に従ってください。
5. ロールバック — パッケージのバージョン変更を git revert します。補うために、ほかのパッケージのバージョンを下げてはいけません。

使用する MCP ツール

• find_symbol / find_references — エンティティを特定し、スキーマ変更の影響を評価します
• get_type_hierarchy — TPH/TPT/TPC のエンティティ継承を確認します
• get_project_graph — バージョンアップ前に TFM を監査します
• get_diagnostics — マイグレーション生成後やアップグレード後の警告を検出します

例

User: /migrate

Claude: Checking migration state...
  Last applied: 20250710_AddOrderTable
  Model changes detected: new ShippingAddress property on Order entity.

  Creating migration: AddOrderShippingAddress
  Reviewing SQL (dotnet ef migrations script --idempotent)...
  - ALTER TABLE "Orders" ADD "ShippingStreet" text NULL
  - ALTER TABLE "Orders" ADD "ShippingCity" text NULL
  No data loss. No locking risk. Safe to apply.

  Applying migration... Done. Build: green. Tests: 34/34 passed.

  Rollback (if needed):
  dotnet ef database update AddOrderTable --project src/Infrastructure --startup-project src/Api

関連項目

• ef-core — エンティティ構成、クエリパターン、マイグレーションの内部処理
• /verify — マイグレーション作業後の完全な検証パイプライン
• /checkpoint — リスクの高いマイグレーションの前に安全な状態をコミットします