VISEN GROUP
Technology & Engineering

Solving Distributed Transactions: Ensuring Reliable Event Publishing with the Outbox Pattern

November 4, 20263 min readUncategorized

In microservice architectures, dual-writing—updating a database and publishing an event to a message broker (Kafka, RabbitMQ, NATS) in the same API route—is a dangerous anti-pattern:

TypeScript

// DANGEROUS ANTI-PATTERN: Dual-Write Vulnerability
async function createOrder(req: Request, res: Response) {
  const order = await db.orders.create({ data: req.body }); // Step 1: DB Save
  await messageBroker.publish("OrderCreated", order);       // Step 2: Network Event Call
  return res.json(order);
}

If the database commit succeeds but the message broker is unreachable or network drops between Step 1 and Step 2, the system enters a split-brain state: the order exists in the database, but downstream services (Inventory, Billing, Shipping) never receive the event.

The Transactional Outbox Pattern guarantees At-Least-Once event delivery by converting dual-writes into a single, atomic database transaction.

1. Architectural Blueprint of the Outbox Pattern

[Client Request] ──► [API Service]
                           │
                           ▼ (Single Atomic ACID Transaction)
            ┌──────────────────────────────┐
            │ 1. INSERT INTO orders        │
            │ 2. INSERT INTO outbox_events │
            └──────────────────────────────┘
                           │
                           ▼
                 [(PostgreSQL Database)]
                           │
                           ▼ (Asynchronous Engine)
            [Outbox Relay Worker / CDC Engine]
                           │
                           ▼
            [Message Broker: Kafka / RabbitMQ]

2. Database Schema & Dual-Write Entity Setup

Create a dedicated outbox_events table within the same database schema as your domain entities:

SQL

CREATE TABLE outbox_events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    aggregate_type VARCHAR(100) NOT NULL,
    aggregate_id VARCHAR(100) NOT NULL,
    event_type VARCHAR(100) NOT NULL,
    payload JSONB NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
    retry_count INT NOT NULL DEFAULT 0,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    processed_at TIMESTAMPTZ
);

CREATE INDEX idx_outbox_pending 
ON outbox_events (created_at ASC) 
WHERE status = 'PENDING';

3. Production Code: Atomic Transaction Handling

TypeScript

import { PoolClient } from "pg";
import { dbPool } from "./database";

export async function processOrderCheckout(userId: string, orderData: any) {
  const client: PoolClient = await dbPool.connect();

  try {
    await client.query("BEGIN");

    // 1. Insert Order Domain Entity
    const orderQuery = `
      INSERT INTO orders (user_id, total_amount, status) 
      VALUES ($1, $2, 'CREATED') 
      RETURNING id, total_amount;
    `;
    const orderRes = await client.query(orderQuery, [userId, orderData.totalAmount]);
    const newOrder = orderRes.rows[0];

    // 2. Insert Outbox Event within the SAME Transaction
    const eventPayload = {
      orderId: newOrder.id,
      userId,
      amount: newOrder.total_amount,
      timestamp: new Date().toISOString()
    };

    const outboxQuery = `
      INSERT INTO outbox_events (aggregate_type, aggregate_id, event_type, payload) 
      VALUES ('ORDER', $1, 'OrderCreated', $2);
    `;
    await client.query(outboxQuery, [newOrder.id, JSON.stringify(eventPayload)]);

    // Commit both operations atomically
    await client.query("COMMIT");
    return newOrder;
  } catch (error) {
    await client.query("ROLLBACK");
    throw new Error(`Order checkout transaction failed: ${(error as Error).message}`);
  } finally {
    client.release();
  }
}

4. Outbox Relay Worker Implementation (Polling Publisher)

The relay worker reads pending events using PostgreSQL’s FOR UPDATE SKIP LOCKED clause to allow multiple worker instances to process outbox records concurrently without lock contention:

TypeScript

import { dbPool } from "./database";
import { KafkaPublisher } from "./kafka";

export async function startOutboxRelayWorker() {
  const client = await dbPool.connect();

  try {
    await client.query("BEGIN");

    // Fetch and lock up to 50 pending outbox events safely across workers
    const selectQuery = `
      SELECT id, event_type, payload 
      FROM outbox_events 
      WHERE status = 'PENDING' 
      ORDER BY created_at ASC 
      LIMIT 50 
      FOR UPDATE SKIP LOCKED;
    `;
    const { rows: events } = await client.query(selectQuery);

    for (const event of events) {
      try {
        // Publish to Kafka / Message Broker
        await KafkaPublisher.send(event.event_type, event.payload);

        // Mark as processed
        await client.query(
          `UPDATE outbox_events SET status = 'PROCESSED', processed_at = NOW() WHERE 
           [event.id]
         ); 
         } 
       catch (pubErr) { // Increment retry count on failure await client.query(                  `UPDATE outbox_events SET retry_count = retry_count + 1 WHERE id = $1`,
       [event.id]
       ); 
     } 
   } 
      await client.query("COMMIT"); 
      } catch (err) { await client.query("ROLLBACK"); 
      } finally { client.release(); 
    } 
   } 
// Run relay polling on a tight loop (e.g., every 500ms) setInterval(startOutboxRelayWorker, 500);

Leave a Reply

Your email address will not be published. Required fields are marked *