Lewati ke isi

ClickHouse Patterns

Pola desain OLAP untuk ERP. DDL: ../../database/migrations/clickhouse/. Konvensi migrasi: README.md.

Model data

Prinsip Implementasi
Satu database erp_clickhouse — bukan DB per tenant
Isolasi tenant Kolom tenant_kode di semua tabel fakta
Sumber kebenaran PostgreSQL — CH adalah read model
Versi baris versi UInt64 microseconds untuk ReplacingMergeTree

Engine per tipe tabel

Tabel Engine Query pattern
transaksi, transaksi_detail, jurnal, stok, akun* ReplacingMergeTree(versi) WHERE is_deleted = 0 + FINAL bila perlu dedup
*_riwayat MergeTree Append-only audit; tidak pakai FINAL untuk histori
Materialized Views SummingMergeTree / derived Agregat dashboard — rebuild DROP+CREATE

Stok: tanpa _riwayat — cache; mutasi audit lewat transaksi_detail.

Kolom audit CDC

Kolom Tipe Fungsi
versi UInt64 Tie-break ReplacingMergeTree
is_deleted UInt8 Soft delete dari op d
op String c/u/d/r

Materialized Views

MV tidak bisa ALTER — perubahan skema:

  1. DROP MATERIALIZED VIEW
  2. CREATE MATERIALIZED VIEW baru
  3. Data MV terisi ulang dari insert berikutnya / backfill

Contoh MV: mv_dashboard_penjualan_harian, mv_saldo_akun — lihat migrasi material_views/V301__*.sql.

Skip indexes

Filter query wajib punya skip index bila memfilter volume besar (saldo, jatuh_tempo, jenis_kode).

-- Verifikasi (contoh)
EXPLAIN indexes = 1 SELECT ... FROM transaksi WHERE tenant_kode = 'sparepart' AND jenis_kode = 'PJ';

Referensi: V105__transaksi_add_skip_indexes.sql, QUICKREF.md.

Sinkronisasi DDL dengan PostgreSQL

Operasi Urutan
Tambah kolom ClickHouse dulu → PostgreSQL
Hapus kolom PostgreSQL dulu → ClickHouse
Ubah tipe Stop consumer → CH → PG → start
Rename Anggap hapus + tambah

Kolom baru: wajib DEFAULT atau Nullable. Tabel *_riwayat selalu diupdate bersama tabel utama.

Rujuk AGENTS.md.

Query dari backend

  • Service: backend/src/database/clickhouse.service.ts
  • Dashboard: dashboard.service.ts
  • Selalu filter tenant_kode dari JWT — jangan andalkan CH untuk isolasi tanpa filter

Initial load vs CDC delta

Fase Metode
Baseline Direct load PG → CH (SOP_INITIAL_LOAD)
Steady CDC Kafka consumer
Validasi Count PG = CH sebelum Start Consumer (guardrail UI masih parsial)

Tooling dev

clickhouse-client -q "SELECT count() FROM erp_clickhouse.transaksi WHERE tenant_kode='sparepart'"

Kredensial dev: AGENTS.md § ClickHouse, INSTALL.md.

Dokumen terkait