相乗りキーの設定行をロック無しで読んで→マージして→書くと、同時保存でキーが消える

結論

1つのJSONB行に複数の設定キーを相乗りさせ、「既存値を読む→スプレッドでマージする→丸ごと書き戻す」upsertを書くとき、その読み取りをSELECT ... FOR UPDATEで行ロックしていなければ、並行更新と競合したときに相手が直前に書いたキーごと上書きして消す。 行ロックを足すだけで直る。

症状になりうる状態

学校ごとの表示設定を持つschool_configsテーブルには、scope='school', kind='display_settings'の行が1行あり、そのvalue列（JSONB）に複数の設定キーが相乗りしていた。

• assignmentDeadlineFormat（提出物の期日表示形式。“daysLeft” か “until”）
• signageDesign（学校既定のサイネージデザイン）
• editorDayCutover（エディタの既定対象日を切り替える時刻）

school_configsのvalueはupsertで列ごと全置換になる。1つのキーだけを変えたい保存Actionでも、他の2キーを消さないためには、保存前に既存のvalueを読んでオブジェクトにスプレッドし、変更したいキーだけ差し替えてから書き戻す必要がある。

const prev = await lockDisplaySettingsValue(tx);
const base =
  prev && typeof prev === "object" && !Array.isArray(prev)
    ? (prev as Record<string, unknown>)
    : {};

const id = await upsertSchoolConfig(tx, {
  schoolId: actor.schoolId,
  kind: "display_settings",
  value: { ...base, assignmentDeadlineFormat: rawFormat },
  actorUserId,
});

この形自体は問題なく見える。だがlockDisplaySettingsValueが行ロック無しの素のSELECTだった場合、次の順序で並行更新が起こりうる。

1. トランザクションA（assignmentDeadlineFormatを保存）が既存値{signageDesign: "pattern2", editorDayCutover: "15:30"}を読む
2. ほぼ同時にトランザクションB（/opsの生JSON編集などでsignageDesignを保存）が同じ既存値を読む
3. Aが{signageDesign: "pattern2", editorDayCutover: "15:30", assignmentDeadlineFormat: "until"}でUPSERTしてコミット
4. Bが自分が読んだAのコミット前の値をもとに{signageDesign: "pattern3", editorDayCutover: "15:30"}でUPSERTしてコミット

Bの書き込みにはAが足したassignmentDeadlineFormat: "until"が含まれていない。BのUPSERTはvalue列を丸ごと置き換えるため、Aが直前に保存した設定はテーブル上から消える。どちらの保存も単体で見れば正しく成功しており、エラーは一切出ない。

原因

read-merge-write（読んでスプレッドしてから書き戻す）というパターンそのものは、1つの行に複数のキーを相乗りさせて部分更新を模倣する以上、避けにくい。問題は、この「読む」の時点で行をロックしていなかったことにある。

行ロックを伴わない読み取りは、2つのトランザクションに同じ既存値を見せてしまう。両者は互いの存在を知らないまま、それぞれ正しい差分を計算し、それぞれ正しくUPSERTを実行する。しかし後にコミットした側が、先にコミットした側の変更を含まない値で行全体を上書きする。これはSQLレベルでは制約違反でも何でもなく、静かに成立してしまうlast-writer-winsの事故で、アプリケーションのログにもDBのエラーログにも痕跡が残らない。

直し方

既存値の読み取りを、同一トランザクション内のSELECT ... FOR UPDATEに変えた。

async function lockDisplaySettingsValue(tx: TenantTx): Promise<unknown | null> {
  const [row] = await tx
    .select({ value: schoolConfigs.value })
    .from(schoolConfigs)
    .where(and(eq(schoolConfigs.scope, "school"), eq(schoolConfigs.kind, "display_settings")))
    .limit(1)
    .for("update");
  return row ? row.value : null;
}

行ロックを取ると、後から同じ行を読もうとするトランザクションは、先行トランザクションがコミット（またはロールバック）してロックを解放するまでブロックされる。PostgreSQLのデフォルト分離レベル（READ COMMITTED）では、ロック解放後の読み取りは最新のコミット済み値を返すため、後発のトランザクションは必ず先行トランザクションが書いたキーを含んだ状態からマージを始められる。これで2つの保存は事実上直列化され、どちらのキーも欠落しない。

行がまだ存在しない場合（初回保存でINSERTになる場合）はロック対象自体が無い。この経路の同時実行は行ロックでは防げないが、対象にはux_school_configs_targetのユニーク制約とonConflictDoUpdateを使ったupsertが別途あり、そちらが一意性を保証する。行ロックが効くのは「既に行があり、その値を読んでマージする」2回目以降の保存からになる。

再発防止

このパターンは、display_settingsと同じように「1行に複数の設定キーを相乗りさせ、read-merge-writeで部分更新する」他のテーブルにも当てはまる。読み取りをFOR UPDATEにする対応自体は既存のlockAndCountActiveSchoolAdminsと同じ作法で揃えており、新しい仕組みを持ち込んだわけではない。

同じ行に複数のキーを相乗りさせる設計を選ぶ以上、「読んでマージして書く」経路には必ずこの並行更新ロストのリスクが伴う。read-merge-write を書くたびに、その読み取りが行ロックを伴っているかを確認する価値がある。