跳到主要内容

MySQL 数据源

Daspire 使用同一个 MySQL Source Connector 覆盖自建 MySQL 和已支持的云厂商。 请按下文选择各平台的 Endpoint、网络和 CA；不要为每个云厂商重复创建 Connector。

Clean Source 发布状态​

独立 clean MySQL Source 使用独立镜像，并自 2026 年 7 月 20 日起作为唯一 MySQL Source 定义的默认 runtime。Legacy runtime 和旧镜像 fallback 已退休；显式关闭 clean route、提供 非法镜像或使用只属于 legacy 的配置时会 fail-closed，不再启动旧镜像。本次变更不会复制或 批量迁移 Source 配置、Catalog、state、Destination 或客户数据。

能力Clean Source 状态
Full Refresh已验证 Generic MySQL、Amazon RDS MySQL、Aurora Provisioned、Aurora Serverless v2、Azure Flexible Server、Google Cloud SQL
标准增量已验证上述六种环境
Binlog CDC已验证 Generic MySQL 5.7/8.0、Amazon RDS MySQL、Aurora Provisioned、Aurora Serverless v2、Azure Flexible Server、Google Cloud SQL
直接 TLS支持；推荐 verify_identity
删除捕获仅已验证的 clean binlog CDC 支持
SSH TunnelClean Source 不支持

旧的已保存配置可能包含 legacy CDC、ssl=false 或 SSH Tunnel 选项，这些选项不再通过 fallback Connector 执行。重新启用此类 Source 前必须改成 clean contract；Daspire 不会 静默降低 TLS 安全级别，也不会模拟 SSH Tunnel。

Aurora Serverless v1 已 EOL，不再做新验证，请迁移至 Aurora Serverless v2。

通用连接字段​

  • host：使用下文各平台指定的精确 DNS hostname；不得包含 scheme、port、path 或用户信息。
  • port：通常为 3306。
  • database：本次 Discover 的一个数据库/namespace。
  • username、password，或经过批准的 managed credential handle。
  • ssl_mode：生产建议使用 verify_identity，同时验证 CA 和 hostname。
  • ssl_ca：数据库管理员或云厂商提供的完整 PEM CA bundle。提供该字段后，本连接只信任 此 bundle，不再叠加系统 trust store；云厂商公告 root rotation 时需包含全部必要 root。
  • 服务器要求双向 TLS 时，再提供 ssl_cert 和 ssl_key。
  • replication_method：Standard；仅已验证环境可选 CDC。
  • stream_allowlist：可选，只允许精确表名。

verify_ca 只验证证书链，不验证 hostname。require 只加密但不认证服务器证书，不建议 用于生产。prefer 只允许 loopback 兼容目标回退，不允许公网明文连接。最低 TLS 版本为 TLS 1.2。

各平台网络、Endpoint 和 CA​

Generic MySQL 5.7/8.0​

  • 只允许 Daspire egress IP 或私有运行网络访问 MySQL 端口，不得向公网开放 3306。
  • 使用证书 SAN 中包含的稳定 writer hostname；启用 verify_identity 时不要填 IP。
  • 从数据库管理员取得 CA chain，并在证书链轮换前更新。
  • Full Refresh 可以读取可访问的表或 View；标准增量和 CDC 还须满足后文限制。

Amazon RDS for MySQL​

  • DB Security Group 只允许 Daspire Security Group、私有网络或精确 egress CIDR 访问 3306。Publicly accessible 不等于网络已经放行，还需检查 Route Table、NACL 和 SG。
  • 使用 writer 的 RDS DB instance endpoint，不要使用 IP 或临时解析地址。
  • 从 AWS 下载当前 RDS CA bundle，用精确 endpoint 配合 verify_identity。
  • Automated backup retention 必须大于 0，否则 RDS 会关闭 binary logging。CDC 还需 配置后文参数和 retention。

Aurora MySQL Provisioned​

  • Cluster Security Group 只允许批准的 Daspire 网络访问 3306。
  • CDC 必须使用 Aurora cluster writer endpoint。Binary log 只能从 primary instance 读取，不得用 reader endpoint 做可续传 CDC。
  • 使用 AWS RDS CA bundle，并验证精确 cluster endpoint hostname。
  • 在专用 DB cluster parameter group 设置 CDC 参数；修改 binlog_format 后需要重启 writer 才能验收。

Aurora Serverless v2​

  • 网络、writer endpoint、CA 和 cluster parameter group 要求与 Aurora Provisioned 相同。
  • Host 必须是 Serverless v2 cluster writer endpoint，不是 Data API 或 reader endpoint。
  • 若允许 auto-pause 至 0 ACU，应给 wake/reconnect 留足 timeout。唤醒不是 state reset， 仍须从同一已接受 server identity 的 committed state 续传。
  • Serverless v1 已 EOL，必须迁移至 Serverless v2。

