Debezium DB2 CDC Source Connector

Type

source

Class

io.debezium.connector.db2.Db2Connector

Target System

IBM Db2

Maintainer

Debezium / Red Hat

License

Apache License 2.0

Project

github.com/debezium/debezium

Download

Debezium Releases

This page documents version 3.5.0.Final. Newer versions should be compatible unless there are breaking changes, but field names or default values may differ. If you notice discrepancies, please contact Axual Support.

Description

The Debezium DB2 CDC Source Connector captures change events from IBM Db2 databases and publishes them as records to Kafka topics.

It relies on Db2’s built-in ASN Capture feature. ASN (Applied System Networking) is IBM Db2’s native replication subsystem. The Capture component reads the Db2 transaction log and writes row-level changes into dedicated change tables (CD tables) in the database. Debezium then reads from those CD tables to produce CDC events, without requiring direct access to the transaction log. This means ASN Capture must be enabled and running on the target database before the connector can start.

It is maintained by the Debezium community as part of the open-source github.com/debezium/debezium.

Schema history is stored in a dedicated Kafka topic so events are decoded correctly even after schema changes.

Features

Real-time Change Data Capture (CDC) from Db2 tables using ASN Capture
Captures inserts, updates, and deletes
Schema history stored in a dedicated Kafka topic
Axual-specific SSL key material managed via keyvault references
Stream name follows the convention <nickname>.<schema>.<table>

When to Use

You need real-time CDC from Db2 tables into Kafka.
You want to capture all DML events (inserts, updates, deletes) with low latency.

When NOT to Use

You only need periodic polling — use the JDBC Source Connector with a Db2 driver instead.
Db2 ASN Capture is not enabled on your database.

Installation

The connector is available from the Debezium Releases.

The Debezium DB2 connector requires the IBM Db2 JDBC driver (db2jcc4.jar) to be placed in the connector’s plugin directory. The driver must be obtained separately from the IBM Db2 JDBC Downloads page.

Navigate to the releases page and select the version matching your Kafka Connect installation.
Download the connector archive and extract the JAR files.
Download db2jcc4.jar from the IBM Db2 JDBC Downloads page and add it to the connector plugin directory.

For installation steps, see Installing Connector Plugins.

Configuration

For the complete configuration reference, see the official source connector documentation.

To configure a connector in Axual Self-Service, see Starting Connectors.

Axual Platform requirements

The Debezium DB2 connector maintains a schema history by writing to and reading from a dedicated Kafka topic (schema.history.internal.kafka.topic). On the Axual Platform, Kafka requires SSL authentication, so this internal connection must also be configured with the SSL credentials of the connector application. The SSL values are read from Axual’s keyvault at runtime using the ${keyvault:…} reference syntax.

Supply the following additional properties when running this connector on the Axual Platform.

auto.create.topics.enable

false

schema.history.internal.consumer.group.id

This consumer-group name must be resolved!

Example resolved value:
axual-local-default-db2_nickname-dbhistory

schema.history.internal.consumer.security.protocol

SSL

schema.history.internal.consumer.ssl.key.password

${keyvault:connectors/axual/local/default/my_db2_app:ssl.key.password}

schema.history.internal.consumer.ssl.keystore.location

${keyvault:connectors/axual/local/default/my_db2_app:ssl.keystore.location}

schema.history.internal.consumer.ssl.keystore.password

${keyvault:connectors/axual/local/default/my_db2_app:ssl.keystore.password}

schema.history.internal.consumer.ssl.truststore.location

${keyvault:connectors/axual/local/default/my_db2_app:ssl.truststore.location}

schema.history.internal.consumer.ssl.truststore.password

${keyvault:connectors/axual/local/default/my_db2_app:ssl.truststore.password}

schema.history.internal.producer.security.protocol

SSL

schema.history.internal.producer.ssl.key.password

${keyvault:connectors/axual/local/default/my_db2_app:ssl.key.password}

schema.history.internal.producer.ssl.keystore.location

${keyvault:connectors/axual/local/default/my_db2_app:ssl.keystore.location}

schema.history.internal.producer.ssl.keystore.password

${keyvault:connectors/axual/local/default/my_db2_app:ssl.keystore.password}

schema.history.internal.producer.ssl.truststore.location

${keyvault:connectors/axual/local/default/my_db2_app:ssl.truststore.location}

schema.history.internal.producer.ssl.truststore.password

${keyvault:connectors/axual/local/default/my_db2_app:ssl.truststore.password}

Getting Started

Prerequisites

Db2 instance with ASN Capture enabled

You need a running IBM Db2 instance with ASN Capture configured on the target database.

Enable ASN Capture on the target table:

-- Enable CDC on the table
CALL ASNCDC.ADDTABLE('TESTDB', 'HOTEL');
CALL ASNCDC.ASNCDCSERVICES('start', 'asncdc');

Axual name-resolving properties

Some properties require Axual’s custom name-resolving mechanism.
Consult an Axual platform operator to acquire the following information:

Tenant shortName

Example value:
axual

Instance shortName

Example value:
local

Environment shortName

Example value:
default

Connect-Application shortName

This value is already provided. We’ll use:
my_db2_app

Resolving pattern for topic-names

Example pattern:
${tenant-shortName}-${instance-shortName}-${environment-shortName}-${topic-name}
Example resolved topic name:
axual-local-default-transactions

Resolving pattern for consumer-groups

Example pattern:
${tenant-shortName}-${instance-shortName}-${environment-shortName}-${consumerGroup-name}
Example resolved consumer group:
axual-local-default-com.axual.transactionProcessor

