> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Debezium Server

> Deploy Debezium Server on Control Plane for standalone Change Data Capture (CDC). Streams database changes from PostgreSQL, MySQL, MongoDB, SQL Server, or Oracle to Kafka, Redis, NATS, HTTP, AWS Kinesis, GCP Pub/Sub, Apache Pulsar, or Azure Event Hubs.

## Overview

Debezium Server is a standalone Change Data Capture (CDC) application that tails a database's transaction log and streams row-level change events to a messaging system. Unlike Debezium connectors that run inside Kafka Connect, Debezium Server runs as a self-contained process — no Kafka Connect cluster required.

This template deploys Debezium Server on Control Plane with configurable source connectors, multiple sink options, flexible offset storage, and Universal Cloud Identity integration for AWS and GCP sinks.

### Architecture

* **Debezium workload** — Reads the source database's replication stream (WAL for PostgreSQL, binlog for MySQL, oplog for MongoDB), converts each change to a structured event, and delivers it to the configured sink. Stateful when using file-based offset storage; stateless when using Redis or JDBC offset storage.
* **pgdog.toml / application.properties** — Rendered as a secret and mounted at startup. Defines the source, sink, serialization format, and offset storage settings.

### What Gets Created

* **Standard Debezium Server Workload** — Single-replica CDC workload.
* **Volume Set** — For offset and schema history persistence *(only when using file offset storage)*.
* **Identity & Policy** — Identity with access to credential secrets, and cloud account access when using Kinesis or Pub/Sub sinks.
* **Secrets** — Three opaque secrets: Debezium configuration (`application.properties`), credentials (passwords for source, sink, offset storage), and a startup entrypoint script.

<Note>
  This template does not create a GVC. You must deploy it into an existing GVC.
</Note>

## Prerequisites

### Source Database

Configure your source database to allow Debezium to read its replication stream before deploying.

<Tabs>
  <Tab title="PostgreSQL">
    <Steps>
      <Step title="Enable logical replication">
        Add the following to `postgresql.conf` and restart PostgreSQL:

        ```
        wal_level = logical
        max_replication_slots = 4
        max_wal_senders = 4
        ```

        When using the [PostgreSQL Highly Available](/template-catalog/templates/postgres-highly-available) template, set `postgres.walLevel: logical` in its values before installing.
      </Step>

      <Step title="Create a publication">
        ```sql theme={null}
        CREATE PUBLICATION dbz_publication FOR ALL TABLES;
        ```

        Debezium creates the replication slot automatically on first connect.
      </Step>

      <Step title="Grant permissions">
        ```sql theme={null}
        GRANT USAGE ON SCHEMA public TO debezium;
        GRANT SELECT ON ALL TABLES IN SCHEMA public TO debezium;
        ALTER USER debezium REPLICATION;
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="MySQL">
    <Steps>
      <Step title="Enable binary logging">
        Add the following to `my.cnf` and restart MySQL:

        ```
        server-id         = 1
        log_bin           = mysql-bin
        binlog_format     = ROW
        binlog_row_image  = FULL
        ```
      </Step>

      <Step title="Grant permissions">
        ```sql theme={null}
        GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT
          ON *.* TO 'debezium'@'%';
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="MongoDB">
    MongoDB must be running as a replica set. Debezium tails the oplog; no additional configuration is needed beyond connection credentials with `read` access to the databases you want to capture.
  </Tab>

  <Tab title="SQL Server">
    CDC must be enabled on the SQL Server instance and on each database/table you want to capture:

    ```sql theme={null}
    EXEC sys.sp_cdc_enable_db;
    EXEC sys.sp_cdc_enable_table @source_schema = 'dbo', @source_name = 'my_table', @role_name = NULL;
    ```
  </Tab>
</Tabs>

### Cloud Sinks (Kinesis / Pub/Sub)

For AWS Kinesis or GCP Pub/Sub sinks, set up a Cloud Account in Control Plane before installing:

