Arsitektur Multi-Tenant Database PostgreSQL: Schema-per-Tenant, PgBouncer Multiplexing, dan NestJS

1. Mengapa Multi-Tenancy Tradisional Selalu Berujung Bencana?

Pernahkah kamu membayangkan skenario mimpi buruk di mana data faktur pajak, daftar pesanan rahasia, atau nomor kontak pelanggan milik satu perusahaan klien tiba-tiba muncul di dasbor perusahaan kompetitor mereka? Atau saat server database PostgreSQL mendadak mati suri karena kehabisan koneksi tepat saat bisnismu mulai mendapatkan ratusan klien baru?

Pengalaman mengerikan itulah yang pernah saya dan tim hadapi ketika pertama kali merancang platform Software-as-a-Service (SaaS) logistik B2B. Di awal perancangan, kami dihadapkan pada dilema klasik:

• Jika menggunakan pendekatan Shared Schema (Row-Level Multi-Tenancyℹ) dengan menyelipkan kolom tenant_id di setiap tabel, satu kelalaian kecil pengembang yang lupa menuliskan klausa WHERE tenant_id = :currentTenant dalam kueri SQL kompleks langsung memicu kebocoran data massal lintas-organisasi (cross-tenant data leakage).
• Jika menggunakan pendekatan Database-per-Tenant, menjalankan ratusan instance database terpisah membutuhkan biaya server yang membengkak gila-gilaan, di mana ribuan gigabyte RAM terbuang percuma hanya untuk menahan koneksi idle.

Ketika kami mencoba menjembatani keduanya dengan model Schema-per-Tenant, kami justru tersandung dua masalah produksi fatal:

• Connection Starvationℹ: Setiap podℹ NestJS membuka puluhan koneksi langsung ke PostgreSQL. Karena model internal PostgreSQL melahirkan proses Linux baru untuk setiap koneksi (fork()), ratusan koneksi idle menguras habis RAM dan CPU database hingga server tumbang total.
• Tragedi Schema Bleeding: Saat kami buru-buru memasang connection pooler PgBouncerℹ tanpa pemahaman mendalam, penggunaan perintah naif SET search_path mencemari state sesi koneksi. Data sensitif organisasi Tenant Acme bocor ke layar dasbor Tenant Beta!

Dari rangkaian insiden berdarah tersebut, kami menyadari satu hukum arsitektural: keamanan isolasi data dan efisiensi memori hanya bisa tercapai jika kamu mengombinasikan Schema-per-Tenant dengan PgBouncerℹ Transaction Pooling dan isolasi transaksional SET LOCAL.

2. Peta Topologi dan Matriks Komparasi 3 Model Multi-Tenancy

Sebelum kita membedah insiden lapangan dan implementasi kode, mari kita bandingkan trade-off mendasar antara ketiga paradigma arsitektur multi-tenancyℹ di industri:

3. Krisis Saturasi Koneksi PostgreSQL & Solusi PgBouncer

Masalah 1: Model Proses Fork() PostgreSQL yang Membakar RAM Server

Berbeda dengan MySQL atau Node.js yang berbasis multi-threaded, arsitektur PostgreSQL beroperasi dengan model multi-process:

• Setiap koneksi TCP klien yang tiba diterima oleh proses daemon utama (postmaster).
• postmaster kemudian memanggil syscall sistem operasi Linux fork() untuk melahirkan satu proses worker Linux mandiri (postgres: worker process).
• Setiap proses worker mengalokasikan sekitar 10 MB RAM murni hanya untuk menahan soket TCP dalam kondisi idle tanpa kueri.
• Jika kamu memiliki 15 podℹ NestJS di Kubernetes di mana masing-masing podℹ membuka pool 40 koneksi langsung, ada 600 koneksi fisik yang menuntut 6 GB RAM hanya untuk standby! Begitu traffic melonjak, CPU habis terkuras untuk context switching di tingkat kernel daripada mengeksekusi kueri SQL.

Solusi 1: PgBouncer Transaction Pooling Multiplexing

Kami memasang PgBouncerℹ di depan PostgreSQL dengan mode pool_mode = transaction. PgBouncerℹ memutus relasi 1:1 antara pod aplikasiℹ dan proses worker PostgreSQL:

• Ribuan koneksi klien dari podℹ NestJS ditampung di PgBouncerℹ dengan memori sangat ringan (<50 MB).
• PgBouncerℹ hanya meminjamkan koneksi fisik backend ke PostgreSQL selama transaksi berlangsung (dari BEGIN hingga COMMIT).
• Begitu kueri selesai, koneksi fisik langsung dikembalikan ke pool untuk melayani request berikutnya. Cukup 20-30 koneksi fisik backend untuk melayani ribuan request per detik!

Masalah 2: Bencana Schema Bleeding Akibat Perintah Naif SET search_path

Saat tim kami pertama kali mengaktifkan PgBouncerℹ Transaction Pooling, sebuah bencana baru muncul. Pengembang menulis kueri seperti ini:

Perintah SET search_path reguler mengubah konfigurasi pada level sesi koneksi fisik PostgreSQL backend. Karena PgBouncerℹ meminjamkan koneksi tersebut ke klien lain setelah kueri usai, request berikutnya dari Tenant Globex mendapatkan koneksi yang masih membawa variabel search_path = tenant_acme! Data faktur Tenant Acme bocor ke layar Tenant Globex!