Azure Database for MySQL Flexible Server​

  • Public access 时只把 Daspire egress IP/CIDR 加入 server firewall；Private access 时， 必须让 Daspire runtime 具备 VNet/Private Link 路由和 DNS。
  • 使用 <server>.mysql.database.azure.com。Azure 建议使用 FQDN，不能依赖会变化的 IP。
  • 保持 require_secure_transport=ON。完整验证时提供 DigiCert Global Root G2 与 Microsoft RSA Root CA 2017，并使用 Azure FQDN 和 verify_identity。
  • Full Refresh、标准增量和 clean binlog CDC 均已验证。CDC 需要 binlog_row_image=FULL、binlog_row_metadata=FULL、空的 binlog_row_value_options，并建议从 binlog_expire_logs_seconds=604800（7 天）开始；需要重启的参数应用后必须查询实际 global value。

Google Cloud SQL for MySQL​

  • Public IP 只允许 Daspire egress CIDR；Private IP 方案需提供 VPC 连接和 private DNS。
  • Google-managed shared CA 场景必须复制 Cloud SQL 返回的 DNS 名称，并按 *.sql.goog. absolute FQDN 配置。末尾点不可省略，例如 example-id.us-central1.sql.goog.。不得改成公网 IP，也不得删除末尾点。
  • 下载 Cloud SQL server CA chain 并使用 verify_identity。IP 或缺少末尾点的 hostname 必须在证书 hostname verification 阶段失败。
  • Full Refresh、标准增量和 clean binlog CDC 均已验证。CDC 必须启用 automated backup 和 binary logging/PITR，并设置 binlog_row_image=FULL、 binlog_row_metadata=FULL、空的 binlog_row_value_options。建议从 7 天 transaction log 和 backup retention 开始，并持续监控 storage 与最大恢复时间。

最小只读账号​

用受限 host pattern 和 database 创建专用账号：

CREATE USER 'daspire'@'approved-host' IDENTIFIED BY 'use-a-secret-manager';
GRANT SELECT ON `your_database`.* TO 'daspire'@'approved-host';

Full Refresh 和标准增量只需要选中对象的 SELECT。CDC 还需要复制协议权限：

GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'daspire'@'approved-host';

Clean snapshot 不申请 RELOAD、global table lock、DDL 或写权限。不要授予 SUPER、 FILE、PROCESS、CREATE、ALTER、DROP、INSERT、UPDATE、DELETE。

Full Refresh​

选择 Standard，并把 stream 配置为 full_refresh。

  • 不要求 cursor 或主键。
  • 可读取 base table 和可访问的 View。
  • 每次都重新读取选中对象；不会把两次同步间的删除作为 change event 捕获。
  • Full Refresh 没有可续传记录位点；中断后从头重跑该 stream。

标准增量​

选择 Standard，并把 stream 配置为 incremental。

  • 必须是有 source-defined primary key 的 base table。
  • 选择一个 non-null cursor，类型只能是精确整数、DECIMAL、NUMERIC、DATE、 DATETIME 或 TIMESTAMP。
  • Daspire 按 cursor 加其余全部主键列排序和续传，避免相同 cursor value 的记录被跳过。
  • State v1 的 cursor 和主键必须与 Catalog 一致；未知版本、非法值、Catalog drift 或主键 变化均在读取前 fail closed。
  • 若记录后来写入但 cursor 小于或等于 committed position，不会自动被发现；cursor 不单调 时必须 reset stream。
  • 标准增量不捕获 DELETE。

Binlog CDC​

Server 参数​

支持表中的六种已验证环境都必须满足：

server_id                = a-unique-nonzero-value
log_bin                  = ON
binlog_format            = ROW
binlog_row_image         = FULL

MySQL 8.0 还需：

binlog_row_metadata      = FULL
binlog_row_value_options =

Clean Source 支持 gtid_mode=ON 和 gtid_mode=OFF；ON_PERMISSIVE、 OFF_PERMISSIVE 会 fail closed。启用 GTID 时也必须启用 enforce_gtid_consistency。

RDS MySQL 使用专用 DB parameter group，保持 automated backup 开启，并在应用后查询实际 global value。Aurora Provisioned/Serverless v2 使用专用 DB cluster parameter group； 静态参数需要重启 writer 后才生效。AWS 默认值可能是 OFF_PERMISSIVE；启用 CDC 前必须 显式设置 gtid-mode=OFF，或按云厂商支持的步骤完成到 ON 的迁移。

Azure Flexible Server 的 binary logging 与 ROW format 由云厂商管理；需设置上述两个 FULL 参数、保持 partial JSON option 为空、配置 binlog_expire_logs_seconds，并在重启后 查询实际值。Google Cloud SQL 需启用 automated backup 和 binary logging/PITR，设置两个 FULL 参数并确认 partial JSON option 为空。Clean Source 已分别验证 Azure 的 GTID OFF state 与 Cloud SQL 的 GTID ON state。