* **Kinesis**: [Create an AWS Cloud Account](https://docs.controlplane.com/guides/create-cloud-account) and enable it under `sink.kinesis.cloudAccount`.
* **Pub/Sub**: [Create a GCP Cloud Account](https://docs.controlplane.com/guides/create-cloud-account) and enable it under `sink.pubsub.cloudAccount`.

To install, follow the instructions for your preferred method:

<CardGroup cols={2}>
  <Card title="UI" href="/template-catalog/install-manage/ui" icon="laptop">
    Browse, install, and manage templates visually
  </Card>

  <Card title="CLI" href="/template-catalog/install-manage/cli" icon="terminal">
    Manage templates from your terminal
  </Card>

  <Card title="Terraform" href="/template-catalog/install-manage/terraform" icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><g fill-rule="evenodd"><path d="M77.941 44.5v36.836L46.324 62.918V26.082zm0 0" fill="#5c4ee5"/><path d="M81.41 81.336l31.633-18.418V26.082L81.41 44.5zm0 0" fill="#4040b2"/><path d="M11.242 42.36L42.86 60.776V23.941L11.242 5.523zm0 0M77.941 85.375L46.324 66.957v36.82l31.617 18.418zm0 0" fill="#5c4ee5"/></g></svg>}>
    Declare templates in your Terraform configurations
  </Card>

  <Card
    title="Pulumi"
    href="/template-catalog/install-manage/pulumi"
    icon={<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" id="Pulumi-Icon--Streamline-Svg-Logos" height="24" width="24">
    <desc>
        Pulumi Icon Streamline Icon: https://streamlinehq.com
    </desc>
    <path fill="#f26e7e" d="M4.683025 13.3318c0.869125 -0.5018 0.870575 -2.1264 0.003225 -3.62865s-2.27504 -2.313275 -3.1441725 -1.811475C0.672945 8.3935 0.6715 10.0181 1.53885 11.52035c0.86735 1.502275 2.27505 2.313275 3.144175 1.81145Zm0.0052 3.2167c0.86735 1.502275 0.865925 3.126875 -0.003225 3.628675 -0.86915 0.5018 -2.2768275 -0.309225 -3.144175 -1.81145 -0.8673525 -1.50225 -0.8659075 -3.126875 0.003225 -3.628675 0.8691325 -0.5018 2.276825 0.309225 3.144175 1.81145Zm5.922875 3.4243c0.86735 1.50225 0.8659 3.126775 -0.003225 3.62875 -0.869125 0.501775 -2.27685 -0.309325 -3.1442 -1.81155 -0.867325 -1.50225 -0.865875 -3.12685 0.00325 -3.628675 0.869125 -0.5018 2.276825 0.309225 3.144175 1.811475Zm-0.001925 -6.845275c0.86735 1.50225 0.8659 3.12685 -0.003225 3.628675 -0.869125 0.5018 -2.276825 -0.309225 -3.144175 -1.811475 -0.86735 -1.50225 -0.8659 -3.12685 0.003225 -3.62865 0.869125 -0.501825 2.276825 0.3092 3.144175 1.81145Z" stroke-width="0.25"></path>
    <path fill="#8a3391" d="M22.45775 11.524125c0.86725 -1.502225 0.865925 -3.12685 -0.003225 -3.62865 -0.869125 -0.501825 -2.276825 0.3092 -3.144175 1.811475 -0.86735 1.50225 -0.8659 3.126825 0.003225 3.62865 0.869125 0.501825 2.276825 -0.3092 3.144175 -1.811475Zm0.000175 3.2151c0.869075 0.5018 0.870625 2.1264 0.003225 3.62865 -0.86735 1.50225 -2.27505 2.313275 -3.144175 1.81145 -0.869125 -0.5018 -0.870575 -2.126425 -0.003225 -3.62865 0.86735 -1.50225 2.27505 -2.313275 3.144175 -1.81145ZM16.536225 18.157875c0.86915 0.501825 0.8706 2.126425 0.00325 3.628675 -0.86735 1.502125 -2.275075 2.313225 -3.1442 1.81145 -0.869125 -0.50175 -0.870575 -2.126425 -0.003225 -3.62865 0.867375 -1.502275 2.27505 -2.3133 3.144175 -1.811475Zm-0.003325 -6.843775c0.869125 0.5018 0.870575 2.126425 0.003225 3.628675s-2.27505 2.313275 -3.1442 1.811475c-0.869125 -0.501825 -0.870575 -2.126425 -0.003225 -3.628675 0.86735 -1.502275 2.27505 -2.313275 3.1442 -1.811475Z" stroke-width="0.25"></path>
    <path fill="#f7bf2a" d="M15.138225 2.06721c0 1.003615 -1.40625 1.817215 -3.14095 1.817215 -1.7347 0 -3.14095 -0.8136 -3.14095 -1.817215C8.856325 1.06359 10.262575 0.25 11.997275 0.25c1.7347 0 3.14095 0.81359 3.14095 1.81721ZM9.2166 5.482375c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172s1.40625 -1.817225 3.14095 -1.817225c1.7347 0 3.14095 0.8136 3.14095 1.817225Zm8.71005 1.8172c1.7347 0 3.14095 -0.813575 3.14095 -1.8172s-1.40625 -1.817225 -3.14095 -1.817225c-1.7347 0 -3.14095 0.8136 -3.14095 1.817225s1.40625 1.8172 3.14095 1.8172Zm-2.788425 1.605625c0 1.003625 -1.40625 1.8172 -3.14095 1.8172 -1.7347 0 -3.14095 -0.813575 -3.14095 -1.8172 0 -1.0036 1.40625 -1.8172 3.14095 -1.8172 1.7347 0 3.14095 0.8136 3.14095 1.8172Z" stroke-width="0.25"></path>
    </svg>}
  >
    Declare templates in your Pulumi programs
  </Card>
</CardGroup>

## Configuration

### Quick Start Examples

**PostgreSQL → Kafka:**

```yaml theme={null}
source:
  type: postgres
  database:
    hostname: my-postgres.my-gvc.cpln.local
    port: 5432
    name: mydb
    user: debezium
    password: secret
  serverName: myserver
  tableIncludeList: "public.users,public.orders"
  postgres:
    slotName: debezium_slot
    publicationName: dbz_publication

sink:
  type: kafka
  kafka:
    bootstrapServers: kafka.my-gvc.cpln.local:9092
    topic: cdc-events
```

**MySQL → Redis Streams:**

```yaml theme={null}
source:
  type: mysql
  database:
    hostname: mysql.my-gvc.cpln.local
    port: 3306
    name: mydb
    user: debezium
    password: secret
  serverName: myserver
  mysql:
    serverId: 85744
    includeSchemaChanges: true

sink:
  type: redis
  redis:
    address: redis.my-gvc.cpln.local:6379
    streamName: cdc-stream
```

**PostgreSQL → AWS Kinesis (Universal Cloud Identity):**

```yaml theme={null}
source:
  type: postgres
  database:
    hostname: my-rds.us-east-1.rds.amazonaws.com
    port: 5432
    name: mydb
    user: debezium
    password: secret
  serverName: myserver

sink:
  type: kinesis
  kinesis:
    region: us-east-1
    streamName: cdc-events
    credentialsProvider: default
    cloudAccount:
      enabled: true
      name: my-aws-account
```

### Full `values.yaml`

```yaml theme={null}
image: quay.io/debezium/server:3.0

resources:
  cpu: 500m
  memory: 512Mi

source:
  type: postgres  # options: postgres, mysql, mongodb, sqlserver, oracle

  database:
    hostname: ""
    port: 5432
    name: ""
    user: ""
    password: ""

  serverName: "dbserver1"
  tableIncludeList: ""
  tableExcludeList: ""

  postgres:
    slotName: "debezium"
    publicationName: "dbz_publication"
    pluginName: "pgoutput"        # options: pgoutput, decoderbufs
    slotDropOnStop: false
    heartbeatIntervalMs: 0        # set to 5000 for HA/patroni setups
    heartbeatActionQuery: ""

  mysql:
    serverId: 85744
    includeSchemaChanges: true

  mongodb:
    connectionString: ""
    replicaSet: ""

  sqlserver:
    databaseNames: ""
    snapshotMode: "initial"       # options: initial, schema_only, initial_only

  oracle:
    pdbName: ""
    logMiningStrategy: "online_catalog"

  offset:
    storage: file  # options: file, redis, jdbc
    flushIntervalMs: 10000
    flushTimeoutMs: 60000

    file:
      filename: "/debezium/data/offsets.dat"

    redis:
      address: ""
      key: "debezium:offsets"
      password: ""
      ssl: false

    jdbc:
      url: ""
      user: ""
      password: ""
      tableName: "debezium_offsets"

  schemaHistory:              # MySQL and SQL Server only
    storage: file             # options: file, redis, jdbc
    file:
      filename: "/debezium/data/schema-history.dat"
    redis:
      address: ""
      key: "debezium:schema-history"
      password: ""
      ssl: false
    jdbc:
      url: ""
      user: ""
      password: ""
      tableName: "debezium_schema_history"

  errors:
    retryDelayInitialMs: 300
    retryDelayMaxMs: 10000
    maxRetries: -1              # -1 = infinite retries

sink:
  type: kafka  # options: kafka, redis, nats-jetstream, http, kinesis, pubsub, pulsar, eventhubs

  kafka:
    bootstrapServers: ""
    topic: ""
    securityProtocol: "PLAINTEXT"
    saslMechanism: ""
    saslUsername: ""
    saslPassword: ""

  redis:
    address: ""
    password: ""
    ssl: false
    streamName: ""

  nats:
    url: ""
    subject: ""
    username: ""
    password: ""

  http:
    url: ""
    headers: {}
    authType: ""              # options: none, basic, bearer
    username: ""
    password: ""
    bearerToken: ""

  kinesis:
    region: ""
    streamName: ""
    credentialsProvider: "default"
    cloudAccount:
      enabled: false
      name: ""

  pubsub:
    projectId: ""
    topic: ""
    cloudAccount:
      enabled: false
      name: ""

  pulsar:
    serviceUrl: ""
    topic: ""
    authPluginClassName: ""
    authToken: ""

  eventhubs:
    connectionString: ""
    hubName: ""

format:
  key: json    # options: json, avro, protobuf
  value: json
  schemaRegistry:
    url: ""
    username: ""
    password: ""

volumeset:
  capacity: 10                         # GiB — only used with file offset storage
  performanceClass: general-purpose-ssd

firewall:
  internal:
    inboundAllowType: same-gvc         # options: none, same-gvc, same-org, workload-list
    workloads: []
  external:
    outboundAllowCIDR:
      - 0.0.0.0/0
```

### Supported Sources

| Database   | Default Port | Key Settings                                |
| ---------- | ------------ | ------------------------------------------- |
| PostgreSQL | `5432`       | `slotName`, `publicationName`, `pluginName` |
| MySQL      | `3306`       | `serverId`, `includeSchemaChanges`          |
| MongoDB    | `27017`      | `connectionString`, `replicaSet`            |
| SQL Server | `1433`       | `databaseNames`, `snapshotMode`             |
| Oracle     | `1521`       | `pdbName`, `logMiningStrategy`              |

### Supported Sinks

| Sink             | Key Settings                  | Notes                         |
| ---------------- | ----------------------------- | ----------------------------- |
| Kafka            | `bootstrapServers`, `topic`   | No Kafka Connect required     |
| Redis            | `address`, `streamName`       | Redis Streams                 |
| NATS JetStream   | `url`, `subject`              | Cloud-native messaging        |
| HTTP             | `url`                         | Webhooks and custom endpoints |
| AWS Kinesis      | `region`, `streamName`        | Uses Universal Cloud Identity |
| GCP Pub/Sub      | `projectId`, `topic`          | Uses Universal Cloud Identity |
| Apache Pulsar    | `serviceUrl`, `topic`         | Optional token auth           |
| Azure Event Hubs | `connectionString`, `hubName` | Kafka-compatible protocol     |

### Offset Storage

Debezium tracks its position in the source database's replication stream using offset storage. If the process restarts, it resumes from the last committed offset.

| Backend | Persistence                            | Notes                                                                 |
| ------- | -------------------------------------- | --------------------------------------------------------------------- |
| `file`  | Volume Set mounted at `/debezium/data` | Default. Simple, requires a Volume Set.                               |
| `redis` | Redis key                              | No Volume Set needed. Use with an existing Redis instance.            |
| `jdbc`  | Relational table                       | No Volume Set needed. Use with an existing PostgreSQL/MySQL instance. |

### Schema History (MySQL and SQL Server only)

MySQL and SQL Server connectors track DDL changes in a schema history store. Configure `source.schemaHistory.storage` with the same backend options as offset storage (`file`, `redis`, or `jdbc`).

### Serialization Formats

Events can be serialized as JSON, Avro, or Protobuf. For Avro or Protobuf, configure a Schema Registry:

```yaml theme={null}
format:
  key: avro
  value: avro
  schemaRegistry:
    url: http://schema-registry.my-gvc.cpln.local:8081
    username: ""
    password: ""
```

### Universal Cloud Identity

AWS Kinesis and GCP Pub/Sub sinks support credential-free access via Control Plane's Universal Cloud Identity — no access keys or service account JSON files are needed.

Enable by setting `cloudAccount.enabled: true` and providing the Cloud Account name registered in Control Plane:

```yaml theme={null}
sink:
  type: kinesis
  kinesis:
    region: us-east-1
    streamName: my-stream
    credentialsProvider: default
    cloudAccount:
      enabled: true
      name: my-aws-account
```

## Health Checks

Debezium Server exposes Quarkus health endpoints:

| Endpoint          | Purpose                                    |
| ----------------- | ------------------------------------------ |
| `/q/health/ready` | Connector is ready and connected to source |
| `/q/health/live`  | Server process is alive                    |

## Troubleshooting

<Accordion title="Connector not starting">
  * Verify database hostname and port are reachable from the GVC (check `firewall.external.outboundAllowCIDR`).
  * Confirm the database user has the required replication permissions.
  * View startup logs: `cpln workload logs {release-name}-debezium --gvc {gvc}`
</Accordion>

<Accordion title="Offset storage errors">
  * **File storage**: confirm the Volume Set is mounted and has sufficient capacity.
  * **Redis/JDBC**: verify connectivity, credentials, and that the backend is accessible within the GVC.
</Accordion>

<Accordion title="Sink delivery failures">
  * Verify the sink endpoint is reachable from the workload.
  * For Kinesis/Pub/Sub: confirm the Cloud Account is configured and has the correct IAM/IAM permissions.
  * For Kafka with SASL: verify `saslUsername`, `saslPassword`, and `saslMechanism` match the broker config.
</Accordion>

## External References

<CardGroup cols={2}>
  <Card title="Debezium Server Documentation" href="https://debezium.io/documentation/reference/stable/operations/debezium-server.html" icon="server">
    Full Debezium Server configuration reference
  </Card>

  <Card title="Debezium Connectors" href="https://debezium.io/documentation/reference/stable/connectors/" icon="database">
    Source connector configuration for each supported database
  </Card>

  <Card title="CDC Pipeline Template" href="/template-catalog/templates/cdc-pipeline" icon="arrow-right-arrow-left">
    Deploy a complete CDC pipeline (PostgreSQL HA + Kafka + Debezium) in one step
  </Card>

  <Card title="Create a Cloud Account" href="https://docs.controlplane.com/guides/create-cloud-account" icon="cloud">
    Set up AWS or GCP cloud accounts for Kinesis and Pub/Sub sinks
  </Card>
</CardGroup>