マイグレーションのデプロイ順序

要点

production.yml / staging.yml のジョブ順は migrate → deploy → verify である。この順序は追加のみのマイグレーションでは正しく、値の変換や削除では危険。 どちらに該当するかを、マイグレーションを書いた時点で判定して記録する。

したがって順序の担保はワークフローの叩き方ではなくリリースの切り方で行う。

判定表

追加と削除を混在させない

したがってリリースを分割する。

互換コードの merge とマイグレーションの merge を分ける。同じ PR に入れない。 どちらも 3 段になるが、マイグレーションを置く段が種別で違うので取り違えないこと。

削除・リネームの場合（旧構造の削除が最後）

EcAuthDocs#110 が実際にこの形になっている。EcAuth#521 がリリース 1、 GetUnclaimedByExternalIdAsync と B2BUser.ExternalId の除去がリリース 2、 b2b_user.external_id の削除がリリース 3。

値の変換の場合（値を変換するマイグレーションが中間）

同一カラムの形式を変える場合（平文 → ハッシュ等）は、変換を旧形式対応の除去より前に置く。

未適用マイグレーションを溜めないこと。複数溜まると種別が混ざり、この分割が 無意味になる。staging は main へのマージごとに自動適用されるので通常は溜まらないが、 production は手動 dispatch なので溜まりうる。

UNIQUE 追加時の重複検査

UNIQUE を追加するときは順序だけでは足りない。既存データに重複があると CREATE UNIQUE INDEX 自体が失敗し、migrate-only がそこで止まる。 デプロイ順序とは独立に、事前に実 SQL Server で重複を検査して解消しておく。

SELECT col_a, col_b, COUNT(*) AS dup
FROM dbo.some_table
GROUP BY col_a, col_b
HAVING COUNT(*) > 1;

EcAuth#521 では、b2b_user の (organization_id, external_id) を UNIQUE へ 戻す Down がまさにこれで失敗することを実測している。

The CREATE UNIQUE INDEX statement terminated because a duplicate key was found
for the object name 'dbo.b2b_user' and the index name
'IX_b2b_user_organization_id_external_id'. The duplicate key value is (2, DUP-HASH).

この Down は非一意で再作成する形に変更した。一意性を緩和した索引を Down で UNIQUE へ戻す設計は、機能が使われた後にこそ失敗するので避ける。

重複解消と制約追加を別マイグレーションに分けない。分けると、その間に流れるリクエストが リリース 1 のコード経由であっても、解消済みの重複を作り直す余地を残すことになる。 なお解消 SQL は DML なので EXEC() でラップする。

なぜ効くのか

効いているのは順序そのものではなく、データが変わる瞬間に、両形式を扱えるコードだけが動いている という状態である。

sequenceDiagram
    autonumber
    participant W as ワークフロー
    participant A as App Service
    participant D as Azure SQL

    Note over W,D: 危険な順序（値の変換を migrate-and-deploy で流す）
    W->>D: migrate（値を新形式へ変換）
    Note over A: まだ旧コード（再起動ラグ）
    A->>D: 旧形式で書き込み ← 不整合が生まれる
    W->>A: deploy（新コードへ）

    Note over W,D: 安全な形（リリース分割・削除の例）
    W->>A: リリース1 deploy（二重書き + 読みは新旧両対応）
    Note over A,D: 混在期間。二重書きなので旧インスタンスも読める
    W->>W: ロールアウト確認してから次をマージ
    W->>A: リリース2 deploy（旧構造への参照を完全に除去）
    Note over A,D: 動いているコードは旧構造を一切参照しない
    W->>W: ロールアウト確認してから次をマージ
    W->>D: リリース3 migrate（旧構造を削除）
    Note over A,D: 参照するコードがもう居ないので安全

リリース 1 のデプロイ中は App Service の再起動ラグで旧インスタンスが残るが、 二重書きしているので旧インスタンスも新規データを読める。リリース 3 の migrate が走るときには 旧構造を参照するコードがもう動いていない。

手順

追加のみの場合

既定のまま 1 回の workflow_dispatch で流す。

action=migrate-and-deploy, dry_run=false

削除・リネームの場合

