Transactional Outboxパターン｜二重書き込みの再現と実装・実測

登場人物は3つです。業務トランザクションの中で outbox に書く「書き手」、outbox を読んで配送し配送済みの印を付ける「リレー」、同じイベントが2回届いても結果が変わらない「冪等なコンシューマ」です。

flowchart TD
    A[アプリ] -->|1つのトランザクション| T[(orders + outbox)]
    T -->|SKIP LOCKED で取り出す| R[リレー]
    R -->|HTTP / Redis Stream| C[コンシューマ]
    R -.->|published_at を付ける| T
    C -->|event_id で重複を捨てる| P[(processed_events)]

よく調べられることの答えを先にまとめます。

確認環境：Ubuntu 24.04.5 LTS（2 CPU・メモリ 8GB の共用機）の上で、PostgreSQL 16.15 を自分の作業領域に initdb して 127.0.0.1 のポートに起動し、データベース t242db に注文テーブル・outbox テーブル・コンシューマ用スキーマを作りました。アプリ・リレー・配送先はすべて Python 3.13.18 と psycopg 3.3.7 で書き、配送先は 127.0.0.1 の自作 HTTP サーバー（標準ライブラリの http.server）と、自分で起動した Redis 7.0.15 の Stream（redis-py 8.1.0）です。プロセスの停止は os._exit(1) で再現し、遅延・件数は PostgreSQL 側の clock_timestamp() と pg_stat_database で数えています。Kafka と Debezium はこの環境で動かしていないため、Debezium の Outbox Event Router と Kafka の順序の話は公式ドキュメントで確かめた範囲だけを書いています。パターンの定義は microservices.io と AWS Prescriptive Guidance、NOTIFY の動作は PostgreSQL 16 の公式マニュアルで確かめました。図は mermaid 11.16.0 で描画を確かめています（確認日 2026年11月4日）。

二重書き込み問題を再現する（DB更新とメッセージ送信を別々に行うと何が壊れるか）

この節では、「注文を INSERT して、出荷サービスに HTTP で通知する」という素朴な実装が、どの瞬間に落ちるとどう壊れるかが、実際の件数で分かります。

DB とメッセージ基盤は別のシステムなので、両方への書き込みをまとめて成功・失敗させる手段がありません。 これが二重書き込み（dual write）問題です。microservices.io は「データベースとメッセージブローカーにまたがる従来の分散トランザクション（2PC）は現実的でない」と書いています。送る順番を入れ替えても解決しないことを、5つの経路で確かめました。

with psycopg.connect(DSN) as conn:
    cur = conn.cursor()
    cur.execute("INSERT INTO orders(customer_id, amount) VALUES (%s, 1200) RETURNING id", (customer,))
    order_id = cur.fetchone()[0]
    conn.commit()
    if scenario == "crash-after-commit":
        os._exit(1)                 # COMMIT の直後、送信の前に落ちる
    send(order_id)                  # 出荷サービスへ POST /events

配送先は「届いたぶんだけ出荷指示を作る」素朴なコンシューマです。5つのシナリオを1回ずつ流した結果が次の表です。

集計すると、注文は3件、出荷指示も3件で「件数は合っている」のに、中身を突き合わせると存在しない注文の出荷が2件、出荷されない注文が2件でした。

 orders | shipments | ghost_shipments | orders_without_shipment
--------+-----------+-----------------+-------------------------
      3 |         3 |               2 |                       2

接続できなかったときの原文はこうです。アプリは例外を呼び出し元に返しますが、注文はすでに COMMIT されています。利用者は「失敗した」と思って再注文し、注文が2件になる経路でもあります。

urllib.error.URLError: <urlopen error [Errno 111] Connection refused>

Transactional Outbox パターンとは（仕組みと登場人物）

この節では、パターンの定義と、3つの登場人物がそれぞれ何に責任を持つかが分かります。

microservices.io の定義では、「業務エンティティを更新するトランザクションの中でメッセージをデータベースに保存し、別のプロセス（Message relay）がそれをブローカーへ送る」のが Transactional Outbox です。 利点として「2PC を使わない」「データベーストランザクションがコミットされたとき、そのときに限ってメッセージが送られることが保証される」、欠点として「開発者が outbox への書き込みを忘れうる」ことが挙げられています。AWS Prescriptive Guidance も同じ構造を「dual write 問題を解決するパターン」として説明しています。

