Connectors for Change Data Capture (CDC)

When to use change data capture connectors

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).

Etlworks supports native log-based change data capture for PostgreSQL, SQL Server, MySQL, Oracle, and MongoDB.

The CDC connection is used as a source in the:

• CDC flows when the target is a relational database
• CDC flows when the target is Snowflake
• CDC flows when the target is Amazon Redshift

Creating a connection

Step 1. Enable CDC for the source database.

• Microsoft SQL Server
• MySQL
• Oracle
• PostgreSQL
• MongoDB

Step 2. In the Connections window, click the + button and type in cdc.

 

Step 3. Select the source database.

Step 3. Enter connection parameters.

Connection parameters

All databases 

• Name - a required unique name of the connection. Attempting to register again with the same name will fail. The value of this field is used as a part of the offset file name, which tracks the latest CDC offrest.  
• Whitelisted Databases(s) - a comma-separated list of whitelisted databases(s) to extract data from.
• Whitelisted Table(s) - a comma-separated list of regular expressions that match fully-qualified table identifiers for tables to be monitored; any table not included in the whitelist will be excluded from monitoring. Each identifier is of the form databaseName.tableName. By default, the connector will monitor every non-system table in each monitored database. This parameter will be overridden in the TO field of the CDC flow.
• Blacklisted Columns(s) - an optional comma-separated list of regular expressions that match the fully-qualified names of columns that should be excluded from change event message values. Fully-qualified names for columns are of the form databaseName.tableName.columnName, or databaseName.schemaName.tableName.columnName.
• CDC Key - a template for CDC key. The CDC key is used as a file name when serializing CDC events to the CSV files in local storage and as a topic name when sending events to the message queue, such as Kafka. The CDC key template is different for each database (see below).

Authentication

• User - the user name
• Password - the password

Serialization

The properties below are used exclusively to configure the flow which stores CDC events in local storage as CSV files.

• Serialize CDC events as CSV files into internal storage - If this option is enabled, the CDC connector ignores the destination and saves the CDC events into the internal storage as database.table_uuid.csv files.
• Location of the CDC events serialized as CSV files - optional location of the CDC events serialized as CSV files. The default location is {app.data}/debezium_data/events.
• Max Rows in CSV file - the maximum number of rows in CSV file.
• Maximum wait time before closing the CSV file if not updated (ms) - maximum wait time in milliseconds before closing the CSV file if not updated.
• Force close CSV file after (ms) - the wait time in milliseconds before force closing the CSV file even if it is still getting updated or has not reached the maximum number of rows.
• Escape double-quotes - is this option is enabled, a double-quote appearing inside a field will be escaped by preceding it with another double quote
• Treat 'null' as null - if this option is enabled the connection will treat strings equal to 'null' as NULL (no value) when creating the CSV file.
• Preprocessor - the optional JavaScript that can be used to change the CDC event before saving it to the CSV file. The following variables are available in the preprocessor code:
  • event - the CDC event serialized as com.fasterxml.jackson.databind.JsonNode. You can change the event using the methods of the JsonNode class.
  •  key - the CDC key. This variable is immutable. 

Offset parameters

Active CDC connection records the latest offset in the transaction log to the file {app.data}/debezium_data/offeset_file_name.dat. You can override the default file name which is calculated using the unique name of the connection.

• Offset Commit Interval (ms) - Interval at which connector will be committing offsets. The default is 1 minute.
• Offset Flush Timeout (ms) - maximum number of milliseconds to wait for records to flush and partition offset data to be committed to offset storage before canceling the process and restoring the offset data to be committed in a future attempt. The default is 5 seconds.
• Offset File Name - the offset file name. If this field is empty the offset file name will be calculated automatically using the unique name of the connection. The offset file is located in {app.data}/debezium_data.
• DDL History File Name - the DDL history file name. If this field is empty the DDL file name will be calculated automatically using the unique name of the connection. The DDL history file is located in {app.data}/debezium_data.

Other parameters

• Snapshot Mode - specifies the criteria for running a snapshot upon startup of the connector. It is different for each database (see below).
• Restream from the beginning if Error - if an error occurred and this option is enabled, the system will automatically switch to the snapshot mode and attempt to reload the whole table in the next run. Read more about handling errors in CDC flows. 
• Use Internal Queue - If the use of queue is enabled, the system will store CDC events in the queue before sending them further in the pipeline for processing. The queue is used to reprocess events in case of failures. This option is ignored if Restream from the beginning if Error is enabled. Read more about using internal queue.
• Always generate INSERT - if enabled, the system will always generate INSERT SQL, even for UPDATEs and DELETEs. When this option is enabled the following fields will be automatically added to the downstream payload:
  • debezium_cdc_op - event type, "c" for create, "u" for update and "d" for delete.
  • debezium_cdc_timestamp - the event timestamp encoded as EPOCH time in milliseconds. 
