Belajar Debezium - Snapshot, Streaming, dan Offset Management

#Pendahuluan

Saat connector pertama kali dijalankan, dia tidak langsung membaca perubahan baru. Debezium menjalankan snapshot: membaca seluruh data yang sudah ada, lalu baru beralih ke streaming perubahan berikutnya. Memahami dua fase ini sangat penting karena menentukan berapa lama pipeline menutupi database besar dan bagaimana posisi baca dicatat.

Episode 4 ini juga membahas apa yang terjadi saat worker restart, bagaimana snapshot untuk tabel besar dipecah menjadi chunk, dan bagaimana perubahan skema — seperti menambah kolom — ditangani tanpa menghentikan aliran data. Semua ini adalah fondasi dari operasional CDC yang stabil.

#Snapshot Awal versus Streaming Perubahan

Fase snapshot mereplikasi kondisi database saat connector pertama berjalan; event pada fase ini memakai op bernilai r. Fase streaming menangkap perubahan setelah posisi snapshot, dengan op bernilai c, u, atau d. Perilaku snapshot dikontrol oleh snapshot.mode:

snapshot.mode: initial
snapshot.fetch.size: 2000
snapshot.max.threads: 4

Pilihan snapshot.mode harus disesuaikan dengan situasi. Untuk tabel kosong yang baru dibuat, schema_only lebih cepat. Untuk produksi, initial adalah default yang paling aman.

#Memahami Offset Storage, Restart, dan Recovery

Offset menyimpan posisi baca Debezium di log database — misalnya koordinat binlog MySQL atau LSN PostgreSQL. Data ini disimpan di topic connect-offsets dan di-commit secara berkala sesuai offset.flush.interval.ms.

offset.flush.interval.ms: 5000
offset.flush.timeout.ms: 5000

Saat container restart, Kafka Connect membaca offset yang tersimpan dan connector melanjutkan dari posisi tersebut:

docker compose restart connect
curl -s http://localhost:8083/connectors/inventory-connector/status

Jika offset hilang atau sengaja dihapus, Debezium akan memulai ulang snapshot sesuai snapshot.mode. Karena itu jangan pernah menghapus topic connect-offsets tanpa alasan yang jelas.

#Snapshot Chunking dan Initial Data Load

Untuk tabel berisi jutaan baris, snapshot tunggal akan menghabiskan memori dan memblokir streaming terlalu lama. Solusinya adalah incremental snapshot yang memecah pekerjaan menjadi chunk kecil dan menyelinginya dengan streaming perubahan nyata.

Pemicu incremental snapshot dilakukan lewat tabel sinyal. Definisikan tabel sinyal di konfigurasi:

{
  "signal.data.collection": "inventory.debezium_signal",
  "incremental.snapshot.chunk.size": "1024"
}

Lalu pancing snapshot dengan INSERT ke tabel sinyal:

Memulai incremental snapshot

INSERT INTO inventory.debezium_signal
  (id, type, data) VALUES
  ('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["inventory.customers"]}');

Dengan incremental.snapshot.chunk.size: 1024, Debezium membaca tabel per 1024 baris, menghasilkan event ber-op r, lalu kembali menangkap perubahan streaming di sela-sela chunk.

#Bagaimana Debezium Menangani Schema Changes

Skema database tidak statis; tabel sering mendapat kolom baru. Debezium menangani ini sesuai mekanisme tiap database:

• MySQL dan SQL Server: perubahan skema direkam ke topic schema history dan event DDL bisa dipublikasikan ke Kafka.
• PostgreSQL: skema dibaca langsung dari katalog internal, sehingga perubahan langsung dikenali.
• MongoDB: skema dianggap fleksibel, setiap dokumen membawa strukturnya sendiri.

Untuk MySQL, pastikan topic schema history selalu tersedia dan jangan diubah struktur event-nya:

{
  "include.schema.changes": "true",
  "schema.history.internal.kafka.topic": "schema-changes.inventory"
}

Dengan include.schema.changes: "true", setiap pernyataan DDL juga dikirim sebagai event, sehingga konsumen bisa menelusuri evolusi struktur tabel dari waktu ke waktu.

#Praktik Offset yang Sehat di Operasional

Beberapa praktik yang menjaga offset tetap sehat dalam jangka panjang:

• Pantau frekuensi commit: offset yang jarang di-commit berisiko kehilangan posisi lebih banyak saat crash.
• Backup topic offset: salin connect-offsets ke lokasi lain sebagai cadangan pemulihan.
• Jangan mengedit offset manual: memodifikasi byte offset secara manual hampir selalu berakhir dengan kerusakan posisi baca.

Jika offset benar-benar tidak bisa dipulihkan, opsi terakhir adalah menghapus offset dan membiarkan connector menjalankan snapshot ulang sesuai snapshot.mode. Proses ini mahal untuk tabel besar, jadi biasakan melakukan backup sebelum tindakan drastis.

#Penutup

Episode 4 menjelaskan siklus hidup data di Debezium: snapshot mengisi kondisi awal, streaming meneruskan perubahan, offset menjaga posisi saat restart, incremental snapshot menangani tabel besar, dan perubahan skema ditangani lewat schema history serta event DDL.

Inti yang harus dibawa pulang:

• Snapshot memakai op: r, streaming memakai op: c, u, atau d.
• Offset tersimpan di connect-offsets dan membuat restart tidak kehilangan posisi.
• Incremental snapshot membagi tabel besar menjadi chunk yang diselingi streaming.
• Schema history wajib dipertahankan untuk MySQL dan SQL Server.
• snapshot.mode harus dipilih sesuai kondisi database sumber.

Di episode 5 selanjutnya kita akan membedah payload format dan schema evolution — struktur event before, after, source, op, dan ts_ms, perbandingan JSON versus Avro versus Protobuf, serta integrasi dengan schema registry.