Debezium Week: Oracle Fixes, Offset Safety and a Docs Modularization Push

Debezium, the change data capture platform for Kafka Connect, saw 86 commits land on main in the past week. The diffstat reads 249 files changed, 8385 insertions and 1135 deletions across debezium/debezium. Roughly three themes dominate: Oracle connector reliability work, a change in how the engine treats failed final offset commits, and a sustained docs restructure into modular content blocks.

The Oracle connector received the most code attention, and the fixes target failure modes operators actually hit.

Zero dates were the classic one. Oracle happily stores 00-000-00 style dates, and downstream serialization chokes on them. The fix in d7b50d85 adds a ZeroDateFallbackConverter custom converter so you can map zero dates to a sane fallback value instead of watching a task fail mid streaming. The change touched OracleConnectorConfig.java and the LogMiner query builder, plus tests.

Two other Oracle fixes deserve attention:

  • af94b28d fixes an XStream crash when a change event contains an unknown column. The emitter now tolerates the condition instead of taking the task down.
  • fd67f792 resolves a NullPointerException in InfinispanLogMinerTransactionCache.addTransactionEvent after a restart with a persisted Infinispan buffer. The eventIds field came back null on recovery, so any connector using a durable in memory buffer on Oracle would crash on restart.

On the retry side, XStream attach now uses RetryingRunnable with a retriableWhen predicate (c57f8e10 and b46b3865). Attach failures that are transient no longer require a connector restart; the runnable decides which exceptions are worth retrying.

Two commits shifted how the engine treats offsets, and both change behavior at restart.

Wagner Santos contributed 16a6c5c7: the engine now fails its completion when the final offset commit fails. Before this, a connector could shut down cleanly while the last offsets never landed in Kafka, leaving the next startup to reprocess or, worse, to skip work silently. If you run connectors under automated restart policies, expect the task to surface an error instead of exiting green.

Chris Cranford’s 5d1a9f2d treats both rollback and commit as offset checkpoints. That closes a window where a transaction boundary would not advance the offset, forcing unnecessary event replay after a rebalance.

Two smaller fixes round out the operator facing list:

  • 2d5ef781 fixes a ReselectColumnsPostProcessor NPE with adjusted primary key field names.
  • 6eb66fc5 caches failed PostgreSQL type OID lookups. A dropped or unknown type no longer triggers a fresh lookup per event, which previously added overhead on every record of that type.

The HTTP notification channel shipped in Debezium for operator signal routing had no auth story. Two commits landed for that. 1eda137a adds authorization configuration to HttpNotificationChannel, and 09565e10 fixes the password pattern so credentials with authorization characters validate correctly. If you currently post notifications to an internal endpoint over plain HTTP, you can now require basic auth without patching the source.

For the reselect columns post processor, the RocksDB cache gained compaction control (270d546e and 46d15dbe). Setting the compaction value to 0 disables compaction entirely. On a connector that writes a stream of tiny tombstones to a reselect cache, aggressive default compaction can eat IOPS you would rather spend on the source database. Worth flipping if reselect is part of your pipeline.

Around 8000 of the insertions this week are documentation. The work tracks a modularization effort, refactoring connector pages into shared partials and fragments with explicit metadata. The most recent commit, a4c282ea, adds modularization annotations to headers in the Informix and SQL Server docs. Companions insert include directives and heading metadata (ce5fdaad) and rechunk the MariaDB and MySQL partials (552d7827).

The practical payoff: shared content like monitoring metrics and Kafka Connect deployment procedures lives in one file, cross referenced by every connector page. The diff excerpt shows the pattern, each section now carries Type, ModuleID, and Title comments for downstream tooling. oracle.adoc took 10 commits of this alone. 16021290 also documents the downstream link fixing rules in AGENTS.md, which tells you contributors are working with automated agents on this restructure.

A normal maintenance pass also landed:

  • MySQL and MariaDB CI jobs combined, and the Oracle 23.3.x job removed (01241ced, 104d2b09). Informix 12 left the test matrix (101ed9c2).
  • Driver bumps across the board: PostgreSQL to 42.7.14, Oracle ojdbc11 to 23.26.4.0.0, SingleStore to 1.2.12, StarRocks to 1.1.2, and the MySQL binlog reader to 0.42.0.
  • If you run Oracle connectors with a persisted Infinispan buffer, plan an upgrade before the next connector restart; the eventIds NPE fix is likely already in your queue.
  • Watch task exit codes after this offset commit change. A previously clean shutdown can now report failure when the final offset write fails, and your alerting should match that.
  • Track the modularization work in the connector docs. If you maintain a downstream fork of the documentation, include directives and xref criteria are changing under you.