migration-workflow

移行ワークフロー

基本原則

1. 適用前に確認する — データベースに適用する前に、生成された移行 SQL を必ず確認してください。dotnet ef migrations script で正確な SQL を確認できます。内容を確認せずに適用してはいけません。
2. 必ずロールバック計画を用意する — すべての移行にロールバック手段を用意します。EF Core の場合：dotnet ef database update <PreviousMigration>。パッケージの場合：git revert。.NET のバージョンの場合：ブランチを使ったロールバックです。適用前にロールバック方法を文書化してください。
3. 移行後にテストする — 移行の各ステップ後に、テストスイート全体を実行してください。テストを失敗させる移行は完了とはいえません。Testcontainers を使った統合テストで、実際のデータベースの問題を検出できます。
4. 1 回の移行につき変更は 1 つ — EF Core の各移行は、1 つの論理的な変更（テーブルの追加、列名の変更、インデックスの追加など）を表すようにしてください。無関係な変更を 1 つの移行にまとめると、ロールバックできなくなります。
5. 段階的に更新する — パッケージは 1 つずつ更新して、ビルドとテストを実行してください。ターゲットフレームワークも 1 つずつ更新して、ビルドとテストを実行してください。無関係な変更をまとめてはいけません。問題が発生した場合、原因となった変更を特定する必要があります。

パターン

EF Core の移行ワークフロー

データベースの移行を安全に作成して適用するための、手順に沿ったワークフローです。

ステップ 1：現在の状態を確認する

# List all migrations and their status
dotnet ef migrations list --project src/Infrastructure --startup-project src/Api

# Verify the database is at the expected migration
dotnet ef database update --project src/Infrastructure --startup-project src/Api -- --dry-run

ステップ 2：移行を作成する エンティティ名ではなく、変更内容が分かる説明的な名前を使います。

# GOOD — Describes the change
dotnet ef migrations add AddOrderShippingAddress --project src/Infrastructure --startup-project src/Api
dotnet ef migrations add RenameCustomerEmailToContactEmail --project src/Infrastructure --startup-project src/Api
dotnet ef migrations add AddIndexOnOrderCreatedAt --project src/Infrastructure --startup-project src/Api

# BAD — Describes the entity, not the change
dotnet ef migrations add Order
dotnet ef migrations add UpdateCustomer

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

# Generate the SQL script for review
dotnet ef migrations script --idempotent --project src/Infrastructure --startup-project src/Api

# Or generate from a specific migration
dotnet ef migrations script PreviousMigration AddOrderShippingAddress --project src/Infrastructure --startup-project src/Api

次の点を確認します。

• ⚠️ データ損失：DROP COLUMN、DROP TABLE、精度が失われる列型の変更
• ⚠️ 長時間のロック：大きなテーブルに対して、インデックスを同時作成せずに実行する ALTER TABLE
• ⚠️ デフォルト値：新しい null 非許容列には、既存の行に対するデフォルト値が必要です

ステップ 4：データ損失の警告に対処する EF Core がデータ損失の可能性について警告した場合：

// In the migration file — explicitly handle data transformation
protected override void Up(MigrationBuilder migrationBuilder)
{
    // Step 1: Add new column as nullable
    migrationBuilder.AddColumn<string>("ContactEmail", "Customers", nullable: true);

    // Step 2: Copy data from old column
    migrationBuilder.Sql("UPDATE \"Customers\" SET \"ContactEmail\" = \"Email\"");

    // Step 3: Make non-nullable after data is copied
    migrationBuilder.AlterColumn<string>("ContactEmail", "Customers", nullable: false);

    // Step 4: Drop old column
    migrationBuilder.DropColumn("Email", "Customers");
}

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

# Apply to development database
dotnet ef database update --project src/Infrastructure --startup-project src/Api

# Run tests to verify
dotnet test

ステップ 6：ロールバックする（必要な場合）

# Rollback to previous migration
dotnet ef database update PreviousMigrationName --project src/Infrastructure --startup-project src/Api

# Remove the failed migration from code
dotnet ef migrations remove --project src/Infrastructure --startup-project src/Api

NuGet 依存関係の更新ワークフロー

ビルドを壊さずに NuGet パッケージを更新する安全な手順です。

ステップ 1：現在の状態を監査する

# List all outdated packages
dotnet list package --outdated

# Check for vulnerable packages
dotnet list package --vulnerable

ステップ 2：更新を分類する

• パッチ更新（1.0.0 → 1.0.1）：安全で、バグ修正のみです。すべてのパッチをまとめて更新します。
• マイナー更新（1.0.0 → 1.1.0）：通常は安全で、新機能が含まれます。1 つずつ更新します。
• メジャー更新（1.0.0 → 2.0.0）：破壊的変更が予想されます。1 つずつ更新し、リリースノートを確認します。

ステップ 3：段階的に更新する

# Patch updates — batch is safe
dotnet outdated --upgrade Patch