Axual streams

Follow the Creating streams documentation to create and deploy the following streams:

db2_nickname._schema-changes — Stores the database schema history.
db2_nickname.TESTDB.HOTEL — Contains DB events for the HOTEL table.
Stream name follows the pattern <nickname>.<schema>.<table>. Create one per watched table.

All streams should use Key/Value type String/String, Partition count 1, Retention Time 157680000000 (5 years).

Steps

Step 1 — Create a connector application

Follow the Configure and install a connector documentation to set up a new Connector-Application.
Let’s call it my_db2_app.
The plugin name is io.debezium.connector.db2.Db2Connector.
If a plugin isn’t available, ask a platform operator to install plugins.

Use the following application ID: db2_nickname-dbhistory.

Step 2 — Configure the connector

Provide the following configuration:

database.hostname

Example value:
123.123.123.123

database.port

50000

database.user

db2inst1

database.password

Example value:
1234abcdEFG

database.dbname

TESTDB

topic.prefix

db2_nickname

table.include.list

Example value:
TESTDB.HOTEL

schema.history.internal.kafka.bootstrap.servers

Example values:
- Local (helm platform): platform.local:31757
- Axual-Cloud rokin cluster: bootstrap-c1-ams01-azure.axual.cloud:9094
- SAAS trial: oberon-kafka-bootstrap.axual.cloud:9094

schema.history.internal.kafka.topic

This topic name must be resolved! Use the name-resolving values acquired above.

Example resolved value:
axual-local-default-db2_nickname._schema-changes

Supply the Axual Platform-required properties described in [_axual_platform_requirements].

Step 3 — Start the connector

Authorize the my_db2_app source connector application to produce to and consume from all streams:

db2_nickname._schema-changes
db2_nickname.TESTDB.HOTEL

Then start the connector application from Axual Self-Service.

Step 4 — Verify

In Axual Self-Service, use stream-browse on db2_nickname.TESTDB.HOTEL to confirm CDC events are arriving when rows are inserted or updated in Db2.

Cleanup

When you are done:

Stop the connector application in Axual Self-Service.
Remove stream access for the application if no longer needed.

Known limitations

Db2 ASN Capture must be enabled on the target database before starting the connector.
The IBM Db2 JDBC driver (db2jcc4.jar) must be manually provided — it is not bundled with the connector.
The schema.history.internal.kafka.topic value must be resolved using Axual’s name-resolving mechanism before the connector can be started.
SSL configuration values must use the keyvault: prefix format specific to Axual.

Examples

Full configuration on Axual Platform

{
  "name": "my-debezium-db2-source",
  "config": {
    "connector.class": "io.debezium.connector.db2.Db2Connector",
    "tasks.max": "1",
    "database.hostname": "db2.example.com",
    "database.port": "50000",
    "database.user": "db2inst1",
    "database.password": "Deb3zium@Db2Pass",
    "database.dbname": "TESTDB",
    "topic.prefix": "db2_nickname",
    "table.include.list": "TESTDB.HOTEL",
    "topic.creation.enable": "false",
    "snapshot.mode": "initial",
    "key.converter": "org.apache.kafka.connect.json.JsonConverter",
    "key.converter.schemas.enable": "false",
    "value.converter": "org.apache.kafka.connect.json.JsonConverter",
    "value.converter.schemas.enable": "false",
    "schema.history.internal.kafka.bootstrap.servers": "kafka.axual.example.com:9093",
    "schema.history.internal.kafka.topic": "axual-myinstance-exampleenvironment-schema-history-db2",
    "schema.history.internal.consumer.group.id": "my-debezium-db2-app",
    "schema.history.internal.consumer.security.protocol": "SSL",
    "schema.history.internal.consumer.ssl.keystore.location": "${keyvault:connectors/<tenant>/<instance>/<environment>/<application>:ssl.keystore.location}",
    "schema.history.internal.consumer.ssl.keystore.password": "${keyvault:connectors/<tenant>/<instance>/<environment>/<application>:ssl.keystore.password}",
    "schema.history.internal.consumer.ssl.key.password": "${keyvault:connectors/<tenant>/<instance>/<environment>/<application>:ssl.key.password}",
    "schema.history.internal.consumer.ssl.truststore.location": "${keyvault:connectors/<tenant>/<instance>/<environment>/<application>:ssl.truststore.location}",
    "schema.history.internal.consumer.ssl.truststore.password": "${keyvault:connectors/<tenant>/<instance>/<environment>/<application>:ssl.truststore.password}",
    "schema.history.internal.producer.security.protocol": "SSL",
    "schema.history.internal.producer.ssl.keystore.location": "${keyvault:connectors/<tenant>/<instance>/<environment>/<application>:ssl.keystore.location}",
    "schema.history.internal.producer.ssl.keystore.password": "${keyvault:connectors/<tenant>/<instance>/<environment>/<application>:ssl.keystore.password}",
    "schema.history.internal.producer.ssl.key.password": "${keyvault:connectors/<tenant>/<instance>/<environment>/<application>:ssl.key.password}",
    "schema.history.internal.producer.ssl.truststore.location": "${keyvault:connectors/<tenant>/<instance>/<environment>/<application>:ssl.truststore.location}",
    "schema.history.internal.producer.ssl.truststore.password": "${keyvault:connectors/<tenant>/<instance>/<environment>/<application>:ssl.truststore.password}",
    "errors.log.enable": "true",
    "errors.log.include.messages": "true",
    "errors.tolerance": "none"
  }
}

License

Debezium source connector is licensed under the Apache License, Version 2.0.