• This field must be enabled when loading data into an online data warehouses, such as Amazon Redshift or Snowflake.
• Extra columns - the columns specified in this field will be added to the end of the stream. The column value will be either empty or set to the value of the global variable with the same name.
• Number of retries before giving up - the number of retries before giving up if poll returns no records. The default is 5.
• Retry N minutes before giving up - the number of minutes to retry before giving up if the poll returns no records.
• Maximum Queue Size - a positive integer value that specifies the maximum size of the blocking queue into which change events read from the database log are placed before they are written to stream. This queue can provide backpressure to the transactional log reader when, for example, writes to the stream are slower. Events that appear in the queue are not included in the offsets periodically recorded by this connector. Defaults to 8192, and should always be larger than the maximum batch size.
• Maximum Batch Size - a positive integer value that specifies the maximum size of each batch of events that should be processed during each iteration of this connector. Defaults to 2048.
• Poll Interval in Milliseconds - positive integer value that specifies the number of milliseconds the connector should wait during each iteration for new change events to appear. Defaults to 1000 milliseconds, or 1 second. 
• Connection Timeout in Milliseconds - a positive integer value that specifies the maximum time in milliseconds this connector should wait after trying to connect to the database server before timing out. Defaults to 30 seconds.
• Other Parameters - other parameters as key=value pairs. The parameters are specific for the different connectors.
• Template - use template to populate columns for mapping without actually connecting to the source database. Example: {\"first\":\"string\",\"last\":\"string\"}
• 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).
• Template - Use the template to populate columns. Example: {\"first\":\"string\",\"last\":\"string\"}

Connecting to a database over SSH tunnel

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.

Database specific parameters

SQL Server

• Host - the host or IP address of the source database.
• Port - the port the source database is listening to.
• Database - the name of the database to connect on startup.
• CDC Key - a template for CDC key. The CDC key is used as a file name when serializing CDC events to the CSV files in local storage and as a topic name when sending events to the message queue, such as Kafka. Example of the CDC key: testDB_dbo_customers_cdc_stream. Available tokens: [db] - database name, [schema] - schema name, [table] - table name. Also: [op], [timestamp], [version], [connector], [name], [ts_ms], [snapshot], [change_lsn], [commit_lsn], [event_serial_no].
• JDBC Fetch Size - the JDBC Fetch Size field can be used to set the maximum number of records which will be retrieved in one database call when fetching the data in a snapshot mode, thus limiting the memory consumption within the JVM. The default is 10000.
• Max Rows to Read - the maximum number of rows to read when fetching the data in a snapshot mode. The default is empty, hence no limit.
• Max Field Size - sets the limit for the maximum number of bytes that can be returned for character and binary column values in a ResultSet object produced by this Statement object. The default is empty, hence there is no limit.
• 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.
• 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

• Host - the host or IP address of the source database.
• Port - the port the source database is listening to.
• Database - the name of the database to connect on startup.
• CDC Key - a template for CDC key. The CDC key is used as a file name when serializing CDC events to the CSV files in local storage and as a topic name when sending events to the message queue, such as Kafka. Example of the CDC key: inventory_customers_cdc_stream. Available tokens: [db] - database name, [table] - table name. Also: [op], [timestamp], [version], [connector], [name], [ts_ms], [snapshot], [server_id], [gtid], [file], [pos], [row].
• JDBC Fetch Size - the JDBC Fetch Size field can be used to set the maximum number of records which will be retrieved in one database call when fetching the data in a snapshot mode, thus limiting the memory consumption within the JVM. The default is 10000.
• Max Rows to Read - the maximum number of rows to read when fetching the data in a snapshot mode. The default is empty, hence no limit.
• Max Field Size - sets the limit for the maximum number of bytes that can be returned for character and binary column values in a ResultSet object produced by this Statement object. The default is empty, hence no limit.
• 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.
• Case sensitive matching - By default, the system will use the case insensitive pattern to whitelist the db.table to stream. For example, if there is a database 'test' and the tables 'abc' and 'Abc' the stream will include records from 'test.abc' and 'test.Abc'. By enabling this option you can enforce the case sensitive matching of the db.table defined for the source.
• 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.
• We recommend setting the snapshot mode to when_needed. 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.

Oracle

• Host - the host or IP address of the source database.
• Port - the port that the source database is listening to.
• Database - the name of the database to connect on startup. 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.
• CDC Key - a template for CDC key. The CDC key is used as a file name when serializing CDC events to the CSV files in local storage and as a topic name when sending events to the message queue, such as Kafka. Example of the CDC key: server1_DEBEZIUM_CUSTOMERS_Envelope_cdc_stream. Available tokens: [source] - fully qualified event source. Also: [op], [timestamp], [version], [name], [snapshot], [txId], [scn]
• JDBC Fetch Size - the JDBC Fetch Size field can be used to set the maximum number of records which will be retrieved in one database call when fetching the data in a snapshot mode, thus limiting the memory consumption within the JVM. The default is 10000.
• Max Rows to Read - the maximum number of rows to read when fetching the data in a snapshot mode. The default is empty, hence there is no limit.
• Max Field Size - sets the limit for the maximum number of bytes that can be returned for character and binary column values in a ResultSet object produced by this Statement object. The default is empty, hence there is no limit.
• 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.
• 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

• Host - the host or IP address of the source database.
• Port - the port the source database is listening to.
• Database - the name of the database to connect on startup.
• CDC Key - a template for CDC key. The CDC key is used as a file name when serializing CDC events to the CSV files in local storage and as a topic name when sending events to the message queue, such as Kafka. Example of the CDC key: postgres_public_customers_cdc_stream.  Available tokens: [db] - database name, [schema] - schema name, [table] - table name. Also: [op], [timestamp], [version], [connector], [name], [ts_ms], [snapshot], [txId], [lsn], [xmin].
• JDBC Fetch Size - the JDBC Fetch Size field can be used to set the maximum number of records which will be retrieved in one database call when fetching the data in a snapshot mode, thus limiting the memory consumption within the JVM. The default is 10000.
• Max Rows to Read - the maximum number of rows to read when fetching the data in a snapshot mode. The default is empty, hence there is no limit.
• Max Field Size - sets the limit for the maximum number of bytes that can be returned for character and binary column values in a ResultSet object produced by this Statement object. The default is empty, hence there is no limit.
• 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.
• Output Plugin - PostgreSQL’s logical decoding feature was first introduced in version 9.4 and is a mechanism that 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.

MongoDB

• Cluster URL - the required connection string. Read about the MongoDB connection string.
• Replica Sets or Shards - to use the MongoDB connector with a replica set, simply provide the addresses of one or more replica set servers as seed addresses. The connector will use these seeds to connect to the replica set, and then once connected will get from the replica set the complete set of members and which member is primary. The connector will start a task to connect to the primary and capture the changes from the primary’s oplog. When the replica set elects a new primary, the task will automatically switch over to the new primary. To use the MongoDB connector with a sharded cluster, configure the connector with the host addresses of the configuration server replica set. When the connector connects to this replica set, it discovers that it is acting as the configuration server for a sharded cluster, discovers the information about each replica set used as a shard in the cluster, and will then start up a separate task to capture the changes from each replica set. If new shards are added to the cluster or existing shards removed, the connector will automatically adjust its tasks accordingly.
• CDC Key - a template for CDC key. The CDC key is used as a file name when serializing CDC events to the CSV files in local storage and as a topic name when sending events to the message queue, such as Kafka. Example of the CDC key: inventory_customers_cdc_stream. Available tokens: [db] - database name, [collection] - collection name Also: [op], [timestamp], [version], [connector], [name], [ts_ms], [snapshot], [order], [h].
• Cluster Name - a unique name that identifies the MongoDB replica set or sharded cluster that this connector monitors. Defaults to URL, though we recommend using an explicit and meaningful logical name.
• Collection - the MongoDB collection to stream changes from. This parameter can be overwritten in the flow.
• Snapshot Mode - specifies the criteria for running a snapshot (eg. initial sync) upon startup of the connector. The default is initial, and specifies that the connector reads a snapshot when either no offset is found or if the oplog no longer contains the previous offset. The never option specifies that the connector should never use snapshots, instead the connector should proceed to tail the log.
• New name of the Object ID (_id) field - each record in MongoDB collection has an "_id" field. Typically it is some sort of nested JSON object, often generated automatically. The CDC flow will automatically flatten the value of the "_id" field and transform it into a unique string. Example: "_id": ObjectId("54759eb3c090d83494e2d804") to "_id": "54759eb3c090d83494e2d804". It will also rename the "_id" field. The default new name is "mongo_id".
• Number of Documents in Explorer - The maximum number of the MongoDB documents that can be displayed in the Explorer. The default value is 10, the maximum possible value is 9999. MongoDB can contain millions of documents, so displaying all of them can kill the server.