トランザクションOutbox:業務書き込みと同じ副作用

要点: DBへ書いてからメールAPI・Webhook・ERPを呼ぶのは二重書き込みで、どちらも単独で成功し得ます。業務変更と同じトランザクションにoutbox行を置き、リレーがコミット済み行を少なくとも1回配信。受信側は冪等である必要があります。

トランザクションOutboxの図。リクエストハンドラが同一のデータベーストランザクションで業務行とoutbox行を書き、コミット後にリレーがポーリングまたはログ追跡でoutboxを読み、メール、Webhook、ERP送信を少なくとも1回配信する。受信側は冪等の関門を置く。底部の注記は、永続outboxなしで業務書き込みをコミットしてからネットワークを呼ぶなと警告する。
図1. 業務書き込みとoutbox行を同一トランザクションに置き、リレーがコミット後の配信を担う。

1.0 二重書き込みの問題

注文を保存してから確認メールを送るハンドラは、データベースとメール提供者という二つのシステムへ書いています。帳票をERPへ送る場合や、パートナーへWebhookを出す場合も同じ形です。

データベースがコミットし、ネットワーク呼び出しが失敗すると、業務状態は正しいのに誰にも届きません。先に通知してコミットが失敗すると、相手側は存在しなかったものに基づいて動いてしまいます。データベースとメールAPIにまたがる二相コミットはほとんど使えず、望ましくもないことが多いです。これがトランザクションOutboxパターンが扱う二重書き込みの問題です(末尾のChris Richardsonの説明とAWS Prescriptive Guidanceを参照)。

2.0 同一トランザクションに入れるもの

書き込み業務変更と同じトランザクションか
業務行(注文、支払い、チケットなど)はい
Outbox行(type、message id、payload、status)はい
メール / Webhook / ERP のHTTP呼び出しいいえ — コミット後、リレー経由
Outbox行を published にする / 削除するリレー成功後(またはログ追跡の掃除)

Outbox行は、すでに回線上で起きたことのログではありません。副作用を行う永続的な意図であり、業務書き込みがコミットしたときだけ記録されます。

3.0 リレー:ポーリングかログ追跡か

別プロセス(または同一サービスのワーカー)が、コミット済みのoutbox行を外の世界へ移します。

方式仕事の見つけ方典型的なトレードオフ
ポーリング発行idまたはcreated_at順で保留行を SELECT単純;通常のSQLで動く;間隔と表サイズで遅延と負荷が増える
トランザクションログ追跡DBログ(WAL、binlog、streams)から挿入を読む遅延が小さい;DB固有の道具が要る;それでも少なくとも1回

microservices.ioは両方をoutboxの相棒として書いています。量や遅延が逼迫するまではポーリングで足り、ログ追跡への投資はその後で構いません。いずれにせよPublishは 少なくとも1回 です。「送信成功」と「行を完了にした」の間で落ちると再送になります。

4.0 安定させておく行の形

運用が「何が詰まっているか」をアプリケーションのメモリを読まずに答えられるだけの列を持たせます。

  • id — 単調またはULID。順序とリレーのチェックポイント用。
  • message_id / 冪等キー — この論理的副作用で安定。受信側がこれで重複排除。
  • type — どのリレーハンドラが動くか(email.order_paid、erp.order_push など)。
  • aggregate_key — 注文ID、リードID、デバイスID。順序とサポート照会用。
  • payload — ハンドラが要る版付きJSON。秘密を入れない。
  • status — pending → publishing(任意のリース)→ published / failed_terminal。
  • attempts、next_attempt_at、last_error — バックオフとアラート用。
  • created_at — 任意で published_at も。

原子的な更新で行を確保します(pending → publishing、所有者とリース期限付き)。二人のリレーワーカーが同じメールを送らないようにするためです。成功したら published(表を小さく保ち監査はバックアップに任せるなら削除でも可)。再試行可能な失敗ではattemptsを増やし next_attempt_at を設定。設定上限のあと failed_terminal にして人に知らせます。

5.0 順序と重複

単一の集約では、割り当てられたoutbox id(または通し番号)の順にPublishし、パートナーが「出荷済み」を「作成」より先に見ないようにします。集約をまたぐ並列ワーカーは問題ありません。

重複は想定内です。本ノートと Webhookの冪等性とリトライ:重複排除キー、保持期間、副作用の置き場所 を合わせて読んでください。Outboxは業務書き込み成功後に副作用が試行されることを保証し、受信側の重複排除ストアが一度だけ適用されることを保証します。ERP送信も相手側で同じ規律が要ります — 帳票上の安定した業務キーは ERPとの受注連携:手動審査、冪等な送信、同期ログ を参照。

6.0 リクエスト経路に置かないこと

  • DBトランザクションを開いたまま第三者のHTTP APIを呼び、そのあとコミットしないこと。タイムアウトとロックで失敗の読み解きが難しくなります。
  • クラッシュでその副作用を失うのが許容できないなら、永続Outbox(または同等物)なしのgoroutineやキューPublishのfire-and-forgetはしないこと。
  • メールAPIの「HTTP 200」を「顧客へ通知済み」の正本にしないこと。結果も永続化していない限りです。望ましいのは、outboxがpublishedで、提供者のmessage idを行に残すことです。

7.0 可観測性

  • 指標:pendingの経過(p50/p95)、Publishの成功/失敗率、終端失敗、リレー遅延。
  • アラート:最古の pending/publishing が閾値超え;デプロイ後の終端失敗の急増。
  • サポート:aggregate_key で探し、業務レコードの横にoutbox状態を出す。

決済、ERP、デバイスクラウド向けの副作用を配線している場合は、Web・クラウド・デバイス管理をご覧いただくか、プロジェクトのご相談からご連絡ください。

参考資料

よくあるご質問

Outboxはメッセージキューと同じものですか。

Outboxは業務書き込みと同じデータベース内のテーブル(またはドキュメントのフィールド)で、両方が一緒にコミットするか一緒にロールバックします。キューやブローカーはリレーの後段に置きます。業務書き込みなしではPublishが成功せず、その逆も起きないようにするのがOutboxの役割です。

受信側でも冪等性は必要ですか。

必要です。リレーは複数回Publishし得ます。送信成功のあと、行を完了にする前に落ちると再送になります。消費者は少なくとも1回の配信として扱い、Webhookのノートにある冪等キーと保持期間のやり方などが使えます。

データベースのトランザクション内でメールAPIを呼べますか。

避けてください。ネットワーク呼び出しを待ちながらDBトランザクションを開いたままにするとロックが長くなり、タイムアウト時にメールが届いたかどうかも分かりません。Outbox行を書いてコミットし、ネットワーク作業はリレーに任せてください。

Outboxテーブルのポーリングは無駄に見えます。別の方法はありますか。

ポーリングはどのSQLデータベースでも動き、中程度の量なら大抵足ります。データベースが対応していれば、トランザクションログの追跡(WALやbinlogからoutbox挿入を読むなど)で遅延と負荷を下げられます。どちらも少なくとも1回の配信です。

Outboxのペイロードには何を入れますか。

リレーが意図を再構成せずに動ける分だけです。種別、安定した冪等またはメッセージID、業務キー、下流呼び出しに必要なフィールド。不透明な集約全体のダンプより版付きスキーマを好み、コード変更後も古い行が読めるようにします。