保証の中身を言葉にすると、「コミットされた業務変更に対応するイベントは、いつか必ず、1回以上配送される」です。「ちょうど1回」ではありません。microservices.io は「Message relay はメッセージを2回以上発行しうる」「メッセージコンシューマは冪等でなければならない」と明記しており、この記事の後半で実際に重複を起こして確かめます。

outbox テーブルの設計と同一トランザクションでの書き込み

この節では、outbox テーブルの列と部分インデックスの設計、アプリ側の書き方、ROLLBACK とプロセス停止で outbox にも何も残らないことの確認結果が分かります。

outbox は「イベントの封筒」を入れる表です。 列は Debezium の Outbox Event Router が期待する形（id・aggregatetype・aggregateid・type・payload）に寄せておくと、後でポーリングから CDC に替えるときに表を作り直さずに済みます。

CREATE TABLE outbox (
  id              bigserial   PRIMARY KEY,
  event_id        uuid        NOT NULL DEFAULT gen_random_uuid(),  -- 冪等キー
  aggregate_type  text        NOT NULL,   -- 例: orders（トピック名の元）
  aggregate_id    text        NOT NULL,   -- 例: 注文ID（順序を守る単位）
  event_type      text        NOT NULL,   -- 例: OrderCreated
  payload         jsonb       NOT NULL,
  created_at      timestamptz NOT NULL DEFAULT clock_timestamp(),
  published_at    timestamptz,            -- NULL = 未配送
  attempts        integer     NOT NULL DEFAULT 0,
  next_attempt_at timestamptz NOT NULL DEFAULT clock_timestamp(),
  last_error      text
);
-- 未配送の行だけを持つ部分インデックス
CREATE INDEX outbox_unpublished_idx ON outbox (id) WHERE published_at IS NULL;

部分インデックスの効き目（配送済み20万行・未配送50行）

配送済みの行が20万件たまった状態で、リレーの取り出しクエリを EXPLAIN (ANALYZE, BUFFERS) しました。部分インデックスは 16kB で、取り出しは 0.1ms です。同じ表でインデックスを落とすと、20万行を読み飛ばす Seq Scan になり 34ms・7,979 ブロックでした。

-- 部分インデックスあり
 Limit (actual time=0.024..0.073 rows=50 loops=1)   Buffers: shared hit=60
   ->  LockRows
         ->  Index Scan using outbox_unpublished_idx on outbox (rows=50)
 Execution Time: 0.103 ms

-- 部分インデックスなし
 Limit (actual time=34.187..34.225 rows=50 loops=1)   Buffers: shared hit=7979
   ->  LockRows -> Sort (Sort Key: id)
         ->  Seq Scan on outbox (rows=50)   Rows Removed by Filter: 200000
 Execution Time: 34.261 ms

アプリ側は「同じ conn.transaction() の中で2つ INSERT する」だけ

def create_order(conn, customer_id):
    with conn.transaction():          # 1つのトランザクション
        cur = conn.cursor()
        cur.execute("INSERT INTO orders(customer_id, amount) VALUES (%s, 1200) RETURNING id", (customer_id,))
        order_id = cur.fetchone()[0]
        cur.execute("""INSERT INTO outbox(aggregate_type, aggregate_id, event_type, payload)
                       VALUES ('orders', %s, 'OrderCreated', %s)""",
                    (str(order_id), Jsonb({"order_id": order_id, "amount": "1200"})))
        return order_id                # ここで COMMIT。送信はしない

ROLLBACK すると両方消えることを psql で確かめました。

BEGIN;
INSERT INTO orders(customer_id, amount) VALUES (7, 980) RETURNING id;          -- id = 1
INSERT INTO outbox(aggregate_type, aggregate_id, event_type, payload)
  VALUES ('orders', '1', 'OrderCreated', '{"order_id": 1}') RETURNING id, event_id;  -- id = 1
ROLLBACK;
SELECT (SELECT count(*) FROM orders) AS orders, (SELECT count(*) FROM outbox) AS outbox;
 orders | outbox
--------+--------
      0 |      0

COMMIT の前に os._exit(1) でプロセスを落とした場合も同じで、orders も outbox も 0 件でした。二重書き込みで起きていた「存在しない注文の通知」は、この時点で起こりえなくなります。

ポーリング・リレーの実装（FOR UPDATE SKIP LOCKED・バッチ・再試行）

