トランザクションOutbox:業務書き込みと同じ副作用
要点: DBへ書いてからメールAPI・Webhook・ERPを呼ぶのは二重書き込みで、どちらも単独で成功し得ます。業務変更と同じトランザクションにoutbox行を置き、リレーがコミット済み行を少なくとも1回配信。受信側は冪等である必要があります。
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・クラウド・デバイス管理をご覧いただくか、プロジェクトのご相談からご連絡ください。
参考資料
- Chris Richardson, Pattern: Transactional outbox: https://microservices.io/patterns/data/transactional-outbox.html
- Chris Richardson, Pattern: Polling publisher: https://microservices.io/patterns/data/polling-publisher.html
- Chris Richardson, Pattern: Transaction log tailing: https://microservices.io/patterns/data/transaction-log-tailing.html
- AWS Prescriptive Guidance, Transactional outbox pattern: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html
よくあるご質問
Outboxはメッセージキューと同じものですか。
Outboxは業務書き込みと同じデータベース内のテーブル(またはドキュメントのフィールド)で、両方が一緒にコミットするか一緒にロールバックします。キューやブローカーはリレーの後段に置きます。業務書き込みなしではPublishが成功せず、その逆も起きないようにするのがOutboxの役割です。
受信側でも冪等性は必要ですか。
必要です。リレーは複数回Publishし得ます。送信成功のあと、行を完了にする前に落ちると再送になります。消費者は少なくとも1回の配信として扱い、Webhookのノートにある冪等キーと保持期間のやり方などが使えます。
データベースのトランザクション内でメールAPIを呼べますか。
避けてください。ネットワーク呼び出しを待ちながらDBトランザクションを開いたままにするとロックが長くなり、タイムアウト時にメールが届いたかどうかも分かりません。Outbox行を書いてコミットし、ネットワーク作業はリレーに任せてください。
Outboxテーブルのポーリングは無駄に見えます。別の方法はありますか。
ポーリングはどのSQLデータベースでも動き、中程度の量なら大抵足ります。データベースが対応していれば、トランザクションログの追跡(WALやbinlogからoutbox挿入を読むなど)で遅延と負荷を下げられます。どちらも少なくとも1回の配信です。
Outboxのペイロードには何を入れますか。
リレーが意図を再構成せずに動ける分だけです。種別、安定した冪等またはメッセージID、業務キー、下流呼び出しに必要なフィールド。不透明な集約全体のダンプより版付きスキーマを好み、コード変更後も古い行が読めるようにします。