Konsep dan Aturan

Istilah

Istilah	Arti
Tabel terdaftar	Tabel sumber yang memiliki row konfigurasi pada kv_cache_table.
table_name	Nama tabel PostgreSQL dan nama subject CDC sumber.
cache_name	Alias namespace Redis; jika kosong, menggunakan table_name.
query_source	Query SELECT kustom untuk membentuk isi cache.
Full sync	Membaca seluruh hasil query, mengganti index, dan menghapus row cache yang tidak lagi ada.
Single-row sync	Membaca ulang satu id setelah event create/update/delete.

Bentuk data Redis

Jika CACHE_PREFIX=dev, tabel machine dengan row id=42 menghasilkan:

Key	Tipe	Isi
dev:config.machine.42	string JSON	Data row lengkap.
dev:config.machine.index	Redis set	Kumpulan ID row untuk tabel tersebut.
global:config	string JSON	Objek { [cacheName]: { [id]: row } } untuk Node-RED.

CACHE_PREFIX hanya diterapkan pada key config.*. Key global:config selalu tanpa prefix.

Aturan registrasi tabel

Saat bootstrap, konfigurasi hanya diproses jika:

• row kv_cache_table.status bernilai published;
• date_deleted bernilai NULL; dan
• table_name terdapat pada directus_collections.

Setiap row konfigurasi yang lolos juga disimpan ke namespace cache kv_cache_table. Daftar ini kemudian dipakai oleh KvCacheTableItemService untuk membuat subscription CDC per tabel.

Aturan query

• Tanpa query_source, bootstrap menjalankan SELECT * FROM <table_name>.
• Tanpa query_source, full sync realtime hanya mengambil row dengan status = 'published'.
• Single-row realtime juga mensyaratkan id dan status = 'published'.
• Dengan query_source, query harus dimulai dengan SELECT atau WITH dan lolos SQL guard read-only.
• Single-row dengan query kustom membungkus query sebagai subquery lalu memfilter subq.id = $1; hasil query karena itu harus memiliki kolom id.

Perbedaan filter bootstrap dan realtime di atas berasal langsung dari implementasi. Tabel tanpa query_source yang memiliki row non-published dapat masuk saat bootstrap, lalu dibuang saat row tersebut diproses realtime.

Aturan perubahan

Kondisi	Tindakan
Create/update dengan row ditemukan	Upsert row, tambahkan ID ke index, perbarui global:config, publish event row.
Delete	Hapus row, hapus ID dari index, bersihkan global:config, publish event delete.
Update tetapi row tidak ditemukan atau tidak published	Perlakukan sebagai delete.
Full sync	Upsert hasil query, hapus orphan, ganti index, publish snapshot tabel.
Konfigurasi tabel soft-deleted	Hapus seluruh namespace cache dan entry tabel pada global:config.

Batasan yang terlihat dari source

• Row tanpa id dilewati dan tidak masuk index.
• Tidak ada TTL pada key Redis; konsistensi bergantung pada bootstrap dan CDC.
• Subject config.sync.force terdaftar di stream, tetapi tidak ada handler atau publisher-nya dalam source yang dianalisis.
• Operasi Redis untuk row, index, dan global:config tidak dibungkus transaksi atomik.