この節では、リレーの取り出しクエリと1ループの流れ、配送先が 500 を返したときの再試行とバックオフの実物が分かります。

取り出しは「未配送・再試行時刻を過ぎている・上限回数未満」の行を id 順に LIMIT 件、FOR UPDATE SKIP LOCKED でロックして行います。 PostgreSQL の公式マニュアルは SKIP LOCKED を「複数のコンシューマがキューのような表にアクセスするときのロック競合を避けるために使える」と説明しています。ロックはトランザクションの中だけ有効なので、リレーが途中で落ちても行は自動的に解放され、「取り出し中のまま残った行を回収する」仕組みが要りません。

SELECT id, event_id, aggregate_type, aggregate_id, event_type, payload
  FROM outbox
 WHERE published_at IS NULL
   AND next_attempt_at <= clock_timestamp()
   AND attempts < 5
 ORDER BY id
 LIMIT 100
 FOR UPDATE SKIP LOCKED;

配送先に「次の3リクエストだけ 500 を返す」よう仕込んで、イベント2件を流したログと outbox の状態です。

[relay 0] outbox id=1 failed: HTTP Error 500: Internal Server Error
[relay 0] outbox id=2 failed: HTTP Error 500: Internal Server Error
[relay 0] outbox id=1 failed: HTTP Error 500: Internal Server Error
[relay 0] exit. sent_total=2

 id | attempts |              last_error               | published_at | next_attempt_at
----+----------+---------------------------------------+--------------+-----------------
  1 |        3 | HTTP Error 500: Internal Server Error | 03:36:57.129 | 03:36:56.991
  2 |        2 | HTTP Error 500: Internal Server Error | 03:36:56.602 | 03:36:56.536

id=1 は 200ms・400ms 待って3回目で届き、id=2 は 200ms 待って2回目で届きました。attempts < 5 を超えた行は取り出し対象から外れ、そのまま「配送できなかったイベントの一覧」（デッドレター）になります。SELECT * FROM outbox WHERE published_at IS NULL AND attempts >= 5 を監視に載せ、原因を直してから UPDATE outbox SET attempts = 0 で戻すのが運用の形です。

少なくとも1回配送になる理由（リレーのクラッシュを再現）

この節では、「送った後・印を付ける前」にリレーが落ちると何が起きるかを、実際の受信ログで確かめた結果が分かります。

配送と published_at の更新は別システムへの2操作なので、ここにも小さな二重書き込みがあります。 ただし壊れ方は一方向で、「送ったのに未配送のまま残る → もう一度送る」にしかなりません。「送っていないのに配送済みになる」は、UPDATE を配送の後に置く限り起きません。

イベント5件に対し、3件送ったところでリレーを os._exit(1) で落とし、再起動しました。

[relay 0] sent 3 events, crashing BEFORE marking published
 id | aggregate_id | published
----+--------------+-----------
  2 | 2            | f
  3 | 3            | f          ← 3件送ったが、印は1件も付いていない
  4 | 4            | f
  5 | 5            | f
  6 | 6            | f
[relay 0] exit. sent_total=5     ← 再起動後は5件すべてを送る

素朴なコンシューマ（届いたぶんだけ出荷指示を作る）の受信ログと出荷指示です。

 seq | order_id | outbox_id | received_at
-----+----------+-----------+--------------
   1 | 2        |         2 | 03:36:44.273
   2 | 3        |         3 | 03:36:44.279
   3 | 4        |         4 | 03:36:44.284
   4 | 2        |         2 | 03:36:44.479   ← 再送
   5 | 3        |         3 | 03:36:44.485   ← 再送
   6 | 4        |         4 | 03:36:44.490   ← 再送
   7 | 5        |         5 | 03:36:44.497
   8 | 6        |         6 | 03:36:44.502

 order_id | shipments
----------+-----------
 2        |         2   ← 二重出荷
 3        |         2
 4        |         2
 5        |         1
 6        |         1

注文2・3・4が二重に出荷されました。これは outbox パターンの欠陥ではなく、パターンが約束しているのは「少なくとも1回」であり、重複を消す責任は受け手にあるという設計の分担です。AWS のガイドも「イベント処理サービスは重複したメッセージを送りうるので、処理済みメッセージを記録して消費側を冪等にすることを推奨する」と書いています。