每个并发 CDC client 配置唯一的 cdc_server_id，范围 1 至 4294967295。这是复制 client identity，不是数据库自身的 server_id。

Binlog retention​

Retention 必须长于最大计划停机时间加恢复时间，并持续监控 binlog storage：

  • Generic MySQL 8.0：建议从 binlog_expire_logs_seconds=864000（10 天）开始。
  • Generic MySQL 5.7：建议从 expire_logs_days=10 开始。
  • RDS MySQL：执行 CALL mysql.rds_set_configuration('binlog retention hours', 168);。AWS 对 RDS MySQL 的上限为 168 小时（7 天）。
  • Aurora MySQL：建议从 CALL mysql.rds_set_configuration('binlog retention hours', 240); 开始，再根据 storage 调整。Aurora MySQL v2.11+ 和 v3 上限为 2160 小时。
  • Azure Flexible Server：建议从 binlog_expire_logs_seconds=604800（7 天）开始；最大 停机加恢复窗口更长时应提高。
  • Google Cloud SQL：启用 automated backup 与 binary logging/PITR，建议从 7 天 transaction-log retention 开始；结合 backup retention 与可用 storage 调整。

若 file/position 已不存在，或 GTID purge 产生 committed state 未覆盖的 gap，Connector 返回 cdc_position_expired。确定性恢复方式是：停止 Source、reset CDC state、重新 Discover/接受 Catalog，再做一次 initial snapshot。Connector 不会猜测新位点。

Initial snapshot、记录与 state​

  • 每个 CDC stream 必须是有 source-defined primary key 的 InnoDB base table。View、无主键 表、非 InnoDB 表均 fail closed。
  • 首次运行先记录 binlog/GTID 位点，再执行 InnoDB repeatable-read consistent snapshot， 不获取 global table lock。完整 snapshot 结束前不发送 state。
  • 起始位点记录后、snapshot 建立前提交的变化，可能在 snapshot 和 binlog 中各出现一次。 这是 initial at-least-once duplicate boundary；下游必须按主键 upsert。
  • INSERT 发送 after image，UPDATE 发送完整 after image，DELETE 发送完整 before image。每条记录包含 _daspire_cdc_event、_daspire_cdc_deleted_at、 _daspire_cdc_log_file、_daspire_cdc_log_pos、_daspire_cdc_gtid。
  • 只有 transaction commit 后才发送 checkpoint。如果记录已经发送但 checkpoint 尚未 commit 时进程终止，重启后整个未 checkpoint transaction 可能再次发送。没有 exactly-once 保证。
  • CDC state v1 绑定 database、选中 stream 顺序、Catalog fingerprint、server identity、 GTID mode 以及 committed GTID 或 file/position。未知或非法 state 会被拒绝。

Schema change​

本版本不支持 CDC 自动 schema evolution。在消费区间发现 CREATE、ALTER、DROP、 RENAME 或 TRUNCATE 时 fail closed，且 state 不跨过 DDL。应停止写入、完成 schema 变更、重新 Discover/接受 Catalog、reset CDC state 并重新 snapshot。Partial JSON row image 同样会被拒绝。

Clean Source 明确不支持的配置​

  • SSH Tunnel。请使用已批准的直连私网、VPN、Private Link 或 Private Service Connect。
  • Aurora Serverless v1。
  • 无主键 CDC 表、非 InnoDB CDC snapshot、partial row image、partial JSON update、 自动 schema evolution。
  • 批量客户迁移。Clean 镜像现在是定义默认值，但 Daspire 不会以批处理方式改写现有 Source 配置、Catalog、state 或客户数据。

故障排查​

  • tls_verification_failed：检查 CA chain 和精确 hostname；Cloud SQL shared CA 要确认 *.sql.goog. 名称包含末尾点。
  • authentication_failed：检查 managed credential 和 MySQL host pattern；不得通过降低 TLS 安全级别绕过密码认证问题。
  • permission_denied：检查 SELECT；CDC 还要检查 REPLICATION SLAVE 和 REPLICATION CLIENT。
  • cdc_precondition_failed：查询 writer 上实际生效的 global binlog 参数，不要只看 parameter group desired value。
  • cdc_position_expired：不得手工改 state；确认 retention/Catalog 后 reset 并 resnapshot。
  • schema_changed：停止 Source，重新 Discover/审核 Catalog，reset CDC state 并 resnapshot。

云厂商细节请参考 AWS RDS CA、 AWS RDS binlog retention、 Aurora binary logging、 Azure Flexible Server networking、 Azure TLS 和 Cloud SQL server identity verification。