Sending signals to a Debezium connector
Overview
The Debezium signaling mechanism provides a way to modify the behavior of a connector, or to trigger a one-time action, such as initiating an ad hoc snapshot of a table. To trigger a connector to perform a specified action, you issue a SQL command to add a signal message to a specialized signaling table, also referred to as a signaling data collection. The signaling table, which you create on the source database, is designated exclusively for communicating with Debezium. When Debezium detects that a new logging record or ad hoc snapshot record is added to the signaling table, it reads the signal, and initiates the requested operation.
Signaling is available for use with the following Debezium connectors:
-
Db2
-
MongoDB (Technology Preview)
-
MySQL
-
Oracle
-
PostgreSQL
-
SQL Server
Enabling signaling
By default, the Debezium signaling mechanism is disabled. You must explicitly enable signaling for each connector that you want to use it with.
-
On the source database, create a signaling data collection table for sending signals to the connector. For information about the required structure of the signaling data collection, see Structure of a signaling data collection.
-
For source databases such as Db2 or SQL Server that implement a native change data capture (CDC) mechanism, enable CDC for the signaling table.
-
Add the name of the signaling data collection to the Debezium connector configuration.
In the connector configuration, add the propertysignal.data.collection
, and set its value to the fully-qualified name of the signaling data collection that you created in Step 1.
For example,signal.data.collection = inventory.debezium_signals
.
The format for the fully-qualified name of the signaling collection depends on the connector.
The following example shows the naming formats to use for each connector:- Db2
-
<schemaName>.<tableName>
- MongoDB
-
<databaseName>.<collectionName>
- MySQL
-
<databaseName>.<tableName>
- Oracle
-
<databaseName>.<schemaName>.<tableName>
- PostgreSQL
-
<schemaName>.<tableName>
- SQL Server
-
<databaseName>.<schemaName>.<tableName>
For more information about setting thesignal.data.collection
property, see the table of configuration properties for your connector.
Structure of a signaling data collection
A signaling data collection, or signaling table, stores signals that you send to a connector to trigger a specified operation. The structure of the signaling table must conform to the following standard format.
-
Contains three fields (columns).
-
Fields are arranged in a specific order, as shown in Table 1.
Field | Type | Description |
---|---|---|
|
|
An arbitrary unique string that identifies a signal instance. |
|
|
Specifies the type of signal to send. |
|
|
Specifies JSON-formatted parameters to pass to a signal action. |
The field names in a data collection are arbitrary. The preceding table provides suggested names. If you use a different naming convention, ensure that the values in each field are consistent with the expected content. |
Creating a signaling data collection
You create a signaling table by submitting a standard SQL DDL query to the source database.
-
You have sufficient access privileges to create a table on the source database.
-
Submit a SQL query to the source database to create a table that is consistent with the required structure, as shown in the following example:
CREATE TABLE <tableName> (id VARCHAR(<varcharValue>) PRIMARY KEY, type VARCHAR(<varcharValue>) NOT NULL, data VARCHAR(<varcharValue>) NULL);
The amount of space that you allocate to the |
The following example shows a CREATE TABLE
command that creates a three-column debezium_signal
table:
CREATE TABLE debezium_signal (id VARCHAR(42) PRIMARY KEY, type VARCHAR(32) NOT NULL, data VARCHAR(2048) NULL);
Signal actions
You can use signaling to initiate the following actions:
Some signals are not compatible with all connectors.
Logging signals
You can request a connector to add an entry to the log by creating a signaling table entry with the log
signal type.
After processing the signal, the connector prints the specified message to the log.
Optionally, you can configure the signal so that the resulting message includes the streaming coordinates.
Column | Value | Description |
---|---|---|
id |
|
|
type |
|
The action type of the signal. |
data |
|
The |
Ad hoc snapshot signals
You can request a connector to initiate an ad hoc snapshot by creating a signaling table entry with the execute-snapshot
signal type.
After processing the signal, the connector runs the requested snapshot operation.
Unlike the initial snapshot that a connector runs after it first starts, an ad hoc snapshot occurs during runtime, after the connector has already begun to stream change events from a database. You can initiate ad hoc snapshots at any time.
Ad hoc snapshots are available for the following Debezium connectors:
-
Db2
-
MongoDB
-
MySQL
-
Oracle
-
PostgreSQL
-
SQL Server
Column | Value |
---|---|
id |
|
type |
|
data |
|
Currently, the execute-snapshot
action triggers incremental snapshots only.
For more information about ad hoc snapshots, see the Snapshots topic in the documentation for your connector.
Ad hoc snapshot stop signals
You can request a connector to stop an in-progress ad hoc snapshot by creating a signal table entry with the stop-snapshot
signal type.
After processing the signal, the connector will stop the current in-progress snapshot operation.
You can stop ad hoc snapshots for the following Debezium connectors:
-
Db2
-
MongoDB
-
MySQL
-
Oracle
-
PostgreSQL
-
SQL Server
Column | Value |
---|---|
id |
|
type |
|
data |
|
You must specify the type
of the signal.
The data-collections
field is optional.
Leave the data-collections
field blank to request the connector to stop all activity in the current snapshot.
If you want the incremental snapshot to proceed, but you want to exclude specific collections from the snapshot, provide a comma-separated list of the names of the collections or regular expressions to exclude.
After the connector processes the signal, the incremental snapshot proceeds, but it excludes data from the collections that you specify.
Incremental snapshots
Incremental snapshots are a specific type of ad hoc snapshot. In an incremental snapshot, the connector captures the baseline state of the tables that you specify, similar to an initial snapshot. However, unlike an initial snapshot, an incremental snapshot captures tables in chunks, rather than all at once. The connector uses a watermarking method to track the progress of the snapshot.
By capturing the initial state of the specified tables in chunks rather than in a single monolithic operation, incremental snapshots provide the following advantages over the initial snapshot process:
-
While the connector captures the baseline state of the specified tables, streaming of near real-time events from the transaction log continues uninterrupted.
-
If the incremental snapshot process is interrupted, it can be resumed from the point at which it stopped.
-
You can initiate an incremental snapshot at any time.
Incremental snapshot pause signals
You can request a connector to pause an in-progress incremental snapshot by creating a signal table entry with the pause-snapshot
signal type.
After processing the signal, the connector will stop pause current in-progress snapshot operation.
Therefor it’s not possible to specify the data collection as the snapshot processing will be paused in position where it is in time of processing of the signal.
You can pause incremental snapshots for the following Debezium connectors:
-
Db2
-
MongoDB
-
MySQL
-
Oracle
-
PostgreSQL
-
SQL Server
Column | Value |
---|---|
id |
|
type |
|
You must specify the type
of the signal.
The data
field is ignored.
Incremental snapshot resume signals
You can request a connector to resume a paused incremental snapshot by creating a signal table entry with the resume-snapshot
signal type.
After processing the signal, the connector will resume previously paused snapshot operation.
You can resume incremental snapshots for the following Debezium connectors:
-
Db2
-
MongoDB
-
MySQL
-
Oracle
-
PostgreSQL
-
SQL Server
Column | Value |
---|---|
id |
|
type |
|
You must specify the type
of the signal.
The data
field is ignored.
For more information about incremental snapshots, see the Snapshots topic in the documentation for your connector.