冪等なコンシューマの作り方（冪等キーと処理済みテーブル）

この節では、event_id を主キーにした処理済みテーブルで重複を捨てる実装と、同じ再送シナリオで二重出荷が0件になった結果が分かります。

要点は、「処理済みの記録」と「副作用」を受け手側の1つのトランザクションに入れることです。 記録だけ先に COMMIT すると、副作用の前に落ちたときにそのイベントが永久に処理されません。

CREATE TABLE consumer.processed_events (
  event_id     uuid PRIMARY KEY,
  processed_at timestamptz NOT NULL DEFAULT clock_timestamp()
);

with psycopg.connect(DSN) as conn, conn.transaction():
    cur = conn.cursor()
    cur.execute("INSERT INTO consumer.processed_events(event_id) VALUES (%s) ON CONFLICT DO NOTHING",
                (body["event_id"],))
    if cur.rowcount == 0:                 # 既に処理済み → 副作用を起こさず 200 を返す
        return self._reply(200, {"result": "duplicate-ignored"})
    cur.execute("INSERT INTO consumer.shipments(order_id, event_id) VALUES (%s,%s)",
                (body["aggregate_id"], body["event_id"]))
# ここで COMMIT。記録と副作用が一緒に確定する

同じ「3件送って落とす → 再起動」を、このコンシューマで繰り返した結果です。

 http_received | distinct_events
---------------+-----------------
             8 |               5      ← HTTP は8回届いた

 order_id | shipments
----------+-----------
 1        |         1
 2        |         1      ← 出荷指示はすべて1件
 3        |         1
 4        |         1
 5        |         1

重複に 200 を返しているのも意図的です。4xx や 5xx を返すと、リレー側は失敗とみなして再試行を続けます。受け手にとって「もう済んでいる」は成功です。

• 1冪等キーは送り手が採番するoutbox の event_id（uuid）をそのまま使う。受信側で生成すると再送を見分けられない
• 2処理済みの記録と副作用を同じトランザクションに副作用が外部 API（メール送信など）なら、先に記録して COMMIT → 送信 → 失敗時は記録を消す、の順を設計する
• 3重複には 200 を返すエラーを返すとリレーが再試行し続け、デッドレターに溜まる
• 4処理済み表にも保持期間を決めるoutbox 側の再送は数分〜数時間以内に収まる。processed_at を基準に期限切れの行を消す

冪等キーの設計そのものは、関連記事「冪等性とは？二重課金を防ぐ冪等キーとリトライ設計」で扱っています。受け手が Webhook のときの署名検証と再試行は、関連記事「Webhookとは？実装までわかる｜署名検証・リトライ・冪等性を実行ログで解説」で扱っています。

順序保証とパーティション（複数リレーで順序が崩れる実測）

この節では、リレーを2つ・4つに増やすと同じ注文のイベントの順序がどれだけ崩れるか、aggregate_id でパーティションすると 0 になること、配送失敗時の順序の守り方が分かります。

リレーが1つなら ORDER BY id で outbox に入った順に送られます。2つ以上にすると、SKIP LOCKED は「互いに違う行」を取るだけで、同じ注文の1件目と2件目が別のリレーに渡り、後のリレーが先に届けることがあります。 300注文 × 3イベント（OrderCreated → OrderUpdated2 → OrderUpdated3）を流し、受信側で「同じ注文の中で outbox_id が戻った回数」を数えました。

パーティションは取り出しクエリに1条件を足すだけです。ワーカー i（全 N）は自分の担当の集約だけを取ります。

  AND abs(hashtext(aggregate_id)) % 4 = 1     -- 4ワーカー中の1番

所要時間は 2 CPU の共用機でコンシューマ（リクエストごとに DB 接続）が頭打ちになっており、リレーを増やしても1割ほどしか速くなりませんでした。順序を守りたいなら、まずリレー1つで間に合うかを測り、増やすときは集約でパーティションする、が判断の順です。Kafka に配送する場合は、Debezium の Outbox Event Router が aggregateid をメッセージのキーに使い、同じ集約のイベントが同じパーティション内で順序を保つように設計されています（公式ドキュメント）。

配送に失敗したときの順序