リリースを分割し、各リリースは既定のまま流す。次のリリースをマージする前に、 前のリリースの deploy とロールアウト確認を必ず終わらせる。

リリース 1（expand: 二重書き + 読みは新旧両対応）を main へマージ
    → staging が自動で migrate-and-deploy
    → production: action=migrate-and-deploy, dry_run=false
    → ロールアウト完了を確認 ★ここを待たずに次をマージしない

リリース 2（transition: 旧構造への参照を完全に除去）を main へマージ
    → staging が自動で migrate-and-deploy（migration は無し）
    → production: action=migrate-and-deploy, dry_run=false
    → ロールアウト完了を確認 ★

リリース 3（contract: 旧構造の削除）を main へマージ
    → staging が自動で migrate-and-deploy（旧構造を参照するコードはもう居ない）
    → production: action=migrate-and-deploy, dry_run=false

値の変換の場合

マイグレーションが 2 段目に来る点が上と違う。取り違えると未変換行が残っている 間ずっと解決に失敗する。

リリース 1（compat: 新旧両形式を読め、新形式で書く）を main へマージ
    → staging が自動で migrate-and-deploy（migration は無し）
    → production: action=migrate-and-deploy, dry_run=false
    → ロールアウト完了を確認 ★

リリース 2（transform: 既存値の変換）を main へマージ
    → staging が自動で migrate-and-deploy（両形式を読めるコードが動いている）
    → production: action=migrate-and-deploy, dry_run=false
    → 変換完了とロールアウトを確認 ★

リリース 3（cleanup: 旧形式の読み取りを除去）を main へマージ
    → staging が自動で migrate-and-deploy（migration は無し）
    → production: action=migrate-and-deploy, dry_run=false

production 限定の追加ガード（任意）

分割したうえで、production ではさらに 2 回に分けて dispatch できる。データを触る前に ロールアウトを目視確認したい場合に使う。staging では上記のとおり成立しない。

1) workflow_dispatch: action=deploy-only,  dry_run=false
2) ロールアウト完了を確認（下記）
3) workflow_dispatch: action=migrate-only, dry_run=false

確認の目安:

• deploy ジョブが success で終わっている
• Azure Portal で当該 App Service のインスタンスがすべて新リビジョンになっている
• 起動ログ（AppServiceConsoleLogs）に新コード側の DbInitializer: Initialization completed が出ている

互換コードの設計

この方式は「新旧両対応コード」を一定期間生かす前提であり、 この互換コード自体がバグの温床になる。ただし表面積を絞りすぎても壊れる。

二重書きが生きている間は解決の一意性に注意する。旧構造は名前空間が粗いことが 多く、フォールバックを無条件に引くと別人に解決されうる。EcAuth#521 のレビュー指摘 4 件のうち 2 件がこれに該当した。

1. Organization 単位のフォールバックが、別発行元のユーザーを返してしまう （そこへ identity を足すと別人が 1 つの subject に恒久統合される）
2. 旧カラム側の衝突で 409 を返す際、先にコミット済みの identity 行が残り、 拒否したはずの subject に以降の解決が向く

フォールバック先は「まだ新構造で取得されていないレコード」に限定し、新構造への書き込みは 衝突判定を通してから行うこと。

実例

実例 1: 値の変換で事故が起きた（EcAuth#423）

B2BUser.external_id のハッシュ化対応。migrate 完了後〜アプリが新コードで 再起動完了するまでの窓で B2B パスキー登録リクエストが旧コードのインスタンスに処理され、 変換後 DB に plaintext の external_id が書き込まれた。

実顧客は無傷で、影響は使い捨て E2E ユーザー 1 件のみだった（削除 + 再デプロイで解消）。 ただし本番でこれが実顧客に当たれば、管理画面ログイン不能に直結する。

実例 2: 追加のみを deploy 先行にすると壊れる（EcAuth#521）

b2b_user_identity テーブルの新設。これを deploy-only 先行でやっていたら 本番が落ちていた。

• B2BUserService.CreateAsync が b2b_user_identity に INSERT する
• B2BUserService.GetByIdentityAsync が同テーブルを SELECT する
• SignupService も identity 行を作る

マイグレーション前にこのコードが動くと、B2B パスキー登録と申込のすべてが Invalid object name 'b2b_user_identity' で落ちる。

