Copyright Debezium Authors. Licensed under the Apache License, Version 2.0.

Debezium Connector for CockroachDB

A Debezium connector for capturing changes from CockroachDB databases, built on CockroachDB's native changefeed infrastructure. Row-level changes are emitted as standard Debezium change events, so any Debezium-compatible consumer or sink connector works unchanged.

Documentation

The connector documentation lives on the Debezium site and is the authoritative reference for configuration properties, delivery modes, data type mappings, snapshots, monitoring, and troubleshooting:

• Debezium connector for CockroachDB
• Debezium JDBC sink connector (for writing into CockroachDB)

Runnable end-to-end examples (CockroachDB to CockroachDB, Oracle, Iceberg, sinkless, mTLS, embedded engine, and workload-based verification) live in the examples repository.

Quick start

Install the plugin from Maven Central (io.debezium:debezium-connector-cockroachdb) into your Kafka Connect plugin.path, or from Confluent Hub (confluent-hub install cockroachdb/debezium-connector-cockroachdb:latest; the Debezium JDBC sink is published there as well). Enable rangefeeds on the source cluster and register a connector:

SET CLUSTER SETTING kv.rangefeed.enabled = true;

{
  "name": "cockroachdb-connector",
  "config": {
    "connector.class": "io.debezium.connector.cockroachdb.CockroachDBConnector",
    "database.hostname": "cockroachdb",
    "database.port": "26257",
    "database.user": "cdc_user",
    "database.password": "",
    "database.dbname": "mydb",
    "topic.prefix": "crdb",
    "table.include.list": "public.orders",
    "cockroachdb.changefeed.sink.type": "kafka",
    "cockroachdb.changefeed.sink.uri": "kafka://kafka:9092",
    "cockroachdb.changefeed.kafka.bootstrap.servers": "kafka:9092"
  }
}

The kafka delivery mode uses an intermediate Kafka cluster that CockroachDB pushes changefeed events to; the sinkless mode streams directly over a SQL connection with no intermediate Kafka. See the connector documentation for the trade-offs.

Building

Requirements: JDK 17+, Docker (for integration tests).

./mvnw clean install

Build the connector plugin archive:

./mvnw clean package -Passembly

Testing

# Unit tests
./mvnw test

# Integration tests (Testcontainers; requires Docker)
./mvnw verify -DskipUTs -P-assembly

# Coverage report (informational): target/site/jacoco/index.html
./mvnw verify jacoco:report

The integration tests pin the CockroachDB version via the cockroachdb.version system property, defaulting to the version set in pom.xml.

Contributing

The Debezium community welcomes anyone who wants to help out in any way, whether that includes reporting problems, helping with documentation, or contributing code changes to fix bugs, add tests, or implement new features. See CONTRIBUTING.md for details.

Issues are tracked at github.com/debezium/dbz with the label component/cockroachdb-connector. Community chat happens in the CockroachDB channel on Debezium Zulip.