リレー1つでも、1件目の配送が失敗して再試行待ちになる間に2件目が送られると順序が崩れます。「同じ集約に、自分より前の未配送の行があれば取り出さない」条件を足すと守れます。

  AND NOT EXISTS (SELECT 1 FROM outbox o2
                   WHERE o2.aggregate_id = outbox.aggregate_id
                     AND o2.published_at IS NULL AND o2.id < outbox.id)

注文1の1件目だけ 500 にして流した受信順です。条件なしでは注文1の2・3件目が先に届き、条件ありでは注文2を先に進めつつ注文1は1→2→3の順で届きました。

条件なし : order1#2 , order1#3 , order2#1 , order2#2 , order2#3 , order1#1
条件あり : order2#1 , order2#2 , order2#3 , order1#1 , order1#2 , order1#3

この条件は「1件詰まると、その集約の後続が全部止まる（head-of-line blocking）」ことと引き換えです。順序が要らないイベント（通知メールなど）には付けないのが設計判断です。

配送遅延とスループットの実測（ポーリング間隔・LISTEN/NOTIFY・バッチ）

この節では、COMMIT から配送先に届くまでの遅延がポーリング間隔でどう変わるか、LISTEN/NOTIFY でどこまで縮むか、バッチサイズで処理量がどう変わるかが分かります。

ポーリングの遅延は「間隔の半分が中央値、間隔が最大」になります。 200ms おきに注文を40件作り、received_at − outbox.created_at を集計しました。

NOTIFY は outbox への INSERT に文（statement）単位のトリガーを付けるだけです。PostgreSQL の公式マニュアルは「トランザクションの中で実行された NOTIFY は、そのトランザクションがコミットされるまで、そしてコミットされた場合に限って配信される」と書いています。つまりリレーは未コミットの行を取りに行って空振りすることがなく、同じトランザクション内の同一チャネル・同一ペイロードの通知は1つにまとめられます。

CREATE FUNCTION outbox_notify() RETURNS trigger LANGUAGE plpgsql AS $$
BEGIN PERFORM pg_notify('outbox_new', ''); RETURN NULL; END $$;
CREATE TRIGGER outbox_notify_trg AFTER INSERT ON outbox
  FOR EACH STATEMENT EXECUTE FUNCTION outbox_notify();

conn = psycopg.connect(DSN, autocommit=True)
conn.execute("LISTEN outbox_new")
while True:
    if poll_once(conn) == 0:                      # 0件なら通知を待つ（上限 1 秒で念のため再確認）
        for _ in conn.notifies(timeout=1.0, stop_after=1):
            pass

NOTIFY だけに頼らず予備のポーリングを残すのは、リレーが再接続した直後など LISTEN していない間の通知は届かないためです。イベントが来ない10秒間に発行されたトランザクション数は、100ms ポーリングで約100回、NOTIFY 待ち（予備1秒）で約10回でした。

バッチサイズと処理量

1万件を Redis Stream に配送したときの所要と、HTTP 配送の比較です。バッチを1件にすると、1件ごとに SELECT … FOR UPDATE と UPDATE と COMMIT が走るぶん遅くなります。

HTTP が遅いのは配送先がリクエストごとに DB へ接続する作りだからで、パターンの差ではありません。ただしバッチを大きくするほど「送ったのに印が付かないまま落ちる」ときの再送件数も大きくなります。100 前後で頭打ちになるので、それ以上は増やす理由がありません。

Redis Stream へ配送する（XADD・コンシューマグループ・XPENDING）

この節では、配送先を HTTP から Redis Stream に替えたときのリレーの差分と、ブローカー側でも「少なくとも1回」が前提になっていることが分かります。

リレー側の差分は deliver() の中身だけです。 ストリーム名は Debezium の既定（outbox.event.<aggregatetype>）に合わせました。

R.xadd(f"outbox.event.{aggregate_type}",
       {"event_id": str(event_id), "aggregate_id": aggregate_id,
        "event_type": event_type, "payload": json.dumps(payload), "outbox_id": outbox_id})

$ redis-cli -p 64242 XLEN outbox.event.orders
3
$ redis-cli -p 64242 XRANGE outbox.event.orders - + COUNT 1
1793731446400-0
event_id      a283ea7f-77f4-49ca-b391-ed533a0cfa9d
aggregate_id  1
event_type    OrderCreated
payload       {"seq": 1, "amount": "1200", "order_id": 1}
outbox_id     1

