Db2

Before you begin

Db2 is a source-only preview connector. Register db2 on the server before creating a connection. The Docker Quickstart does not install it automatically. See Register and test connectors.

Use a non-production database to validate your Db2 version, data types, snapshot, and CDC behavior with the connector artifact you register. This guide covers Db2 LUW, not Db2 for i or Db2 for z/OS.

The connector JAR includes the IBM JDBC driver and runtime client under their applicable license terms. Use of the connector remains subject to the applicable commercial connector agreement.

Source

Choose the outcome you need. Each tab is a complete preparation path; you do not need to combine steps from both tabs.

Ensure the tapstate server can reach the Db2 database service. Use a dedicated account recognized by the database's authentication provider. On Linux with local operating system authentication, an administrator must create the OS user account first:

# On the Db2 host (Linux with local OS authentication)
sudo useradd -m -s /bin/bash tapstate_reader
sudo passwd tapstate_reader

If your database uses LDAP, Kerberos, or another centralized authentication provider, provision the account in that directory instead.

CONNECT TO SAMPLE;

GRANT CONNECT ON DATABASE TO USER TAPSTATE_READER;
GRANT SELECT ON TABLE APP.ORDERS TO USER TAPSTATE_READER;

CONNECT TO SAMPLE USER TAPSTATE_READER USING 'replace-with-a-secret';
SELECT COUNT(*) FROM APP.ORDERS;
CONNECT RESET;

CONNECT TO SAMPLE;

-- Grant database connection and the administrative authority required for log reading
GRANT CONNECT, DBADM ON DATABASE TO USER TAPSTATE_READER;

-- Grant read access to each captured table
GRANT SELECT ON TABLE APP.ORDERS TO USER TAPSTATE_READER;

# Example: configure disk archiving for the database (run as Db2 instance owner)
db2 update db cfg for SAMPLE using LOGARCHMETH1 DISK:/db2/archives/SAMPLE

# Take an offline full backup to clear the BACKUP PENDING state
db2 backup db SAMPLE to /db2/backup

ALTER TABLE APP.ORDERS DATA CAPTURE CHANGES;

CALL SYSPROC.ADMIN_CMD('REORG TABLE APP.ORDERS');

# Confirm LOGARCHMETH1 is configured (not OFF)
db2 get db cfg for SAMPLE | grep -i logarchmeth1

-- Confirm DATACAPTURE is 'Y'
SELECT TABSCHEMA, TABNAME, DATACAPTURE
FROM SYSCAT.TABLES
WHERE TABSCHEMA = 'APP' AND TABNAME = 'ORDERS';

For permission details, see IBM's table grants and log-reading authorities.

Native log reader

The in-process log reader requires:

• A Linux x86_64 tapstate server. The native bridge does not run on ARM64.
• Root access for the first native connection, when the bundled IBM runtime is registered and its private client instance is created.
• libxml2.so.2 on the host and shared libstdc++.so.6 preloaded before the server's JVM starts, with LD_PRELOAD=libstdc++.so.6.

The current Db2 preview JAR bundles the IBM runtime client and initializes it on first use. The Cloud image supplies these dependencies and runs as root. The standard self-hosted image runs as UID 10001, so its operator must start the container as root (--user 0) for the first native connection and supply the preloaded library:

# Example: run as root for first-connection initialization and preload libstdc++
docker run -d --name tapstate \
  --user 0 \
  -e LD_PRELOAD=libstdc++.so.6 \
  -p 8080:8080 \
  ghcr.io/tapstate/tapstate:0.7.0

useNativeMiner defaults to false; enable it explicitly for native CDC. With it disabled, CDC uses a separately deployed raw log service. That path is experimental and requires its own network, authentication, and log-retention preparation.

Create a connection

In the web application, create a Db2 source connection with the prepared endpoint and credentials. For file-based authoring, create this resource:

version: tapstate/v1
kind: source
id: db2_orders
connector: db2
config:
  host: db2.internal
  port: 50000
  database: SAMPLE
  schema: APP
  user: ${DB2_USER}
  password: ${DB2_PASSWORD}
  useNativeMiner: true
  readlogBufsize: 20480
mode: cdc
tables:
  - ORDERS

Use your database service's actual port; the catalog does not provide a default. For a bounded full load, use mode: snapshot and omit useNativeMiner. The connection mode describes its read capability; the pipeline's read_mode selects how the pipeline reads it.

To generate a resource with the CLI instead:

tapstate add source --non-interactive \
  --connector db2 --id db2_orders --mode cdc \
  --set host=db2.internal --set port=50000 \
  --set database=SAMPLE --set schema=APP \
  --set user='${DB2_USER}' --set password='${DB2_PASSWORD}' \
  --set useNativeMiner=true --set readlogBufsize=20480 \
  --workdir tapstate-work

Then select ORDERS in the generated resource's tables list.

Validate the configuration

For a local workspace, check the resource before uploading it:

tapstate validate --workdir tapstate-work

Local validation checks the resource shape and recognized field types. It does not contact Db2 or establish that the native runtime is ready.

Run a connection test in the web application, then discover the source schema. For the CLI, use an authenticated session after applying the workspace:

register db2 -o json
apply
test db2_orders -o json
discover-schema db2_orders -o json
schema db2_orders -o json

Continue only when the test reports outcome: PASSED and discovery returns the selected tables. Then validate a small snapshot, CDC inserts, updates, deletes, and a keep-state restart against your target. Follow Build a pipeline.

Limitations

• Db2 cannot be a serve.sync target. The server rejects writes to Db2 in both Cloud and self-hosted deployments, including connections registered before an upgrade.
• The current release has no automated live-Db2 acceptance lane. Replacing a floating preview JAR requires validating the replacement with your database.
• Native CDC has the platform and initialization requirements listed above. Raw log service mode is experimental and is not intended for production use.
• Log reads consume database CPU, I/O, and network resources. Monitor those resources and retain logs beyond the longest recovery interval.
• After a captured table's DDL changes, coordinate any required CALL SYSPROC.ADMIN_CMD('REORG TABLE APP.ORDERS') with your DBA. Rediscover the schema and test continued capture before resuming normal changes.
• Raw log service nodes must use matching database language and country codes. Looking up an older LRI in a large log history can delay CDC startup; test that delay and recovery behavior before choosing a start position.
• Updates to variable-length fields can appear as multiple low-level log operations. Validate the resulting target rows rather than inferring data correctness from operation counts alone.

Reference

Connection settings

Additional log-reader settings

The raw log endpoint and cluster fields require a prepared raw log service. Use the starting-position and archive settings only with the matching log reader setup; setting them does not prepare that setup automatically.

Data compatibility

Test representative string, numeric, temporal, binary, large-object, and XML columns from your schema. The Db2 preview does not establish an exhaustive version or data-type compatibility matrix. Verify exact decimal precision, temporal values, and update/delete behavior in the destination before relying on them.