# debezium/debezium-connector-cockroachdb architecture

> Architecture diagram of the GitHub repository debezium/debezium-connector-cockroachdb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/debezium/debezium-connector-cockroachdb
- Repository: https://github.com/debezium/debezium-connector-cockroachdb

## Overview

This is a Debezium Kafka Connect source connector for capturing CockroachDB row changes through native changefeeds and emitting standard Debezium events. Its principal workflow configures a task, initializes schema and offsets, then streams changes through either an intermediate Kafka sink or a direct sinkless SQL connection; snapshots and signal-based incremental snapshots are additional capture paths. The graph includes the core conversion and state layers. Relationships are limited to source-index references, shown calls, and README-documented behavior; unsampled implementation details are not inferred.

Main entry points: [`src/main/java/io/debezium/connector/cockroachdb/CockroachDBStreamingChangeEventSource.java`](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBStreamingChangeEventSource.java) (Changefeed streaming), [`src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorTask.java`](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorTask.java) (Connector task), [`src/main/java/io/debezium/connector/cockroachdb/CockroachDBSchema.java`](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBSchema.java) (Schema discovery), [`src/main/java/io/debezium/connector/cockroachdb/connection/CockroachDBConnection.java`](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/connection/CockroachDBConnection.java) (Database connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Connector setup"]
  node_connector["Connector entry"]
  node_config["Connector config"]
  node_task["Connector task"]
  node_module["Connector identity<br/>[Module.java]"]
end

subgraph group_capture["Change capture"]
  node_factory["Source factory"]
  node_snapshot["Initial snapshot"]
  node_stream["Changefeed streaming"]
  node_incremental["Incremental snapshot"]
  node_connection["Database connection"]
end

subgraph group_events["Schema and events"]
  node_schema["Schema discovery"]
  node_mapper["Changefeed JSON"]
  node_converter["Value conversion"]
  node_temporal["Temporal conversion"]
  node_defaultvalue["Default conversion"]
  node_emitter["Change event emitter"]
end

subgraph group_state["Offsets and errors"]
  node_offset["Offset context"]
  node_partition["Source partition"]
  node_sourceinfo["Source metadata<br/>[SourceInfo.java]"]
  node_metadata["Event metadata"]
  node_error["Error handling"]
end

node_operator(("Connect operator"))
node_cockroach[("CockroachDB")]
node_kafka["Kafka broker"]
node_consumer(("Debezium consumer"))

node_operator -->|"registers"| node_connector
node_connector -->|"configures"| node_config
node_connector -->|"creates"| node_task
node_connector -->|"gets identity"| node_module
node_task -->|"loads"| node_config
node_task -->|"initializes"| node_schema
node_task -->|"creates"| node_connection
node_task -->|"configures"| node_factory
node_task -->|"installs"| node_error
node_factory -->|"creates"| node_snapshot
node_factory -->|"creates"| node_stream
node_factory -->|"creates"| node_incremental
node_schema -->|"reads schema"| node_connection
node_schema -->|"builds schemas"| node_converter
node_schema -->|"uses defaults"| node_defaultvalue
node_stream -->|"uses"| node_connection
node_stream -->|"parses payloads"| node_mapper
node_stream -->|"uses"| node_schema
node_stream -->|"tracks position"| node_offset
node_stream -->|"emits changes"| node_emitter
node_incremental -->|"uses"| node_connection
node_incremental -->|"uses"| node_schema
node_cockroach -->|"serves SQL"| node_connection
node_cockroach -->|"publishes changefeed"| node_stream
node_kafka -->|"delivers changefeed"| node_stream
node_emitter -->|"emits events"| node_consumer
node_converter -->|"converts temporal values"| node_temporal
node_emitter -->|"converts values"| node_converter
node_emitter -->|"converts temporal values"| node_temporal
node_offset -->|"stores source state"| node_sourceinfo
node_metadata -->|"reads offsets"| node_offset
node_stream -->|"uses partition"| node_partition

click node_connector "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnector.java"
click node_config "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorConfig.java"
click node_task "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorTask.java"
click node_factory "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBChangeEventSourceFactory.java"
click node_snapshot "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBSnapshotChangeEventSource.java"
click node_stream "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBStreamingChangeEventSource.java"
click node_incremental "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBSignalBasedIncrementalSnapshotChangeEventSource.java"
click node_connection "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/connection/CockroachDBConnection.java"
click node_schema "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBSchema.java"
click node_mapper "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/serialization/ChangefeedJsonMapper.java"
click node_converter "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBValueConverterProvider.java"
click node_temporal "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBTemporalConversions.java"
click node_defaultvalue "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBDefaultValueConverter.java"
click node_emitter "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBChangeRecordEmitter.java"
click node_offset "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBOffsetContext.java"
click node_partition "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBPartition.java"
click node_sourceinfo "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/SourceInfo.java"
click node_metadata "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBEventMetadataProvider.java"
click node_error "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBErrorHandler.java"
click node_module "https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/Module.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_connector,node_config,node_task,node_module toneBlue
class node_factory,node_snapshot,node_stream,node_incremental,node_connection,node_cockroach toneAmber
class node_schema,node_mapper,node_converter,node_temporal,node_defaultvalue,node_emitter toneMint
class node_offset,node_partition,node_sourceinfo,node_metadata,node_error toneRose
class node_operator,node_kafka,node_consumer toneIndigo
```

## Components

### Connector setup

- [Connector entry](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnector.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnector.java`
- [Connector config](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorConfig.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorConfig.java`
- [Connector task](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorTask.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorTask.java`
- [Connector identity](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/Module.java): `src/main/java/io/debezium/connector/cockroachdb/Module.java`

### Change capture

- [Source factory](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBChangeEventSourceFactory.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBChangeEventSourceFactory.java`
- [Initial snapshot](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBSnapshotChangeEventSource.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBSnapshotChangeEventSource.java`
- [Changefeed streaming](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBStreamingChangeEventSource.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBStreamingChangeEventSource.java`
- [Incremental snapshot](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBSignalBasedIncrementalSnapshotChangeEventSource.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBSignalBasedIncrementalSnapshotChangeEventSource.java`
- [Database connection](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/connection/CockroachDBConnection.java): `src/main/java/io/debezium/connector/cockroachdb/connection/CockroachDBConnection.java`

### Schema and events

- [Schema discovery](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBSchema.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBSchema.java`
- [Changefeed JSON](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/serialization/ChangefeedJsonMapper.java): `src/main/java/io/debezium/connector/cockroachdb/serialization/ChangefeedJsonMapper.java`
- [Value conversion](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBValueConverterProvider.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBValueConverterProvider.java`
- [Temporal conversion](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBTemporalConversions.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBTemporalConversions.java`
- [Default conversion](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBDefaultValueConverter.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBDefaultValueConverter.java`
- [Change event emitter](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBChangeRecordEmitter.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBChangeRecordEmitter.java`

### Offsets and errors

- [Offset context](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBOffsetContext.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBOffsetContext.java`
- [Source partition](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBPartition.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBPartition.java`
- [Source metadata](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/SourceInfo.java): `src/main/java/io/debezium/connector/cockroachdb/SourceInfo.java`
- [Event metadata](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBEventMetadataProvider.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBEventMetadataProvider.java`
- [Error handling](https://github.com/debezium/debezium-connector-cockroachdb/blob/main/src/main/java/io/debezium/connector/cockroachdb/CockroachDBErrorHandler.java): `src/main/java/io/debezium/connector/cockroachdb/CockroachDBErrorHandler.java`

### Other components

- **Connect operator**
- **CockroachDB**
- **Kafka broker**
- **Debezium consumer**

## Connections

- Connect operator → Connector entry: registers (evidence: `README.md`)
- Connector entry → Connector config: configures (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnector.java`)
- Connector entry → Connector task: creates (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnector.java`)
- Connector entry → Connector identity: gets identity (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnector.java`)
- Connector task → Connector config: loads (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorTask.java`)
- Connector task → Schema discovery: initializes (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorTask.java`)
- Connector task → Database connection: creates (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorTask.java`)
- Connector task → Source factory: configures (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorTask.java`)
- Connector task → Error handling: installs (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBConnectorTask.java`)
- Source factory → Initial snapshot: creates (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBChangeEventSourceFactory.java`)
- Source factory → Changefeed streaming: creates (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBChangeEventSourceFactory.java`)
- Source factory → Incremental snapshot: creates (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBChangeEventSourceFactory.java`)
- Schema discovery → Database connection: reads schema (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBSchema.java`)
- Schema discovery → Value conversion: builds schemas (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBSchema.java`)
- Schema discovery → Default conversion: uses defaults (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBSchema.java`)
- Changefeed streaming → Database connection: uses (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBStreamingChangeEventSource.java`)
- Changefeed streaming → Changefeed JSON: parses payloads (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBStreamingChangeEventSource.java`)
- Changefeed streaming → Schema discovery: uses (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBStreamingChangeEventSource.java`)
- Changefeed streaming → Offset context: tracks position (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBStreamingChangeEventSource.java`)
- Changefeed streaming → Change event emitter: emits changes (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBStreamingChangeEventSource.java`)
- Incremental snapshot → Database connection: uses (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBSignalBasedIncrementalSnapshotChangeEventSource.java`)
- Incremental snapshot → Schema discovery: uses (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBSignalBasedIncrementalSnapshotChangeEventSource.java`)
- CockroachDB → Database connection: serves SQL (evidence: `README.md`)
- CockroachDB → Changefeed streaming: publishes changefeed (evidence: `README.md`)
- Kafka broker → Changefeed streaming: delivers changefeed (evidence: `README.md`)
- Change event emitter → Debezium consumer: emits events (evidence: `README.md`)
- Value conversion → Temporal conversion: converts temporal values (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBValueConverterProvider.java`)
- Change event emitter → Value conversion: converts values (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBChangeRecordEmitter.java`)
- Change event emitter → Temporal conversion: converts temporal values (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBChangeRecordEmitter.java`)
- Offset context → Source metadata: stores source state (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBOffsetContext.java`)
- Event metadata → Offset context: reads offsets (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBEventMetadataProvider.java`)
- Changefeed streaming → Source partition: uses partition (evidence: `src/main/java/io/debezium/connector/cockroachdb/CockroachDBStreamingChangeEventSource.java`)