同じハザードは逆向きにも実在する。#521 では B2BPasskeySeeder が b2b_user_identity へ書くようになったのに RequiredMigration が 旧マイグレーション名のままで、「マイグレーションがデプロイに遅れた環境で表が無いまま INSERT に 到達し、起動初期化が落ちる」状態になっていた。シーダーが新しい表へ書くときは RequiredMigration をその表を作るマイグレーションへ更新する。

実例 3: 二重書きが生んだ不具合（EcAuth#521）

#521 は移行期間の安全網として b2b_user.external_id への書き込みを残した （二重書き）。レビューで見つかった 4 件の指摘のうち 2 件はこれに起因していた。

1. 旧カラムを Organization 単位で無条件にフォールバック検索していたため、発行元 B の リクエストに発行元 A のユーザーが返り、別人が 1 つの b2b_subject へ 恒久統合されうる
2. 旧カラム側の衝突で 409 を返す際、先にコミット済みの identity 行が残り、 拒否したはずの subject に以降の解決が向く

いずれも「旧カラムにも書き続けた」ことが前提の不具合で、読み取りだけの互換に留めていれば 発生しなかった。

チェックリスト

マイグレーションを含む PR を出すとき:

• このマイグレーションは判定表のどの行か。PR 説明に明記したか
• 値の変換 / 削除 / 制約強化なら、旧構造なしでも動くコードを別 PR で先にマージ したか（同じ PR に入れると staging がマージ時点で旧コード上に migrate してしまう）
• expand なら二重書きしているか。フォールバック先を「新構造で未取得のレコード」に 限定できているか
• 二重書きの新旧 2 か所を同一トランザクションで書いているか （別々にコミットすると片方だけ残る）
• 削除・リネームなら、旧構造への参照（ORM のマッピングを含む）を除去するリリースを contract の前に用意したか
• 削除・リネームなら、transition リリースに冪等な追いつき backfillを 含めたか（リリース 1 の backfill 後〜ロールアウト完了までの行を取りこぼすため）
• 値の変換なら、変換 SQL が旧形式の行だけを対象にしているか、 または冪等か（リリース 1 が書いた新形式を再変換すると壊れる）
• シーダーが新しい表へ書くなら RequiredMigration を更新したか
• 実 SQL Server で検証したか（InMemory プロバイダーは一意インデックスを強制しないため、 制約まわりは実 DB でしか確認できない）

デプロイするとき:

• 未適用マイグレーションを全部確認したか（前回デプロイから複数溜まっていることがある）
• 1 本でも値の変換 / 削除 / 制約強化が混ざっていれば、前段のリリースが本番で稼働完了して いるかを確認したか（削除・リネームなら transition リリースまで済んでいるか）
• 2 回 dispatch を使う場合、migrate-only の前にロールアウト完了を確認したか

残存リスク

この runbook は「分類し忘れ」を防げない。action の既定値は migrate-and-deploy であり、ルールが発動するのはデプロイする人が正しく分類したときだけ。 マイグレーションを書いた人とデプロイする人が別なとき、あるいは未適用マイグレーションが 複数溜まっているときに効いてくる。

機械的なガードを入れるなら、マイグレーションのファイル自身に種別を宣言させ、CI で宣言の 有無を検証し、migrate ジョブが未適用マイグレーションの宣言を読んで migrate-and-deploy を拒否する形が確実である。操作の内容から自動判定する （DropIndex や migrationBuilder.Sql の有無を見る）方式は採らないこと — EcAuth#521 は DropIndex（制約の緩和）と migrationBuilder.Sql（新表への backfill）の両方を含みながら実質は「追加のみ」であり、自動判定では誤って deploy 先行に 倒してしまう。種別は書いた人にしか判断できない。

関連

• EcAuthDocs#94 データ変換マイグレーションのデプロイ順序（旧コード稼働窓の排除）
• EcAuthDocs#110 B2B external_id を不変キー + 名前空間ベースの仕様に見直す
• EcAuth#423 B2BUser.external_id のハッシュ化（実例 1）
• EcAuth#521 B2B 識別子を b2b_user_identity へ分離（実例 2 / 3）