Debezium connector for Db2

Overview

The Debezium Db2 connector is based on the ASN Capture/Apply agents that enable SQL Replication in Db2. A capture agent:

• Generates change-data tables for tables that are in capture mode.

• Monitors tables in capture mode and stores change events for updates to those tables in their corresponding change-data tables.

The Debezium connector uses a SQL interface to query change-data tables for change events.

The database administrator must put the tables for which you want to capture changes into capture mode. For convenience and for automating testing, there are Debezium user-defined functions (UDFs) in C that you can compile and then use to do the following management tasks:

• Start, stop, and reinitialize the ASN agent

• Put tables into capture mode

• Create the replication (ASN) schemas and change-data tables

• Remove tables from capture mode

Alternatively, you can use Db2 control commands to accomplish these tasks.

After the tables of interest are in capture mode, the connector reads their corresponding change-data tables to obtain change events for table updates. The connector emits a change event for each row-level insert, update, and delete operation to a Kafka topic that has the same name as the changed table. This is default behavior that you can modify. Client applications read the Kafka topics that correspond to the database tables of interest and can react to each row-level change event.

Typically, the database administrator puts a table into capture mode in the middle of the life of a table. This means that the connector does not have the complete history of all changes that have been made to the table. Therefore, when the Db2 connector first connects to a particular Db2 database, it starts by performing a consistent snapshot of each table that is in capture mode. After the connector completes the snapshot, the connector streams change events from the point at which the snapshot was made. In this way, the connector starts with a consistent view of the tables that are in capture mode, and does not drop any changes that were made while it was performing the snapshot.

Debezium connectors are tolerant of failures. As the connector reads and produces change events, it records the log sequence number (LSN) of the change-data table entry. The LSN is the position of the change event in the database log. If the connector stops for any reason, including communication failures, network problems, or crashes, upon restarting it continues reading the change-data tables where it left off. This includes snapshots. That is, if the snapshot was not complete when the connector stopped, upon restart the connector begins a new snapshot.

How the connector works

To optimally configure and run a Debezium Db2 connector, it is helpful to understand how the connector performs snapshots, streams change events, determines Kafka topic names, and handles schema changes.

Snapshots

