Database connections for Change Data Capture (CDC)

Change data capture (CDC) is an approach to data integration that is based on the identification, capture, and delivery of the changes made to the source database and stored in the database redo log (also called transaction log).

The CDC connections are used as a source in the CDC flows.

Creating a connection

Step 1. Enable CDC for the source database.

• Microsoft SQL Server
• MySQL
• Oracle
• PostgreSQL

Step 2. In the Connections window, click the + button and select CDC.

Step 3. Select the source database.

Step 3. Enter connection parameters.

Connection parameters

All databases

• Host - the host or IP address of the source database
• Port - the port the source database is listening to
• User - the user name
• Password - the password
• Table - the fully qualified name of the source table. This parameter will be overridden in the TO field of the CDC flow.
• Snapshot Mode - it is different for each database (see below).
• Always generate INSERT - if enabled, the system will always generate INSERT SQL, even for UPDATEs and DELETEs. It will also add two extra columns to the payload: debezium_cdc_op (actual CRUD operation) and debezium_cdc_timestamp (an event timestamp in milliseconds). This field must be enabled when loading data into an online data warehouses, such as Amazon Redshift or Snowflake.
• Number of retries before giving up - the number of retries before giving up if poll returns no records. The default is 0
• Flash Interval (ms) - this parameter defines how often (in milliseconds) the system flashes the offset pointer. The offset pointer is used to thack the last known position of the CDC records in the database transaction log. 
• Other Parameters - other parameters as key=value pairs. The parameters are specific for the different connectors.
• Date and Time Format - the format for TIMESTAMP fields. If not entered the TIMESTAMP fields will be serialized as Linux epoch time (in milliseconds).
• Date Format - the format for DATE fields. If not entered the DATE fields will be serialized as Linux epoch time (in milliseconds).
• Time Format - the format for TIME fields. If not entered the TIME fields will be serialized as Linux epoch time (in milliseconds).

If you need to access a database that can only be accessed via an SSH tunnel, you need to specify additional information in the "Connect over SSH tunnel" section of the database connection screen.

• SSH Host - the name or IP address for the host accepting SSH connections.
• SSH Port - the port accepting SSH connections. The default value is 22.
• SSH User  - the user name
• SSH Password - the optional password
• Private Key File - the private key file in the pem or ppk format used for SSH authentication. Click the "Upload/Select ssh key" button to manage SSH keys using GUI. You can also upload the private key file manually and use the token {app.data} as a part of the filename, for example, {app.data}/keys/secret.pem. This parameter is optional.

SQL Server

• Server - logical name that identifies and provides a namespace for the particular SQL Server database server being monitored. The logical name should be unique across all other connectors.
• Database - the name of the SQL Server database from which to stream the changes.
• Snapshot Mode - a mode for taking an initial snapshot of the structure and optional data of captured tables. Supported values are initial (will take a snapshot of structure and data of captured tables; useful if topics should be populated with a complete representation of the data from the captured tables) and initial_schema_only (will take a snapshot of the structure of captured tables only; useful if only changes happening from now onwards should be propagated to topics). Once the snapshot is complete, the connector will continue reading change events from the database’s redo logs.

MySQL

• Server - logical name that identifies and provides a namespace for the particular MySQL database server/cluster being monitored. The logical name should be unique across all other connectors. Defaults to host:port, though we recommend using an explicit and meaningful logical name.
• Snapshot Mode - specifies the criteria for running a snapshot upon startup of the connector. The default is initial, and specifies the connector can run a snapshot only when no offsets have been recorded for the logical server name. The when_needed option specifies that the connector run a snapshot upon startup whenever it deems it necessary (when no offsets are available, or when a previously recorded offset specifies a binlog location or GTID that is not available in the server). The never option specifies that the connect should never use snapshots and that upon first startup with a logical server name the connector should read from the beginning of the binlog. This should be used with care, as it is only valid when the binlog is guaranteed to contain the entire history of the database. If you don’t need the topics to contain a consistent snapshot of the data but only need them to have the changes since the connector was started, you can use the schema_only option, where the connector only snapshots the schemas (not the data). schema_only_recovery is a recovery option for an existing connector to recover a corrupted or lost database history topic, or to periodically clean up a database history topic (which requires infinite retention) that may be growing unexpectedly.

Oracle

• Server - logical name that identifies and provides a namespace for the particular Oracle database server being monitored. The logical name should be unique across all other connectors.
• Database - the name of the Oracle database from which to stream the changes. Must be the CDB name when working with the CDB + PDB model.
• Name of the PDB - name of the PDB to connect to, when working with the CDB + PDB model.
• Name of the XStream outbound server - name of the XStream outbound server configured in the database.
• Snapshot Mode - a mode for taking an initial snapshot of the structure and optional data of captured tables. Supported values are initial (will take a snapshot of structure and data of captured tables; useful if topics should be populated with a complete representation of the data from the captured tables) and initial_schema_only (will take a snapshot of the structure of captured tables only; useful if only changes happening from now onwards should be propagated to topics). Once the snapshot is complete, the connector will continue reading change events from the database’s redo logs.

Postgres

• Server - logical name that identifies and provides a namespace for the particular PostgreSQL database server/cluster being monitored. The logical name should be unique across all other connectors, since it is used as a prefix for all Kafka topic names coming from this connector. Defaults to host:port/dbname, though we recommend using an explicit and meaningful logical name.
• Database - the name of the PostgreSQL database from which to stream the changes
• Output Plugin - PostgreSQL’s logical decoding feature was first introduced in version 9.4 and is a mechanism which allows the extraction of the changes which were committed to the transaction log and the processing of these changes in a user-friendly manner via the help of an output plugin. This output plugin must be installed prior to running the PostgreSQL server and enabled together with a replication slot in order for clients to be able to consume the changes.
• Snapshot Mode - specifies the criteria for running a snapshot upon startup of the connector. The default is initial, and specifies the connector can run a snapshot only when no offsets have been recorded for the logical server name. The always option specifies that the connector run a snapshot each time on startup. The never option specifies that the connect should never use snapshots and that upon first startup with a logical server name the connector should read from either from where it last left off (last LSN position) or start from the beginning from the point of the view of the logical replication slot. Finally, the initial_only option specifies that the connector should only take an initial snapshot and then stop, without processing any subsequent changes.