MariaDB CDC (Change Data Capture)

Change Data Capture (CDC) streams row-level inserts, updates and deletes from your MariaDB database into your warehouse. Rather than re-reading tables on a schedule or tracking a cursor column, Weld reads MariaDB's binary log (binlog) over a replication connection.

That has three consequences worth knowing before you set it up:

• Deletes and updates propagate. A cursor-based incremental sync only finds rows whose cursor has moved, so rows deleted or updated in place never reach the warehouse. CDC sees every change.
• Lower load on your server. Weld reads the binlog instead of scanning tables.
• Lower latency, because changes are read as they are written rather than on the next scheduled run.

What Weld does on your database

Weld connects to MariaDB as a read-only replica. Specifically:

• No write access is needed. Weld does not create tables, insert rows, or run DDL.
• No locks are taken, including during the initial copy.
• Only the database and tables you select are read.
• No GTID or replication-topology changes are required (see GTIDs below).
• Weld identifies itself with its own unique replica ID, derived per table from the sync.

Prerequisites

1) A user Weld can connect and replicate with

CREATE USER 'weld_cdc_user' IDENTIFIED BY '<set password here>';
-- Read the binary log
GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'weld_cdc_user';
-- Read table data for the initial copy and any backfills
GRANT SELECT ON *.* TO 'weld_cdc_user';
FLUSH PRIVILEGES;

Weld's IP pool must also be reachable — see the MariaDB connector setup guide for the addresses to allow.

2) Row-based binary logging

Check the current values:

-- Must be ON
SHOW VARIABLES LIKE 'log_bin';
-- Must be ROW
SHOW VARIABLES LIKE 'binlog_format';
-- Must be FULL
SHOW VARIABLES LIKE 'binlog_row_image';
-- Must be set, non-zero, and unique in your replication topology
SHOW VARIABLES LIKE 'server_id';

Target values:

• log_bin = ON
• binlog_format = ROW
• binlog_row_image = FULL
• server_id set and unique

3) Binary log retention

Set retention to at least 3 days. CDC resumes from where it left off, so this window is how long you have to fix a broken sync before the changes it missed are gone and a full re-copy is needed — a failure overnight or over a weekend should still be recoverable on the next working day.

Weld enforces a floor of 21600 seconds (6 hours) and will not offer CDC below that. 0 is also accepted and means binary logs never expire.

From MariaDB 10.6 onwards, set it in seconds:

SHOW VARIABLES LIKE 'binlog_expire_logs_seconds';
-- 3 days
SET GLOBAL binlog_expire_logs_seconds = 259200;

On older versions, use expire_logs_days, which accepts fractional days:

SHOW VARIABLES LIKE 'expire_logs_days';
-- 3 days
SET GLOBAL expire_logs_days = 3;

Persist whichever you set in my.cnf so it survives a restart.

4) Every CDC table has a primary key or a unique index

CDC needs a stable row identifier to apply updates and deletes correctly. Weld determines this from INFORMATION_SCHEMA.STATISTICS, and only offers tables that have one.

Run the same query as the Weld user to see exactly which tables will be offered — a table missing from the result cannot be selected:

SELECT DISTINCT TABLE_NAME
FROM INFORMATION_SCHEMA.STATISTICS
WHERE TABLE_SCHEMA = DATABASE() AND NON_UNIQUE = 0;

5) Server timezone

If your server's time_zone is a legacy or OS-specific name rather than an IANA identifier, timestamps cannot be interpreted reliably. Either set the server to the equivalent IANA identifier, or select an IANA timezone in the connector configuration in Weld.

GTIDs and the watermark table

If you have set MySQL CDC up before, you may expect to either enable gtid_mode or create a watermark table for Weld to track the progress of its initial copy. Neither is needed on MariaDB.

MariaDB has no gtid_mode variable — it records GTIDs whenever the binary log is enabled, and exposes gtid_binlog_pos, which Weld uses to mark the boundaries of the initial copy. This is why Weld can run entirely read-only against MariaDB.

🔧 Enable CDC in Weld

Step 1 — Open your MariaDB connection

Open the connection in Weld and enable CDC in its configuration.

Step 2 — Select tables

Choose which tables to replicate with CDC. Only tables with a primary key or unique index are selectable.

Step 3 — Let the initial copy finish

Weld takes one copy of each selected table, then switches to reading the binlog. The initial copy is chunked and takes no locks, but it does read the whole table, so expect it to take a while on large ones.

Housekeeping

• Retention covers your downtime. If a CDC sync is stopped or deleted, binlogs continue to expire on your server's schedule. If Weld is offline for longer than the retention window, the missed changes are gone and the table needs a fresh copy.
• Schema changes are not replicated as DDL. Adding a column is picked up on the next schema refresh; renaming or dropping one may need the table re-copied.

MariaDB-specific type support

Weld maps MariaDB's own column types to strings: