2026-11-18 · 11 min
Transactional Outbox di PostgreSQL: Event Tidak Hilang Lagi
Setelah lonjakan transaksi akhir bulan, tim finance mengirim tangkapan layar yang sudah saya kenal bentuknya: order ada di database dengan status PAID, tetapi tidak ada email konfirmasi, tidak ada jurnal akuntansi, tidak ada notifikasi gudang. Beberapa hari kemudian, laporan kebalikannya: gudang menerima perintah kirim untuk order yang tidak pernah ada. Dua gejala, satu akar masalah. Ini dual write problem, dan transactional outbox pattern adalah cara paling murah yang saya tahu untuk menutupnya.
Dual write problem: dua commit yang tidak bisa atomik
Kode awalnya biasanya terlihat wajar:
await db.query("UPDATE orders SET status = 'PAID' WHERE id = $1", [orderId]);
await queue.add("order.paid", { orderId }); // di sini proses bisa mati
PostgreSQL dan Redis tidak berbagi transaksi. Ada dua kemungkinan gagal:
- Commit sukses, publish gagal. Redis timeout, pod di-restart saat deploy, atau OOM kill tepat di antara dua baris. Order tersimpan, event hilang selamanya.
- Publish sukses, commit gagal. Kalau Anda membalik urutan, atau publish dilakukan di dalam blok transaksi lalu
COMMITgagal karena deadlock atau serialization error, event beredar untuk data yang tidak ada.
Membungkus dengan try/catch, retry, atau menukar urutan tidak menyelesaikannya. Anda hanya memilih mode kegagalan mana yang lebih bisa Anda tolerir. Solusi yang benar adalah memastikan hanya ada satu commit yang menentukan kebenaran.
Idenya: event adalah data, tulis di transaksi yang sama
Alih-alih publish langsung, tulis event sebagai baris di tabel outbox pada transaksi database yang sama dengan perubahan bisnisnya. Atomisitas datang gratis dari PostgreSQL: baris order dan baris outbox sama-sama ada atau sama-sama tidak. Proses terpisah, disebut relay, membaca outbox dan mem-publish ke queue.
CREATE TABLE outbox (
id BIGSERIAL PRIMARY KEY,
event_id UUID NOT NULL DEFAULT gen_random_uuid() UNIQUE,
aggregate_id TEXT NOT NULL,
event_type TEXT NOT NULL,
payload JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
published_at TIMESTAMPTZ
);
-- Index parsial: hanya baris yang belum terkirim, tetap kecil walau tabel besar
CREATE INDEX outbox_unpublished_idx ON outbox (id) WHERE published_at IS NULL;
Index parsial itu penting. Relay hanya peduli pada baris published_at IS NULL, dan index ini membuat query polling tetap murah walaupun tabel sudah berisi jutaan baris lama.
Sisi penulisan: satu transaksi, dua INSERT/UPDATE
import { Pool } from "pg";
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
export async function markOrderPaid(orderId: string) {
const client = await pool.connect();
try {
await client.query("BEGIN");
const { rowCount } = await client.query(
"UPDATE orders SET status = 'PAID' WHERE id = $1 AND status = 'PENDING'",
[orderId],
);
if (rowCount === 0) {
await client.query("ROLLBACK");
return; // sudah dibayar atau tidak ada, jangan buat event
}
await client.query(
`INSERT INTO outbox (aggregate_id, event_type, payload)
VALUES ($1, 'order.paid', $2)`,
[orderId, JSON.stringify({ orderId })],
);
await client.query("COMMIT");
} catch (err) {
await client.query("ROLLBACK");
throw err;
} finally {
client.release();
}
}
Perhatikan bahwa tidak ada pemanggilan Redis di sini. Jalur penulisan hanya bergantung pada PostgreSQL, jadi Redis boleh mati tanpa membuat checkout gagal. Event menunggu di outbox sampai relay bisa mengirimnya.
Relay: batch dengan FOR UPDATE SKIP LOCKED
Relay mengambil batch baris yang belum terkirim, publish, lalu menandainya. Kunci agar bisa dijalankan lebih dari satu instance adalah FOR UPDATE SKIP LOCKED:
import { Queue } from "bullmq";
import { makeConnection } from "./redis";
const queue = new Queue("domain-events", { connection: makeConnection() });
export async function relayOnce(batchSize = 100): Promise<number> {
const client = await pool.connect();
try {
await client.query("BEGIN");
const { rows } = await client.query(
`SELECT id, event_id, event_type, payload
FROM outbox
WHERE published_at IS NULL
ORDER BY id
LIMIT $1
FOR UPDATE SKIP LOCKED`,
[batchSize],
);
for (const row of rows) {
// jobId deterministik: publish ulang event yang sama menjadi satu job
await queue.add(row.event_type, row.payload, { jobId: row.event_id });
}
if (rows.length > 0) {
await client.query(
"UPDATE outbox SET published_at = now() WHERE id = ANY($1)",
[rows.map((r) => r.id)],
);
}
await client.query("COMMIT");
return rows.length;
} catch (err) {
await client.query("ROLLBACK");
throw err;
} finally {
client.release();
}
}
export async function runRelay(signal: AbortSignal) {
while (!signal.aborted) {
const n = await relayOnce().catch((e) => {
console.error("relay error", e);
return 0;
});
if (n === 0) await new Promise((r) => setTimeout(r, 500));
}
}
Tiga detail yang sering terlewat:
SKIP LOCKEDmembuat relay kedua melewati baris yang sedang dipegang relay pertama. Tanpa klausa itu, relay kedua memblokir menunggu, atau lebih buruk, kalau Anda tidak memakaiFOR UPDATE, keduanya mem-publish baris yang sama.ORDER BY idmenjaga urutan kasar per batch, tetapi dengan beberapa relay paralel urutan global tidak dijamin. Kalau urutan per entitas penting, jangan andalkan relay: sertakan versi atau sequence di payload, atau partisi relay berdasarkan hashaggregate_id.- Transaksi relay menahan lock selama publish. Batch kecil (50 sampai 200) menjaga lock tetap singkat. Jangan menaikkan batch ke ribuan hanya untuk mengejar throughput.
Semantik at-least-once, dan apa artinya
Lihat celah di relay: kalau proses mati setelah queue.add tetapi sebelum COMMIT, baris tetap published_at IS NULL dan akan dikirim lagi pada siklus berikutnya. Inilah at-least-once. Anda menukar event yang hilang dengan event yang mungkin ganda, dan itu pertukaran yang sehat, karena duplikat bisa ditangani oleh consumer sedangkan event yang hilang tidak bisa ditemukan kembali.
jobId: row.event_id meredam sebagian besar duplikat di sisi queue, tetapi BullMQ menghapus job selesai sesuai removeOnComplete, jadi jobId bukan jaminan jangka panjang. Untuk detail konfigurasi BullMQ yang aman di produksi, termasuk koneksi Redis dan retry, saya sudah menulisnya di panduan BullMQ dan Redis untuk Node.js dan tidak akan mengulangnya di sini.
Consumer idempoten: garis pertahanan terakhir
Karena pengiriman bisa ganda, consumer harus aman dijalankan dua kali. Pola paling sederhana adalah mencatat id event yang sudah diproses dalam transaksi yang sama dengan efek sampingnya:
import { Worker } from "bullmq";
new Worker(
"domain-events",
async (job) => {
const eventId = job.id!; // = outbox.event_id
const client = await pool.connect();
try {
await client.query("BEGIN");
const res = await client.query(
`INSERT INTO processed_events (event_id) VALUES ($1)
ON CONFLICT DO NOTHING`,
[eventId],
);
if (res.rowCount === 0) {
await client.query("ROLLBACK");
return; // sudah pernah diproses
}
await postJournalEntry(client, job.data); // efek samping di transaksi yang sama
await client.query("COMMIT");
} catch (err) {
await client.query("ROLLBACK");
throw err;
} finally {
client.release();
}
},
{ connection: makeConnection() },
);
Kalau efek samping Anda berada di luar database consumer, misalnya memanggil API pihak ketiga, gunakan idempotency key di API itu. Pola idempotency key, retry, dan replay untuk sisi webhook sudah saya bahas di reliabilitas webhook di produksi dan keamanan webhook dengan HMAC; prinsipnya sama persis, hanya tempatnya berbeda.
Housekeeping: outbox yang tidak dibersihkan akan membengkak
Hapus baris lama secara berkala, jangan sekaligus:
DELETE FROM outbox
WHERE id IN (
SELECT id FROM outbox
WHERE published_at < now() - interval '7 days'
LIMIT 5000
);
Simpan beberapa hari untuk investigasi, lalu buang. Pantau juga dua angka: jumlah baris published_at IS NULL (kalau naik terus, relay Anda tertinggal atau mati) dan umur baris terlama yang belum terkirim. Dua metrik itu saja sudah mendeteksi hampir semua masalah outbox sebelum pelanggan merasakannya.
Kapan beralih ke CDC dengan Debezium
Relay polling punya batas. Pertimbangkan Change Data Capture dengan Debezium ketika:
- Throughput outbox cukup tinggi sehingga polling terus-menerus membebani database primer.
- Latensi event harus konsisten di bawah satu detik, dan interval polling sudah tidak bisa diperkecil tanpa menyiksa database.
- Banyak layanan memakai pola outbox dan Anda tidak mau memelihara relay di masing-masing.
Debezium membaca WAL PostgreSQL lewat logical replication, jadi tidak ada polling dan urutan per baris terjaga. Harganya nyata: Kafka dan Kafka Connect harus dioperasikan, replication slot yang macet menahan WAL dan bisa memenuhi disk, dan skema outbox harus mengikuti konvensi connector. Untuk tim yang masih mengirim ratusan event per detik ke BullMQ, relay polling di atas lebih sederhana dan lebih mudah di-debug. Saya baru pindah ketika angka metrik di bagian housekeeping tadi menunjukkan polling sebagai bottleneck, bukan karena CDC terdengar lebih modern.
Outbox bukan event sourcing
Satu klarifikasi supaya tidak tertukar: outbox hanya menjamin event keluar dengan andal dari satu transaksi. Ia tidak menjadikan event sebagai sumber kebenaran. Kalau Anda memang ingin state diturunkan dari rangkaian event, itu keputusan arsitektur yang lebih besar dan saya bahas di tulisan event sourcing dan CQRS. Dan kalau yang Anda butuhkan hanya fan-out sederhana tanpa jaminan pengiriman, Redis pub/sub masih sah, selama Anda sadar bahwa pesan yang terlewat tidak akan kembali.
Checklist sebelum rilis
- Perubahan bisnis dan INSERT ke
outboxada dalam satu transaksi, tanpa panggilan jaringan di dalamnya. - Index parsial pada
published_at IS NULLsudah ada. - Relay memakai
FOR UPDATE SKIP LOCKEDdengan batch kecil. - Consumer idempoten, dibuktikan dengan test yang mengirim event yang sama dua kali.
- Alert untuk backlog outbox dan umur baris terlama.
- Job pembersihan baris lama berjalan terjadwal.
Bug “order ada, event tidak ada” tidak hilang karena kita lebih teliti menulis kode, tetapi karena kita berhenti meminta dua sistem berkomitmen bersamaan. Satu transaksi, satu sumber kebenaran, dan sisanya adalah pengiriman ulang yang aman.
Ditulis oleh Reza Pradipta