コンシューマグループで読み、ACK せずにワーカーが落ちた状況を作ると、保留（pending）に残り、別のワーカーが XAUTOCLAIM で引き取ります。ここでも同じイベントが2つのワーカーに届きうるので、受け手の冪等キーは変わらず必要です。

$ redis-cli -p 64242 XGROUP CREATE outbox.event.orders shipping 0
$ redis-cli -p 64242 XREADGROUP GROUP shipping worker-1 COUNT 2 STREAMS outbox.event.orders '>'
...（2件届く。worker-1 は XACK せずに落ちたとする）
$ redis-cli -p 64242 XPENDING outbox.event.orders shipping
2  1793731446400-0  1793731446400-1  worker-1 2
$ redis-cli -p 64242 XAUTOCLAIM outbox.event.orders shipping worker-2 0 0-0 COUNT 10
...（worker-2 が同じ2件を受け取る）
$ redis-cli -p 64242 XINFO GROUPS outbox.event.orders
name shipping / consumers 2 / pending 2 / lag 1

Kafka に配送する場合の手順は、関連記事「Kafka入門｜KRaftでトピック作成から消費まで最短手順」で扱っています。SQS（標準キューは少なくとも1回配信）に配送するときの可視性タイムアウトとの関係は、関連記事「Amazon SQSの使い方｜送受信・削除と可視性タイムアウト、FIFO」で扱っています。

よくある落とし穴（シーケンスの穴・ロックの保持・ペイロードの肥大）

この節では、動いているように見えて取りこぼしや遅延を生む設計と、その再現結果・直し方が分かります。

いちばん見つけにくいのは「最後に見た id より大きい行を取る」方式の取りこぼしです。 bigserial の値は INSERT 時に確定し、COMMIT の順とは一致しません。2つのセッションで再現しました。

A inserted id=41 (uncommitted), B inserted id=42 (committed)
watermark relay sees: [42]                      ← last = 42 に進めてしまう
A committed id=41
watermark relay (id > 42) sees: []  <- id 41 is never delivered
published_at IS NULL relay sees: [41, 42]       ← 印で判定すれば拾える

「取り出し中」を UPDATE で記録する方式（claimed_at）と、トランザクション内ロックで持つ方式（この記事）の選び方は次のとおりです。

分散システム全般の再試行と冪等性の落とし穴は、関連記事「分散システムの落とし穴8選｜冪等性・リトライ・CAP定理」で扱っています。

outbox の掃除（DELETE と dead tuple・VACUUM・パーティション）

この節では、配送済みの行を DELETE したときに表の大きさがどうなるか、VACUUM と VACUUM FULL の違い、日次パーティションを DROP する方式の速さが、20万行の実測で分かります。

DELETE は行を「死んだ行（dead tuple）」にするだけで、表のファイルは縮みません。 配送済み20万行（62MB）を消して確かめました。

流量が一定なら、「配送済みを定期的に DELETE し、autovacuum に任せる」で表の大きさは一定に保たれます。VACUUM が末尾を切り詰められないのは、未配送の新しい行がファイルの末尾にあるためで、通常の運用では VACUUM FULL は要りません。問題になるのは、掃除を止めていた期間に膨らんだ表を戻したいときだけです。

パーティションで DROP する

流量が多いなら、created_at の日次 RANGE パーティションにして、保持期間を過ぎたパーティションを DETACH → DROP します。20万行（52MB）のパーティションを落とすのに 0.7ms＋9.9ms でした。dead tuple も出ません。

CREATE TABLE outbox_p (
  id bigint GENERATED ALWAYS AS IDENTITY, event_id uuid NOT NULL DEFAULT gen_random_uuid(),
  aggregate_type text NOT NULL, aggregate_id text NOT NULL, event_type text NOT NULL,
  payload jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
  published_at timestamptz,
  PRIMARY KEY (created_at, id)              -- 主キーにパーティションキーを含める
) PARTITION BY RANGE (created_at);
CREATE INDEX ON outbox_p (id) WHERE published_at IS NULL;
CREATE TABLE outbox_p_2026_11_03 PARTITION OF outbox_p FOR VALUES FROM ('2026-11-03') TO ('2026-11-04');
CREATE TABLE outbox_p_2026_11_04 PARTITION OF outbox_p FOR VALUES FROM ('2026-11-04') TO ('2026-11-05');

