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);


