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

# Debezium PostgreSQL

> Resources, examples, configuration and evidence for Debezium PostgreSQL.

Use the `@bijection/connectors/debezium` entrypoint to declare Debezium PostgreSQL resources.

## Availability

This page describes the pinned source package. Published availability is unestablished for this artifact. [Source build and package availability](https://docs.bijection.com/client/sdk-distribution.md).

## Resources and modes

| Resource | Mode | Description |
| - | - | - |
| Database | `cdc` | cdc |

Declare a resource in application code, then bind deployment-specific settings and credentials. See [typed resources](https://docs.bijection.com/integrations/resources.md), [connections](https://docs.bijection.com/integrations/connections.md) and [source inspection](https://docs.bijection.com/integrations/cli.md).

## Database

### cdc: cdc

The following example matches configuration `standard`.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { debezium } from "@bijection/connectors/debezium";
import { v } from "bijection/values";

export const resource = debezium.database.cdc({
  contract: {
    catalog: {
      decoderRevision: "1",
      schemaDigest:
        "3d730fcc7ce6368476a8f24c333dfe3cd42b90a110e10d37407040635a7c858a",
      tables: {
        lines: {
          columns: {
            id: { key: true, nullable: false, typeModifier: -1, typeOid: 20 },
            order_id: {
              key: false,
              nullable: false,
              typeModifier: -1,
              typeOid: 20,
            },
          },
        },
        orders: {
          columns: {
            id: { key: true, nullable: false, typeModifier: -1, typeOid: 20 },
            total: {
              key: false,
              nullable: false,
              typeModifier: -1,
              typeOid: 1700,
            },
          },
        },
      },
    },
    tables: {
      lines: { id: v.int64(), order_id: v.int64() },
      orders: { id: v.int64(), total: v.string() },
    },
  },
});
```

> **Inferred record types**
>
> ```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> lines: {
>   "id": bigint;
>   "order_id": bigint;
> }
>
> orders: {
>   "id": bigint;
>   "total": string;
> }
> ```

#### Configuration: standard

Case: `debezium/database/cdc/standard`.

Connection and resource configuration are declared by this exact case.

Credential kind: `postgres`. Keep credential material in the private credential inventory.

| Setting | Type | Required | Owner |
| - | - | - | - |
| `host` | string | Yes | Shared connection |
| `port` | number | Yes | Shared connection |
| `database` | string | Yes | Shared connection |
| `publication` | string | Yes | Resource binding |
| `relations` | record of object | Yes | Resource binding |

> **Complete configuration contract**
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "setup": [],
>   "resource": {
>     "access": {},
>     "defaults": {},
>     "connector": "postgres",
>     "output": {
>       "kind": "group",
>       "collections": [
>         "lines",
>         "orders"
>       ]
>     },
>     "credential_kind": "postgres",
>     "connection_fields": [
>       "host",
>       "port",
>       "database"
>     ]
>   },
>   "connection_setup": {
>     "type": "object",
>     "value": {
>       "host": {
>         "fieldType": {
>           "type": "string"
>         },
>         "optional": false
>       },
>       "port": {
>         "fieldType": {
>           "type": "number"
>         },
>         "optional": false
>       },
>       "database": {
>         "fieldType": {
>           "type": "string"
>         },
>         "optional": false
>       },
>       "publication": {
>         "fieldType": {
>           "type": "string"
>         },
>         "optional": false
>       },
>       "relations": {
>         "fieldType": {
>           "type": "record",
>           "keys": {
>             "type": "string"
>           },
>           "values": {
>             "fieldType": {
>               "type": "object",
>               "value": {
>                 "schema": {
>                   "fieldType": {
>                     "type": "string"
>                   },
>                   "optional": false
>                 },
>                 "table": {
>                   "fieldType": {
>                     "type": "string"
>                   },
>                   "optional": false
>                 }
>               }
>             },
>             "optional": false
>           }
>         },
>         "optional": false
>       }
>     }
>   },
>   "execution": null
> }
> ```

Native admission analysis is available for this exact declaration.

**Collection: lines**

| Contract | Meaning |
| - | - |
| Initial | Pinned snapshot |
| Changes | Complete change feed under the declared contract |
| Deletions | Explicit deletion evidence |
| Resume | Provider source position |
| Gap | Explicit repair required after a gap |
| Retention | Unspecified |

> **Complete native profile**
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "movement": {
>     "exchanges": {},
>     "nativeInputLimitBytes": "0",
>     "steps": [
>       {
>         "id": "acquire.1",
>         "inputs": [],
>         "action": {
>           "operation": "acquire",
>           "subject": "native input",
>           "limitBytes": "0"
>         }
>       },
>       {
>         "id": "retain.1",
>         "inputs": [
>           "acquire.1"
>         ],
>         "action": {
>           "operation": "retain",
>           "subject": "acquisition evidence",
>           "reason": "recovery",
>           "release": "acquisition_custody"
>         }
>       },
>       {
>         "id": "interpret.1",
>         "inputs": [
>           "retain.1"
>         ],
>         "action": {
>           "operation": "interpret",
>           "subject": "acquired input",
>           "produces": "records"
>         }
>       },
>       {
>         "id": "materialize.1",
>         "inputs": [
>           "interpret.1"
>         ],
>         "action": {
>           "operation": "materialize",
>           "subject": "source rows",
>           "reason": "serving",
>           "release": "replacement"
>         }
>       },
>       {
>         "id": "publish.1",
>         "inputs": [
>           "materialize.1"
>         ],
>         "action": {
>           "operation": "publish",
>           "subject": "source rows",
>           "visibility": "with_acquisition"
>         }
>       }
>     ]
>   },
>   "initial": "pinned_snapshot",
>   "changes": "complete_feed",
>   "deletions": "explicit_events",
>   "resume": "source_position",
>   "retentionMs": null,
>   "gap": "explicit_repair",
>   "limits": {
>     "columns_per_table": "256",
>     "complete_input_hard_bytes": "137438953472",
>     "exchange_evidence_bytes": "524288",
>     "prepared_hard_bytes": "137438953472",
>     "prepared_rows_hard": "1073741824",
>     "selected_tables": "100",
>     "transaction_wire_hard_bytes": "268435456"
>   },
>   "restrictions": [
>     "Input and preparation must fit operator-configured custody quotas; hard ceilings do not establish measured capacity",
>     "Serial pgoutput protocol 1; source schema changes require an explicit baseline and stable key identity"
>   ],
>   "commands": {}
> }
> ```

**Collection: orders**

| Contract | Meaning |
| - | - |
| Initial | Pinned snapshot |
| Changes | Complete change feed under the declared contract |
| Deletions | Explicit deletion evidence |
| Resume | Provider source position |
| Gap | Explicit repair required after a gap |
| Retention | Unspecified |

> **Complete native profile**
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "movement": {
>     "exchanges": {},
>     "nativeInputLimitBytes": "0",
>     "steps": [
>       {
>         "id": "acquire.1",
>         "inputs": [],
>         "action": {
>           "operation": "acquire",
>           "subject": "native input",
>           "limitBytes": "0"
>         }
>       },
>       {
>         "id": "retain.1",
>         "inputs": [
>           "acquire.1"
>         ],
>         "action": {
>           "operation": "retain",
>           "subject": "acquisition evidence",
>           "reason": "recovery",
>           "release": "acquisition_custody"
>         }
>       },
>       {
>         "id": "interpret.1",
>         "inputs": [
>           "retain.1"
>         ],
>         "action": {
>           "operation": "interpret",
>           "subject": "acquired input",
>           "produces": "records"
>         }
>       },
>       {
>         "id": "materialize.1",
>         "inputs": [
>           "interpret.1"
>         ],
>         "action": {
>           "operation": "materialize",
>           "subject": "source rows",
>           "reason": "serving",
>           "release": "replacement"
>         }
>       },
>       {
>         "id": "publish.1",
>         "inputs": [
>           "materialize.1"
>         ],
>         "action": {
>           "operation": "publish",
>           "subject": "source rows",
>           "visibility": "with_acquisition"
>         }
>       }
>     ]
>   },
>   "initial": "pinned_snapshot",
>   "changes": "complete_feed",
>   "deletions": "explicit_events",
>   "resume": "source_position",
>   "retentionMs": null,
>   "gap": "explicit_repair",
>   "limits": {
>     "columns_per_table": "256",
>     "complete_input_hard_bytes": "137438953472",
>     "exchange_evidence_bytes": "524288",
>     "prepared_hard_bytes": "137438953472",
>     "prepared_rows_hard": "1073741824",
>     "selected_tables": "100",
>     "transaction_wire_hard_bytes": "268435456"
>   },
>   "restrictions": [
>     "Input and preparation must fit operator-configured custody quotas; hard ceilings do not establish measured capacity",
>     "Serial pgoutput protocol 1; source schema changes require an explicit baseline and stable key identity"
>   ],
>   "commands": {}
> }
> ```

> **Commands, occurrences and artifacts**
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "records": {
>     "lines": {
>       "protocol": "transactional_feed",
>       "coverage": "committed_prefix",
>       "consistency": "snapshot",
>       "atomicity": "source_transaction",
>       "history": "complete_changes",
>       "recordRefresh": false,
>       "reconciliation": false,
>       "notifications": false,
>       "snapshotMaxRows": null,
>       "profile": {
>         "movement": {
>           "exchanges": {},
>           "nativeInputLimitBytes": "0",
>           "steps": [
>             {
>               "id": "acquire.1",
>               "inputs": [],
>               "action": {
>                 "operation": "acquire",
>                 "subject": "native input",
>                 "limitBytes": "0"
>               }
>             },
>             {
>               "id": "retain.1",
>               "inputs": [
>                 "acquire.1"
>               ],
>               "action": {
>                 "operation": "retain",
>                 "subject": "acquisition evidence",
>                 "reason": "recovery",
>                 "release": "acquisition_custody"
>               }
>             },
>             {
>               "id": "interpret.1",
>               "inputs": [
>                 "retain.1"
>               ],
>               "action": {
>                 "operation": "interpret",
>                 "subject": "acquired input",
>                 "produces": "records"
>               }
>             },
>             {
>               "id": "materialize.1",
>               "inputs": [
>                 "interpret.1"
>               ],
>               "action": {
>                 "operation": "materialize",
>                 "subject": "source rows",
>                 "reason": "serving",
>                 "release": "replacement"
>               }
>             },
>             {
>               "id": "publish.1",
>               "inputs": [
>                 "materialize.1"
>               ],
>               "action": {
>                 "operation": "publish",
>                 "subject": "source rows",
>                 "visibility": "with_acquisition"
>               }
>             }
>           ]
>         },
>         "initial": "pinned_snapshot",
>         "changes": "complete_feed",
>         "deletions": "explicit_events",
>         "resume": "source_position",
>         "retentionMs": null,
>         "gap": "explicit_repair",
>         "limits": {
>           "columns_per_table": "256",
>           "complete_input_hard_bytes": "137438953472",
>           "exchange_evidence_bytes": "524288",
>           "prepared_hard_bytes": "137438953472",
>           "prepared_rows_hard": "1073741824",
>           "selected_tables": "100",
>           "transaction_wire_hard_bytes": "268435456"
>         },
>         "restrictions": [
>           "Input and preparation must fit operator-configured custody quotas; hard ceilings do not establish measured capacity",
>           "Serial pgoutput protocol 1; source schema changes require an explicit baseline and stable key identity"
>         ],
>         "commands": {}
>       }
>     },
>     "orders": {
>       "protocol": "transactional_feed",
>       "coverage": "committed_prefix",
>       "consistency": "snapshot",
>       "atomicity": "source_transaction",
>       "history": "complete_changes",
>       "recordRefresh": false,
>       "reconciliation": false,
>       "notifications": false,
>       "snapshotMaxRows": null,
>       "profile": {
>         "movement": {
>           "exchanges": {},
>           "nativeInputLimitBytes": "0",
>           "steps": [
>             {
>               "id": "acquire.1",
>               "inputs": [],
>               "action": {
>                 "operation": "acquire",
>                 "subject": "native input",
>                 "limitBytes": "0"
>               }
>             },
>             {
>               "id": "retain.1",
>               "inputs": [
>                 "acquire.1"
>               ],
>               "action": {
>                 "operation": "retain",
>                 "subject": "acquisition evidence",
>                 "reason": "recovery",
>                 "release": "acquisition_custody"
>               }
>             },
>             {
>               "id": "interpret.1",
>               "inputs": [
>                 "retain.1"
>               ],
>               "action": {
>                 "operation": "interpret",
>                 "subject": "acquired input",
>                 "produces": "records"
>               }
>             },
>             {
>               "id": "materialize.1",
>               "inputs": [
>                 "interpret.1"
>               ],
>               "action": {
>                 "operation": "materialize",
>                 "subject": "source rows",
>                 "reason": "serving",
>                 "release": "replacement"
>               }
>             },
>             {
>               "id": "publish.1",
>               "inputs": [
>                 "materialize.1"
>               ],
>               "action": {
>                 "operation": "publish",
>                 "subject": "source rows",
>                 "visibility": "with_acquisition"
>               }
>             }
>           ]
>         },
>         "initial": "pinned_snapshot",
>         "changes": "complete_feed",
>         "deletions": "explicit_events",
>         "resume": "source_position",
>         "retentionMs": null,
>         "gap": "explicit_repair",
>         "limits": {
>           "columns_per_table": "256",
>           "complete_input_hard_bytes": "137438953472",
>           "exchange_evidence_bytes": "524288",
>           "prepared_hard_bytes": "137438953472",
>           "prepared_rows_hard": "1073741824",
>           "selected_tables": "100",
>           "transaction_wire_hard_bytes": "268435456"
>         },
>         "restrictions": [
>           "Input and preparation must fit operator-configured custody quotas; hard ceilings do not establish measured capacity",
>           "Serial pgoutput protocol 1; source schema changes require an explicit baseline and stable key identity"
>         ],
>         "commands": {}
>       }
>     }
>   },
>   "occurrences": null,
>   "artifacts": {
>     "raw_archive": false,
>     "native_file_transfer_limit_bytes": null,
>     "external_versions": false,
>     "files": {}
>   },
>   "commands": {}
> }
> ```

**Recorded checks**

| Requirement | Scope | Evidence | Result |
| - | - | - | - |
| change-history-gap | \{"kind":"collection","name":"lines"} | Debezium runtime qualification has not been recorded for this scoped requirement. | Execution result unavailable |
| page-publication-recovery | \{"kind":"collection","name":"lines"} | Debezium runtime qualification has not been recorded for this scoped requirement. | Execution result unavailable |
| change-history-gap | \{"kind":"collection","name":"orders"} | Debezium runtime qualification has not been recorded for this scoped requirement. | Execution result unavailable |
| page-publication-recovery | \{"kind":"collection","name":"orders"} | Debezium runtime qualification has not been recorded for this scoped requirement. | Execution result unavailable |
| group-publication-recovery | \{"kind":"group"} | Debezium runtime qualification has not been recorded for this scoped requirement. | Execution result unavailable |

Hosted qualification: **unestablished for this catalog configuration**. Installed connections report their own identity, authority and current status.

## Provider guidance

`debezium.database.cdc({contract: cdc})` consumes the module generated by
`bijection debezium capture --connection /private/cdc.json --output cdc.json`.
Capture writes `cdc.json` and `cdc.ts`. The installation's `postgresConnection`
points to the ordinary private PostgreSQL credential JSON. Capture reads the
catalog in a read-only serializable transaction while holding schema locks;
the application does not repeat schemas or keys. Native admission independently
compares type OIDs, modifiers, nullability, primary keys and the complete scope.

This profile pins PostgreSQL 16.14, Debezium 3.7.0.Final and Kafka Connect 4.1.0.
It requires pgoutput, a complete initial snapshot, transaction metadata,
single-partition topics from offset zero, embedded JSON schemas, precise
decimals and REPLICA IDENTITY FULL. Install `io.bijection.debezium.SourceOffsets`
from the pipelines repository's `src/debezium/` package. Filtering, custom keys,
other transforms and unsafe producer overrides are refused. Topic access must
include DescribeConfigs: effective cleanup.policy must be delete, retention.ms
at least seven days (or unlimited), and retention.bytes unlimited. Offset
continuity is checked independently, including after retention changes.

The customer operates Kafka Connect, Kafka and the PostgreSQL replication slot.
The responding Connect worker must report the pinned version and PostgreSQL
plugin; this is an observation of that worker, not a cluster-wide attestation.
Operators must deploy the admitted artifacts uniformly across eligible workers.
The actual broker cluster ID must match both Connect and the installed binding.

The PostgreSQL private credential adds `debezium.configuration_digest`,
`broker_cluster_id`, `broker`, `broker_credential` (shared Kafka TLS/SASL JSON),
`connect_endpoint`, optional Connect authentication and private CA, `connector`,
`topic_prefix` and `notification_topic`. SQL catalog access is required. Physical
bindings and secrets stay outside the generated application module.

Raw Kafka records enter bounded ordinary acquisition custody before decoding.
Raw acquisition and interpretation have independent cursors; a semantic refusal
continues raw capture within the source budget. The archive pins input across
publication and crashes. Stable provider identities reject conflicting duplicate
content at different Kafka offsets. The earliest unresolved transaction gets
priority over unrelated lookahead. BEGIN/END counts, table counts and global
order must agree before tables, required views and the checkpoint publish.
Tombstones do not prove deletion; complete delete envelopes do.

`integration source-status` reports raw, sealed and published progress, their
timestamps, waiting topic, bounds and stage pauses. `integration postgres-control`
accepts `pause_acquisition`, `resume_acquisition`, `pause_publication` and
`resume_publication` with the observed native revision. Acquisition pause does
not pause interpretation of retained input. Publication pause is checked again
in the final publication transaction. These are independent of Connect pause.

To retry a decoder failure after deploying a repair, pause acquisition, inspect
the exact `debezium_archive.replay_plan` digest, then use control `replay --plan`
with that digest and revision. It retries the retained unpublished prefix,
preserving its generation, schema and published predecessor. It cannot roll
back publication, invent missing bytes or admit a changed schema. Schema,
identity and continuity changes require an explicit new contract and rebaseline.

This is a bounded recovery archive, not indefinite Kafka history. Capacity
exhaustion stops acquisition visibly without advancing publication. Empty broker
polls do not improve source freshness. Complete zero-row source transactions
can establish quiet progress. Hosted qualification remains separate from source
checks and in-memory tests.

Connect mutations require a deployed `--source` and the usual deployment
selector. The native external-call owner commits intent before a PUT, uses an
exclusive hold, and reconciles unknown outcomes with GET only. The private
PostgreSQL credential must declare `debezium.control_authority` as
`{"kind":"observe"}` or `{"kind":"exclusive","grants":["configure","pause","resume","stop"]}`.
Grant only needed actions. Configuration control repairs the installation's
captured contract; initial enrollment and changed private bindings use a checked
capture and the normal connection owner. `debezium operation-status --operation`
inspects retained control custody without starting a pending send. Task status
remains the evidence of asynchronous connector completion. Replay also validates
the current SQL catalog before resuming retained interpretation.

## Provider references

Provider references and prerequisites are maintained in the connector guidance above. No separate provider-documentation review date is recorded.

## Source and evidence

[Canonical connector source](https://github.com/bijectionhq/component-support/blob/b632604330ce9cbcfe17a5a680ef4fbe80f6f672/packages/connectors/src/connectors/debezium/README.md), [native analysis](https://github.com/bijectionhq/component-support/blob/b632604330ce9cbcfe17a5a680ef4fbe80f6f672/packages/connectors/contract-analysis.json) and [check receipts](https://github.com/bijectionhq/component-support/blob/b632604330ce9cbcfe17a5a680ef4fbe80f6f672/packages/connectors/evidence.json).

Connector artifact: `905888ea276a2a28e36981a79e8142b2547ea451c3e63162cb6915ad4a7d1305`.

The resource declaration examples above are compiled and compared with exact catalog declarations. Recorded checks apply only to their source, declaration and runtime identities. Configure a connection and inspect its status to establish deployment-specific readiness.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.