# Minor updates — one at a time
dotnet add src/Api/Api.csproj package Serilog.AspNetCore --version 9.1.0
dotnet build
dotnet test

# Major updates — one at a time with careful review
dotnet add src/Api/Api.csproj package WolverineFx
dotnet build  # Fix compilation errors
dotnet test   # Fix behavioral changes

ステップ 4：パッケージの推奨事項を参照する 新しいパッケージを追加する前に、knowledge/package-recommendations.md を確認してください。

• .NET の組み込み機能で代替できますか？（例：サードパーティ製キャッシュではなく HybridCache）
• パッケージは積極的にメンテナンスされていますか？
• キットの推奨事項に沿っていますか？

ステップ 5：検証する

dotnet build   # Clean compilation
dotnet test    # All tests pass

.NET バージョンの移行ワークフロー

古い .NET バージョンから .NET 10 への、手順に沿ったアップグレードです。

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

→ get_project_graph
  List all projects and their target frameworks.
  Flag: mixed TFMs, test projects on different versions.

ステップ 2：移行前のチェックリスト

• 現在のバージョンですべてのテストに合格する
• 未適用の EF Core 移行がない
• 依存関係が .NET 10 との互換性について確認済みである
• 移行作業用のブランチが作成されている

ステップ 3：global.json を更新する

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestMinor"
  }
}

ステップ 4：ターゲットフレームワークを更新する 各 .csproj を更新します（または一元管理している場合は Directory.Build.props を更新します）。

<PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>14</LangVersion>
</PropertyGroup>

ステップ 5：パッケージを更新する

# Update all Microsoft.* packages to 10.x
dotnet outdated --upgrade Major --include Microsoft.*
dotnet build  # Fix compilation issues

ステップ 6：新機能を取り入れる knowledge/dotnet-whats-new.md を参照してください。

• DateTime.Now／DateTime.UtcNow を TimeProvider に置き換える
• IDistributedCache ではなく HybridCache を使用する
• 適切な場合は、クラスをプライマリコンストラクターに変換する
• コレクション式を使用する：int[] x = [1, 2, 3]
• プロパティアクセサーで field キーワードを使用する

ステップ 7：検証する

dotnet build                    # Clean build
dotnet test                     # All tests pass
dotnet format --verify-no-changes  # Formatting consistent

その後、project-setup スキルのヘルスチェックワークフローを実行し、新しいベースラインを確立します。

アンチパターン

SQL を確認せずに移行を適用する

# BAD — Blindly applying
dotnet ef database update
# Oops, dropped a column with 10 million rows of data

# GOOD — Review first, then apply
dotnet ef migrations script --idempotent > review.sql
# Read review.sql, check for DROP, ALTER, data loss
dotnet ef database update

すべてのパッケージを一度に更新する

# BAD — Update everything, pray it works
dotnet outdated --upgrade Major
dotnet build  # 47 errors — which package caused this?

# GOOD — One at a time, build after each
dotnet add package WolverineFx
dotnet build && dotnet test  # ✅
dotnet add package Serilog --version 5.0.0
dotnet build && dotnet test  # ❌ — Serilog 5.0 broke the sink config

移行後のテストを省略する

# BAD
dotnet ef database update  # "It compiled, ship it"

# GOOD
dotnet ef database update
dotnet test  # Run FULL test suite, especially integration tests
# Integration tests with Testcontainers will catch schema mismatches

1 つの移行に無関係な変更を複数含める

# BAD — Three unrelated changes in one migration
dotnet ef migrations add UpdateEverything
# Contains: new table + renamed column + dropped index
# Rollback is all-or-nothing for three unrelated changes

# GOOD — One change per migration
dotnet ef migrations add AddShippingAddressTable
dotnet ef migrations add RenameCustomerEmailColumn
dotnet ef migrations add DropUnusedOrderIndex
# Each can be rolled back independently

判断ガイド

シナリオ	ワークフロー	主な手順
新しいデータベーステーブル	EF Core Migration	エンティティ＋設定＋マイグレーションを作成
列名の変更	EF Core Migration	データが保持されることを確認するため、SQL をレビュー
インデックスの追加	EF Core Migration	大きなテーブルで長時間のロックが発生しないか確認
データ変換	EF Core Migration + raw SQL	SQL ステートメントを使ってカスタムの Up() を作成
古くなったパッケージ	NuGet Update	1 つずつ更新し、更新のたびにビルドとテストを実施
脆弱性のあるパッケージ	NuGet Update (urgent)	すぐに更新し、テストしてデプロイ
.NET バージョンのアップグレード	.NET Migration	フェーズ 1～4 を進め、各フェーズで検証
新しいパッケージの追加	NuGet Update	まず package-recommendations.md を確認
ExecuteUpdateAsync とマイグレーションの使い分け	状況による	スキーマにはマイグレーションを使用し、実行時の一括データ更新には ExecuteUpdateAsync を使用
既存のマイグレーションの変更	適用済みの場合は絶対にしない	代わりに新しいマイグレーションを作成