Db2`s replication feature is not designed to store the complete history of database changes. Consequently, when a Debezium Db2 connector connects to a database for the first time, it takes a consistent snapshot of tables that are in capture mode and streams this state to Kafka. This establishes the baseline for table content.

By default, when a Db2 connector performs a snapshot, it does the following:

1. Determines which tables are in capture mode, and thus must be included in the snapshot. By default, all non-system tables are in capture mode. Connector configuration properties, such as table.exclude.list and table.include.list let you specify which tables should be in capture mode.

2. Obtains a lock on each of the tables in capture mode. This ensures that no schema changes can occur in those tables during the snapshot. The level of the lock is determined by the snapshot.isolation.mode connector configuration property.

3. Reads the highest (most recent) LSN position in the server’s transaction log.

4. Captures the schema of all tables that are in capture mode. The connector persists this information in its internal database history topic.

5. Optional, releases the locks obtained in step 2. Typically, these locks are held for only a short time.

6. At the LSN position read in step 3, the connector scans the capture mode tables as well as their schemas. During the scan, the connector:

   1. Confirms that the table was created before the start of the snapshot. If it was not, the snapshot skips that table. After the snapshot is complete, and the connector starts emitting change events, the connector produces change events for any tables that were created during the snapshot.

   2. Produces a read event for each row in each table that is in capture mode. All read events contain the same LSN position, which is the LSN position that was obtained in step 3.

   3. Emits each read event to the Kafka topic that has the same name as the table.

7. Records the successful completion of the snapshot in the connector offsets.

Change-data tables

After a complete snapshot, when a Debezium Db2 connector starts for the first time, the connector identifies the change-data table for each source table that is in capture mode. The connector does the following for each change-data table:

1. Reads change events that were created between the last stored, highest LSN and the current, highest LSN.

2. Orders the change events according to the commit LSN and the change LSN for each event. This ensures that the connector emits the change events in the order in which the table changes occurred.

3. Passes commit and change LSNs as offsets to Kafka Connect.

4. Stores the highest LSN that the connector passed to Kafka Connect.

After a restart, the connector resumes emitting change events from the offset (commit and change LSNs) where it left off. While the connector is running and emitting change events, if you remove a table from capture mode or add a table to capture mode, the connector detects this and modifies its behavior accordingly.

Topic names

By default, the Db2 connector writes change events for all insert, update, and delete operations on a single table to a single Kafka topic. The name of the Kafka topic has the following format:

databaseName.schemaName.tableName

databaseName

The logical name of the connector as specified with the database.server.name connector configuration property.

schemaName

The name of the schema in which the operation occurred.

tableName

The name of the table in which the operation occurred.

For example, consider a Db2 installation with the mydatabase database, which contains four tables: PRODUCTS, PRODUCTS_ON_HAND, CUSTOMERS, and ORDERS that are in the MYSCHEMA schema. The connector would emit events to these four Kafka topics:

• mydatabase.MYSCHEMA.PRODUCTS

• mydatabase.MYSCHEMA.PRODUCTS_ON_HAND

• mydatabase.MYSCHEMA.CUSTOMERS

• mydatabase.MYSCHEMA.ORDERS

To configure a Db2 connector to emit change events to differently-named Kafka topics, see the documentation for the topic routing transformation.

Schema change topic

For a table that is in capture mode, the Debezium Db2 connector stores the history of schema changes to that table in a database history topic. This topic reflects an internal connector state and you should not use it. If your application needs to track schema changes, there is a public schema change topic. The name of the schema change topic is the same as the logical server name specified in the connector configuration.

Debezium emits a message to the schema change topic when:

• A new table goes into capture mode.

• A table is removed from capture mode.

• During a database schema update, there is a change in the schema for a table that is in capture mode.

A message to the schema change topic contains a logical representation of the table schema, for example:

{
  "schema": {
  ...
  },
  "payload": {
    "source": {
      "version": "1.4.2.Final",
      "connector": "db2",
      "name": "db2",
      "ts_ms": 1588252618953,
      "snapshot": "true",
      "db": "testdb",
      "schema": "DB2INST1",
      "table": "CUSTOMERS",
      "change_lsn": null,
      "commit_lsn": "00000025:00000d98:00a2",
      "event_serial_no": null
    },
    "databaseName": "TESTDB", (1)
    "schemaName": "DB2INST1",
    "ddl": null, (2)
    "tableChanges": [ (3)
      {
        "type": "CREATE", (4)
        "id": "\"DB2INST1\".\"CUSTOMERS\"", (5)
        "table": { (6)
          "defaultCharsetName": null,
          "primaryKeyColumnNames": [ (7)
            "ID"
          ],
          "columns": [ (8)
            {
              "name": "ID",
              "jdbcType": 4,
              "nativeType": null,
              "typeName": "int identity",
              "typeExpression": "int identity",
              "charsetName": null,
              "length": 10,
              "scale": 0,
              "position": 1,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            },
            {
              "name": "FIRST_NAME",
              "jdbcType": 12,
              "nativeType": null,
              "typeName": "varchar",
              "typeExpression": "varchar",
              "charsetName": null,
              "length": 255,
              "scale": null,
              "position": 2,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            },
            {
              "name": "LAST_NAME",
              "jdbcType": 12,
              "nativeType": null,
              "typeName": "varchar",
              "typeExpression": "varchar",
              "charsetName": null,
              "length": 255,
              "scale": null,
              "position": 3,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            },
            {
              "name": "EMAIL",
              "jdbcType": 12,
              "nativeType": null,
              "typeName": "varchar",
              "typeExpression": "varchar",
              "charsetName": null,
              "length": 255,
              "scale": null,
              "position": 4,
              "optional": false,
              "autoIncremented": false,
              "generated": false
            }
          ]
        }
      }
    ]
  }
}

In messages to the schema change topic, the key is the name of the database that contains the schema change. In the following example, the payload field contains the key:

{
  "schema": {
    "type": "struct",
    "fields": [
      {
        "type": "string",
        "optional": false,
        "field": "databaseName"
      }
    ],
    "optional": false,
    "name": "io.debezium.connector.db2.SchemaChangeKey"
  },
  "payload": {
    "databaseName": "TESTDB"
  }
}

Transaction metadata

Debezium can generate events that represent transaction boundaries and that enrich change data event messages. For every transaction BEGIN and END, Debezium generates an event that contains the following fields:

• status - BEGIN or END

• id - string representation of unique transaction identifier

• event_count (for END events) - total number of events emitted by the transaction

• data_collections (for END events) - an array of pairs of data_collection and event_count that provides the number of events emitted by changes originating from the given data collection

Example

{
  "status": "BEGIN",
  "id": "00000025:00000d08:0025",
  "event_count": null,
  "data_collections": null
}
{
  "status": "END",
  "id": "00000025:00000d08:0025",
  "event_count": 2,
  "data_collections": [
    {
      "data_collection": "testDB.dbo.tablea",
      "event_count": 1
    },
    {
      "data_collection": "testDB.dbo.tableb",
      "event_count": 1
    }
  ]
}

The connector emits transaction events to the *database.server.name*.transaction topic.

Data change event enrichment

When transaction metadata is enabled the connector enriches the change event Envelope with a new transaction field. This field provides information about every event in the form of a composite of fields:

• id - string representation of unique transaction identifier

• total_order - absolute position of the event among all events generated by the transaction

• data_collection_order - the per-data collection position of the event among all events that were emitted by the transaction

Following is an example of a message:

{
  "before": null,
  "after": {
    "pk": "2",
    "aa": "1"
  },
  "source": {
...
  },
  "op": "c",
  "ts_ms": "1580390884335",
  "transaction": {
    "id": "00000025:00000d08:0025",
    "total_order": "1",
    "data_collection_order": "1"
  }
}

Data change events

The Debezium Db2 connector generates a data change event for each row-level INSERT, UPDATE, and DELETE operation. Each event contains a key and a value. The structure of the key and the value depends on the table that was changed.

Debezium and Kafka Connect are designed around continuous streams of event messages. However, the structure of these events may change over time, which can be difficult for consumers to handle. To address this, each event contains the schema for its content or, if you are using a schema registry, a schema ID that a consumer can use to obtain the schema from the registry. This makes each event self-contained.

The following skeleton JSON shows the basic four parts of a change event. However, how you configure the Kafka Connect converter that you choose to use in your application determines the representation of these four parts in change events. A schema field is in a change event only when you configure the converter to produce it. Likewise, the event key and event payload are in a change event only if you configure a converter to produce it. If you use the JSON converter and you configure it to produce all four basic change event parts, change events have this structure:

{
 "schema": { (1)
   ...
  },
 "payload": { (2)
   ...
 },
 "schema": { (3)
   ...
 },
 "payload": { (4)
   ...
 },
}

By default, the connector streams change event records to topics with names that are the same as the event’s originating table. See topic names.

Change event keys

A change event’s key contains the schema for the changed table’s key and the changed row’s actual key. Both the schema and its corresponding payload contain a field for each column in the changed table’s PRIMARY KEY (or unique constraint) at the time the connector created the event.

Consider the following customers table, which is followed by an example of a change event key for this table.

Example table

CREATE TABLE customers (
 ID INTEGER IDENTITY(1001,1) NOT NULL PRIMARY KEY,
 FIRST_NAME VARCHAR(255) NOT NULL,
 LAST_NAME VARCHAR(255) NOT NULL,
 EMAIL VARCHAR(255) NOT NULL UNIQUE
);

Example change event key

Every change event that captures a change to the customers table has the same event key schema. For as long as the customers table has the previous definition, every change event that captures a change to the customers table has the following key structure. In JSON, it looks like this:

{
    "schema": {  (1)
        "type": "struct",
        "fields": [  (2)
            {
                "type": "int32",
                "optional": false,
                "field": "ID"
            }
        ],
        "optional": false,  (3)
        "name": "mydatabase.MYSCHEMA.CUSTOMERS.Key"  (4)
    },
    "payload": {  (5)
        "ID": 1004
    }
}

Change event values

The value in a change event is a bit more complicated than the key. Like the key, the value has a schema section and a payload section. The schema section contains the schema that describes the Envelope structure of the payload section, including its nested fields. Change events for operations that create, update or delete data all have a value payload with an envelope structure.

Consider the same sample table that was used to show an example of a change event key:

Example table

CREATE TABLE customers (
 ID INTEGER IDENTITY(1001,1) NOT NULL PRIMARY KEY,
 FIRST_NAME VARCHAR(255) NOT NULL,
 LAST_NAME VARCHAR(255) NOT NULL,
 EMAIL VARCHAR(255) NOT NULL UNIQUE
);

The event value portion of every change event for the customers table specifies the same schema. The event value’s payload varies according to the event type:

• create events

• update events

• delete events

create events

The following example shows the value portion of a change event that the connector generates for an operation that creates data in the customers table:

{
  "schema": {  (1)
    "type": "struct",
    "fields": [
      {
        "type": "struct",
        "fields": [
          {
            "type": "int32",
            "optional": false,
            "field": "ID"
          },
          {
            "type": "string",
            "optional": false,
            "field": "FIRST_NAME"
          },
          {
            "type": "string",
            "optional": false,
            "field": "LAST_NAME"
          },
          {
            "type": "string",
            "optional": false,
            "field": "EMAIL"
          }
        ],
        "optional": true,
        "name": "mydatabase.MYSCHEMA.CUSTOMERS.Value",  (2)
        "field": "before"
      },
      {
        "type": "struct",
        "fields": [
          {
            "type": "int32",
            "optional": false,
            "field": "ID"
          },
          {
            "type": "string",
            "optional": false,
            "field": "FIRST_NAME"
          },
          {
            "type": "string",
            "optional": false,
            "field": "LAST_NAME"
          },
          {
            "type": "string",
            "optional": false,
            "field": "EMAIL"
          }
        ],
        "optional": true,
        "name": "mydatabase.MYSCHEMA.CUSTOMERS.Value",
        "field": "after"
      },
      {
        "type": "struct",
        "fields": [
          {
            "type": "string",
            "optional": false,
            "field": "version"
          },
          {
            "type": "string",
            "optional": false,
            "field": "connector"
          },
          {
            "type": "string",
            "optional": false,
            "field": "name"
          },
          {
            "type": "int64",
            "optional": false,
            "field": "ts_ms"
          },
          {
            "type": "boolean",
            "optional": true,
            "default": false,
            "field": "snapshot"
          },
          {
            "type": "string",
            "optional": false,
            "field": "db"
          },
          {
            "type": "string",
            "optional": false,
            "field": "schema"
          },
          {
            "type": "string",
            "optional": false,
            "field": "table"
          },
          {
            "type": "string",
            "optional": true,
            "field": "change_lsn"
          },
          {
            "type": "string",
            "optional": true,
            "field": "commit_lsn"
          },
        ],
        "optional": false,
        "name": "io.debezium.connector.db2.Source",  (3)
        "field": "source"
      },
      {
        "type": "string",
        "optional": false,
        "field": "op"
      },
      {
        "type": "int64",
        "optional": true,
        "field": "ts_ms"
      }
    ],
    "optional": false,
    "name": "mydatabase.MYSCHEMA.CUSTOMERS.Envelope"  (4)
  },
  "payload": {  (5)
    "before": null,  (6)
    "after": {  (7)
      "ID": 1005,
      "FIRST_NAME": "john",
      "LAST_NAME": "doe",
      "EMAIL": "john.doe@example.org"
    },
    "source": {  (8)
      "version": "1.4.2.Final",
      "connector": "db2",
      "name": "myconnector",
      "ts_ms": 1559729468470,
      "snapshot": false,
      "db": "mydatabase",
      "schema": "MYSCHEMA",
      "table": "CUSTOMERS",
      "change_lsn": "00000027:00000758:0003",
      "commit_lsn": "00000027:00000758:0005",
    },
    "op": "c",  (9)
    "ts_ms": 1559729471739  (10)
  }
}

update events

The value of a change event for an update in the sample customers table has the same schema as a create event for that table. Likewise, the update event value’s payload has the same structure. However, the event value payload contains different values in an update event. Here is an example of a change event value in an event that the connector generates for an update in the customers table:

{
  "schema": { ... },
  "payload": {
    "before": {  (1)
      "ID": 1005,
      "FIRST_NAME": "john",
      "LAST_NAME": "doe",
      "EMAIL": "john.doe@example.org"
    },
    "after": {  (2)
      "ID": 1005,
      "FIRST_NAME": "john",
      "LAST_NAME": "doe",
      "EMAIL": "noreply@example.org"
    },
    "source": {  (3)
      "version": "1.4.2.Final",
      "connector": "db2",
      "name": "myconnector",
      "ts_ms": 1559729995937,
      "snapshot": false,
      "db": "mydatabase",
      "schema": "MYSCHEMA",
      "table": "CUSTOMERS",
      "change_lsn": "00000027:00000ac0:0002",
      "commit_lsn": "00000027:00000ac0:0007",
    },
    "op": "u",  (4)
    "ts_ms": 1559729998706  (5)
  }
}

delete events

The value in a delete change event has the same schema portion as create and update events for the same table. The event value payload in a delete event for the sample customers table looks like this:

{
  "schema": { ... },
  },
  "payload": {
    "before": {  (1)
      "ID": 1005,
      "FIRST_NAME": "john",
      "LAST_NAME": "doe",
      "EMAIL": "noreply@example.org"
    },
    "after": null,  (2)
    "source": {  (3)
      "version": "1.4.2.Final",
      "connector": "db2",
      "name": "myconnector",
      "ts_ms": 1559730445243,
      "snapshot": false,
      "db": "mydatabase",
      "schema": "MYSCHEMA",
      "table": "CUSTOMERS",
      "change_lsn": "00000027:00000db0:0005",
      "commit_lsn": "00000027:00000db0:0007"
    },
    "op": "d",  (4)
    "ts_ms": 1559730450205  (5)
  }
}

A delete change event record provides a consumer with the information it needs to process the removal of this row. The old values are included because some consumers might require them in order to properly handle the removal.

Db2 connector events are designed to work with Kafka log compaction. Log compaction enables removal of some older messages as long as at least the most recent message for every key is kept. This lets Kafka reclaim storage space while ensuring that the topic contains a complete data set and can be used for reloading key-based state.

When a row is deleted, the delete event value still works with log compaction, because Kafka can remove all earlier messages that have that same key. However, for Kafka to remove all messages that have that same key, the message value must be null. To make this possible, after Debezium’s Db2 connector emits a delete event, the connector emits a special tombstone event that has the same key but a null value.

Data type mappings

Db2’s data types are described in Db2 SQL Data Types.

The Db2 connector represents changes to rows with events that are structured like the table in which the row exists. The event contains a field for each column value. How that value is represented in the event depends on the Db2 data type of the column. This section describes these mappings.

Basic types

The following table describes how the connector maps each of the Db2 data types to a literal type and a semantic type in event fields.

• literal type describes how the value is represented using Kafka Connect schema types: INT8, INT16, INT32, INT64, FLOAT32, FLOAT64, BOOLEAN, STRING, BYTES, ARRAY, MAP, and STRUCT.

• semantic type describes how the Kafka Connect schema captures the meaning of the field using the name of the Kafka Connect schema for the field.

If present, a column’s default value is propagated to the corresponding field’s Kafka Connect schema. Change events contain the field’s default value unless an explicit column value had been given. Consequently, there is rarely a need to obtain the default value from the schema. Passing the default value helps satisfy compatibility rules when using Avro as the serialization format together with the Confluent schema registry.

Temporal types

Other than Db2’s DATETIMEOFFSET data type, which contains time zone information, how temporal types are mapped depends on the value of the time.precision.mode connector configuration property. The following sections describe these mappings:

• time.precision.mode=adaptive

• time.precision.mode=connect

time.precision.mode=adaptive

When the time.precision.mode configuration property is set to adaptive, the default, the connector determines the literal type and semantic type based on the column’s data type definition. This ensures that events exactly represent the values in the database.

time.precision.mode=connect

When the time.precision.mode configuration property is set to connect, the connector uses Kafka Connect logical types. This may be useful when consumers can handle only the built-in Kafka Connect logical types and are unable to handle variable-precision time values. However, since Db2 supports tenth of a microsecond precision, the events generated by a connector with the connect time precision results in a loss of precision when the database column has a fractional second precision value that is greater than 3.

Timestamp types

The DATETIME, SMALLDATETIME and DATETIME2 types represent a timestamp without time zone information. Such columns are converted into an equivalent Kafka Connect value based on UTC. For example, the DATETIME2 value “2018-06-20 15:13:16.945104” is represented by an io.debezium.time.MicroTimestamp with the value “1529507596945104”.

The timezone of the JVM running Kafka Connect and Debezium does not affect this conversion.

Decimal types

Setting up Db2

For Debezium to capture change events that are committed to Db2 tables, a Db2 database administrator with the necessary privileges must configure tables in the database for change data capture. After you begin to run Debezium you can adjust the configuration of the capture agent to optimize performance.

Putting tables into capture mode

To put tables into capture mode, Debezium provides a set of user-defined functions (UDFs) for your convenience. The procedure here shows how to install and run these management UDFs. Alternatively, you can run Db2 control commands to put tables into capture mode. The administrator must then enable CDC for each table that you want Debezium to capture.

Prerequisites

• You are logged in to Db2 as the db2instl user.

• On the Db2 host, the Debezium management UDFs are available in the $HOME/asncdctools/src directory. UDFs are available from the Debezium examples repository.

Procedure

1. Compile the Debezium management UDFs on the Db2 server host by using the bldrtn command provided with Db2:

   cd $HOME/asncdctools/src

   ./bldrtn asncdc

2. Start the database if it is not already running. Replace DB_NAME with the name of the database that you want Debezium to connect to.

   db2 start db DB_NAME

3. Ensure that JDBC can read the Db2 metadata catalog:

   cd $HOME/sqllib/bnd

   db2 bind db2schema.bnd blocking all grant public sqlerror continue

4. Ensure that the database was recently backed-up. The ASN agents must have a recent starting point to read from. If you need to perform a backup, run the following commands, which prune the data so that only the most recent version is available. If you do not need to retain the older versions of the data, specify dev/null for the backup location.

   1. Back up the database. Replace DB_NAME and BACK_UP_LOCATION with appropriate values:

      db2 backup db DB_NAME to BACK_UP_LOCATION

   2. Restart the database:

      db2 restart db DB_NAME

5. Connect to the database to install the Debezium management UDFs. It is assumed that you are logged in as the db2instl user so the UDFs should be installed on the db2inst1 user.

   db2 connect to DB_NAME

6. Copy the Debezium management UDFs and set permissions for them:

   cp $HOME/asncdctools/src/asncdc $HOME/sqllib/function

   chmod 777 $HOME/sqllib/function

7. Enable the Debezium UDF that starts and stops the ASN capture agent:

   db2 -tvmf $HOME/asncdctools/src/asncdc_UDF.sql

8. Create the ASN control tables:

   $ db2 -tvmf $HOME/asncdctools/src/asncdctables.sql

9. Enable the Debezium UDF that adds tables to capture mode and removes tables from capture mode:

   $ db2 -tvmf $HOME/asncdctools/src/asncdcaddremove.sql

   After you set up the Db2 server, use the UDFs to control Db2 replication (ASN) with SQL commands. Some of the UDFs expect a return value in which case you use the SQL VALUE statement to invoke them. For other UDFs, use the SQL CALL statement.

10. Start the ASN agent:

    VALUES ASNCDC.ASNCDCSERVICES('start','asncdc');

11. Put tables into capture mode. Invoke the following statement for each table that you want to put into capture. Replace MYSCHEMA with the name of the schema that contains the table you want to put into capture mode. Likewise, replace MYTABLE with the name of the table to put into capture mode:

    CALL ASNCDC.ADDTABLE('MYSCHEMA', 'MYTABLE');

12. Reinitialize the ASN service:

    VALUES ASNCDC.ASNCDCSERVICES('reinit','asncdc');

Additional resource

Reference table for Debezium Db2 management UDFs

Effect of Db2 capture agent configuration on server load and latency

When a database administrator enables change data capture for a source table, the capture agent begins to run. The agent reads new change event records from the transaction log and replicates the event records to a capture table. Between the time that a change is committed in the source table, and the time that the change appears in the corresponding change table, there is always a small latency interval. This latency interval represents a gap between when changes occur in the source table and when they become available for Debezium to stream to Apache Kafka.

Ideally, for applications that must respond quickly to changes in data, you want to maintain close synchronization between the source and capture tables. You might imagine that running the capture agent to continuously process change events as rapidly as possible might result in increased throughput and reduced latency — populating change tables with new event records as soon as possible after the events occur, in near real time. However, this is not necessarily the case. There is a performance penalty to pay in the pursuit of more immediate synchronization. Each time that the change agent queries the database for new event records, it increases the CPU load on the database host. The additional load on the server can have a negative effect on overall database performance, and potentially reduce transaction efficiency, especially during times of peak database use.

It’s important to monitor database metrics so that you know if the database reaches the point where the server can no longer support the capture agent’s level of activity. If you experience performance issues while running the capture agent, adjust capture agent settings to reduce CPU load.

Db2 capture agent configuration parameters

On Db2, the IBMSNAP_CAPPARMS table contains parameters that control the behavior of the capture agent. You can adjust the values for these parameters to balance the configuration of the capture process to reduce CPU load and still maintain acceptable levels of latency.

In the IBMSNAP_CAPPARMS table, the following parameters have the greatest effect on reducing CPU load:

COMMIT_INTERVAL

• Specifies the number of seconds that the capture agent waits to commit data to the change data tables.

• A higher value reduces the load on the database host and increases latency.

• The default value is 30.

SLEEP_INTERVAL

• Specifies the number of seconds that the capture agent waits to start a new commit cycle after it reaches the end of the active transaction log.

• A higher value reduces the load on the server, and increases latency.

• The default value is 5.

Additional resources

• For more information about capture agent parameters, see the Db2 documentation.

Deployment

To deploy a Debezium Db2 connector, you install the Debezium Db2 connector archive, configure the connector, and start the connector by adding its configuration to Kafka Connect.

Prerequisites

• Apache ZooKeeper, Apache Kafka, and Kafka Connect are installed.

• Db2 is installed and capture mode is enabled for tables to prepare the database to be used with the Debezium connector.

Procedure

1. Download the connector’s plug-in archive.

2. Extract the JAR files into your Kafka Connect environment.

3. Add the directory with the JAR files to Kafka Connect’s plugin.path.

4. Obtain the JDBC driver for Db2.

5. Add the JDBC driver JAR file to the directory with the Debezium Db2 connector JARs.

6. Configure the connector and add the configuration to your Kafka Connect cluster.

7. Restart your Kafka Connect process to pick up the new JAR files.

If you are working with immutable containers, see Debezium’s container images for Apache ZooKeeper, Apache Kafka and Kafka Connect with the Db2 connector already installed and ready to run.

You can also run Debezium on Kubernetes and OpenShift.

Db2 connector configuration example

Following is an example of the configuration for a connector instance that captures data from a Db2 server on port 50000 at 192.168.99.100, which we logically name fullfillment. Typically, you configure the Debezium Db2 connector in a JSON file by setting the configuration properties that are available for the connector.

You can choose to produce events for a subset of the schemas and tables in a database. Optionally, you can ignore, mask, or truncate columns that contain sensitive data, that are larger than a specified size, or that you do not need.

{
  "name": "db2-connector",  (1)
  "config": {
    "connector.class": "io.debezium.connector.db2.Db2Connector", (2)
    "database.hostname": "192.168.99.100", (3)
    "database.port": "50000", (4)
    "database.user": "db2inst1", (5)
    "database.password": "Password!", (6)
    "database.dbname": "mydatabase", (7)
    "database.server.name": "fullfillment", (8)
    "table.include.list": "MYSCHEMA.CUSTOMERS", (9)
    "database.history.kafka.bootstrap.servers": "kafka:9092", (10)
    "database.history.kafka.topic": "dbhistory.fullfillment" (11)
  }
}

For the complete list of the configuration properties that you can set for the Debezium Db2 connector, see Db2 connector properties.

You can send this configuration with a POST command to a running Kafka Connect service. The service records the configuration and starts one connector task that performs the following actions:

• Connects to the Db2 database.

• Reads change-data tables for tables that are in capture mode.

• Streams change event records to Kafka topics.

Adding connector configuration

To start running a Db2 connector, create a connector configuration and add the configuration to your Kafka Connect cluster.

Prerequisites

• Db2 replication is enabled to expose change data for tables that are in capture mode.

• The Db2 connector is installed.

Procedure

1. Create a configuration for the Db2 connector.

2. Use the Kafka Connect REST API to add that connector configuration to your Kafka Connect cluster.

Results

When the connector starts, it performs a consistent snapshot of the Db2 database tables that the connector is configured to capture changes for. The connector then starts generating data change events for row-level operations and streaming change event records to Kafka topics.

Connector properties

The Debezium Db2 connector has numerous configuration properties that you can use to achieve the right connector behavior for your application. Many properties have default values. Information about the properties is organized as follows:

• Required configuration properties

• Advanced configuration properties

• Pass-through configuration properties

The following configuration properties are required unless a default value is available.

The following advanced configuration properties have defaults that work in most situations and therefore rarely need to be specified in the connector’s configuration.

Pass-through connector configuration properties

The connector also supports pass-through configuration properties that it uses when it creates Kafka producers and consumers:

• All connector configuration properties that begin with the database.history.producer. prefix are used (without the prefix) when creating the Kafka producer that writes to the database history topic.

• All connector configuration properties that begin with the database.history.consumer. prefix are used (without the prefix) when creating the Kafka consumer that reads the database history when the connector starts.

For example, the following connector configuration properties secure connections to the Kafka broker:

database.history.producer.security.protocol=SSL
database.history.producer.ssl.keystore.location=/var/private/ssl/kafka.server.keystore.jks
database.history.producer.ssl.keystore.password=test1234
database.history.producer.ssl.truststore.location=/var/private/ssl/kafka.server.truststore.jks
database.history.producer.ssl.truststore.password=test1234
database.history.producer.ssl.key.password=test1234
database.history.consumer.security.protocol=SSL
database.history.consumer.ssl.keystore.location=/var/private/ssl/kafka.server.keystore.jks
database.history.consumer.ssl.keystore.password=test1234
database.history.consumer.ssl.truststore.location=/var/private/ssl/kafka.server.truststore.jks
database.history.consumer.ssl.truststore.password=test1234
database.history.consumer.ssl.key.password=test1234

Be sure to consult the Kafka documentation for all of the configuration properties for Kafka producers and consumers. Note that the Db2 connector uses the new consumer.

Also, the connector passes configuration properties that start with database. to the JDBC URL, for example, database.applicationName=debezium.

Monitoring

The Debezium Db2 connector provides three types of metrics that are in addition to the built-in support for JMX metrics that Apache ZooKeeper, Apache Kafka, and Kafka Connect provide.

• Snapshot metrics provide information about connector operation while performing a snapshot.

• Streaming metrics provide information about connector operation when the connector is capturing changes and streaming change event records.

• Schema history metrics provide information about the status of the connector’s schema history.

Debezium monitoring documentation provides details for how to expose these metrics by using JMX.

Snapshot metrics

The MBean is debezium.db2:type=connector-metrics,context=snapshot,server=*<database.server.name>*.

Streaming metrics

The MBean is debezium.db2:type=connector-metrics,context=streaming,server=*<database.server.name>*.

Schema history metrics

The MBean is debezium.db2:type=connector-metrics,context=schema-history,server=*<database.server.name>*.

Management

After you deploy a Debezium Db2 connector, use the Debezium management UDFs to control Db2 replication (ASN) with SQL commands. Some of the UDFs expect a return value in which case you use the SQL VALUE statement to invoke them. For other UDFs, use the SQL CALL statement.

Schema evolution

While a Debezium Db2 connector can capture schema changes, to update a schema, you must collaborate with a database administrator to ensure that the connector continues to produce change events. This is required by the way that Db2 implements replication.

For each table in capture mode, Db2’s replication feature creates a change-data table that contains all changes to that source table. However, change-data table schemas are static. If you update the schema for a table in capture mode then you must also update the schema of its corresponding change-data table. A Debezium Db2 connector cannot do this. A database administrator with elevated privileges must update schemas for tables that are in capture mode.

There are generally two procedures for updating table schemas:

• Offline - executed while Debezium is stopped

• Online - executed while Debezium is running

Each approach has advantages and disadvantages.

Offline schema update

You stop the Debezium Db2 connector before you perform an offline schema update. While this is the safer schema update procedure, it might not be feasible for applications with high-availability requirements.

Prerequisites

• One or more tables that are in capture mode require schema updates.

Procedure

1. Suspend the application that updates the database.

2. Wait for the Debezium connector to stream all unstreamed change event records.

3. Stop the Debezium connector.

4. Apply all changes to the source table schema.

5. In the ASN register table, mark the tables with updated schemas as INACTIVE.

6. xref:connectors/db2.adoc#debezium-db2-reinitialize-asn-service[Reinitialize the ASN capture service.

7. Remove the source table with the old schema from capture mode by running the Debezium UDF for removing tables from capture mode.

8. Add the source table with the new schema to capture mode by running the Debezium UDF for adding tables to capture mode.

9. In the ASN register table, mark the updated source tables as ACTIVE.

10. Reinitialize the ASN capture service.

11. Resume the application that updates the database.

12. Restart the Debezium connector.

Online schema update

An online schema update does not require application and data processing downtime. That is, you do not stop the Debezium Db2 connector before you perform an online schema update. Also, an online schema update procedure is simpler than the procedure for an offline schema update.

However, when a table is in capture mode, after a change to a column name, the Db2 replication feature continues to use the old column name. The new column name does not appear in Debezium change events. You must restart the connector to see the new column name in change events.

Prerequisites

• One or more tables that are in capture mode require schema updates.

Procedure when adding a column to the end of a table

1. Lock the source tables whose schema you want to change.

2. In the ASN register table, mark the locked tables as INACTIVE.

3. Reinitialize the ASN capture service.

4. Apply all changes to the schemas for the source tables.

5. Apply all changes to the schemas for the corresponding change-data tables.

6. In the ASN register table, mark the source tables as ACTIVE.

7. Reinitialize the ASN capture service.

8. Optional. Restart the connector to see updated column names in change events.

Procedure when adding a column to the middle of a table

1. Lock the source table(s) to be changed.

2. In the ASN register table, mark the locked tables as INACTIVE.

3. Reinitialize the ASN capture service.

4. For each source table to be changed:

   1. Export the data in the source table.

   2. Truncate the source table.

   3. Alter the source table and add the column.

   4. Load the exported data into the altered source table.

   5. Export the data in the source table’s corresponding change-data table.

   6. Truncate the change-data table.

   7. Alter the change-data table and add the column.

   8. Load the exported data into the altered change-data table.

5. In the ASN register table, mark the tables as INACTIVE. This marks the old change-data tables as inactive, which allows the data in them to remain but they are no longer updated.

6. Reinitialize the ASN capture service.

7. Optional. Restart the connector to see updated column names in change events.