😊 はじめに

こんにちは。
私が開発とサーバー運用を担当している「XD.GROWTH」はPostgreSQLの分散拡張である Citus を利用してデータベースを水平分散しています。この記事では、Citus環境のバッチ処理で Distributed Deadlock（分散デッドロック）が頻発した際の 調査過程と最終的な対策 について、実運用で得られた知見を共有します。

ERROR: canceling the transaction since it was involved in a distributed deadlock

「同じレコードを更新しているわけでもないのに、なぜデッドロックが起きるんだ……？」と長らくモヤモヤしていたのですが、原因を腰を据えて追いかけてみたら、Citusのアーキテクチャに根差した分かりやすい構造でした。

対象読者は以下を想定しています。

PostgreSQL の運用経験がある方
Citus拡張を運用している、または導入を検討している方
分散デッドロックに悩まされている方

本記事のスコープ
本記事は Citus環境で起きるDistributed Deadlock の発生メカニズムと、アプリケーションロジックでの回避策 に焦点を当てています。Citusの基本的な仕組みやセットアップは扱いません。基本についてはCitus公式ドキュメントを参照してください。

⚙️ 動作環境（参考）

項目	バージョン
PostgreSQL	17.5
Citus	13.1.0

📦 起きていたこと

ざっくり以下のような状況です。

テーブル構成:
- profiles テーブル: ユーザーのプロファイル情報（PK: tenant_id, profile_id）
- profile_relations テーブル: プロファイルに紐づくセッション情報（PK: tenant_id, profile_id, session_id）
分散キー: 両テーブルとも profile_id で分散（co-located）
症状: 異なるテナントのバッチ処理を並列に実行すると、Distributed Deadlock が発生
規模感: 1バッチで10万〜200万件程度の更新

「テナントIDが違うから扱っているデータも違うはずなのに、何でぶつかるんだ？」というのが最初の疑問でした。

🧭 仮説と検証（紆余曲折）

最初はとっ散らかった仮説をいくつも立てては潰す、という時間を過ごしました。

❓ 仮説1: Workerでシャード単位のテーブルロックが取られているのでは？

「テナントが違ってもハッシュ衝突で同じシャードに同居して、シャードレベルのロックで競合しているのでは？」と疑いました。

結論: 外れ。
Citusのシャードは各Worker上では普通のPostgreSQLテーブルで、通常のDML（INSERT/UPDATE/DELETE）では RowExclusiveLock しか取りません。シャード全体を排他ロックするのはDDL・VACUUM FULL・リバランスなど特殊な操作だけです。

❓ 仮説2: FK制約による親テーブルへのロックでは？

結論: 外れ。
そもそもFK制約は張っていませんでした。

❓ 仮説3: 参照テーブル（reference table）への書き込みでは？

参照テーブルへの書き込みは全Workerに2PCで伝播するので、Distributed Deadlock の典型的な発生源です。

結論: 外れ。
マスタデータは別の仕組み（metadata管理）で持っていて、参照テーブルは使っていませんでした。

❓ 仮説4: `INSERT ... ON CONFLICT DO UPDATE` による競合では？

UPSERTはユニークインデックスのページレベルロックと行ロックの取得タイミングが入り組んでいて、デッドロックを生みやすいパターンです。

結論: 外れ。
INSERTは ON CONFLICT DO NOTHING を使っており、行ロックの保持時間が長くなる DO UPDATE は使っていませんでした。

❓ 仮説5: そもそも INSERT じゃなくて DELETE だった

実際のデッドロックログを再度よく見直したところ、エラーが出ていたのは INSERTではなくDELETE文 でした。

DELETE FROM profile_relations
WHERE tenant_id = $1 AND user_id <> $2 AND session_id = $3
RETURNING profile_id

「セッションIDに紐づいているリレーションのうち、今回のユーザーじゃないものを消す」というセッション乗り換え用の処理です。

ここから話が大きく動きました。

🔍 原因の特定：`EXPLAIN` が決定打

このDELETEを EXPLAIN してみたところ、決定的な情報が出てきました。

Custom Scan (Citus Adaptive)
  Task Count: 32
  Tasks Shown: One of 32
  -> Task
    Node: host=citus-worker1 ...
    -> Delete on profile_relations_<shard_id>
      -> Seq Scan on profile_relations_<shard_id>_<partition>
         Filter: ((user_id <> ...) AND (tenant_id = ...) AND (session_id = ...))

Task Count: 32 です。32シャード全てに対して並列にDELETEが発行されている ことが分かりました。

🛠️ なぜそうなるのか

このテーブルの分散キーは profile_id です。ところがDELETEのWHERE句を見ると：

WHERE tenant_id = $1 AND user_id <> $2 AND session_id = $3

分散キー profile_id の条件が含まれていません。Citusはどのシャードに対象データがあるか判定できないため、全シャードにクエリを投げにいくしかない、というわけです。

つまり「1バッチ = 1テナント」というトランザクション設計でも、そのトランザクション自体が全Workerに跨る 構造になっていました。

ハマりポイント
Citusの分散テーブルでは、分散キーがWHERE句に含まれていないクエリ、および分散キーに対して <>、>、<、LIKE、NOT IN などの 非等価演算子 を使うクエリは、シャードプルーニングが効きません。今回は前者のパターン（分散キー自体がWHEREに無い）でした。

❗ Distributed Deadlock が成立するメカニズム

これが分かれば、デッドロックの発生メカニズムは単純です。

