MySQL CDC
MySQL CDC source 连接器
支持这些引擎
Spark
SeaTunnel Zeta
Flink
描述
MySQL CDC连接器允许从MySQL数据库读取快照和增量数据. 本文档描述了如何配置MySQL CDC连接器以对MySQL数据库运行SQL查询.
主要功能
支持的数据源信息
| 数据源 | 支持的版本 | Driver | Url | Maven |
|---|---|---|---|---|
| MySQL | com.mysql.cj.jdbc.Driver | jdbc:mysql://localhost:3306/test | https://mvnrepository.com/artifact/mysql/mysql-connector-java/8.0.28 |
依赖
安装Jdbc驱动
对于Spark/Flink引擎
- 你需要确保 jdbc 驱动 jar package 已经放在目录
${SEATUNNEL_HOME}/plugins/.
对于SeaTunnel Zeta引擎
- 你需要确保 jdbc 驱动 jar package 已经放在目录
${SEATUNNEL_HOME}/lib/.
创建MySQL用户
你必须定义一个MySQL用户,该用户对Debezium MySQL连接器所监控的所有数据库拥有适当的权限.
- 创建MySQL用户:
mysql> CREATE USER 'user'@'localhost' IDENTIFIED BY 'password';
- 给用户赋予所需权限:
mysql> GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user' IDENTIFIED BY 'password';
- 最终确定用户权限:
mysql> FLUSH PRIVILEGES;
启用MySQL Binlog
一定要为MySQL复制启用binlog。binlog记录事务更新以供复制工具传播更改.
- 检查
log-bin是否已经设置为on:
mysql> show variables where variable_name in ('log_bin', 'binlog_format', 'binlog_row_image', 'gtid_mode', 'enforce_gtid_consistency');
+--------------------------+----------------+
| Variable_name | Value |
+--------------------------+----------------+
| binlog_format | ROW |
| binlog_row_image | FULL |
| enforce_gtid_consistency | ON |
| gtid_mode | ON |
| log_bin | ON |
+--------------------------+----------------+
- 如果
log_bin的值不是on, 配置你的MySQL server配置文件($MYSQL_HOME/mysql.cnf),配置文件中包含以下属性,这些属性在以下表格中有描述:
# Enable binary replication log and set the prefix, expiration, and log format.
# The prefix is arbitrary, expiration can be short for integration tests but would
# be longer on a production system. Row-level info is required for ingest to work.
# Server ID is required, but this will vary on production systems
server-id = 223344
log_bin = mysql-bin
expire_logs_days = 10
binlog_format = row
# mysql 5.6+ requires binlog_row_image to be set to FULL
binlog_row_image = FULL
# optional enable gtid mode
# mysql 5.6+ requires gtid_mode to be set to ON, but not required by mysql 8.0+
gtid_mode = on
enforce_gtid_consistency = on
- 重启MySQL Server
/etc/inint.d/mysqld restart
- 修改之后再检查一次binlog的状态:
MySQL 5.5:
mysql> show variables where variable_name in ('log_bin', 'binlog_format', 'binlog_row_image', 'gtid_mode', 'enforce_gtid_consistency');
+--------------------------+----------------+
| Variable_name | Value |
+--------------------------+----------------+
| binlog_format | ROW |
| log_bin | ON |
+--------------------------+----------------+
MySQL 5.6+:
mysql> show variables where variable_name in ('log_bin', 'binlog_format', 'binlog_row_image', 'gtid_mode', 'enforce_gtid_consistency');
+--------------------------+----------------+
| Variable_name | Value |
+--------------------------+----------------+
| binlog_format | ROW |
| binlog_row_image | FULL |
| enforce_gtid_consistency | ON |
| gtid_mode | ON |
| log_bin | ON |
+--------------------------+----------------+
MySQL 8.0+:
show variables where variable_name in ('log_bin', 'binlog_format', 'binlog_row_image', 'gtid_mode', 'enforce_gtid_consistency')
+--------------------------+----------------+
| Variable_name | Value |
+--------------------------+----------------+
| binlog_format | ROW |
| binlog_row_image | FULL |
| enforce_gtid_consistency | OFF |
| gtid_mode | OFF |
| log_bin | ON |
+--------------------------+----------------+
提示
配置MySQL session超时时长
当为大型数据库初始一致快照时,已建立的连接可能在读取表时超时。可以通过在MySQL配置文件中配置interactive_timeout(交互超时时间)和wait_timeout(等待超时时间)来防止这种行为.
interactive_timeout: 服务器在关闭交互连接之前等待活动(交互操作)的秒数. 详见 MySQL’s documentation.wait_timeout: 服务器在关闭非交互式连接之前等待其活动的秒数. 详见 MySQL’s documentation.
更多的数据库配置,见 Debezium MySQL Connector
数据类型映射
| Mysql数据类型 | SeaTunnel数据类型 |
|---|---|
| BIT(1) TINYINT(1) | BOOLEAN |
| TINYINT | TINYINT |
| TINYINT UNSIGNED SMALLINT | SMALLINT |
| SMALLINT UNSIGNED MEDIUMINT MEDIUMINT UNSIGNED INT INTEGER YEAR | INT |
| INT UNSIGNED INTEGER UNSIGNED BIGINT | BIGINT |
| BIGINT UNSIGNED | DECIMAL(20,0) |
| DECIMAL(p, s) DECIMAL(p, s) UNSIGNED NUMERIC(p, s) NUMERIC(p, s) UNSIGNED | DECIMAL(p,s) |
| FLOAT FLOAT UNSIGNED | FLOAT |
| DOUBLE DOUBLE UNSIGNED REAL REAL UNSIGNED | DOUBLE |
| CHAR VARCHAR TINYTEXT MEDIUMTEXT TEXT LONGTEXT ENUM SET JSON | STRING |
| DATE | DATE |
| TIME(s) | TIME(s) |
| DATETIME TIMESTAMP(s) | TIMESTAMP(s) |
| BINARY VARBINAR BIT(p) TINYBLOB MEDIUMBLOB BLOB LONGBLOB GEOMETRY | BYTES |
配置参数选项
| 参数名称 | 类型 | 是否必须 | 默认值 | 描述 |
|---|---|---|---|---|
| url | String | 是 | - | JDBC连接的URL. 例如: jdbc:mysql://localhost:3306/test. |
| username | String | 是 | - | 连接 MySQL 服务时使用的用户名. |
| password | String | 是 | - | 连接到数据库服务所使用的密码. |
| database-names | List | 否 | - | 要监控的数据库名称. |
| database-pattern | String | 否 | .* | 要捕获的数据库名称的正则表达式, 例如: database_prefix.*. |
| table-names | List | 条件必填 | - | 要监控的表名,每个表名都需要包含库名,例如:database_name.table_name。table-names 和 table-pattern 二选一配置。 |
| table-pattern | String | 条件必填 | - | 要捕获的表名正则表达式,匹配到的表名需要包含库名,例如:database.*\\.table_.*。table-names 和 table-pattern 二选一配置。 |
| table-names-config | List | 否 | - | 按表单独配置。例如:[{"table": "db1.table1","primaryKeys": ["key1"],"snapshotSplitColumn": "key2"}]。当表没有主键、需要自定义主键,或需要指定快照拆分列时使用。snapshotSplitColumn 应该是主键或唯一键;如果指定了非唯一列,SeaTunnel 会忽略该配置并自动选择合适的拆分列。 |
| startup.mode | Enum | 否 | INITIAL | MySQL CDC 消费者的可选启动模式, 有效枚举值为 initial, earliest, latest , specific, timestamp 和 snapshot-only. initial: 启动时同步历史数据, 然后同步增量数据.earliest: 从尽可能最早的偏移量开始启动.latest: 从最近的偏移量启动.specific: 从用户提供的特定偏移量开始启动.timestamp: 从用户提供的特定时间戳开始启动.snapshot-only: 仅读取快照数据,读取完成后任务有界结束,不会在快照完成后进入持续 binlog 流式读取。适用于一次性回填或初始化引导场景。该模式支持使用 exactly_once 在快照阶段执行有界回填,但不能与除 never 外的 stop.mode 或 binlog 相关的 startup.specific-offset.*、startup.timestamp 同时使用。不支持在从 checkpoint 恢复时更改 startup.mode。在 snapshot-only 与其他启动模式之间切换时,请提交新作业。 |
| startup.specific-offset.file | String | 否 | - | 从指定的binlog日志文件名开始. 注意, 当使用 startup.mode 选项为 specific 时,此选项为必填项. 当 startup.mode 为 snapshot-only 时不允许配置此选项. |
| startup.specific-offset.pos | Long | 否 | - | 从指定的binlog日志文件位置开始. 注意, 当使用 startup.mode 选项为 specific 时,此选项为必填项. 当 startup.mode 为 snapshot-only 时不允许配置此选项. |
| startup.specific-offset.gtid-set | String | 否 | - | 当 startup.mode 为 specific 时,可选配置 MySQL GTID 集合. 该选项需要和 startup.specific-offset.file、startup.specific-offset.pos 一起使用. 当 startup.mode 为 snapshot-only 时不允许配置此选项. |
| startup.specific-offset.skip-events | Long | 否 | - | 配置 specific 启动偏移量后需要跳过的 binlog event 数量. 未配置时不跳过任何 event. 该选项只能在 startup.mode 为 specific 时使用. |
| startup.specific-offset.skip-rows | Long | 否 | - | 配置 specific 启动偏移量后需要跳过的行数. 未配置时不跳过任何行. 该选项只能在 startup.mode 为 specific 时使用. |
| startup.timestamp | Long | 否 | - | 从指定时间戳启动,单位为 Unix 纪元以来的毫秒数。注意,当 startup.mode 为 timestamp 时,此选项必填。 当 startup.mode 为 snapshot-only 时不允许配置此选项。 |
| stop.mode | Enum | 否 | NEVER | MySQL CDC 消费者的可选停止模式, 有效枚举值为 never, latest 和 specific. never: 实时任务一直运行不停止.latest: 从最新的偏移量处停止. 与需要执行快照的启动模式(initial/earliest)组合使用时, 停止偏移量在快照阶段完成后解析, 因此快照运行期间写入源表的变更仍会被 binlog 阶段捕获, 不会丢失.specific: 从用户提供的特定偏移量处停止.当 startup.mode 为 snapshot-only 时只允许配置为 never. |
| stop.specific-offset.file | String | 否 | - | 从指定的binlog日志文件名停止. 注意, 当使用 stop.mode 选项为 specific 时,此选项为必填项. |
| stop.specific-offset.pos | Long | 否 | - | 从指定的binlog日志文件位置停止. 注意, 当使用 stop.mode 选项为 specific 时,此选项为必填项. |
| snapshot.split.size | Integer | 否 | 8096 | 表快照的分割大小(行数),读取表的快照时,被捕获的表会被分割成多个分割块. |
| snapshot.fetch.size | Integer | 否 | 1024 | 每次轮询读取表快照时的最大获取大小. |
| incremental.parallelism | Integer | 否 | 1 | 增量(binlog)阶段并行读取器的数量. |
| server-id | String | 否 | - | 此 CDC 读取器使用的数字 ID 或数字 ID 范围,例如 5400 或 5400-5408。每个 ID 在 MySQL 集群中必须唯一。当任务有多个读取并发或并行读取多张表时,请配置足够大的 ID 范围。未配置时 SeaTunnel 会随机生成 ID,但生产环境建议显式配置。 |
| server-time-zone | String | 否 | - | 数据库服务中的会话时区. 如果没设置, 使用 ZoneId.systemDefault() 来确定服务的时区. |
| connect.timeout.ms | Long | 否 | 30000 | 连接器在尝试连接数据库服务器后,在超时之前应等待的最长时间. |
| connect.max-retries | Integer | 否 | 3 | 连接器在构建数据库服务器连接时应重试的最大重试次数. |
| connection.pool.size | Integer | 否 | 20 | jdbc连接池大小. |
| chunk-key.even-distribution.factor.upper-bound | Double | 否 | 100 | 块键分布因子的上限. 该因子用于确定表数据是否分布均匀. 如果分布式因子计算结果小于或等于此上限 (即., (MAX(id) - MIN(id) + 1) / row count), 表的分块将被优化以实现均匀分布. 否则, 如果分布因子大于此上限, 该表将被视为分布不均, 并且如果估计的分片数量超过 sample-sharding.threshold 所指定的值, 则将使用基于采样的分片策略. 默认值是100.0. |
| chunk-key.even-distribution.factor.lower-bound | Double | 否 | 0.05 | 块键分布因子的下限. 该因子用于确定表数据是否分布均匀. 如果计算得出的分布因子大于或等于此下限 (即., (MAX(id) - MIN(id) + 1) / row count), 表的分块将被优化以实现均匀分布. 否则, 如果分布因子小于此下限, 该表将被视为分布不均, 并且如果预估的分片数量超过了 sample-sharding.threshold 所指定的值,则将使用基于采样的分片策略. 默认值是 0.05. |
| sample-sharding.threshold | Integer | 否 | 1000 | 此配置指定了触发采样分片策略的预估分片数量阈值. 当分配因子超出由 chunk-key.even-distribution.factor.upper-bound 和 chunk-key.even-distribution.factor.lower-bound 所指定的范围时, 如果估计的分片数量 (按近似行数/块大小 计算) 超过此阈值, 则将使用样本分片策略. 这有助于更高效地处理大型数据集. 默认值为 1000 分片. |
| inverse-sampling.rate | Integer | 否 | 1000 | 采样分片策略中使用的采样率的倒数. 例如, 如果该值设置为 1000, 则表示在采样过程中应用了 1/1000 的采样率. 此选项在控制采样的粒度方面提供了灵活性, 从而影响最终的分片数量. 在处理非常大的数据集时非常有用, 因为此时更倾向于使用较低的采样率. 默认值为 1000. |
| split.allow-sampling | Boolean | 否 | true | 是否允许基于采样的分片策略。当设置为 false 时,无论预估分片数是否超过阈值,系统都将回退到非均匀分片方式(迭代查询方式)。默认值为 true。 |
| enable_concurrent_read | Boolean | 否 | true | 是否在快照阶段启用基于分片的并发读取。当设置为 false 时,source 会跳过分片分析,并以单个 split 读取整张表,适合没有索引的表。默认值为 true。 |
| exactly_once | Boolean | 否 | false | 启用精确一次语义。当 startup.mode 为 initial 或 snapshot-only 时,还会在快照阶段额外启用有界的 low-to-high-watermark binlog 回填。 |
| format | Enum | 否 | DEFAULT | MySQL CDC 的可选输出格式, 有效的枚举值为 DEFAULT、COMPATIBLE_DEBEZIUM_JSON. |
| schema-changes.enabled | Boolean | 否 | false | 模式演进默认是禁用的. 当前我们只支持 add column、drop column、rename column 和 modify column. |
| schema-changes.include | List | 否 | - | 仅向下游发送列出的 schema change 事件类型(需 schema-changes.enabled = true)。为空表示全部允许。详见 Schema change 事件过滤。 |
| schema-changes.exclude | List | 否 | - | 此处列出的 schema change 事件类型不会发送到下游。在 schema-changes.include 之后应用;冲突时 exclude 优先。详见 Schema change 事件过滤。 |
| debezium | Config | 否 | - | 传递 Debezium的属性 给Debezium嵌入式引擎, 该引擎用于捕获 MySQL 服务的数据变更. |
| int_type_narrowing | Boolean | 否 | true | Int类型收窄,如果为 true,则 tinyint(1) 类型将被收窄为 boolean 类型(如果没有精度损失)。目前仅支持 MySQL。 |
| common-options | 否 | - | Source插件通用参数, 详见 Source Common Options |
int_type_narrowing
Int类型收窄,如果为 true,则 tinyint(1) 类型将被收窄为 boolean 类型(如果没有精度损失)。目前仅支持 MySQL。
例:
int_type_narrowing = true
| MySQL | SeaTunnel |
|---|---|
| TINYINT(1) | Boolean |
int_type_narrowing = false
| MySQL | SeaTunnel |
|---|---|
| TINYINT(1) | TINYINT |
任务示例
简单的示例
支持多表读取
env {
parallelism = 1
job.mode = "STREAMING"
checkpoint.interval = 10000
}
source {
MySQL-CDC {
url = "jdbc:mysql://localhost:3306/testdb"
username = "root"
password = "root@123"
table-names = ["testdb.table1", "testdb.table2"]
startup.mode = "initial"
}
}
sink {
Console {
}
}
支持向Kafka发送与Debezium兼容的格式
一定是使用kafka作为sink, 详见 compatible debezium format
支持表的自定义主键
env {
parallelism = 1
job.mode = "STREAMING"
checkpoint.interval = 10000
}
source {
MySQL-CDC {
url = "jdbc:mysql://localhost:3306/testdb"
username = "root"
password = "root@123"
table-names = ["testdb.table1", "testdb.table2"]
table-names-config = [
{
table = "testdb.table2"
primaryKeys = ["id"]
}
]
}
}
sink {
Console {
}
}
支持模式演变(表结构变更)
env {
# You can set engine configuration here
parallelism = 5
job.mode = "STREAMING"
checkpoint.interval = 5000
read_limit.bytes_per_second=7000000
read_limit.rows_per_second=400
}
source {
MySQL-CDC {
server-id = 5652-5657
username = "st_user_source"
password = "mysqlpw"
table-names = ["shop.products"]
url = "jdbc:mysql://mysql_cdc_e2e:3306/shop"
schema-changes.enabled = true
}
}
sink {
jdbc {
url = "jdbc:mysql://mysql_cdc_e2e:3306/shop"
driver = "com.mysql.cj.jdbc.Driver"
user = "st_user_sink"
password = "mysqlpw"
generate_sink_sql = true
database = shop
table = mysql_cdc_e2e_sink_table_with_schema_change_exactly_once
primary_keys = ["id"]
is_exactly_once = true
xa_data_source_class_name = "com.mysql.cj.jdbc.MysqlXADataSource"
}
}
Schema change 事件过滤
当 schema-changes.enabled = true 时,可通过 schema-changes.include / schema-changes.exclude 进一步
控制哪些 schema change 事件类型会被发送到下游。
使用以下 SeaTunnel 统一的规范名称
| 规范名称 | 操作 |
|---|---|
add.column | 新增列 |
drop.column | 删除列 |
modify.column | 修改列的类型/属性,列名不变 |
change.column | 列重命名,可同时改类型 |
update.columns | 上述四种列级变更的分组别名 |
优先级规则(确定性):
- 若设置了
schema-changes.include,则只有被包含的事件类型才有资格; - 然后应用
schema-changes.exclude; - 当某类型同时出现在两个列表中时,exclude 优先。
source {
MySQL-CDC {
# ...
schema-changes.enabled = true
schema-changes.include = ["add.column", "drop.column"]
schema-changes.exclude = ["change.column"]
}
}
排除 drop.column 时的数据处理方式。 对于被保留的 NOT NULL 列,写入 NULL 会被 sink 拒绝,因此对一个源端已不再供数的
NOT NULL 列排除 drop.column 会在 sink 端失败。
表名支持正则以读取多个表
table-pattern和table-names只能选择一个
env {
# You can set engine configuration here
parallelism = 1
job.mode = "STREAMING"
checkpoint.interval = 5000
read_limit.bytes_per_second=7000000
read_limit.rows_per_second=400
}
source {
MySQL-CDC {
server-id = 5652
username = "st_user_source"
password = "mysqlpw"
database-pattern = "source.*"
table-pattern = "source.*\\..*"
url = "jdbc:mysql://mysql_cdc_e2e:3306"
}
}
sink {
Console {
}
}
配置 Debezium 心跳
对于低流量表,binlog 只有在发生行变更时才会推进。使用 Debezium 心跳让 binlog 位置持续向前滚动,便于下游 checkpoint 记录到新鲜偏移,并让复制延迟可观测。心跳表必须提前在 MySQL 服务端创建。
source {
MySQL-CDC {
username = "st_user_source"
password = "mysqlpw"
table-names = ["mysql_cdc.mysql_cdc_e2e_source_table"]
url = "jdbc:mysql://mysql_cdc_e2e:3306/mysql_cdc"
debezium {
heartbeat.interval.ms = 100
heartbeat.action.query = "INSERT INTO mysql_cdc.heartbeat (ts) VALUES (NOW())"
}
}
}
定时刷新,无需等待 batch_size
当 source 写入量非常低时,JDBC sink 可能在 checkpoint 触发前一直处于空闲状态。在 sink 中开启定时刷新,即使没有达到 batch_size,缓冲的数据也会被写入。
env {
parallelism = 1
job.mode = "STREAMING"
checkpoint.interval = 300000
sink.flush.interval = 500
}
source {
MySQL-CDC {
server-id = 5680-5690
username = "st_user_source"
password = "mysqlpw"
table-names = ["mysql_cdc.timer_flush_src"]
url = "jdbc:mysql://mysql_cdc_e2e:3306/mysql_cdc"
}
}
sink {
Jdbc {
url = "jdbc:mysql://mysql_cdc_e2e:3306/mysql_cdc"
driver = "com.mysql.cj.jdbc.Driver"
username = "st_user_sink"
password = "mysqlpw"
generate_sink_sql = true
database = mysql_cdc
table = timer_flush_sink
primary_keys = ["id"]
batch_size = 100000000
batch_interval_ms = 0
}
}
sink.flush.interval 配置在 env 块中,无论 batch_size 是否达到,都会作用于 sink 流水线。
读取没有主键的表
根据源表能够提供的保证来选择合适的路径:
- 仅追加(append-only)场景:源表不会产生 UPDATE/DELETE 事件,保持
exactly_once = false且不声明主键,源端会退回到尽力而为的行标识。在没有可用主键的情况下,connector 无法安全地应用 UPDATE/DELETE 事件。 - 存在唯一非主键列:通过
table-names-config.primaryKeys显式声明该列,并设置exactly_once = true,让快照阶段与 binlog 阶段都使用同一配置主键作为稳定的行标识。该列在数据库中必须为 NOT NULL:可空列不会用于切分快照,开启exactly_once = true时作业会在启动时失败。
env {
parallelism = 1
job.mode = "STREAMING"
checkpoint.interval = 5000
}
source {
MySQL-CDC {
server-id = 5652
username = "st_user_source"
password = "mysqlpw"
table-names = ["mysql_cdc.mysql_cdc_e2e_source_table_no_primary_key"]
url = "jdbc:mysql://mysql_cdc_e2e:3306/mysql_cdc"
table-names-config = [
{
table = "mysql_cdc.mysql_cdc_e2e_source_table_no_primary_key"
primaryKeys = ["id"]
}
]
exactly_once = true
}
}
上述示例演示的是"逻辑主键"场景:源表本身没有物理主键,但通过 table-names-config.primaryKeys 显式声明了一列作为稳定行标识,并启用 exactly_once = true,让快照阶段与 binlog 阶段都使用同一逻辑主键。只有当被声明的列在源数据中确实保持唯一时,UPDATE/DELETE 才能被正确路由;如果源数据中存在重复值,行为将不再可靠。
可空唯一键列中的 NULL 值,以及 table-names-config.primaryKeys 中配置的可空列中的 NULL 值,在快照阶段和 binlog 阶段都会按 NULL 输出。NULL 无法标识一行数据,因此当需要按键应用 UPDATE/DELETE 事件时,请选择 NOT NULL 的列作为键。开启 exactly_once = true 时,键为 NULL 的行同样无法区分,每个快照分片中只会保留其中一行。
从指定 Binlog 位置启动
当需要从明确的 binlog 文件和位置开始读取时,可以使用 startup.mode = "specific"。
source {
MySQL-CDC {
server-id = 5654
username = "st_user_source"
password = "mysqlpw"
table-names = ["mysql_cdc.mysql_cdc_e2e_source_table"]
url = "jdbc:mysql://mysql_cdc_e2e:3306/mysql_cdc"
startup.mode = "specific"
startup.specific-offset.file = "mysql-bin.000001"
startup.specific-offset.pos = 154
}
}
仅快照(一次性引导)
当只需要做一次性全量引导(backfill)而不希望任务持续消费 binlog 时,使用 startup.mode = "snapshot-only"。任务会读取配置表的快照数据,读取完成后自然结束(有界任务),不会进入增量/binlog 阶段。
该模式不会进入持续 binlog 流式读取,因此与除 never 外的 stop.mode 以及 binlog 相关的 startup.specific-offset.*、startup.timestamp 选项互斥;同时配置这些选项会在启动时报错。exactly_once 仍可用于快照阶段的有界回填,但不会启动持续 binlog 流式读取。
snapshot-only 任务从 checkpoint 或 savepoint 恢复时,只读取 checkpoint 中记录的表:checkpoint 之后新建或新加入 table-names 的表不会被读取;如果 checkpoint 中仍有未读快照数据的某张表已不在配置中或已不存在,恢复会失败,报错中会列出这些表。只有数据库名和表名(包括大小写)完全相同时,checkpoint 中的表才与配置的表匹配。需要修改读取的表时,请提交新作业。
并发写入下的一致性取决于 exactly_once:
exactly_once = false(默认)时,每个快照分片在各自的时间点通过普通查询读取,不做 binlog 回填。如果任务运行期间源表有写入,有界输出并不是一个一致的时间点快照:同一个变更可能只体现在部分分片中。仅在任务运行期间源表无写入时使用该配置。exactly_once = true时,每个分片会用其低水位到高水位之间的 binlog 事件进行修正,因此每个分片的输出与其自身的高水位一致。各分片完成时间不同,整体输出仍不是单一的全局时间点快照;分片完成之后发生的变更不会被读取,因为任务不会进入持续 binlog 流式读取。源表在快照期间可能有写入时请开启该配置;如果要求整体输出对应同一时间点,请在任务运行期间暂停写入。
当 exactly_once = true 时,快照阶段的有界回填会为每个 reader 打开独立的 MySQL 复制连接,因此需要将 server-id 配置为覆盖任务并行度的范围(例如并行度为 2 时配置 server-id = "5656-5657")。每个 reader 使用范围内的 起始值 + subtask 序号 作为 server id。SeaTunnel 不会在提交任务时校验该范围是否覆盖任务并行度;范围过小时,只会在 reader 启动时报错,提示 subtask ID 超出了 server id 范围。该范围还必须与复制同一个 MySQL 实例的其他任务、从库和工具互不重复:当另一个复制连接以相同的 server id 注册时,MySQL 会断开先前的连接,表现为回填过程中间歇性的读取失败。
下面的示例以并行度 2 读取快照并开启有界 binlog 回填。请将占位符替换为实际值,并使用配置变量替换传入凭据,不要把真实凭据直接写入作业文件,例如提交任务时通过 -i mysql_password=<password> 传入,或设置 mysql_password 环境变量。
env {
parallelism = 2
job.mode = "BATCH"
}
source {
MySQL-CDC {
url = "jdbc:mysql://<mysql_host>:3306/<database>"
username = "<username>"
password = "${mysql_password}"
table-names = ["<database>.<table>"]
startup.mode = "snapshot-only"
exactly_once = true
server-id = "5656-5657"
}
}
有界读取:在指定 Binlog 位置停止
使用 stop.mode = "specific" 可以将作业变为有界读取:作业读取启动偏移量(或启动时间戳)
与配置的停止偏移量之间的 binlog,然后自行终止(FINISHED),而不是一直运行下去。
注意:有界读取的终止行为目前仅在 Zeta 引擎上支持。 Flink 和 Spark 引擎暂不支持有界增量分片的终止。
stop.mode = "latest" 同样会使作业变为有界读取:停止偏移量为快照阶段完成时的 binlog 位置
(当 startup.mode 为 initial/earliest 时),或作业启动时的 binlog 位置(其他启动模式)。
特别是与需要执行快照的启动模式组合使用时,快照运行期间写入源表的变更不会丢失——
它们会在作业终止前被 binlog 阶段捕获。
source {
MySQL-CDC {
server-id = 5654
username = "st_user_source"
password = "mysqlpw"
table-names = ["mysql_cdc.mysql_cdc_e2e_source_table"]
url = "jdbc:mysql://mysql_cdc_e2e:3306/mysql_cdc"
startup.mode = "initial"
stop.mode = "latest"
}
}
source {
MySQL-CDC {
server-id = 5654
username = "st_user_source"
password = "mysqlpw"
table-names = ["mysql_cdc.mysql_cdc_e2e_source_table"]
url = "jdbc:mysql://mysql_cdc_e2e:3306/mysql_cdc"
startup.mode = "specific"
startup.specific-offset.file = "mysql-bin.000001"
startup.specific-offset.pos = 154
stop.mode = "specific"
stop.specific-offset.file = "mysql-bin.000010"
stop.specific-offset.pos = 4096
}
}
stop.mode = "specific" 也可以与 startup.mode = "timestamp" 组合使用,同时按时间和
binlog 位置限定读取范围:
source {
MySQL-CDC {
server-id = 5654
username = "st_user_source"
password = "mysqlpw"
table-names = ["mysql_cdc.mysql_cdc_e2e_source_table"]
url = "jdbc:mysql://mysql_cdc_e2e:3306/mysql_cdc"
startup.mode = "timestamp"
startup.timestamp = 1716076800000
stop.mode = "specific"
stop.specific-offset.file = "mysql-bin.000010"
stop.specific-offset.pos = 4096
}
}
多表读取后写入 JDBC
当一个 MySQL CDC source 读取多张表时,JDBC sink 可以使用占位符保留原始表名。
source {
MySQL-CDC {
plugin_output = "customers_mysql_cdc"
server-id = 5652-5660
username = "st_user_source"
password = "mysqlpw"
table-names = ["mysql_cdc.orders", "mysql_cdc.products"]
url = "jdbc:mysql://mysql_cdc_e2e:3306/mysql_cdc"
}
}
sink {
jdbc {
plugin_input = "customers_mysql_cdc"
url = "jdbc:mysql://mysql_cdc_e2e:3306/mysql_cdc2"
driver = "com.mysql.cj.jdbc.Driver"
user = "st_user_sink"
password = "mysqlpw"
database = "mysql_cdc2"
table = "${table_name}"
primary_keys = ["${primary_key}"]
generate_sink_sql = true
}
}
常见问题
MySQL CDC 需要哪些权限?
MySQL 用户需要以下权限:
GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user'@'%';
同时需要在 my.cnf / my.ini 中开启 binlog:
[mysqld]
log_bin = mysql-bin
binlog_format = ROW
binlog_row_image = FULL
SeaTunnel 能从 MySQL 从库读取 CDC 数据吗?
可以。SeaTunnel 通过订阅 binlog 工作,从库也有 binlog 流。将 SeaTunnel 指向从库可以减轻主库压力。需确保从库开启了 binlog,并在配置中设置 log_slave_updates = ON。
MySQL CDC 是否支持无主键表?
默认要求主键。如果源表没有声明主键,但存在其他可唯一标识记录的列,可以像当前文档中的
source options 示例那样,通过 table-names-config.primaryKeys 指定自定义主键。若没有稳定的
唯一键,下游就无法安全处理 UPDATE / DELETE 事件。
全量快照阶段如何工作?何时切换为增量读取?
使用 startup.mode = "initial" 时,SeaTunnel 会对已配置的表执行一致性全量快照,随后从快照开始时记录的 binlog 位置切换为增量读取,确保切换过程中不丢失变更事件。使用 startup.mode = "snapshot-only" 时,source 会在快照阶段完成后结束,不会进入持续 binlog 读取。
MySQL CDC 是否支持 DDL 传播?
支持,但能力有限。需要启用 schema-changes.enabled = true,并遵循当前页面以及
Schema Evolution 文档中已经定义好的契约。
目前文档中明确支持 add column、drop column、rename column 和 modify column。
运行多个 CDC 任务时如何避免 server-id 冲突?
每个 CDC 任务必须使用唯一的 server-id 或不重叠的范围。重复的 server-id 会导致 MySQL 服务器断开其中一个客户端连接。建议为每个任务分配独立的范围,例如一个任务用 5400-5600,另一个用 5601-5800。
初始快照为什么很慢?
快照速度取决于表大小、JDBC fetch size 和网络带宽。可以通过调整 snapshot.split.size
和 snapshot.fetch.size 来控制快照切分与抓取行为。对于不需要历史数据的大表,可将
startup.mode 设为 "latest",从最新 offset 启动并跳过初始快照。
如何处理时区和字符集问题?
将 server-time-zone 设置为与 MySQL 服务器一致的时区,例如 "Asia/Shanghai"。字符集问题可通过在 JDBC 连接 URL 中追加 characterEncoding=UTF-8&useUnicode=true 来解决。
MySQL CDC 能在 Spark 引擎上运行吗?
可以。无论 BATCH 还是 STREAMING 作业,Spark 引擎都在一个 Spark task 中运行该数据源,这个 task 同时包含分片枚举器和所有 reader,parallelism 决定其中 reader 的数量。
Spark 不会为该数据源做 checkpoint,因此:
- 作业无法从 checkpoint 恢复,重启的作业会按
startup.mode重新开始。 - 只在 checkpoint 或批次写满时才写出的 sink 可能会暂时攒住数据,例如使用默认
batch_size的 JDBC sink。需要数据及时写出时,请调小batch_size。 - 不支持通过 Spark 微批流式读取(
readStream)该数据源。
另请参阅
若需要一份面向生产的端到端实践指南,涵盖全量 + 增量同步生命周期、2PC sink 配置、Schema 演进与常见故障排查,请参阅 CDC 生产实战手册。