Solusi 2: Penegakan Deterministiik dengan SET LOCAL search_path

Solusi mutlak dan aman untuk mengeliminasi pencemaran state koneksi adalah menggunakan klausa SET LOCAL di dalam transaksi ACID:

4. Kasus Nyata di Medan Produksi: Dua Insiden Berantai yang Mengguncang Platform

Pada kuartal pertama peluncuran sistem logistik B2B kami, tim menghadapi insiden ganda yang menjadi pelajaran paling berharga dalam karir rekayasa kami:

Episode 1: Bencana Connection Starvation

Tepat pukul 00:05 saat promo dimulai, 15 podℹ NestJS mencoba membuka koneksi maksimal ke PostgreSQL secara bersamaan. CPU database terkunci di 100%. PostgreSQL kehabisan alokasi worker dan melempar error fatal: FATAL: remaining connection slots are reserved for non-replication superuser connections. Seluruh aplikasi mengalami cascading timeout HTTP 503 selama 45 menit.

Episode 2: Tindakan Cepat yang Berbuah Petaka (Schema Bleeding)

Untuk meredakan krisis koneksi, tim segera menyalakan PgBouncerℹ dengan mode transaction pooling. Namun, karena kueri aplikasi masih menggunakan SET search_path = "tenant_acme", koneksi yang dikembalikan ke pool masih membawa state skema lama. Staf akuntansi Tenant Beta tiba-tiba melihat faktur dan nomor kontak pelanggan milik Tenant Acme!

Tim segera melakukan perbaikan definitif:

1. 1Melakukan rolling restart PgBouncerℹ untuk membersihkan seluruh koneksi yang tercemar.
2. 2Mengubah modul database NestJS agar selalu menggunakan blok transaksi BEGIN; SET LOCAL search_path ... COMMIT;.
3. 3Memasang middleware sanitasi identifier skema berbasis regex untuk mencegah SQL Injection.

5. Implementasi Kode NestJS Skala Produksi (TypeScript)

Berikut adalah arsitektur implementasi produksi di NestJS yang aman dari kebocoran data dan ramah performa:

A. Context Propagation via AsyncLocalStorage

Menjaga identitas tenant di sepanjang rantai pemanggilan asynchronous tanpa perlu mengoper objek tenantId secara manual di setiap parameter fungsi:

B. Tenant Context Middleware dengan Sanitasi Regex Anti-Injection

C. Konfigurasi pgbouncer.ini (Transaction Pooling)

D. Tenant Database Service dengan SET LOCAL

6. Hasil Riil di Produksi: Metrik Sebelum vs Sesudah

Pengujian beban komparatif dilakukan menggunakan k6 pada server 8 vCPU / 16 GB RAM dengan 1.000 Virtual Users (VU) konkurenℹ yang mengirim kueri simultan ke 100 skema tenant:

7. 5 Kaidah Emas Rekayasa Multi-Tenant Produksi

1. 1Wajib Transaksional untuk SET LOCAL: Jangan pernah menjalankan SET search_path tanpa klausa LOCAL saat menggunakan mode transaction pooling. Selalu bungkus eksekusi di dalam batas BEGIN ... COMMIT.
2. 2Ukuran Pool Backend Kecil dan Padat: Hindari menyetel pool backend PgBouncerℹ ke angka ratusan. Formula optimal untuk koneksi backend PostgreSQL adalah (2 * CPU Core) + Jumlah Disk Spindle (15 hingga 30 koneksi fisik sudah optimal melayani ribuan request klien).
3. 3Sanitasi Ketat Identifier Skema: Lindungi eksekusi DDL nama skema dinamis dari ancaman SQL Injection dengan memvalidasi string identifier hanya berupa alfanumerik aman (/^[a-z0-9_]{3,32}$/).
4. 4Isolasi Konteks Bebas Race-Conditionℹ via AsyncLocalStorageℹ: Hindari menyimpan context tenant di level variabel modul global atau objek request yang rentan terhadap race conditionℹ asinkron di Node.js.
5. 5Pantau Metrik Internal PgBouncerℹ Secara Proaktif: Monitor metrik cl_waiting dan sv_active pada output perintah SHOW POOLS; secara berkala untuk mendeteksi potensi antrean koneksi sebelum berdampak pada pengguna akhir.

8. Simulator Interaktif & Laboratorium Multi-Tenant

Kamu dapat menguji dan membuktikan secara langsung seluruh konsep arsitektur di atas melalui simulator interaktif di artikel ini:

• Uji Mode PgBouncerℹ Aman (SET LOCAL): Kirim kueri untuk Acme Corp, Globex, atau Wayne Enterprise dan perhatikan bagaimana koneksi backend dikembalikan ke pool dalam kondisi higienis.
• Uji Kerentanan State Bleed pada Mode Unsafe: Saksikan langsung peringatan bahaya saat request tenant berikutnya mengeksekusi data di bawah skema milik penyewa sebelumnya.
• Uji Saturasi Koneksiℹ Langsung (Direct PostgreSQL): Amati lonjakan konsumsi memori akibat syscall fork() Linux per koneksi.
• Simulasi Dekoupling Microservices: Saksikan betapa mudahnya mencopot skema tenant besar menjadi database mandiri terdedikasi tanpa perlu merombak struktur DDL tabel.