Dalam arsitektur microservices modern, integrasi antar-layanan sering kali melibatkan dua tindakan sekaligus: menyimpan status bisnis ke database lokal dan menerbitkan event atau webhook ke sistem eksternal (seperti message broker RabbitMQ, Kafka, atau server mitra B2B).
Pola implementasi yang paling umum dilakukan pengembang adalah memanggil fungsi publikasi event tepat setelah perintah commit database dijalankan. Pola ini dikenal sebagai Dual-Write Problem, yang menyimpan celah inkonsistensi data kritis: jika server mengalami crash atau jaringan terputus tepat setelah database menyimpan data namun sebelum broker menerima event, transaksi bisnis tercatat tetapi pesan integrasi hilang permanen.
Masalah Dual-Write Konvensional:
Database SQL Aplikasi Layanan Message Broker
│ │ │
├────── Commit Sukses ───────┤ │
│ ├─── Kirim Event Jaringan ──► (Jaringan Putus / Timeout)
│ │ X Pesan Hilang!
Solusi: Transactional Outbox Pattern #
Untuk menjamin bahwa data bisnis dan event selalu berada dalam kondisi konsisten (at-least-once delivery), arsitektur enterprise menerapkan Transactional Outbox Pattern.
Alih-alih mengirim pesan langsung ke broker melalui jaringan, aplikasi menyimpan payload event ke dalam tabel sementara bernama outbox_events di dalam transaksi database lokal yang sama dengan data bisnis. Karena keduanya berada dalam satu transaksi ACID, keduanya dijamin berhasil bersamaan atau gagal bersamaan.
Alur Transactional Outbox Pattern:
┌────────────────────────────────────────────────────────┐
│ Transaksi Database Atomik (ACID) │
│ 1. INSERT INTO pesanan (id, total, status) │
│ 2. INSERT INTO outbox_events (id, aggregate, payload) │
└────────────────────────────────────────────────────────┘
│
▼ Tersimpan Aman di Disk DB
┌────────────────────────────────────────────────────────┐
│ Outbox Relay / CDC Worker (Debezium / Polling Daemon) │
│ Membaca log outbox_events yang belum terproses │
└────────────────────────────────────────────────────────┘
│
▼ Mengalirkan Event Tanpa Kehilangan
┌────────────────────────────────────────────────────────┐
│ Message Broker / Webhook Klien B2B │
└────────────────────────────────────────────────────────┘
Skema Database Tabel Outbox #
Berikut adalah skema tabel outbox yang dirancang untuk PostgreSQL dengan dukungan partisi dan tipe data JSONB:
CREATE TABLE outbox_events (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
aggregate_type VARCHAR(64) NOT NULL,
aggregate_id VARCHAR(64) NOT NULL,
event_type VARCHAR(128) NOT NULL,
payload JSONB NOT NULL,
headers JSONB DEFAULT '{}'::jsonb,
status VARCHAR(24) NOT NULL DEFAULT 'PENDING', -- PENDING, PUBLISHED, FAILED
retry_count INT NOT NULL DEFAULT 0,
last_error TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
processed_at TIMESTAMPTZ
);
-- Indeks komposit untuk mempercepat polling antrean pending
CREATE INDEX idx_outbox_pending_events
ON outbox_events (status, created_at)
WHERE status = 'PENDING';
Implementasi Penyimpanan Transaksional pada NestJS #
Berikut adalah implementasi transaksi bisnis dan outbox dalam satu unit kerja menggunakan TypeORM atau Prisma pada runtime TypeScript:
import { Injectable } from '@nestjs/common';
import { DataSource } from 'typeorm';
export interface CreateOrderDto {
orderId: string;
customerId: string;
amount: number;
items: Array<{ productId: string; quantity: number }>;
}
@Injectable()
export class OrderService {
constructor(private readonly dataSource: DataSource) {}
async createOrder(dto: CreateOrderDto): Promise<void> {
const queryRunner = this.dataSource.createQueryRunner();
await queryRunner.connect();
await queryRunner.startTransaction();
try {
// 1. Simpan Entitas Bisnis
await queryRunner.manager.query(
`INSERT INTO orders (id, customer_id, total_amount, status)
VALUES ($1, $2, $3, 'CREATED')`,
[dto.orderId, dto.customerId, dto.amount]
);
// 2. Simpan Event ke Outbox dalam Transaksi yang Sama
const eventPayload = {
orderId: dto.orderId,
customerId: dto.customerId,
amount: dto.amount,
items: dto.items,
timestamp: new Date().toISOString(),
};
await queryRunner.manager.query(
`INSERT INTO outbox_events (aggregate_type, aggregate_id, event_type, payload, status)
VALUES ('Order', $1, 'ORDER_CREATED', $2, 'PENDING')`,
[dto.orderId, JSON.stringify(eventPayload)]
);
// Commit kedua operasi secara atomik
await queryRunner.commitTransaction();
} catch (error) {
await queryRunner.rollbackTransaction();
throw new Error(`Gagal memproses pesanan: ${(error as Error).message}`);
} finally {
await queryRunner.release();
}
}
}
Mekanisme Penerusan Pesan: Polling vs Change Data Capture (CDC) #
Terdapat dua strategi utama untuk membaca tabel outbox dan meneruskannya ke broker eksternal:
- Polling Publisher:
Sebuah worker terjadwal melakukan querySELECT ... FROM outbox_events WHERE status = 'PENDING' ORDER BY created_at ASC LIMIT 100 FOR UPDATE SKIP LOCKED. Pendekatan ini mudah diimplementasikan tanpa dependensi infrastruktur tambahan, namun membebani database jika interval polling terlalu rapat. - Change Data Capture (CDC) via Debezium:
Pendekatan paling scalable untuk volume transaksi masif. Debezium membaca log replikasi internal PostgreSQL (Write-Ahead Log / WAL) secara streaming tanpa melakukan query SQL ke tabel. Ketika baris baru masuk keoutbox_events, Debezium langsung meneruskannya ke Kafka dalam hitungan sub-milidetik.
Merancang Consumer Idempoten di Sisi Penerima #
Karena pola outbox menjamin pengiriman pesan at-least-once (bisa terjadi pengiriman ulang saat koneksi jaringan terputus pasca kirim), layanan penerima (consumer) wajib bersifat idempoten. Consumer harus memastikan bahwa menerima pesan yang sama dua kali tidak akan memicu eksekusi ganda (seperti pemotongan saldo dua kali).
Tabel pencatatan idempoten pada consumer:
CREATE TABLE processed_events (
idempotency_key VARCHAR(128) PRIMARY KEY,
consumer_name VARCHAR(64) NOT NULL,
processed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
Implementasi pemrosesan idempoten di sisi consumer:
export async function handleOrderCreatedEvent(
eventId: string,
payload: any,
dataSource: any
): Promise<void> {
const queryRunner = dataSource.createQueryRunner();
await queryRunner.connect();
await queryRunner.startTransaction();
try {
// Upaya pencatatan kunci idempoten dengan ON CONFLICT DO NOTHING
const result = await queryRunner.manager.query(
`INSERT INTO processed_events (idempotency_key, consumer_name)
VALUES ($1, 'inventory-service')
ON CONFLICT (idempotency_key) DO NOTHING
RETURNING idempotency_key`,
[eventId]
);
// Jika baris kosong, event sudah pernah diproses sebelumnya
if (result.length === 0) {
await queryRunner.rollbackTransaction();
console.log(`Event ${eventId} sudah pernah diproses. Lewati.`);
return;
}
// Eksekusi mutasi bisnis (misalnya alokasi stok barang)
await queryRunner.manager.query(
`UPDATE product_stocks
SET reserved_quantity = reserved_quantity + $1
WHERE product_id = $2`,
[payload.items[0].quantity, payload.items[0].productId]
);
await queryRunner.commitTransaction();
} catch (error) {
await queryRunner.rollbackTransaction();
throw error;
} finally {
await queryRunner.release();
}
}
Kombinasi Transactional Outbox di sisi publisher dan tabel idempotency ledger di sisi consumer menjamin integritas data 100% konsisten pada jaringan terdistribusi tanpa risiko pesanan fiktif atau event hilang.
