Ürün Detayı

Debezium ile PostgreSQL'den Kafka'ya CDC

PostgreSQL için Debezium kurulumu, olay yapısı ve slot/WAL işletmesi.

Debezium, veritabanının işlem günlüğünü okuyup her satır değişikliğini bir Kafka topic'ine olay olarak yazar. Bu sayfa PostgreSQL kurulumunu ve işletirken karşınıza çıkacak tuzakları anlatır; CDC kavramının kendisi için Kafka CDC rehberine, Kafka'nın temelleri için Kafka nedir sayfasına bakın.

Bağlayıcıyı kaydetmeden önce PostgreSQL tarafı

Debezium, PostgreSQL'in mantıksal çözümlemesini (logical decoding) kullanır; bunun için sunucuda wal_level=logical olmalıdır. wal_level değişikliği PostgreSQL'in yeniden başlatılmasını gerektirir, bu yüzden bakım penceresine koyun. Çıktı eklentisi olarak pgoutput ya da decoderbufs seçilebilir; pgoutput PostgreSQL ile birlikte gelir, ayrıca kurulum istemez.

Bağlayıcı kaydında hangi parametreler önemli?

Kayıt, Kafka Connect'e gönderilen bir yapılandırmadır. Aşağıdaki parametreler PostgreSQL bağlayıcısının resmî belgesinden alınmıştır; tablo hangilerinin zorunlu olduğunu ayırmaz, zorunlu/isteğe bağlı ayrımı ve varsayılan değerler için resmî belgedeki özellik listesine bakın. Sürümünüze uygun tam örnek için "Connector configuration example" bölümünü temel alın.

Parametre	Ne belirler?
`database.hostname`, `database.port`, `database.user`, `database.password`, `database.dbname`	PostgreSQL bağlantısı ve izlenecek veritabanı
`topic.prefix`	Topic adlarının ön eki; olaylar `topic.prefix.şema.tablo` adlı topic'e yazılır
`plugin.name`	Mantıksal çözümleme eklentisi: `decoderbufs` veya `pgoutput`
`slot.name`	Bağlayıcının kullandığı replikasyon slotunun adı
`publication.name`	`pgoutput` kullanılırken tabloların yayınlandığı publication
`table.include.list`	İzlenecek tabloları daraltan isteğe bağlı süzgeç
`snapshot.mode`	İlk anlık görüntü davranışı; varsayılan `initial`
`heartbeat.interval.ms`	Heartbeat aralığı (WAL bölümüne bakın)

Eski örnekleri kopyalamayın: Debezium 1.x örneklerindeki database.server.name özelliği 2.0'da topic.prefix adını aldı (2.0.0.Final, 17 Ekim 2022). Eski bir örneği alıyorsanız bu özelliği topic.prefix olarak yazın.

Silme ve güncelleme olayında önceki değer ne zaman boş gelir?

Olayın türü op alanında durur: c ekleme, u güncelleme, d silme, r anlık görüntüden okuma, t truncate, m mesaj. Önceki değerlerin ne kadarının geleceğini tablonun REPLICA IDENTITY ayarı belirler. Varsayılan ayarda silmede birincil anahtar gelir, ama sıradan bir güncellemede önceki değer boştur.

REPLICA IDENTITY	Olay ve önceki değer
DEFAULT, DELETE	Birincil anahtar sütunlarının önceki değerleri
DEFAULT, UPDATE	Önceki değer yalnız anahtar sütunları değiştiyse gelir; sıradan güncellemede boştur
FULL	DELETE ve UPDATE'te tüm sütunların önceki değerleri
INDEX	DELETE'te belirtilen indeksteki sütunların önceki değerleri; UPDATE'te yalnız o sütunlar değiştiyse
NOTHING	Önceki değer bilgisi yok

Her güncellemede ve silmede tüm sütunların eski halini hedefte görmek istiyorsanız tabloyu FULL yapın (PostgreSQL mantıksal replikasyon protokolü: eski satırın tamamı yalnız FULL iken gönderilir); komut ALTER TABLE tablo_adi REPLICA IDENTITY FULL biçimindedir.

Silme olayında after alanı null olur, satırın artık var olmadığını gösterir. Bağlayıcı varsayılan olarak (tombstones.on.delete) ardından aynı anahtarlı, değeri null özel bir tombstone olayı da yazar. Tüketicinizde null değerli her kaydı hata saymayın; tombstone silmenin ikinci mesajıdır.

Slot ve WAL şişmesi: disk neden doluyor?

Hata: Bağlayıcı günlerdir kapalı, PostgreSQL diski doluyor. Neden: Replikasyon slotu tüketicisi bağlı olmasa da gereken WAL'ı tutar (PostgreSQL belgesi: slot "ihtiyaç duyulan kaynakların silinmesini engeller"). Çözüm: Bağlayıcı geri dönecekse önce onu yeniden çalıştırın. Slotu yalnız bağlayıcı kalıcı olarak kaldırıldıysa silin. Slotu silmek, bağlayıcının kaldığı yerden devam edememesi ve aradaki değişiklikler için yeni bir anlık görüntü (snapshot) gerekmesi demektir.
Hata: Bağlayıcı çalışıyor ama WAL büyüyor. Neden: İzlenen tablolar az değişiyor, aynı PostgreSQL örneğindeki diğer veritabanları yoğun yazılıyor; WAL tüm veritabanları için ortaktır ve Debezium okuyana kadar silinemez (Debezium blogu, 2020). Çözüm: heartbeat.interval.ms ile heartbeat açın.
Hata: Slot "lost" duruma geçti. Neden: Slotun gerektirdiği WAL artık tutulmuyor; max_slot_wal_keep_size negatif olmayan bir değerdeyse, slot bu sınırdan fazla geride kaldığında olur. Çözüm: lost slot artık kullanılamaz (PostgreSQL belgesi). Debezium belgesine göre bağlayıcı, ayarlı slot yoksa ve bağlanan kullanıcının yetkisi yeterliyse onu kendisi oluşturur. snapshot.mode=when_needed ise kayıtlı konum sunucuda artık yoksa yeniden anlık görüntü alır; varsayılan initial bunu kendiliğinden yapmaz.

Slotun durumunu şu sorguyla izleyin; wal_status sütunu reserved, extended, unreserved ya da lost döner.

SELECT slot_name, active, restart_lsn, confirmed_flush_lsn, wal_status
FROM pg_replication_slots;

Hangi sürümlerle çalışır?

26 Ekim 2026 itibarıyla Debezium'un güncel kararlı sürümü 3.7.0.Final (29 Eylül 2026).

Bileşen	Gereksinim
Java	Bağlayıcılar için 17+; Debezium Server, Operator, Outbox ve Quarkus uzantısı için 21+
Kafka Connect	3.1 ve sonrası
PostgreSQL	14, 15, 16, 17, 18
Diğer kararlı hatlar	3.6.3.Final (18 Eylül 2026), 2.7.4.Final (11 Aralık 2024)

Kaynak: debezium.io/releases. Sürümler sık değişir; kurulumdan önce sayfayı kontrol edin.

Debezium'un çevresindeki platform

Debezium olayları Kafka'ya yazdıktan sonra şemaları Schema Registry ile yönetebilir, Flink veya Spark ile akış işleyebilir, TLS ve rol tabanlı erişimle güvenliği kurabilirsiniz. Kurulum ve işletme desteği için Kafka danışmanlığı sayfasına, uçtan uca bir anlatım için CDC ve gerçek zamanlı veri aktarımı yazısına bakabilirsiniz.

Kafka & Debezium için iletişime geç

BIAnalytics