ALTER TABLE outbox_p DETACH PARTITION outbox_p_2026_11_03;   -- Time: 0.677 ms
DROP TABLE outbox_p_2026_11_03;                               -- Time: 9.885 ms

DROP する前に「そのパーティションに未配送の行が無い」ことを確かめる1行を掃除ジョブに入れておきます。未配送が残っていればパーティションを残し、警告を出すのが安全側です。

SELECT count(*) FROM outbox_p_2026_11_03 WHERE published_at IS NULL;   -- 0 なら DROP してよい

CDC（Debezium のログテーリング）との比較

この節では、ポーリング・リレーを Debezium（変更データキャプチャ）に置き換えるとき何が変わり、何が変わらないかが、公式ドキュメントの範囲で分かります。

CDC は「outbox テーブルを SELECT で見張る」代わりに「outbox テーブルへの INSERT を WAL（トランザクションログ）から読む」方式です。 microservices.io は Message relay の実装として Transaction log tailing と Polling publisher の2つを挙げています。outbox に書く側のアプリの形は同じで、変わるのはリレーだけです。Kafka と Debezium はこの環境で動かしていないため、以下は Debezium 公式ドキュメント（Outbox Event Router）で確かめた範囲です。

Debezium のドキュメントは、outbox テーブルを「キューのように扱い、変更は INSERT で行う」こと、UPDATE が来たときの扱いは table.op.invalid.behavior（既定 warn）で決まることを書いています。ポーリング方式の published_at UPDATE は、CDC に移るときには「送った行を DELETE する」に置き換えるのが自然です。

採用する・しないの判断表（同期で済む場合・Saga・2PC との違い）

この節では、outbox を入れる前に確かめる順番と、入れない方がよい状況、近い名前のパターンとの違いが分かります。

outbox が要るのは「DB の変更と、別システムへの通知の両方が、片方だけでは成立しない」ときだけです。 次の順に考えると判断がぶれません。

1. 1通知先が同じ DB の別テーブルか → 普通のトランザクションoutbox も リレーも要らない。同じトランザクションで両方 UPDATE する
2. 2同期呼び出しの失敗を、そのまま利用者に返してよいか → 同期で済む先に相手を呼び、成功したら COMMIT する。相手が落ちていれば注文も失敗にする設計が許されるなら、それが最も単純
3. 3通知の取りこぼしが業務上許されるか → 素朴な送信＋監視分析用のログ送信など。欠けたら後で突合で埋められるもの
4. 4コミットされた変更を必ず届けたい → Transactional Outbox出荷指示・請求・在庫引き当て・他サービスの投影の更新。受け手の冪等性とセット
5. 5複数サービスの DB を順に更新し、途中で失敗したら戻したい → Saga各ステップのイベント発行に outbox を使う。AWS のガイドも「サービスをまたぐなら Saga」と書いている

導入の費用は、表1つ・リレー1プロセス・受け手の処理済み表・掃除ジョブ・デッドレターの監視です。小さくはないので、「落ちたら失敗にしてよい」なら同期呼び出しを選ぶのは正当な判断です。トランザクションの境界をどこで切るかは、関連記事「トランザクション設計の考え方｜境界の決め方と長い処理の分割手順」で扱っています。

よくある質問

Q. outbox テーブルは業務テーブルと同じデータベースに置く必要がありますか？

はい。同じトランザクションで書けることがパターンの前提なので、同じデータベース（同じ接続・同じトランザクション）に置きます。別のデータベースに置くと、それ自体が二重書き込みになります。

Q. 「ちょうど1回（exactly once）」にはできませんか？

リレーと配送先の間では「少なくとも1回」が限界で、この記事でも送信後・印を付ける前の停止で再送が起きました。ちょうど1回「に見える」結果は、受け手の冪等性（処理済み表）で作ります。ブローカーが重複排除の機能を持っていても、受け手側の冪等性は残しておくのが安全です。

Q. リレーは何個動かすべきですか？

まず1つで測ります。この記事の環境では2つにしても1割しか速くならず、順序は 300 注文中 25〜30 件で崩れました。増やすなら aggregate_id のハッシュで担当を分け、同じ集約が同じリレーに行くようにします。

Q. ポーリング間隔はどれくらいが妥当ですか？

遅延の中央値は間隔の半分、最大は間隔とほぼ同じでした（1秒で 507.6ms／1003.0ms）。数百 ms が要るなら LISTEN/NOTIFY を足す方が、間隔を 100ms に詰めて空振りのクエリを増やすより DB にやさしい結果でした。