テナントAのバッチが32シャード全てに書き込みロックを取りに行く
テナントBのバッチも32シャード全てに書き込みロックを取りに行く
各Worker上で、AとBがロック取得順を逆転させると待ち合いが発生する
待ち合いがWorker跨ぎで循環すると、PostgreSQL本体の検出器（単一インスタンス内しか見ない）では検出できない
CitusのCoordinator側で動いている Distributed Deadlock Detector が循環を発見し、トランザクションをキャンセル

「テナントが違うのにデッドロック」の正体は、「テナントごとのトランザクションが全Workerに跨っていて、それが並列に走るとぶつかる」という構造でした。

📐 設計背景：なぜ `profile_id` 分散なのか

「じゃあテナントID分散にすれば？」という案が当然浮かびます。が、こちらは過去に検討済みで、却下した経緯があります。

データスキューがひどい: 大規模テナントのデータが特定シャードに集中してホットスポット化
SELECT性能が出ない: テナント単位のクエリが単一Workerに集中して捌けない

profile_id 分散は、

データがほぼ均等に分散される
プロファイル単位のクエリ（最頻アクセス）が高速

というメリットがある反面、「セッションID起点の検索など、分散キーが指定できないクエリがマルチシャード化する」というデメリットを抱えています。今回のDELETEはまさにそのデメリットが顕在化したケースでした。

つまり、分散キー設計そのものを変えるのではなく、問題のクエリを工夫してこのデメリットを軽減する、という方向で対策を考えます。

✅ 対策：二段階処理への書き換え

採用したのは「先にSELECTで対象 profile_id を取得し、それを明示してDELETEする」という二段階処理です。

Before（マルチシャードDELETE）

DELETE FROM profile_relations
WHERE tenant_id = $1 AND user_id <> $2 AND session_id = $3
RETURNING profile_id

After（二段階処理）

-- ステップ1: 対象 profile_id を取得（読み取り専用なので長期ロックを取らない）
SELECT profile_id FROM profile_relations
WHERE tenant_id = $1 AND user_id <> $2 AND session_id = $3;

-- ステップ2: 取得した profile_id を分散キーに含めてDELETE
DELETE FROM profile_relations
WHERE profile_id = ANY($1::bigint[])
  AND tenant_id = $2
  AND user_id <> $3
  AND session_id = $4
RETURNING profile_id;

ポイントは以下の2点です。

profile_id = ANY(...) は シャードプルーニング可能 な形なので、対象シャードだけにDELETEが発行される
ステップ1はSELECTなので、長期の書き込みロックを取らず、デッドロックの起点になりにくい

🔐 `SELECT ... FOR UPDATE` を付けないことについて

「ステップ1とステップ2の間に他のトランザクションが割り込んだらどうする？」という疑問があるかもしれません。が、本ケースでは FOR UPDATE は 付けていません。理由は以下です。

Citusの SELECT ... FOR UPDATE には制約がある。シングルシャードクエリでは動きますが、マルチシャードクエリでは制限があり、本ケース（マルチシャードSELECT）では使えないか挙動が読みにくい
ステップ2のDELETEでWHERE条件が再評価されるので、SELECT〜DELETE間に状態が変わっても、DELETEは現在の状態に基づいて正しく動く
ユースケース的に二重実行や微妙な競合の害が小さい（セッション乗り換え処理は冪等的に振る舞える）

排他制御をどうしても入れたい場合は、Citusの制約と無関係に動く pg_advisory_xact_lock を使うのが現実的かなと思います。

📊 効果の検証

実際に書き換えて EXPLAIN を取り直したところ、

Task Count が SELECT で取得したレコード数と一致する

ようになりました。本ケースでは通常1〜5件しか対象がないので、Task Count も1〜5です。

指標	Before	After
Task Count	32（固定）	1〜5（対象件数に比例）
ロック取得シャード数	32	1〜5
並列バッチ間の競合確率	ほぼ100%	(5/32)² ≈ 2.4% 程度
スキャン範囲	全シャード × 全パーティション	該当シャードの該当パーティションのみ

並列バッチが同じシャードを取り合う確率が劇的に下がるので、Distributed Deadlock は実用上ほぼ起きなくなる見込みです。レイテンシも改善が期待できます。

🛡️ 既存の緩和策との位置づけ

書き換え前から、運用上の応急処置として以下を入れていました。

バッチの並列実行数を起動時に制御（並列1〜2に抑制）
デッドロック発生時の自動リトライ

これらは書き換え後も 安全ネットとして残す のがおすすめです。書き換えで根本対応はできますが、想定外のケースで何かが起きたときの保険として機能します。書き換え後はリトライがほぼ発動しなくなるはずなので、メトリクスとして観測しておくと 改善効果の可視化 にも使えます。

📌 まとめ

今回の調査を通じての学びです。

エラーメッセージで distributed deadlock と明記されている場合、必ず複数Workerに跨る操作が含まれている。「1テナント1トランザクションだから単一Workerのはず」と思い込まずに、クエリが分散キーで絞れているかを疑いましょう。
分散キーがWHERE句に無いクエリ・非等価演算子を使うクエリは要警戒。これらはハッシュ分散テーブルではシャードプルーニング不能です。
シャードプルーニングの効きは EXPLAIN の Task Count で必ず確認できます。Task Count: 1 ならシングルシャード、それ以外はマルチシャードです。
分散キー設計はトレードオフ。どの設計を選んでも代償はあるので、代償が顕在化したクエリをアプリケーションロジックの工夫で軽減する、というアプローチが現実的です。

Citusは強力ですが、PostgreSQL単体とは違う考え方が必要な場面が確かにあります。同じような事象に遭遇された方の助けになれば嬉しいです。

最後まで読んでいただきありがとうございました
Citus運用での Distributed Deadlock 対策について、この記事が参考になれば幸いです。