Q. 配送先が長時間落ちていたらどうなりますか？

outbox に未配送の行が溜まり、attempts の上限に達した行は取り出し対象から外れます。復旧後に UPDATE outbox SET attempts = 0, next_attempt_at = clock_timestamp() WHERE published_at IS NULL で戻せば、id 順に配送が再開します。溜まっている間も業務トランザクションは影響を受けません。

Q. 1つの業務トランザクションで複数のイベントを書いてもよいですか？

はい。同じ aggregate_id なら id 順に配送されます。この記事の順序の実験は1注文に3イベントを書いて行いました。

Q. payload には何を入れるべきですか？

受け手が処理に必要な最小限（ID・変更の種類・変更後の要点）と、スキーマのバージョンです。集約全体を毎回入れると表と WAL が太ります。受け手が詳細を要るなら API で取りに行く形（通知＋取得）も選べます。

Q. 配送済みの行はいつ消せますか？

published_at が付いた行は、再送の必要が無くなった時点で消せます。監査や再配送（リプレイ）に使うなら数日〜数週間残し、日次パーティションで DROP するのが軽い方法です。DELETE 方式では autovacuum が追いつくかを n_dead_tup で見ます。

Q. ORM（JPA・SQLAlchemy など）でも同じことができますか？

できます。要点は「業務エンティティの保存と outbox エンティティの保存を同じトランザクション境界に入れる」ことだけです。AWS のガイドの例も Spring の @Transactional メソッドの中で2つの repository の save を呼んでいます。

Q. CDC にすれば受け手の冪等性は要らなくなりますか？

要ります。Debezium から Kafka、Kafka から受け手のどちらの区間でも再配送は起きえます。CDC で変わるのはリレーの作りと遅延であって、配送の保証の種類は変わりません。

まとめ

• DB 更新とメッセージ送信を別々に行うと、送る順番をどう変えても「存在しない注文の通知」か「通知されない注文」のどちらかが起きる。5経路すべてをプロセス停止と ROLLBACK で再現できた。
• Transactional Outbox は、送りたい事実を同じトランザクションで outbox テーブルに書き、別プロセスのリレーが配送する。ROLLBACK や COMMIT 前の停止では outbox にも何も残らない。
• リレーは published_at IS NULL の部分インデックス＋FOR UPDATE SKIP LOCKED で 0.1ms で取り出せる。配送後・印を付ける前に落ちると再送されるので、受け手は event_id の処理済み表で冪等にする（HTTP 8回受信・出荷指示 5件）。
• 複数リレーは aggregate_id でパーティションしないと順序が崩れる（300注文中 25〜30）。遅延はポーリング間隔の半分が中央値で、LISTEN/NOTIFY なら 6ms。
• outbox は DELETE しても表は縮まず、空きが再利用されるだけ。流量が多ければ日次パーティションの DROP。同じ DB で完結する・同期の失敗を返してよい場合は、outbox を入れない判断が正しい。

参考・出典

• microservices.io「Pattern: Transactional outbox」 https://microservices.io/patterns/data/transactional-outbox.html（確認日 2026年11月4日）
• AWS Prescriptive Guidance「Transactional outbox pattern」 https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html（確認日 2026年11月4日）
• Debezium Documentation「Outbox Event Router」 https://debezium.io/documentation/reference/stable/transformations/outbox-event-router.html（確認日 2026年11月4日）
• PostgreSQL 16 Documentation「SELECT」（The Locking Clause・SKIP LOCKED） https://www.postgresql.org/docs/16/sql-select.html（確認日 2026年11月4日）
• PostgreSQL 16 Documentation「NOTIFY」 https://www.postgresql.org/docs/16/sql-notify.html（確認日 2026年11月4日）
• PostgreSQL 16 Documentation「Table Partitioning」 https://www.postgresql.org/docs/16/ddl-partitioning.html（確認日 2026年11月4日）
• Redis Documentation「Redis Streams」（XREADGROUP・XPENDING・XAUTOCLAIM） https://redis.io/docs/latest/develop/data-types/streams/（確認日 2026年11月4日）
• psycopg 3 Documentation「Asynchronous notifications」 https://www.psycopg.org/psycopg3/docs/advanced/async.html（確認日 2026年11月4日）

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。