From 3f4c437bfb172fe15bccb277e3e041ea874e2d09 Mon Sep 17 00:00:00 2001 From: Aolin Date: Thu, 28 Nov 2024 17:04:23 +0800 Subject: [PATCH 1/9] cdc: reformat Changefeed config and Server config Signed-off-by: Aolin --- ticdc/ticdc-changefeed-config.md | 914 ++++++++++++++++++++----------- ticdc/ticdc-server-config.md | 191 +++++-- 2 files changed, 720 insertions(+), 385 deletions(-) diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index ff951fa6b9df..6bfa92d47ee8 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -36,332 +36,588 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl 本章节详细介绍了同步任务的配置。 -```toml -# 指定该 Changefeed 在 Capture Server 中内存配额的上限。对于超额使用部分， -# 会在运行中被 Go runtime 优先回收。默认值为 `1073741824`，即 1 GB。 -# memory-quota = 1073741824 - -# 指定配置文件中涉及的库名、表名是否为大小写敏感 -# 该配置会同时影响 filter 和 sink 相关配置。自 v6.5.6、v7.1.3 和 v7.5.0 起，默认值由 true 改为 false -case-sensitive = false - -# 是否开启 Syncpoint 功能，从 v6.3.0 开始支持，该功能默认关闭。 -# 从 v6.4.0 开始，使用 Syncpoint 功能需要同步任务拥有下游集群的 SYSTEM_VARIABLES_ADMIN 或者 SUPER 权限。 -# 注意：该参数只有当下游为 TiDB 时，才会生效。 -# enable-sync-point = false - -# Syncpoint 功能对齐上下游 snapshot 的时间间隔 -# 配置格式为 h m s，例如 "1h30m30s" -# 默认值为 10m，最小值为 30s -# 注意：该参数只有当下游为 TiDB 时，才会生效。 -# sync-point-interval = "5m" - -# Syncpoint 功能在下游表中保存的数据的时长，超过这个时间的数据会被清理 -# 配置格式为 h m s，例如 "24h30m30s" -# 默认值为 24h -# 注意：该参数只有当下游为 TiDB 时，才会生效。 -# sync-point-retention = "1h" - -# 从 v6.5.6、v7.1.3、v7.5.0 起引入，用于设置解析 DDL 时使用的 SQL 模式，多个模式之间用逗号分隔 -# 默认值和 TiDB 的默认 SQL 模式一致 -# sql-mode = "ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION" - -# 默认值为 false，表示不处于 BDR 模式。 -# 如果要使用 TiCDC 搭建 BDR 集群，需要将该参数设置为 true，同时要将 TiDB 集群设置为 BDR 模式。 -# 详情请参考：https://docs.pingcap.com/zh/tidb/stable/ticdc-bidirectional-replication#ticdc-双向复制 -# bdr-mode = false - -# changefeed 发生内部错误或异常时允许自动重试的时间，默认值为 30 分钟。 -# 若 changefeed 发生内部错误或异常，且持续时间超过该参数设置的时间，changefeed 会进入 Failed 状态。 -# 当 changefeed 处于 failed 状态时，需要手动重启 changefeed 才能恢复。 -# 配置格式为 "h m s"，例如 "1h30m30s"。 -changefeed-error-stuck-duration = "30m" - -[mounter] -# mounter 解码 KV 数据的线程数，默认值为 16 -# worker-num = 16 - -[filter] -# 忽略指定 start_ts 的事务 -# ignore-txn-start-ts = [1, 2] - -# 过滤器规则 -# 过滤规则语法：https://docs.pingcap.com/zh/tidb/stable/table-filter#表库过滤语法 -rules = ['*.*', '!test.*'] - -# 事件过滤器规则 -# 事件过滤器的详细配置规则可参考：https://docs.pingcap.com/zh/tidb/stable/ticdc-filter -# 第一个事件过滤器规则 -# [[filter.event-filters]] -# matcher = ["test.worker"] # matcher 是一个白名单，表示该过滤规则只应用于 test 库中的 worker 表 -# ignore-event = ["insert"] # 过滤掉 insert 事件 -# ignore-sql = ["^drop", "add column"] # 过滤掉以 "drop" 开头或者包含 "add column" 的 DDL -# ignore-delete-value-expr = "name = 'john'" # 过滤掉包含 name = 'john' 条件的 delete DML -# ignore-insert-value-expr = "id >= 100" # 过滤掉包含 id >= 100 条件的 insert DML -# ignore-update-old-value-expr = "age < 18" # 过滤掉旧值 age < 18 的 update DML -# ignore-update-new-value-expr = "gender = 'male'" # 过滤掉新值 gender = 'male' 的 update DML - -# 第二个事件过滤器规则 -# [[filter.event-filters]] -# matcher = ["test.fruit"] # 该事件过滤器只应用于 test.fruit 表 -# ignore-event = ["drop table", "delete"] # 忽略 drop table 的 DDL 事件和 delete 类型的 DML 事件。需要注意的是，在更新 TiDB 中聚簇索引的列值时，TiCDC 会将一个 UPDATE 事件拆分成为 DELETE 和 INSERT 事件，TiCDC 无法将该类事件识别为 UPDATE 事件，因此无法正确地进行过滤。 -# ignore-sql = ["^drop table", "alter table"] # 忽略以 drop table 开头的，或者包含 alter table 的 DDL 语句 -# ignore-insert-value-expr = "price > 1000 and origin = 'no where'" # 忽略包含 price > 1000 和 origin = 'no where' 条件的 insert DML - -[scheduler] -# 将表以 Region 为单位分配给多个 TiCDC 节点进行同步。 -# 注意：该功能只在 Kafka changefeed 上生效，暂不支持 MySQL changefeed。 -# 默认为 "false"。设置为 "true" 以打开该功能。 -enable-table-across-nodes = false -# enable-table-across-nodes 开启后，有两种分配模式 -# 1. 按 Region 的数量分配，即每个 CDC 节点处理 region 的个数基本相等。当某个表 Region 个数大于 `region-threshold` 值时，会将表分配到多个节点处理。`region-threshold` 默认值为 10000。 -# region-threshold = 10000 -# 2. 按写入的流量分配，即每个 CDC 节点处理 region 总修改行数基本相当。只有当表中每分钟修改行数超过 `write-key-threshold` 值时，该表才会生效。 -# write-key-threshold = 30000 -# 注意： -# `write-key-threshold` 参数默认值为 0，代表默认不会采用流量的分配模式。 -# 两种方式配置一种即可生效，当 `region-threshold` 和 `write-key-threshold` 同时配置时，TiCDC 将优先采用按流量分配的模式，即 `write-key-threshold`。 - - -[sink] -############ 以下是 MQ 类型 sink 配置 ############ -# 对于 MQ 类的 Sink，可以通过 dispatchers 配置 event 分发器 -# 支持 partition 及 topic（从 v6.1 开始支持）两种 event 分发器。二者的详细说明见下一节。 -# matcher 的匹配语法和过滤器规则语法相同，matcher 匹配规则的详细说明见下一节。 -# 注意：该参数只有当下游为消息队列时，才会生效。 -# 注意：当下游 MQ 为 Pulsar 时，如果 partition 的路由规则未指定为 'ts', 'index-value', 'table', 'default' 中的任意一个，那么将会使用你设置的字符串作为每一条 Pulsar message 的 key 进行路由。例如，如果你指定的路由规则为 'code' 字符串，那么符合该 matcher 的所有 Pulsar message 都将会以 'code' 作为 key 进行路由。 -# dispatchers = [ -# {matcher = ['test1.*', 'test2.*'], topic = "Topic 表达式 1", partition = "index-value"}, -# {matcher = ['test3.*', 'test4.*'], topic = "Topic 表达式 2", partition = "index-value", index = "index1"}, -# {matcher = ['test1.*', 'test5.*'], topic = "Topic 表达式 3", partition = "table"}, -# {matcher = ['test6.*'], partition = "columns", columns = "['a', 'b']"} -# {matcher = ['test7.*'], partition = "ts"} -# ] - -# column-selectors 从 v7.5.0 开始引入，仅对 Kafka Sink 生效。 -# column-selectors 用于选择部分列进行同步。 -# column-selectors = [ -# {matcher = ['test.t1'], columns = ['a', 'b']}, -# {matcher = ['test.*'], columns = ["*", "!b"]}, -# {matcher = ['test1.t1'], columns = ['column*', '!column1']}, -# {matcher = ['test3.t'], columns = ["column?", "!column1"]}, -# ] - -# protocol 用于指定编码消息时使用的格式协议 -# 当下游类型是 Kafka 时，支持 canal-json、avro、debezium、open-protocol、simple。 -# 当下游类型是 Pulsar 时，仅支持 canal-json 协议。 -# 当下游类型是存储服务时，目前仅支持 canal-json、csv 两种协议。 -# 注意：该参数只有当下游为 Kafka、Pulsar，或存储服务时，才会生效。 -# protocol = "canal-json" - -# delete-only-output-handle-key-columns 用于指定 Delete 事件的输出内容，只对 canal-json 和 open-protocol 协议有效。从 v7.2.0 开始引入。 -# 该参数和 `force-replicate` 参数不兼容，如果同时将该参数和 `force-replicate` 设置为 true，创建 changefeed 会报错。 -# 默认值为 false，即输出所有列的内容。当设置为 true 时，只输出主键列，或唯一索引列的内容。 -# Avro 协议不受该参数控制，总是只输出主键列，或唯一索引列的内容。 -# CSV 协议不受该参数控制，总是输出所有列的内容。 -delete-only-output-handle-key-columns = false - -# Schema 注册表的 URL。 -# 注意：该参数只有当下游为消息队列时，才会生效。 -# schema-registry = "http://localhost:80801/subjects/{subject-name}/versions/{version-number}/schema" - -# 编码数据时所用编码器的线程数。 -# 默认值为 32。 -# 注意：该参数只有当下游为消息队列时，才会生效。 -# encoder-concurrency = 32 - -# 是否开启 Kafka Sink V2。Kafka Sink V2 内部使用 kafka-go 实现。 -# 默认值为 false。 -# 注意：该参数是一个实验特性，并且只有当下游为消息队列时才会生效。 -# enable-kafka-sink-v2 = false - -# 是否只向下游同步有内容更新的列。从 v7.1.0 开始支持。 -# 默认值为 false。 -# 注意：该参数只有当下游为消息队列，并且使用 Open Protocol 或 Canal-JSON 时，才会生效。 -# only-output-updated-columns = false - -############ 以下是存储服务类型 sink 配置 ############ -# 以下三个配置项仅在同步到存储服务的 sink 中使用，在 MQ 和 MySQL 类 sink 中无需设置。 -# 换行符，用来分隔两个数据变更事件。默认值为空，表示使用 "\r\n" 作为换行符。 -# terminator = '' - -# 文件路径的日期分隔类型。可选类型有 `none`、`year`、`month` 和 `day`。默认值为 `day`，即按天分隔。详见 。 -# 注意：该参数只有当下游为存储服务时，才会生效。 -date-separator = 'day' - -# 是否使用 partition 作为分隔字符串。默认值为 true，即一张表中各个 partition 的数据会分不同的目录来存储。建议保持该配置项为 true 以避免下游分区表可能丢数据的问题 。使用示例详见 。 -# 注意：该参数只有当下游为存储服务时，才会生效。 -enable-partition-separator = true - -# 是否关闭 schema 信息的输出。默认值为 false，即输出 schema 信息。 -# 注意：该参数只有当 sink 类型为 MQ 且输出协议为 Debezium 时才生效。 -debezium-disable-schema = false - -# 从 v6.5.0 开始，TiCDC 支持以 CSV 格式将数据变更记录保存至存储服务中，在 MQ 和 MySQL 类 sink 中无需设置。 -# [sink.csv] -# 字段之间的分隔符。必须为 ASCII 字符，默认值为 `,`。 -# delimiter = ',' -# 用于包裹字段的引号字符。空值代表不使用引号字符。默认值为 `"`。 -# quote = '"' -# CSV 中列为 NULL 时将以什么字符来表示。默认值为 `\N`。 -# null = '\N' -# 是否在 CSV 行中包含 commit-ts。默认值为 false。 -# include-commit-ts = false -# 二进制类型数据的编码方式，可选 'base64' 或 'hex'。默认值为 'base64'。 -# binary-encoding-method = 'base64' -# 是否输出 handle 列信息。默认值为 false。该配置项仅用于内部实现，不推荐设置该配置项。 -# output-handle-key = false -# 是否输出行数据更改前的值。默认值为 false。开启后，Update 事件会输出两行数据：第一行为 Delete 事件，输出更改前的数据；第二行为 Insert 事件，输出更改后的数据。 -# 开启后，即当该参数设为 true 时，会在变更数据列前增加 "is-update" 列。该列用来标识当前行的变更数据是来自 Update 事件，还是原始的 Insert/Delete 事件。 -# 如果当前行的变更数据来自 Update 事件，则 "is-update" 列为 true，否则为 false。 -# output-old-value = false - -# 从 v8.0.0 开始，TiCDC 新增了 Simple Protocol 消息编码协议，以下为该协议的配置参数。 -# 关于该协议的详情，请参考 。 -# 以下为 Simple Protocol 参数，用来控制 bootstrap 消息的发送行为。 -# send-bootstrap-interval-in-sec 用来控制发送 bootstrap 消息的时间间隔，单位为秒。 -# 默认值为 120 秒，即每张表每隔 120 秒发送一次 bootstrap 消息。 -# send-bootstrap-interval-in-sec = 120 - -# send-bootstrap-in-msg-count 用来控制发送 bootstrap 的消息间隔，单位为消息数。 -# 默认值为 10000，即每张表每发送 10000 条行变更消息就发送一次 bootstrap 消息。 -# send-bootstrap-in-msg-count = 10000 -# 注意：如果要关闭 bootstrap 消息的发送，则将 send-bootstrap-interval-in-sec 和 send-bootstrap-in-msg-count 均设置为 0。 - -# send-bootstrap-to-all-partition 用来控制是否发送 bootstrap 消息到所有的 partition。 -# 默认值为 true，即发送 bootstrap 消息到对应表 topic 的所有的 partition。 -# 如果设置为 false，则只发送 bootstrap 消息到对应表 topic 的第一个 partition。 -# send-bootstrap-to-all-partition = true - -[sink.kafka-config.codec-config] -# encoding-format 用来控制 simple protocol 的消息的编码格式，目前支持 "json" 和 "avro" 两种格式。 -# 默认值为 "json"。 -# encoding-format = "json" - -[sink.open] -# 是否输出行数据更改前的值。默认值为 true。关闭后，Update 事件不会输出 "p" 字段的数据。 -# output-old-value = true - -[sink.debezium] -# 是否输出行数据更改前的值。默认值为 true。关闭后，Update 事件不会输出 "before" 字段的数据。 -# output-old-value = true - -# consistent 中的字段用于配置 Changefeed 的数据一致性。详细的信息，请参考 。 -# 注意：一致性相关参数只有当下游为数据库并且开启 redo log 功能时，才会生效。 -[consistent] -# 数据一致性级别。默认值为 "none"，可选值为 "none" 和 "eventual"。 -# 设置为 "none" 时将关闭 redo log。 -level = "none" -# redo log 的最大日志大小，单位为 MB。默认值为 64。 -max-log-size = 64 -# 两次 redo log 刷新的时间间隔，单位为毫秒。默认值为 2000。 -flush-interval = 2000 -# redo log 使用存储服务的 URI。默认值为空。 -storage = "" -# 是否将 redo log 存储到本地文件中。默认值为 false。 -use-file-backend = false -# 控制 redo 模块中编解码 worker 的数量，默认值为 16。 -encoding-worker-num = 16 -# 控制 redo 模块中上传文件 worker 的数量，默认值为 8。 -flush-worker-num = 8 -# redo log 文件的压缩行为，可选值为 "" 和 "lz4"。默认值为 ""，表示不进行压缩。 -compression = "" -# redo log 上传单个文件的并发数，默认值为 1，表示禁用并发。 -flush-concurrency = 1 - -[integrity] -# 是否开启单行数据的 Checksum 校验功能，默认值为 "none"，即不开启。可选值为 "none" 和 "correctness"。 -integrity-check-level = "none" -# 当单行数据的 Checksum 校验失败时，Changefeed 打印错误行数据相关日志的级别。默认值为 "warn"，可选值为 "warn" 和 "error"。 -corruption-handle-level = "warn" - -# 以下参数仅在下游为 Kafka 时生效。 -[sink.kafka-config] -# Kafka SASL 认证机制。该参数默认值为空，表示不使用 SASL 认证。 -sasl-mechanism = "OAUTHBEARER" -# Kafka SASL OAUTHBEARER 认证机制中的 client-id。默认值为空。在使用该认证机制时，该参数必填。 -sasl-oauth-client-id = "producer-kafka" -# Kafka SASL OAUTHBEARER 认证机制中的 client-secret。默认值为空。需要 Base64 编码。在使用该认证机制时，该参数必填。 -sasl-oauth-client-secret = "cHJvZHVjZXIta2Fma2E=" -# Kafka SASL OAUTHBEARER 认证机制中的 token-url 用于获取 token。默认值为空。在使用该认证机制时，该参数必填。 -sasl-oauth-token-url = "http://127.0.0.1:4444/oauth2/token" -# Kafka SASL OAUTHBEARER 认证机制中的 scopes。默认值为空。在使用该认证机制时，该参数可选填。 -sasl-oauth-scopes = ["producer.kafka", "consumer.kafka"] -# Kafka SASL OAUTHBEARER 认证机制中的 grant-type。默认值为 "client_credentials"。在使用该认证机制时，该参数可选填。 -sasl-oauth-grant-type = "client_credentials" -# Kafka SASL OAUTHBEARER 认证机制中的 audience。默认值为空。在使用该认证机制时，该参数可选填。 -sasl-oauth-audience = "kafka" - -# 控制是否输出原始的数据变更事件，默认值为 false。更多信息，请参考 https://docs.pingcap.com/zh/tidb/dev/ticdc-split-update-behavior#控制是否拆分主键或唯一键-update-事件 -# output-raw-change-event = false - -# 以下配置仅在选用 avro 作为协议，并且使用 AWS Glue Schema Registry 时需要配置 -# 请参考 "同步数据到 Kafka" 这一文档中 "使用 AWS Glue Schema Registry" 这一节内容：https://docs.pingcap.com/zh/tidb/dev/ticdc-sink-to-kafka#ticdc-集成-aws-glue-schema-registry -# [sink.kafka-config.glue-schema-registry-config] -# region="us-west-1" -# registry-name="ticdc-test" -# access-key="xxxx" -# secret-access-key="xxxx" -# token="xxxx" - -# 以下参数仅在下游为 Pulsar 时生效。 -[sink.pulsar-config] -# 使用 token 进行 Pulsar 服务端的认证，此处为 token 的值。 -authentication-token = "xxxxxxxxxxxxx" -# 指定使用 token 进行 Pulsar 服务端的认证，此处为 token 所在文件的路径。 -token-from-file="/data/pulsar/token-file.txt" -# Pulsar 使用 basic 账号密码验证身份。 -basic-user-name="root" -# Pulsar 使用 basic 账号密码验证身份，此处为密码。 -basic-password="password" -# Pulsar TLS 加密认证证书路径。 -auth-tls-certificate-path="/data/pulsar/certificate" -# Pulsar TLS 加密认证私钥路径。 -auth-tls-private-key-path="/data/pulsar/certificate.key" -# Pulsar TLS 加密可信证书文件路径。 -tls-trust-certs-file-path="/data/pulsar/tls-trust-certs-file" -# Pulsar oauth2 issuer-url 更多详细配置请看 Pulsar 官方介绍：https://pulsar.apache.org/docs/2.10.x/client-libraries-go/#tls-encryption-and-authentication -oauth2.oauth2-issuer-url="https://xxxx.auth0.com" -# Pulsar oauth2 audience -oauth2.oauth2-audience="https://xxxx.auth0.com/api/v2/" -# Pulsar oauth2 private-key -oauth2.oauth2-private-key="/data/pulsar/privateKey" -# Pulsar oauth2 client-id -oauth2.oauth2-client-id="0Xx...Yyxeny" -# Pulsar oauth2 oauth2-scope -oauth2.oauth2-scope="xxxx" - -# TiCDC 中缓存 Pulsar Producer 的个数，默认上限为 10240 个。每个 Pulsar Producer 对应一个 topic，如果你需要同步的 topic 数量大于默认值，则需要调大该数量。 -pulsar-producer-cache-size=10240 -# Pulsar 数据压缩方式，默认不压缩，可选 "lz4"、"zlib"、"zstd"。 -compression-type="" -# Pulsar 客户端与服务端建立 TCP 连接的超时时间，默认 5 秒。 -connection-timeout=5 -# Pulsar 客户端发起创建、订阅等操作的超时时间，默认为 30 秒。 -operation-timeout=30 -# Pulsar Producer 发送消息时的单个 batch 内的消息数量上限，默认值为 1000。 -batching-max-messages=1000 -# Pulsar Producer 消息攒批的时间间隔，默认 10 毫秒。 -batching-max-publish-delay=10 -# Pulsar Producer 发送消息的超时时间，默认 30 秒。 -send-timeout=30 - -# 控制是否输出原始的数据变更事件，默认值为 false。更多信息，请参考 https://docs.pingcap.com/zh/tidb/dev/ticdc-split-update-behavior#控制是否拆分主键或唯一键-update-事件 -# output-raw-change-event = false - -[sink.cloud-storage-config] -# 向下游存储服务保存数据变更记录的并发度，默认值为 16。 -worker-count = 16 -# 向下游存储服务保存数据变更记录的间隔，默认值为 "2s"。 -flush-interval = "2s" -# 单个数据变更文件的字节数超过 `file-size` 时将其保存至存储服务中，默认值为 67108864，即 64 MiB。 -file-size = 67108864 -# 文件保留的时长，仅在 date-separator 配置为 day 时生效，默认值为 0，表示禁用文件清理。假设 `file-expiration-days = 1` 且 `file-cleanup-cron-spec = "0 0 0 * * *"`，TiCDC 将在每天 00:00:00 时刻清理已保存超过 24 小时的文件。例如，2023/12/02 00:00:00 将清理 2023/12/01 之前（注意：不包括 2023/12/01）的文件。 -file-expiration-days = 0 -# 定时清理任务的运行周期，与 crontab 配置兼容，格式为 ` `，默认值为 "0 0 2 * * *"，表示每天凌晨两点执行清理任务 -file-cleanup-cron-spec = "0 0 2 * * *" -# 上传单个文件的并发数，默认值为 1，表示禁用并发。 -flush-concurrency = 1 -# 控制是否输出原始的数据变更事件，默认值为 false。更多信息，请参考 https://docs.pingcap.com/zh/tidb/dev/ticdc-split-update-behavior#控制是否拆分主键或唯一键-update-事件 -output-raw-change-event = false -``` +### `memory-quota` + +- 指定该 Changefeed 在 Capture Server 中内存配额的上限。对于超额使用部分，会在运行中被 Go runtime 优先回收。默认值为 `1073741824`，即 1 GB。 +- 默认值：`1073741824` + +### `case-sensitive` + +- 指定配置文件中涉及的库名、表名是否为大小写敏感 +- 该配置会同时影响 filter 和 sink 相关配置。自 v6.5.6、v7.1.3 和 v7.5.0 起，默认值由 true 改为 false +- 默认值：`false` + +### `enable-sync-point` + +- 是否开启 Syncpoint 功能，从 v6.3.0 开始支持，该功能默认关闭。 +- 从 v6.4.0 开始，使用 Syncpoint 功能需要同步任务拥有下游集群的 SYSTEM_VARIABLES_ADMIN 或者 SUPER 权限。 +- 注意：该参数只有当下游为 TiDB 时，才会生效。 +- 默认值：`false` + +### `sync-point-interval` + +- Syncpoint 功能对齐上下游 snapshot 的时间间隔 +- 配置格式为 h m s，例如 "1h30m30s" +- 默认值为 10m，最小值为 30s +- 注意：该参数只有当下游为 TiDB 时，才会生效。 +- 默认值：`"10m"` +- 最小值：`"30s"` + +### `sync-point-retention` + +- Syncpoint 功能在下游表中保存的数据的时长，超过这个时间的数据会被清理 +- 配置格式为 h m s，例如 "24h30m30s" +- 默认值为 24h +- 注意：该参数只有当下游为 TiDB 时，才会生效 +- 默认值：`"24h"` + +### `sql-mode` + +- 从 v6.5.6、v7.1.3、v7.5.0 起引入，用于设置解析 DDL 时使用的 SQL 模式，多个模式之间用逗号分隔 +- 默认值和 TiDB 的默认 SQL 模式一致 + +### `bdr-mode` + +- 默认值为 false，表示不处于 BDR 模式。 +- 如果要使用 TiCDC 搭建 BDR 集群，需要将该参数设置为 true，同时要将 TiDB 集群设置为 BDR 模式。 +- 详情请参考：https://docs.pingcap.com/zh/tidb/stable/ticdc-bidirectional-replication#ticdc-双向复制 +- 默认值：`false` + +### `changefeed-error-stuck-duration` + +- changefeed 发生内部错误或异常时允许自动重试的时间，默认值为 30 分钟。 +- 若 changefeed 发生内部错误或异常，且持续时间超过该参数设置的时间，changefeed 会进入 Failed 状态。 +- 当 changefeed 处于 failed 状态时，需要手动重启 changefeed 才能恢复。 +- 配置格式为 "h m s"，例如 "1h30m30s"。 +- 默认值：`"30m"` + +### `mounter` + +- mounter 解码 KV 数据的线程数 +- 默认值：`16` + +#### `worker-num` + +- mounter 解码 KV 数据的线程数，默认值为 16 + +### `filter` + +#### `ignore-txn-start-ts` + +- 忽略指定 start_ts 的事务 + +#### `rules` + +- 过滤器规则 +- 过滤规则语法：https://docs.pingcap.com/zh/tidb/stable/table-filter#表库过滤语法 + +#### `event-filters` + +##### First Filter Rule + +###### `matcher` + +- matcher 是一个白名单，表示该过滤规则只应用于 test 库中的 worker 表 + +###### `ignore-event` + +- 过滤掉 insert 事件 + +###### `ignore-sql` + +- 过滤掉以 "drop" 开头或者包含 "add column" 的 DDL + +###### `ignore-delete-value-expr` + +- 过滤掉包含 name = 'john' 条件的 delete DML + +###### `ignore-insert-value-expr` + +- 过滤掉包含 id >= 100 条件的 insert DML + +###### `ignore-update-old-value-expr` + +- 过滤掉旧值 age < 18 的 update DML + +###### `ignore-update-new-value-expr` + +- 过滤掉新值 gender = 'male' 的 update DML + +##### Second Filter Rule + +###### `matcher` + +- 该事件过滤器只应用于 test.fruit 表 + +###### `ignore-event` + +- 忽略 drop table 的 DDL 事件和 delete 类型的 DML 事件 +- 需要注意的是，在更新 TiDB 中聚簇索引的列值时，TiCDC 会将一个 UPDATE 事件拆分成为 DELETE 和 INSERT 事件，TiCDC 无法将该类事件识别为 UPDATE 事件，因此无法正确地进行过滤 + +###### `ignore-sql` + +- 忽略以 drop table 开头的，或者包含 alter table 的 DDL 语句 + +###### `ignore-insert-value-expr` + +- 忽略包含 price > 1000 和 origin = 'no where' 条件的 insert DML + +### `scheduler` + +- 将表以 Region 为单位分配给多个 TiCDC 节点进行同步 +- 注意：该功能只在 Kafka changefeed 上生效，暂不支持 MySQL changefeed + +#### `enable-table-across-nodes` + +- 默认为 "false"。设置为 "true" 以打开该功能 +- 默认值：`false` + +#### `region-threshold` + +- enable-table-across-nodes 开启后的分配模式之一：按 Region 的数量分配，即每个 CDC 节点处理 region 的个数基本相等。当某个表 Region 个数大于 `region-threshold` 值时，会将表分配到多个节点处理 +- 默认值：`10000` + +#### `write-key-threshold` + +- enable-table-across-nodes 开启后的分配模式之一：按写入的流量分配，即每个 CDC 节点处理 region 总修改行数基本相当。只有当表中每分钟修改行数超过 `write-key-threshold` 值时，该表才会生效 +- 默认值：`0` +- 注意： + - `write-key-threshold` 参数默认值为 0，代表默认不会采用流量的分配模式 + - 两种方式配置一种即可生效，当 `region-threshold` 和 `write-key-threshold` 同时配置时，TiCDC 将优先采用按流量分配的模式，即 `write-key-threshold` + +### `sink` + +#### MQ 类型 sink 配置 + +##### `dispatchers` + +- 对于 MQ 类的 Sink，可以通过 dispatchers 配置 event 分发器 +- 支持 partition 及 topic（从 v6.1 开始支持）两种 event 分发器 +- matcher 的匹配语法和过滤器规则语法相同 +- 注意：该参数只有当下游为消息队列时，才会生效 +- 注意：当下游 MQ 为 Pulsar 时，如果 partition 的路由规则未指定为 'ts', 'index-value', 'table', 'default' 中的任意一个，那么将会使用你设置的字符串作为每一条 Pulsar message 的 key 进行路由 + +##### `column-selectors` + +- 从 v7.5.0 开始引入，仅对 Kafka Sink 生效 +- 用于选择部分列进行同步 + +##### `protocol` + +- 用于指定编码消息时使用的格式协议 +- 当下游类型是 Kafka 时，支持 canal-json、avro、debezium、open-protocol、simple +- 当下游类型是 Pulsar 时，仅支持 canal-json 协议 +- 当下游类型是存储服务时，目前仅支持 canal-json、csv 两种协议 +- 注意：该参数只有当下游为 Kafka、Pulsar，或存储服务时，才会生效 + +##### `delete-only-output-handle-key-columns` + +- 用于指定 Delete 事件的输出内容，只对 canal-json 和 open-protocol 协议有效。从 v7.2.0 开始引入 +- 该参数和 `force-replicate` 参数不兼容，如果同时将该参数和 `force-replicate` 设置为 true，创建 changefeed 会报错 +- 默认值：`false` + +##### `schema-registry` + +- Schema 注册表的 URL +- 注意：该参数只有当下游为消息队列时，才会生效 + +##### `encoder-concurrency` + +- 编码数据时所用编码器的线程数 +- 默认值：`32` +- 注意：该参数只有当下游为消息队列时，才会生效 + +##### `enable-kafka-sink-v2` + +- 是否开启 Kafka Sink V2。Kafka Sink V2 内部使用 kafka-go 实现 +- 默认值：`false` +- 注意：该参数是一个实验特性，并且只有当下游为消息队列时才会生效 + +##### `only-output-updated-columns` + +- 是否只向下游同步有内容更新的列。从 v7.1.0 开始支持 +- 默认值：`false` +- 注意：该参数只有当下游为消息队列，并且使用 Open Protocol 或 Canal-JSON 时，才会生效 + +#### 存储服务类型 sink 配置 + +##### `terminator` + +- 换行符，用来分隔两个数据变更事件 +- 默认值：`\r\n` + +##### `date-separator` + +- 文件路径的日期分隔类型 +- 可选值：`none`, `year`, `month`, `day` +- 默认值：`day` +- 注意：该参数只有当下游为存储服务时，才会生效 + +##### `enable-partition-separator` + +- 是否使用 partition 作为分隔字符串 +- 默认值：`true` +- 注意：该参数只有当下游为存储服务时，才会生效 + +##### `debezium-disable-schema` + +- 是否关闭 schema 信息的输出 +- 默认值：`false` +- 注意：该参数只有当 sink 类型为 MQ 且输出协议为 Debezium 时才生效 + +#### `csv` + +##### `delimiter` + +- 字段之间的分隔符 +- 必须为 ASCII 字符 +- 默认值：`,` + +##### `quote` + +- 用于包裹字段的引号字符 +- 空值代表不使用引号字符 +- 默认值：`"` + +##### `null` + +- CSV 中列为 NULL 时将以什么字符来表示 +- 默认值：`\N` + +##### `include-commit-ts` + +- 是否在 CSV 行中包含 commit-ts +- 默认值：`false` + +##### `binary-encoding-method` + +- 二进制类型数据的编码方式 +- 可选值：`base64`, `hex` +- 默认值：`base64` + +##### `output-handle-key` + +- 是否输出 handle 列信息 +- 默认值：`false` +- 该配置项仅用于内部实现，不推荐设置该配置项 + +##### `output-old-value` + +- 是否输出行数据更改前的值 +- 默认值：`false` + +#### Simple Protocol 配置 + +##### `send-bootstrap-interval-in-sec` + +- 用来控制发送 bootstrap 消息的时间间隔，单位为秒 +- 默认值：`120` + +##### `send-bootstrap-in-msg-count` + +- 用来控制发送 bootstrap 的消息间隔，单位为消息数 +- 默认值：`10000` + +##### `send-bootstrap-to-all-partition` + +- 用来控制是否发送 bootstrap 消息到所有的 partition +- 默认值：`true` + +#### `kafka-config.codec-config` + +##### `encoding-format` + +- 用来控制 simple protocol 的消息的编码格式 +- 可选值：`json`, `avro` +- 默认值：`json` + +#### `open` + +##### `output-old-value` + +- 是否输出行数据更改前的值 +- 默认值：`true` +- 关闭后，Update 事件不会输出 "p" 字段的数据 + +#### `debezium` + +##### `output-old-value` + +- 是否输出行数据更改前的值 +- 默认值：`true` +- 关闭后，Update 事件不会输出 "before" 字段的数据 + +### `consistent` + +- consistent 中的字段用于配置 Changefeed 的数据一致性 +- 注意：一致性相关参数只有当下游为数据库并且开启 redo log 功能时，才会生效 + +#### `level` + +- 数据一致性级别 +- 默认值：`none` +- 可选值：`none`, `eventual` +- 设置为 "none" 时将关闭 redo log + +#### `max-log-size` + +- redo log 的最大日志大小，单位为 MB +- 默认值：`64` + +#### `flush-interval` + +- 两次 redo log 刷新的时间间隔，单位为毫秒 +- 默认值：`2000` + +#### `storage` + +- redo log 使用存储服务的 URI +- 默认值：`` + +#### `use-file-backend` + +- 是否将 redo log 存储到本地文件中 +- 默认值：`false` + +#### `encoding-worker-num` + +- 控制 redo 模块中编解码 worker 的数量 +- 默认值：`16` + +#### `flush-worker-num` + +- 控制 redo 模块中上传文件 worker 的数量 +- 默认值：`8` + +#### `compression` + +- redo log 文件的压缩行为 +- 可选值：`""`, `lz4` +- 默认值：`""`（表示不进行压缩） + +#### `flush-concurrency` + +- redo log 上传单个文件的并发数 +- 默认值：`1`（表示禁用并发） + +### `integrity` + +#### `integrity-check-level` + +- 是否开启单行数据的 Checksum 校验功能 +- 默认值：`none` +- 可选值：`none`, `correctness` + +#### `corruption-handle-level` + +- 当单行数据的 Checksum 校验失败时，Changefeed 打印错误行数据相关日志的级别 +- 默认值：`warn` +- 可选值：`warn`, `error` + +### `sink.kafka-config` + +- 以下参数仅在下游为 Kafka 时生效 + +#### `sasl-mechanism` + +- Kafka SASL 认证机制 +- 默认值：``（表示不使用 SASL 认证） +- 可选值：`OAUTHBEARER` + +#### `sasl-oauth-client-id` + +- Kafka SASL OAUTHBEARER 认证机制中的 client-id +- 默认值：`` +- 在使用 OAUTHBEARER 认证机制时，该参数必填 + +#### `sasl-oauth-client-secret` + +- Kafka SASL OAUTHBEARER 认证机制中的 client-secret +- 默认值：`` +- 需要 Base64 编码 +- 在使用 OAUTHBEARER 认证机制时，该参数必填 + +#### `sasl-oauth-token-url` + +- Kafka SASL OAUTHBEARER 认证机制中的 token-url，用于获取 token +- 默认值：`` +- 在使用 OAUTHBEARER 认证机制时，该参数必填 + +#### `sasl-oauth-scopes` + +- Kafka SASL OAUTHBEARER 认证机制中的 scopes +- 默认值：`` +- 在使用 OAUTHBEARER 认证机制时，该参数可选填 + +#### `sasl-oauth-grant-type` + +- Kafka SASL OAUTHBEARER 认证机制中的 grant-type +- 默认值：`client_credentials` +- 在使用 OAUTHBEARER 认证机制时，该参数可选填 + +#### `sasl-oauth-audience` + +- Kafka SASL OAUTHBEARER 认证机制中的 audience +- 默认值：`` +- 在使用 OAUTHBEARER 认证机制时，该参数可选填 + +#### `output-raw-change-event` + +- 控制是否输出原始的数据变更事件 +- 默认值：`false` + +### `sink.kafka-config.glue-schema-registry-config` + +- 以下配置仅在选用 avro 作为协议，并且使用 AWS Glue Schema Registry 时需要配置 + +#### `region` + +- AWS 区域名称 + +#### `registry-name` + +- Schema Registry 的名称 + +#### `access-key` + +- AWS 访问密钥 ID + +#### `secret-access-key` + +- AWS 密钥访问密钥 + +#### `token` + +- AWS 会话令牌 + +### `sink.pulsar-config` + +- 以下参数仅在下游为 Pulsar 时生效 + +#### `authentication-token` + +- 使用 token 进行 Pulsar 服务端的认证，此处为 token 的值 + +#### `token-from-file` + +- 指定使用 token 进行 Pulsar 服务端的认证，此处为 token 所在文件的路径 + +#### `basic-user-name` + +- Pulsar 使用 basic 账号密码验证身份 + +#### `basic-password` + +- Pulsar 使用 basic 账号密码验证身份，此处为密码 + +#### `auth-tls-certificate-path` + +- Pulsar TLS 加密认证证书路径 + +#### `auth-tls-private-key-path` + +- Pulsar TLS 加密认证私钥路径 + +#### `tls-trust-certs-file-path` + +- Pulsar TLS 加密可信证书文件路径 + +#### `oauth2.oauth2-issuer-url` + +- Pulsar oauth2 issuer-url + +#### `oauth2.oauth2-audience` + +- Pulsar oauth2 audience + +#### `oauth2.oauth2-private-key` + +- Pulsar oauth2 private-key + +#### `oauth2.oauth2-client-id` + +- Pulsar oauth2 client-id + +#### `oauth2.oauth2-scope` + +- Pulsar oauth2 oauth2-scope + +#### `pulsar-producer-cache-size` + +- TiCDC 中缓存 Pulsar Producer 的个数 +- 默认值：`10240` + +#### `compression-type` + +- Pulsar 数据压缩方式 +- 默认值：``（表示不压缩） +- 可选值：`lz4`, `zlib`, `zstd` + +#### `connection-timeout` + +- Pulsar 客户端与服务端建立 TCP 连接的超时时间 +- 默认值：`5`（秒） + +#### `operation-timeout` + +- Pulsar 客户端发起创建、订阅等操作的超时时间 +- 默认值：`30`（秒） + +#### `batching-max-messages` + +- Pulsar Producer 发送消息时的单个 batch 内的消息数量上限 +- 默认值：`1000` + +#### `batching-max-publish-delay` + +- Pulsar Producer 消息攒批的时间间隔 +- 默认值：`10`（毫秒） + +#### `send-timeout` + +- Pulsar Producer 发送消息的超时时间 +- 默认值：`30`（秒） + +#### `output-raw-change-event` + +- 控制是否输出原始的数据变更事件 +- 默认值：`false` + +### `sink.cloud-storage-config` + +#### `worker-count` + +- 向下游存储服务保存数据变更记录的并发度 +- 默认值：`16` + +#### `flush-interval` + +- 向下游存储服务保存数据变更记录的间隔 +- 默认值：`2s` + +#### `file-size` + +- 单个数据变更文件的字节数超过 `file-size` 时将其保存至存储服务中 +- 默认值：`67108864`（64 MiB） + +#### `file-expiration-days` + +- 文件保留的时长，仅在 date-separator 配置为 day 时生效 +- 默认值：`0`（表示禁用文件清理） +- 示例：假设 `file-expiration-days = 1` 且 `file-cleanup-cron-spec = "0 0 0 * * *"`，TiCDC 将在每天 00:00:00 时刻清理已保存超过 24 小时的文件。例如，2023/12/02 00:00:00 将清理 2023/12/01 之前（注意：不包括 2023/12/01）的文件 + +#### `file-cleanup-cron-spec` + +- 定时清理任务的运行周期，与 crontab 配置兼容 +- 格式：` ` +- 默认值：`0 0 2 * * *`（表示每天凌晨两点执行清理任务） + +#### `flush-concurrency` + +- 上传单个文件的并发数 +- 默认值：`1`（表示禁用并发） + +#### `output-raw-change-event` + +- 控制是否输出原始的数据变更事件 +- 默认值：`false` \ No newline at end of file diff --git a/ticdc/ticdc-server-config.md b/ticdc/ticdc-server-config.md index 0a5b80809f41..92066ebddc6d 100644 --- a/ticdc/ticdc-server-config.md +++ b/ticdc/ticdc-server-config.md @@ -30,59 +30,138 @@ summary: 了解 TiCDC 详细的命令行参数和配置文件定义。 对于 `cdc server` 命令中 `config` 参数指定的配置文件说明如下： -```toml -# 下面的字段的配置含义与命令行参数相同，但是命令行参数优先级更高。 -addr = "127.0.0.1:8300" -advertise-addr = "" -log-file = "" -log-level = "info" -data-dir = "" -gc-ttl = 86400 # 24 h -tz = "System" -cluster-id = "default" -# 控制 GOGC Tuner 自动调节的最大内存阈值（单位为 byte）：设置较小的阈值会提高 GC 频率；设置较大的阈值会降低 GC 频率并使 TiCDC 进程占用更多的内存资源；超过阈值后 GOGC Tuner 会停止工作。默认值为 0，表示禁用 GOGC Tuner。 -gc-tuner-memory-threshold = 0 - -[security] - ca-path = "" - cert-path = "" - key-path = "" - # 控制是否开启 TLS 客户端鉴权，默认值为 false。 - mtls = false - # 控制是否使用用户名和密码进行客户端鉴权，默认值为 false。 - client-user-required = false - # 指定可用于客户端鉴权的用户名，列表中不存在的用户的鉴权请求将被直接拒绝。默认值为 null。 - client-allowed-user = ["username_1", "username_2"] - -# TiCDC 与 etcd 服务间的 session 时长（单位为秒），默认为 10，可选。 -capture-session-ttl = 10 # 10s -# TiCDC 集群中的 owner 模块尝试推进同步任务进度的周期，默认值为 `50000000` 纳秒（即 50 毫秒），可选。该参数有两种配置方式：只指定数字（例如，配置为 `40000000` 表示 40000000 纳秒，即 40 毫秒），或同时指定数字和单位（例如，直接配置为 `40ms`）。 -owner-flush-interval = 50000000 # 50 ms -# TiCDC 集群中的 processor 模块尝试推进同步任务进度的周期，默认值为 `50000000` 纳秒（即 50 毫秒），可选。该参数配置方式与 `owner-flush-interval` 相同。 -processor-flush-interval = 50000000 # 50 ms - -# [log] -# # 用于指定 zap log 模块内部的错误日志的输出位置。默认是 "stderr"，可选。 -# error-output = "stderr" -# [log.file] -# # 单个 log 文件的最大文件大小，单位为 MiB。默认值为 300，可选。 -# max-size = 300 # 300 MiB -# # log 文件最长保留天数，默认值为 `0`，代表永不删除，可选。 -# max-days = 0 -# # log 文件的保留个数，默认值为 `0`，代表保留所有 log 文件，可选。 -# max-backups = 0 - -#[sorter] -# Sorter 模块给默认启动的 8 个 pebble DB 共享的 pebble block cache 的大小，单位为 MiB，默认值为 128。 -# cache-size-in-mb = 128 -# Sorter 文件相对于 data-dir 的目录，默认值为 "/tmp/sorter"，可选。 -# sorter-dir = "/tmp/sorter" - -# [kv-client] -# 单个 Region worker 中可使用的线程数量，默认为 8，可选。 -# worker-concurrent = 8 -# TiCDC 中共享线程池中线程的数量，主要用于处理 KV 事件，默认值为 `0`，表示默认为 CPU 核数的 2 倍，可选。 -# worker-pool-size = 0 -# Region 连接重试时间，默认值为 `60000000000` 纳秒（即 1 分钟），可选。该参数有两种配置方式：只指定数字（例如，配置为 `50000000` 表示 50000000 纳秒，即 50 毫秒），或同时指定数字和单位（例如，直接配置为 `50ms`）。 -# region-retry-duration = 60000000000 -``` +下面的字段的配置含义与命令行参数相同，但是命令行参数优先级更高 + +### `addr` + +- 默认值：`"127.0.0.1:8300"` + +### `advertise-addr` + +- 默认值：`""` + +### `log-file` + +- 默认值：`""` + +### `log-level` + +- 默认值：`"info"` + +### `data-dir` + +- 默认值：`""` + +### `gc-ttl` + +- 默认值：`86400` (24h) + +### `tz` + +- 默认值：`"System"` + +### `cluster-id` + +- 默认值：`"default"` + +### `gc-tuner-memory-threshold` + +- 控制 GOGC Tuner 自动调节的最大内存阈值（单位为 byte）：设置较小的阈值会提高 GC 频率；设置较大的阈值会降低 GC 频率并使 TiCDC 进程占用更多的内存资源；超过阈值后 GOGC Tuner 会停止工作。默认值为 0，表示禁用 GOGC Tuner。 +- 默认值：`0` + +### security + +#### `ca-path` + +- 默认值：`""` + +#### `cert-path` + +- 默认值：`""` + +#### `key-path` + +- 默认值：`""` + +#### `mtls` + +- 控制是否开启 TLS 客户端鉴权 +- 默认值：`false` + +#### `client-user-required` + +- 控制是否使用用户名和密码进行客户端鉴权 +- 默认值：`false` + +#### `client-allowed-user` + +- 指定可用于客户端鉴权的用户名，列表中不存在的用户的鉴权请求将被直接拒绝。默认值为 null。 +- 默认值：`null` + +### `capture-session-ttl` + +- TiCDC 与 etcd 服务间的 session 时长（单位为秒），默认为 10，可选。 +- 默认值：`10` + +### `owner-flush-interval` + +- TiCDC 集群中的 owner 模块尝试推进同步任务进度的周期，默认值为 `50000000` 纳秒（即 50 毫秒），可选。该参数有两种配置方式：只指定数字（例如，配置为 `40000000` 表示 40000000 纳秒，即 40 毫秒），或同时指定数字和单位（例如，直接配置为 `40ms`）。 +- 默认值：`50000000`（50ms） + +### `processor-flush-interval` + +- TiCDC 集群中的 processor 模块尝试推进同步任务进度的周期，默认值为 `50000000` 纳秒（即 50 毫秒），可选。该参数配置方式与 `owner-flush-interval` 相同。 +- 默认值：`50000000`（50ms） + +### log + +#### `error-output` + +- 用于指定 zap log 模块内部的错误日志的输出位置。可选。 +- 默认值：`"stderr"` + +#### log.file + +##### `max-size` + +- 单个 log 文件的最大文件大小，单位为 MiB。默认值为 300，可选。 +- 默认值：`300` + +##### `max-days` + +- log 文件最长保留天数，默认值为 `0`，代表永不删除，可选。 +- 默认值：`0`（代表永不删除） + +##### `max-backups` + +- log 文件的保留个数，默认值为 `0`，代表保留所有 log 文件，可选。 +- 默认值：`0`（代表保留所有 log 文件） + +### sorter + +#### `cache-size-in-mb` + +- Sorter 模块给默认启动的 8 个 pebble DB 共享的 pebble block cache 的大小，单位为 MiB，默认值为 128。 +- 默认值：`128` + +#### `sorter-dir` + +- Sorter 文件相对于 data-dir 的目录，默认值为 "/tmp/sorter"，可选。 +- 默认值：`"/tmp/sorter"` + +### kv-client + +#### `worker-concurrent` + +- 单个 Region worker 中可使用的线程数量，默认为 8，可选。 +- 默认值：`8` + +#### `worker-pool-size` + +- TiCDC 中共享线程池中线程的数量，主要用于处理 KV 事件，默认值为 `0`，表示默认为 CPU 核数的 2 倍，可选。 +- 默认值：`0`（表示默认为 CPU 核数的 2 倍） + +#### `region-retry-duration` + +- Region 连接重试时间，默认值为 `60000000000` 纳秒（即 1 分钟），可选。该参数有两种配置方式：只指定数字（例如，配置为 `50000000` 表示 50000000 纳秒，即 50 毫秒），或同时指定数字和单位（例如，直接配置为 `50ms`）。 +- 默认值：`60000000000`（1分钟） From 967c31c95c118a23648e6bc674b904f8fdbaafcc Mon Sep 17 00:00:00 2001 From: Aolin Date: Mon, 9 Dec 2024 17:20:43 +0800 Subject: [PATCH 2/9] reformat ticdc-server-config.md Signed-off-by: Aolin --- ticdc/ticdc-server-config.md | 79 ++++++++++++++++++++---------------- 1 file changed, 44 insertions(+), 35 deletions(-) diff --git a/ticdc/ticdc-server-config.md b/ticdc/ticdc-server-config.md index 92066ebddc6d..f7d1a3229bfc 100644 --- a/ticdc/ticdc-server-config.md +++ b/ticdc/ticdc-server-config.md @@ -28,90 +28,96 @@ summary: 了解 TiCDC 详细的命令行参数和配置文件定义。 ## `cdc server` 配置文件说明 -对于 `cdc server` 命令中 `config` 参数指定的配置文件说明如下： +对于 `cdc server` 命令中 `config` 参数指定的配置文件说明如下。你可以在 [`pkg/cmd/util/ticdc.toml`](https://github.com/pingcap/tiflow/blob/master/pkg/cmd/util/ticdc.toml) 找到默认值的配置文件。 -下面的字段的配置含义与命令行参数相同，但是命令行参数优先级更高 +[//]: # (下面的字段的配置含义与命令行参数相同，但是命令行参数优先级更高) ### `addr` -- 默认值：`"127.0.0.1:8300"` +- 示例值：`"127.0.0.1:8300"` ### `advertise-addr` -- 默认值：`""` +- 示例值：`""` ### `log-file` -- 默认值：`""` +- 示例值：`""` ### `log-level` -- 默认值：`"info"` +- 示例值：`"info"` ### `data-dir` -- 默认值：`""` +- 示例值：`""` ### `gc-ttl` -- 默认值：`86400` (24h) +- 示例值：`86400` (24h) ### `tz` -- 默认值：`"System"` +- 示例值：`"System"` ### `cluster-id` -- 默认值：`"default"` +- 示例值：`"default"` ### `gc-tuner-memory-threshold` -- 控制 GOGC Tuner 自动调节的最大内存阈值（单位为 byte）：设置较小的阈值会提高 GC 频率；设置较大的阈值会降低 GC 频率并使 TiCDC 进程占用更多的内存资源；超过阈值后 GOGC Tuner 会停止工作。默认值为 0，表示禁用 GOGC Tuner。 -- 默认值：`0` +- 控制 GOGC Tuner 自动调节的最大内存阈值。设置较小的阈值会提高 GC 频率；设置较大的阈值会降低 GC 频率并使 TiCDC 进程占用更多的内存资源；超过阈值后 GOGC Tuner 会停止工作。 +- 默认值：`0`，表示禁用 GOGC Tuner。 +- 单位：Byte ### security #### `ca-path` -- 默认值：`""` +- 示例值：`""` #### `cert-path` -- 默认值：`""` +- 示例值：`""` #### `key-path` -- 默认值：`""` +- 示例值：`""` #### `mtls` -- 控制是否开启 TLS 客户端鉴权 +- 控制是否开启 TLS 客户端鉴权。 - 默认值：`false` #### `client-user-required` -- 控制是否使用用户名和密码进行客户端鉴权 +- 控制是否使用用户名和密码进行客户端鉴权。 - 默认值：`false` #### `client-allowed-user` -- 指定可用于客户端鉴权的用户名，列表中不存在的用户的鉴权请求将被直接拒绝。默认值为 null。 +- 指定可用于客户端鉴权的用户名，列表中不存在的用户的鉴权请求将被直接拒绝。 - 默认值：`null` +[//]: # (- 示例值：`["username_1", "username_2"]`) + ### `capture-session-ttl` -- TiCDC 与 etcd 服务间的 session 时长（单位为秒），默认为 10，可选。 +- TiCDC 与 etcd 服务间的 session 时长。可选。 - 默认值：`10` +- 单位：秒 ### `owner-flush-interval` -- TiCDC 集群中的 owner 模块尝试推进同步任务进度的周期，默认值为 `50000000` 纳秒（即 50 毫秒），可选。该参数有两种配置方式：只指定数字（例如，配置为 `40000000` 表示 40000000 纳秒，即 40 毫秒），或同时指定数字和单位（例如，直接配置为 `40ms`）。 -- 默认值：`50000000`（50ms） +- TiCDC 集群中的 owner 模块尝试推进同步任务进度的周期，默认值为 `50000000` 纳秒（即 50 毫秒）。可选。 +- 该参数有两种配置方式：只指定数字（例如，配置为 `40000000` 表示 40000000 纳秒，即 40 毫秒），或同时指定数字和单位（例如，直接配置为 `40ms`）。 +- 默认值：`50000000`，即 50 毫秒 ### `processor-flush-interval` -- TiCDC 集群中的 processor 模块尝试推进同步任务进度的周期，默认值为 `50000000` 纳秒（即 50 毫秒），可选。该参数配置方式与 `owner-flush-interval` 相同。 -- 默认值：`50000000`（50ms） +- TiCDC 集群中的 processor 模块尝试推进同步任务进度的周期，默认值为 `50000000` 纳秒（即 50 毫秒）。可选。 +- 该参数配置方式与 `owner-flush-interval` 相同。 +- 默认值：`50000000`，即 50 毫秒 ### log @@ -124,44 +130,47 @@ summary: 了解 TiCDC 详细的命令行参数和配置文件定义。 ##### `max-size` -- 单个 log 文件的最大文件大小，单位为 MiB。默认值为 300，可选。 +- 单个 log 文件的最大文件大小。可选。 - 默认值：`300` +- 单位：MiB ##### `max-days` -- log 文件最长保留天数，默认值为 `0`，代表永不删除，可选。 -- 默认值：`0`（代表永不删除） +- log 文件最长保留天数。可选。 +- 默认值：`0`，代表永不删除 ##### `max-backups` -- log 文件的保留个数，默认值为 `0`，代表保留所有 log 文件，可选。 -- 默认值：`0`（代表保留所有 log 文件） +- log 文件的保留个数。可选。 +- 默认值：`0`，代表保留所有 log 文件 ### sorter #### `cache-size-in-mb` -- Sorter 模块给默认启动的 8 个 pebble DB 共享的 pebble block cache 的大小，单位为 MiB，默认值为 128。 +- Sorter 模块给默认启动的 8 个 pebble DB 共享的 pebble block cache 的大小。 - 默认值：`128` +- 单位：MiB #### `sorter-dir` -- Sorter 文件相对于 data-dir 的目录，默认值为 "/tmp/sorter"，可选。 +- Sorter 文件相对于 data-dir 的目录。可选。 - 默认值：`"/tmp/sorter"` ### kv-client #### `worker-concurrent` -- 单个 Region worker 中可使用的线程数量，默认为 8，可选。 +- 单个 Region worker 中可使用的线程数量。可选。 - 默认值：`8` #### `worker-pool-size` -- TiCDC 中共享线程池中线程的数量，主要用于处理 KV 事件，默认值为 `0`，表示默认为 CPU 核数的 2 倍，可选。 -- 默认值：`0`（表示默认为 CPU 核数的 2 倍） +- TiCDC 中共享线程池中线程的数量，主要用于处理 KV 事件。可选。 +- 默认值：`0`，表示默认为 CPU 核数的 2 倍 #### `region-retry-duration` -- Region 连接重试时间，默认值为 `60000000000` 纳秒（即 1 分钟），可选。该参数有两种配置方式：只指定数字（例如，配置为 `50000000` 表示 50000000 纳秒，即 50 毫秒），或同时指定数字和单位（例如，直接配置为 `50ms`）。 -- 默认值：`60000000000`（1分钟） +- Region 连接重试时间，默认值为 `60000000000` 纳秒（即 1 分钟）。可选。 +- 该参数有两种配置方式：只指定数字（例如，配置为 `50000000` 表示 50000000 纳秒，即 50 毫秒），或同时指定数字和单位（例如，直接配置为 `50ms`）。 +- 默认值：`60000000000`，即 1 分钟 From 82be93b8523c8082089692c6df0b6f8dbd6ec9a2 Mon Sep 17 00:00:00 2001 From: Aolin Date: Mon, 9 Dec 2024 18:35:32 +0800 Subject: [PATCH 3/9] reformat ticdc-changefeed-config.md Signed-off-by: Aolin --- ticdc/ticdc-changefeed-config.md | 510 +++++++++++++++---------------- 1 file changed, 246 insertions(+), 264 deletions(-) diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index 6bfa92d47ee8..4f1dfef9413b 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -38,586 +38,568 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl ### `memory-quota` -- 指定该 Changefeed 在 Capture Server 中内存配额的上限。对于超额使用部分，会在运行中被 Go runtime 优先回收。默认值为 `1073741824`，即 1 GB。 -- 默认值：`1073741824` +- 指定该 Changefeed 在 Capture Server 中内存配额的上限。对于超额使用部分，会在运行中被 Go runtime 优先回收。 +- 默认值：`1073741824`，即 1 GB ### `case-sensitive` -- 指定配置文件中涉及的库名、表名是否为大小写敏感 -- 该配置会同时影响 filter 和 sink 相关配置。自 v6.5.6、v7.1.3 和 v7.5.0 起，默认值由 true 改为 false +- 指定配置文件中涉及的库名、表名是否为大小写敏感。自 v6.5.6、v7.1.3 和 v7.5.0 起，默认值由 `true` 改为 `false`。 +- 该配置会同时影响 filter 和 sink 相关配置。 - 默认值：`false` -### `enable-sync-point` +### `enable-sync-point` 从 v6.3.0 版本开始引入 - 是否开启 Syncpoint 功能，从 v6.3.0 开始支持，该功能默认关闭。 - 从 v6.4.0 开始，使用 Syncpoint 功能需要同步任务拥有下游集群的 SYSTEM_VARIABLES_ADMIN 或者 SUPER 权限。 -- 注意：该参数只有当下游为 TiDB 时，才会生效。 +- 该参数只有当下游为 TiDB 时，才会生效。 - 默认值：`false` ### `sync-point-interval` -- Syncpoint 功能对齐上下游 snapshot 的时间间隔 -- 配置格式为 h m s，例如 "1h30m30s" -- 默认值为 10m，最小值为 30s -- 注意：该参数只有当下游为 TiDB 时，才会生效。 +- Syncpoint 功能对齐上下游 snapshot 的时间间隔。 +- 该参数只有当下游为 TiDB 时，才会生效。 +- 配置格式为 `"h m s"`，例如 `"1h30m30s"` - 默认值：`"10m"` - 最小值：`"30s"` ### `sync-point-retention` -- Syncpoint 功能在下游表中保存的数据的时长，超过这个时间的数据会被清理 -- 配置格式为 h m s，例如 "24h30m30s" -- 默认值为 24h -- 注意：该参数只有当下游为 TiDB 时，才会生效 +- Syncpoint 功能在下游表中保存的数据的时长，超过这个时间的数据会被清理。 +- 该参数只有当下游为 TiDB 时，才会生效。 +- 配置格式为 `"h m s"`，例如 `"24h30m30s"` - 默认值：`"24h"` -### `sql-mode` +### `sql-mode` 从 v6.5.6、v7.1.3 和 v7.5.0 版本开始引入 -- 从 v6.5.6、v7.1.3、v7.5.0 起引入，用于设置解析 DDL 时使用的 SQL 模式，多个模式之间用逗号分隔 -- 默认值和 TiDB 的默认 SQL 模式一致 +- 用于设置解析 DDL 时使用的 [SQL 模式](/sql-mode.md)，多个模式之间用逗号分隔。 +- 默认值：`ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION`，与 TiDB 的默认 SQL 模式一致 ### `bdr-mode` -- 默认值为 false，表示不处于 BDR 模式。 -- 如果要使用 TiCDC 搭建 BDR 集群，需要将该参数设置为 true，同时要将 TiDB 集群设置为 BDR 模式。 -- 详情请参考：https://docs.pingcap.com/zh/tidb/stable/ticdc-bidirectional-replication#ticdc-双向复制 -- 默认值：`false` +- 如果要使用 TiCDC 搭建 BDR 集群，需要将该参数设置为 true，同时要将 TiDB 集群设置为 BDR 模式。详情请参考 [TiCDC 双向复制](/ticdc/ticdc-bidirectional-replication.md#ticdc-双向复制) +- 默认值：`false`，表示不处于 BDR 模式 ### `changefeed-error-stuck-duration` -- changefeed 发生内部错误或异常时允许自动重试的时间，默认值为 30 分钟。 +- changefeed 发生内部错误或异常时允许自动重试的时间。 - 若 changefeed 发生内部错误或异常，且持续时间超过该参数设置的时间，changefeed 会进入 Failed 状态。 - 当 changefeed 处于 failed 状态时，需要手动重启 changefeed 才能恢复。 -- 配置格式为 "h m s"，例如 "1h30m30s"。 +- 配置格式为 `"h m s"`，例如 `"1h30m30s"` - 默认值：`"30m"` -### `mounter` - -- mounter 解码 KV 数据的线程数 -- 默认值：`16` +### mounter #### `worker-num` -- mounter 解码 KV 数据的线程数，默认值为 16 +- mounter 解码 KV 数据的线程数。 +- 默认值：`16` -### `filter` +### filter #### `ignore-txn-start-ts` -- 忽略指定 start_ts 的事务 - -#### `rules` - -- 过滤器规则 -- 过滤规则语法：https://docs.pingcap.com/zh/tidb/stable/table-filter#表库过滤语法 - -#### `event-filters` - -##### First Filter Rule +- 忽略指定 start_ts 的事务。 -###### `matcher` +[//]: # (- 示例值：`[1, 2]`) -- matcher 是一个白名单，表示该过滤规则只应用于 test 库中的 worker 表 - -###### `ignore-event` - -- 过滤掉 insert 事件 +#### `rules` -###### `ignore-sql` +- 过滤器规则，过滤规则语法参考[表库过滤语法](/table-filter.md#表库过滤语法)。 -- 过滤掉以 "drop" 开头或者包含 "add column" 的 DDL +[//]: # (- 示例值：`['*.*', '!test.*']`) -###### `ignore-delete-value-expr` +#### filter.event-filters -- 过滤掉包含 name = 'john' 条件的 delete DML +##### `matcher` -###### `ignore-insert-value-expr` +- matcher 是一个白名单，`matcher = ["test.worker"]` 表示该过滤规则只应用于 `test` 库中的 `worker` 表。 -- 过滤掉包含 id >= 100 条件的 insert DML +##### `ignore-event` -###### `ignore-update-old-value-expr` +- `ignore-event = ["insert"]` 表示过滤掉 insert 事件。 +- `ignore-event = ["drop table", "delete"]` 表示忽略 drop table 的 DDL 事件和 delete 类型的 DML 事件。需要注意的是，在更新 TiDB 中聚簇索引的列值时，TiCDC 会将一个 UPDATE 事件拆分成为 DELETE 和 INSERT 事件，TiCDC 无法将该类事件识别为 UPDATE 事件，因此无法正确地进行过滤。 -- 过滤掉旧值 age < 18 的 update DML +##### `ignore-sql` -###### `ignore-update-new-value-expr` +- `ignore-sql = ["^drop", "add column"]` 表示过滤掉以 `drop` 开头或者包含 `add column` 的 DDL。 -- 过滤掉新值 gender = 'male' 的 update DML +##### `ignore-delete-value-expr` -##### Second Filter Rule +- `ignore-delete-value-expr = "name = 'john'"` 表示过滤掉包含 `name = 'john'` 条件的 delete DML。 -###### `matcher` +##### `ignore-insert-value-expr` -- 该事件过滤器只应用于 test.fruit 表 +- `ignore-insert-value-expr = "id >= 100"` 表示过滤掉包含 id >= 100 条件的 insert DML。 -###### `ignore-event` +##### `ignore-update-old-value-expr` -- 忽略 drop table 的 DDL 事件和 delete 类型的 DML 事件 -- 需要注意的是，在更新 TiDB 中聚簇索引的列值时，TiCDC 会将一个 UPDATE 事件拆分成为 DELETE 和 INSERT 事件，TiCDC 无法将该类事件识别为 UPDATE 事件，因此无法正确地进行过滤 +- `ignore-update-old-value-expr = "age < 18"` 表示过滤掉旧值 `age < 18` 的 update DML。 -###### `ignore-sql` +##### `ignore-update-new-value-expr` -- 忽略以 drop table 开头的，或者包含 alter table 的 DDL 语句 +- `ignore-update-new-value-expr = "gender = 'male'"` 表示过滤掉新值 `gender = 'male'` 的 update DML。 -###### `ignore-insert-value-expr` +### scheduler -- 忽略包含 price > 1000 和 origin = 'no where' 条件的 insert DML +#### `enable-table-across-nodes` -### `scheduler` +- 将表以 Region 为单位分配给多个 TiCDC 节点进行同步。 +- 该功能只在 Kafka changefeed 上生效，暂不支持 MySQL changefeed。 +- `enable-table-across-nodes` 开启后，有两种分配模式： -- 将表以 Region 为单位分配给多个 TiCDC 节点进行同步 -- 注意：该功能只在 Kafka changefeed 上生效，暂不支持 MySQL changefeed + 1. 按 Region 的数量分配，即每个 CDC 节点处理 region 的个数基本相等。当某个表 Region 个数大于 `region-threshold` 值时，会将表分配到多个节点处理。`region-threshold` 默认值为 10000。 + 2. 按写入的流量分配，即每个 CDC 节点处理 region 总修改行数基本相当。只有当表中每分钟修改行数超过 `write-key-threshold` 值时，该表才会生效。 -#### `enable-table-across-nodes` + 两种方式配置一种即可生效，当 `region-threshold` 和 `write-key-threshold` 同时配置时，TiCDC 将优先采用按流量分配的模式，即 `write-key-threshold`。 -- 默认为 "false"。设置为 "true" 以打开该功能 +- 默认为 `false`。设置为 `true` 以打开该功能。 - 默认值：`false` #### `region-threshold` -- enable-table-across-nodes 开启后的分配模式之一：按 Region 的数量分配，即每个 CDC 节点处理 region 的个数基本相等。当某个表 Region 个数大于 `region-threshold` 值时，会将表分配到多个节点处理 - 默认值：`10000` #### `write-key-threshold` -- enable-table-across-nodes 开启后的分配模式之一：按写入的流量分配，即每个 CDC 节点处理 region 总修改行数基本相当。只有当表中每分钟修改行数超过 `write-key-threshold` 值时，该表才会生效 -- 默认值：`0` -- 注意： - - `write-key-threshold` 参数默认值为 0，代表默认不会采用流量的分配模式 - - 两种方式配置一种即可生效，当 `region-threshold` 和 `write-key-threshold` 同时配置时，TiCDC 将优先采用按流量分配的模式，即 `write-key-threshold` +- 默认值：`0`，代表默认不会采用流量的分配模式 -### `sink` +### sink -#### MQ 类型 sink 配置 +[//]: # (以下是 MQ 类型 sink 配置) -##### `dispatchers` +#### `dispatchers` -- 对于 MQ 类的 Sink，可以通过 dispatchers 配置 event 分发器 -- 支持 partition 及 topic（从 v6.1 开始支持）两种 event 分发器 -- matcher 的匹配语法和过滤器规则语法相同 -- 注意：该参数只有当下游为消息队列时，才会生效 -- 注意：当下游 MQ 为 Pulsar 时，如果 partition 的路由规则未指定为 'ts', 'index-value', 'table', 'default' 中的任意一个，那么将会使用你设置的字符串作为每一条 Pulsar message 的 key 进行路由 +- 对于 MQ 类的 Sink，可以通过 dispatchers 配置 event 分发器。 +- 支持 partition 及 topic（从 v6.1 开始支持）两种 event 分发器。二者的详细说明见下一节。 +- matcher 的匹配语法和过滤器规则语法相同，matcher 匹配规则的详细说明见下一节。 +- 该参数只有当下游为消息队列时，才会生效。 +- 当下游 MQ 为 Pulsar 时，如果 partition 的路由规则未指定为 `ts`、`index-value`、`table`、`default` 中的任意一个，那么将会使用你设置的字符串作为每一条 Pulsar message 的 key 进行路由。例如，如果你指定的路由规则为 'code' 字符串，那么符合该 matcher 的所有 Pulsar message 都将会以 'code' 作为 key 进行路由。 -##### `column-selectors` +#### `column-selectors` 从 v7.5.0 版本开始引入 -- 从 v7.5.0 开始引入，仅对 Kafka Sink 生效 -- 用于选择部分列进行同步 +- 用于选择部分列进行同步。仅对 Kafka Sink 生效。 -##### `protocol` +#### `protocol` -- 用于指定编码消息时使用的格式协议 -- 当下游类型是 Kafka 时，支持 canal-json、avro、debezium、open-protocol、simple -- 当下游类型是 Pulsar 时，仅支持 canal-json 协议 -- 当下游类型是存储服务时，目前仅支持 canal-json、csv 两种协议 -- 注意：该参数只有当下游为 Kafka、Pulsar，或存储服务时，才会生效 +- 用于指定编码消息时使用的格式协议。 +- 当下游类型是 Kafka 时，支持 canal-json、avro、debezium、open-protocol、simple。 +- 当下游类型是 Pulsar 时，仅支持 canal-json 协议。 +- 当下游类型是存储服务时，目前仅支持 canal-json、csv 两种协议。 +- 注意：该参数只有当下游为 Kafka、Pulsar，或存储服务时，才会生效。 -##### `delete-only-output-handle-key-columns` +[//]: # (- 示例值：`"canal-json"`) -- 用于指定 Delete 事件的输出内容，只对 canal-json 和 open-protocol 协议有效。从 v7.2.0 开始引入 -- 该参数和 `force-replicate` 参数不兼容，如果同时将该参数和 `force-replicate` 设置为 true，创建 changefeed 会报错 -- 默认值：`false` +#### `delete-only-output-handle-key-columns` 从 v7.2.0 版本开始引入 + +- 用于指定 Delete 事件的输出内容，只对 canal-json 和 open-protocol 协议有效。 +- 该参数和 `force-replicate` 参数不兼容，如果同时将该参数和 `force-replicate` 设置为 `true`，创建 changefeed 会报错。 +- Avro 协议不受该参数控制，总是只输出主键列，或唯一索引列的内容。 +- CSV 协议不受该参数控制，总是输出所有列的内容。 +- 默认值：`false`，即输出所有列的内容。 +- 当设置为 `true` 时，只输出主键列，或唯一索引列的内容。 -##### `schema-registry` +#### `schema-registry` -- Schema 注册表的 URL -- 注意：该参数只有当下游为消息队列时，才会生效 +- Schema 注册表的 URL。 +- 该参数只有当下游为消息队列时，才会生效。 +- 示例值：`"http://localhost:80801/subjects/{subject-name}/versions/{version-number}/schema"` -##### `encoder-concurrency` +#### `encoder-concurrency` -- 编码数据时所用编码器的线程数 +- 编码数据时所用编码器的线程数。 +- 该参数只有当下游为消息队列时，才会生效。 - 默认值：`32` -- 注意：该参数只有当下游为消息队列时，才会生效 -##### `enable-kafka-sink-v2` +#### `enable-kafka-sink-v2` -- 是否开启 Kafka Sink V2。Kafka Sink V2 内部使用 kafka-go 实现 +- 是否开启 Kafka Sink V2。Kafka Sink V2 内部使用 kafka-go 实现。 +- 注意：该参数是一个实验特性，并且只有当下游为消息队列时才会生效。 - 默认值：`false` -- 注意：该参数是一个实验特性，并且只有当下游为消息队列时才会生效 -##### `only-output-updated-columns` +#### `only-output-updated-columns` 从 v7.1.0 版本开始引入 -- 是否只向下游同步有内容更新的列。从 v7.1.0 开始支持 +- 是否只向下游同步有内容更新的列。 +- 注意：该参数只有当下游为消息队列，并且使用 Open Protocol 或 Canal-JSON 时，才会生效。 - 默认值：`false` -- 注意：该参数只有当下游为消息队列，并且使用 Open Protocol 或 Canal-JSON 时，才会生效 -#### 存储服务类型 sink 配置 +[//]: # (以下是存储服务类型 sink 配置) -##### `terminator` +#### `terminator` -- 换行符，用来分隔两个数据变更事件 -- 默认值：`\r\n` +- 该配置项仅在同步到存储服务的 sink 中使用，在 MQ 和 MySQL 类 sink 中无需设置。 +- 换行符，用来分隔两个数据变更事件。 +- 默认值：`""`，表示使用 `\r\n` 作为换行符。 -##### `date-separator` +#### `date-separator` -- 文件路径的日期分隔类型 -- 可选值：`none`, `year`, `month`, `day` -- 默认值：`day` -- 注意：该参数只有当下游为存储服务时，才会生效 +- 文件路径的日期分隔类型。详情参考[数据变更记录](/ticdc/ticdc-sink-to-cloud-storage.md#数据变更记录)。 +- 该参数只有当下游为存储服务时，才会生效。 +- 默认值：`day`，即按天分隔 +- 可选值：`none`、`year`、`month`、`day` -##### `enable-partition-separator` +#### `enable-partition-separator` -- 是否使用 partition 作为分隔字符串 -- 默认值：`true` -- 注意：该参数只有当下游为存储服务时，才会生效 +- 是否使用 partition 作为分隔字符串。 +- 该参数只有当下游为存储服务时，才会生效 +- 默认值：`true`，即一张表中各个 partition 的数据会分不同的目录来存储 +- 建议保持该配置项为 `true` 以避免下游分区表可能丢数据的问题 [#8581](https://github.com/pingcap/tiflow/issues/8581)。使用示例详见[数据变更记录](/ticdc/ticdc-sink-to-cloud-storage.md#数据变更记录)。 -##### `debezium-disable-schema` +#### `debezium-disable-schema` -- 是否关闭 schema 信息的输出 -- 默认值：`false` -- 注意：该参数只有当 sink 类型为 MQ 且输出协议为 Debezium 时才生效 +- 是否关闭 schema 信息的输出。 +- 默认值：`false`，即输出 schema 信息 +- 该参数只有当 sink 类型为 MQ 且输出协议为 Debezium 时才生效。 -#### `csv` +#### sink.csv 从 v6.5.0 版本开始引入 + +从 v6.5.0 开始，TiCDC 支持以 CSV 格式将数据变更记录保存至存储服务中，在 MQ 和 MySQL 类 sink 中无需设置。 ##### `delimiter` -- 字段之间的分隔符 -- 必须为 ASCII 字符 +- 字段之间的分隔符。必须为 ASCII 字符。 - 默认值：`,` ##### `quote` -- 用于包裹字段的引号字符 -- 空值代表不使用引号字符 +- 用于包裹字段的引号字符。空值代表不使用引号字符。 - 默认值：`"` ##### `null` -- CSV 中列为 NULL 时将以什么字符来表示 +- CSV 中列为 NULL 时将以什么字符来表示。 - 默认值：`\N` ##### `include-commit-ts` -- 是否在 CSV 行中包含 commit-ts +- 是否在 CSV 行中包含 commit-ts。 - 默认值：`false` ##### `binary-encoding-method` -- 二进制类型数据的编码方式 -- 可选值：`base64`, `hex` +- 二进制类型数据的编码方式。 - 默认值：`base64` +- 可选值：`base64`、`hex` ##### `output-handle-key` -- 是否输出 handle 列信息 +- 是否输出 handle 列信息。该配置项仅用于内部实现，不推荐设置该配置项。 - 默认值：`false` -- 该配置项仅用于内部实现，不推荐设置该配置项 ##### `output-old-value` -- 是否输出行数据更改前的值 +- 是否输出行数据更改前的值。 +- 开启后，Update 事件会输出两行数据：第一行为 Delete 事件，输出更改前的数据；第二行为 Insert 事件，输出更改后的数据。 +- 开启后，即当该参数设为 true 时，会在变更数据列前增加 "is-update" 列。该列用来标识当前行的变更数据是来自 Update 事件，还是原始的 Insert/Delete 事件。如果当前行的变更数据来自 Update 事件，则 "is-update" 列为 true，否则为 false。 - 默认值：`false` -#### Simple Protocol 配置 +从 v8.0.0 开始，TiCDC 新增了 Simple Protocol 消息编码协议，以下为该协议的配置参数。关于该协议的详情，请参考 [TiCDC Simple Protocol](/ticdc/ticdc-simple-protocol.md)。 -##### `send-bootstrap-interval-in-sec` +以下为 Simple Protocol 参数，用来控制 bootstrap 消息的发送行为。 -- 用来控制发送 bootstrap 消息的时间间隔，单位为秒 -- 默认值：`120` +#### `send-bootstrap-interval-in-sec` -##### `send-bootstrap-in-msg-count` +- 控制发送 bootstrap 消息的时间间隔。 +- 默认值：`120`，即每张表每隔 120 秒发送一次 bootstrap 消息 +- 单位：秒 -- 用来控制发送 bootstrap 的消息间隔，单位为消息数 -- 默认值：`10000` +#### `send-bootstrap-in-msg-count` -##### `send-bootstrap-to-all-partition` +- 控制发送 bootstrap 的消息间隔，单位为消息数。 +- 默认值：`10000`，即每张表每发送 10000 条行变更消息就发送一次 bootstrap 消息 +- 如果要关闭 bootstrap 消息的发送，则将 `send-bootstrap-interval-in-sec` 和 `send-bootstrap-in-msg-count` 均设置为 0。 -- 用来控制是否发送 bootstrap 消息到所有的 partition -- 默认值：`true` +#### `send-bootstrap-to-all-partition` + +- 控制是否发送 bootstrap 消息到所有的 partition。 +- 如果设置为 `false`，则只发送 bootstrap 消息到对应表 topic 的第一个 partition。 + +[//]: # (- 示例值 `true`) -#### `kafka-config.codec-config` +#### sink.kafka-config.codec-config` ##### `encoding-format` -- 用来控制 simple protocol 的消息的编码格式 -- 可选值：`json`, `avro` +- 用来控制 simple protocol 的消息的编码格式，目前支持 "json" 和 "avro" 两种格式。 - 默认值：`json` +- 可选值：`json`、`avro` -#### `open` +#### sink.open ##### `output-old-value` -- 是否输出行数据更改前的值 +- 是否输出行数据更改前的值。关闭后，Update 事件不会输出 "p" 字段的数据。 - 默认值：`true` -- 关闭后，Update 事件不会输出 "p" 字段的数据 -#### `debezium` +#### sink.debezium ##### `output-old-value` -- 是否输出行数据更改前的值 +- 是否输出行数据更改前的值。关闭后，Update 事件不会输出 "before" 字段的数据。 - 默认值：`true` -- 关闭后，Update 事件不会输出 "before" 字段的数据 -### `consistent` +### consistent -- consistent 中的字段用于配置 Changefeed 的数据一致性 -- 注意：一致性相关参数只有当下游为数据库并且开启 redo log 功能时，才会生效 +consistent 中的字段用于配置 Changefeed 的数据一致性。详细信息请参考[灾难场景的最终一致性复制](/ticdc/ticdc-sink-to-mysql.md#灾难场景的最终一致性复制)。 + +注意：一致性相关参数只有当下游为数据库并且开启 redo log 功能时，才会生效。 #### `level` -- 数据一致性级别 -- 默认值：`none` -- 可选值：`none`, `eventual` -- 设置为 "none" 时将关闭 redo log +- 数据一致性级别。设置为 `"none"` 时将关闭 redo log。 +- 默认值：`"none"` +- 可选值：`"none"`、`"eventual"` #### `max-log-size` -- redo log 的最大日志大小，单位为 MB +- redo log 的最大日志大小。 - 默认值：`64` +- 单位：MB #### `flush-interval` -- 两次 redo log 刷新的时间间隔，单位为毫秒 +- 两次 redo log 刷新的时间间隔。 - 默认值：`2000` +- 单位：毫秒 #### `storage` -- redo log 使用存储服务的 URI -- 默认值：`` +- redo log 使用存储服务的 URI。 +- 默认值：`""` #### `use-file-backend` -- 是否将 redo log 存储到本地文件中 +- 是否将 redo log 存储到本地文件中。 - 默认值：`false` #### `encoding-worker-num` -- 控制 redo 模块中编解码 worker 的数量 +- 控制 redo 模块中编解码 worker 的数量。 - 默认值：`16` #### `flush-worker-num` -- 控制 redo 模块中上传文件 worker 的数量 +- 控制 redo 模块中上传文件 worker 的数量。 - 默认值：`8` #### `compression` -- redo log 文件的压缩行为 -- 可选值：`""`, `lz4` -- 默认值：`""`（表示不进行压缩） +- redo log 文件的压缩行为。 +- 默认值：`""`，表示不进行压缩 +- 可选值：`""`、`lz4` #### `flush-concurrency` -- redo log 上传单个文件的并发数 -- 默认值：`1`（表示禁用并发） +- redo log 上传单个文件的并发数。 +- 默认值：`1`，表示禁用并发 -### `integrity` +### integrity #### `integrity-check-level` -- 是否开启单行数据的 Checksum 校验功能 -- 默认值：`none` -- 可选值：`none`, `correctness` +- 是否开启单行数据的 Checksum 校验功能。 +- 默认值：`"none"`，即不开启 +- 可选值：`"none"`、`"correctness"` #### `corruption-handle-level` -- 当单行数据的 Checksum 校验失败时，Changefeed 打印错误行数据相关日志的级别 -- 默认值：`warn` -- 可选值：`warn`, `error` +- 当单行数据的 Checksum 校验失败时，Changefeed 打印错误行数据相关日志的级别。 +- 默认值：`"warn"` +- 可选值：`"warn"`、`"error"` -### `sink.kafka-config` +### sink.kafka-config -- 以下参数仅在下游为 Kafka 时生效 +以下参数仅在下游为 Kafka 时生效。 #### `sasl-mechanism` -- Kafka SASL 认证机制 -- 默认值：``（表示不使用 SASL 认证） -- 可选值：`OAUTHBEARER` +- Kafka SASL 认证机制。 +- 默认值：`""`，表示不使用 SASL 认证 + +[//]: # (- 示例值：`OAUTHBEARER`) #### `sasl-oauth-client-id` -- Kafka SASL OAUTHBEARER 认证机制中的 client-id -- 默认值：`` -- 在使用 OAUTHBEARER 认证机制时，该参数必填 +- Kafka SASL OAUTHBEARER 认证机制中的 client-id。在使用该认证机制时，该参数必填。 +- 默认值：`""` #### `sasl-oauth-client-secret` -- Kafka SASL OAUTHBEARER 认证机制中的 client-secret -- 默认值：`` -- 需要 Base64 编码 -- 在使用 OAUTHBEARER 认证机制时，该参数必填 +- Kafka SASL OAUTHBEARER 认证机制中的 client-secret。需要 Base64 编码。在使用该认证机制时，该参数必填。 +- 默认值：`""` #### `sasl-oauth-token-url` -- Kafka SASL OAUTHBEARER 认证机制中的 token-url，用于获取 token -- 默认值：`` -- 在使用 OAUTHBEARER 认证机制时，该参数必填 +- Kafka SASL OAUTHBEARER 认证机制中的 token-url 用于获取 token。在使用该认证机制时，该参数必填。 +- 默认值：`""` #### `sasl-oauth-scopes` -- Kafka SASL OAUTHBEARER 认证机制中的 scopes -- 默认值：`` -- 在使用 OAUTHBEARER 认证机制时，该参数可选填 +- Kafka SASL OAUTHBEARER 认证机制中的 scopes。在使用该认证机制时，该参数可选填。 +- 默认值：`""` #### `sasl-oauth-grant-type` -- Kafka SASL OAUTHBEARER 认证机制中的 grant-type -- 默认值：`client_credentials` -- 在使用 OAUTHBEARER 认证机制时，该参数可选填 +- Kafka SASL OAUTHBEARER 认证机制中的 grant-type。默认值为 "client_credentials"。在使用该认证机制时，该参数可选填。 +- 默认值：`"client_credentials"` #### `sasl-oauth-audience` -- Kafka SASL OAUTHBEARER 认证机制中的 audience -- 默认值：`` -- 在使用 OAUTHBEARER 认证机制时，该参数可选填 +- Kafka SASL OAUTHBEARER 认证机制中的 audience。在使用该认证机制时，该参数可选填。 +- 默认值：`""` + +[//]: # (- 示例值：`"kafka"`) #### `output-raw-change-event` -- 控制是否输出原始的数据变更事件 +- 控制是否输出原始的数据变更事件。更多信息，请参考[控制是否拆分主键或唯一键 `UPDATE` 事件](/ticdc/ticdc-split-update-behavior.md#控制是否拆分主键或唯一键-update-事件)。 - 默认值：`false` -### `sink.kafka-config.glue-schema-registry-config` - -- 以下配置仅在选用 avro 作为协议，并且使用 AWS Glue Schema Registry 时需要配置 +### sink.kafka-config.glue-schema-registry-config -#### `region` +以下配置仅在选用 avro 作为协议，并且使用 AWS Glue Schema Registry 时需要配置。 -- AWS 区域名称 - -#### `registry-name` - -- Schema Registry 的名称 - -#### `access-key` - -- AWS 访问密钥 ID - -#### `secret-access-key` - -- AWS 密钥访问密钥 - -#### `token` +```toml +region="us-west-1" +registry-name="ticdc-test" +access-key="xxxx" +secret-access-key="xxxx" +token="xxxx" +``` -- AWS 会话令牌 +详细信息请参考 [TiCDC 集成 AWS Glue Schema Registry](/ticdc/ticdc-sink-to-kafka.md#ticdc-集成-aws-glue-schema-registry)。 -### `sink.pulsar-config` +### sink.pulsar-config -- 以下参数仅在下游为 Pulsar 时生效 +以下配置项仅在下游为 Pulsar 时生效。 #### `authentication-token` -- 使用 token 进行 Pulsar 服务端的认证，此处为 token 的值 +- 使用 token 进行 Pulsar 服务端的认证，此处为 token 的值。 -#### `token-from-file` +#### `token-from-file=` -- 指定使用 token 进行 Pulsar 服务端的认证，此处为 token 所在文件的路径 +- 指定使用 token 进行 Pulsar 服务端的认证，此处为 token 所在文件的路径。 #### `basic-user-name` -- Pulsar 使用 basic 账号密码验证身份 +- Pulsar 使用 basic 账号密码验证身份。 #### `basic-password` -- Pulsar 使用 basic 账号密码验证身份，此处为密码 +- Pulsar 使用 basic 账号密码验证身份，此处为密码。 #### `auth-tls-certificate-path` -- Pulsar TLS 加密认证证书路径 +- Pulsar TLS 加密认证证书路径。 #### `auth-tls-private-key-path` -- Pulsar TLS 加密认证私钥路径 +- Pulsar TLS 加密认证私钥路径。 #### `tls-trust-certs-file-path` -- Pulsar TLS 加密可信证书文件路径 +- Pulsar TLS 加密可信证书文件路径。 #### `oauth2.oauth2-issuer-url` - Pulsar oauth2 issuer-url +- 详细配置请参考 [Pulsar 官方介绍](https://pulsar.apache.org/docs/2.10.x/client-libraries-go/#tls-encryption-and-authentication)。 #### `oauth2.oauth2-audience` - Pulsar oauth2 audience +- 详细配置请参考 [Pulsar 官方介绍](https://pulsar.apache.org/docs/2.10.x/client-libraries-go/#tls-encryption-and-authentication)。 #### `oauth2.oauth2-private-key` - Pulsar oauth2 private-key +- 详细配置请参考 [Pulsar 官方介绍](https://pulsar.apache.org/docs/2.10.x/client-libraries-go/#tls-encryption-and-authentication)。 #### `oauth2.oauth2-client-id` - Pulsar oauth2 client-id +- 详细配置请参考 [Pulsar 官方介绍](https://pulsar.apache.org/docs/2.10.x/client-libraries-go/#tls-encryption-and-authentication)。 #### `oauth2.oauth2-scope` - Pulsar oauth2 oauth2-scope +- 详细配置请参考 [Pulsar 官方介绍](https://pulsar.apache.org/docs/2.10.x/client-libraries-go/#tls-encryption-and-authentication)。 #### `pulsar-producer-cache-size` -- TiCDC 中缓存 Pulsar Producer 的个数 -- 默认值：`10240` +- TiCDC 中缓存 Pulsar Producer 的个数，默认上限为 `10240` 个。每个 Pulsar Producer 对应一个 topic，如果你需要同步的 topic 数量大于默认值，则需要调大该数量。 #### `compression-type` -- Pulsar 数据压缩方式 -- 默认值：``（表示不压缩） -- 可选值：`lz4`, `zlib`, `zstd` +- Pulsar 数据压缩方式。 +- 默认值：`""`，表示不压缩 +- 可选值：`"lz4"`、`"zlib"`、`"zstd"` #### `connection-timeout` -- Pulsar 客户端与服务端建立 TCP 连接的超时时间 +- Pulsar 客户端与服务端建立 TCP 连接的超时时间。 - 默认值：`5`（秒） #### `operation-timeout` -- Pulsar 客户端发起创建、订阅等操作的超时时间 +- Pulsar 客户端发起创建、订阅等操作的超时时间。 - 默认值：`30`（秒） #### `batching-max-messages` -- Pulsar Producer 发送消息时的单个 batch 内的消息数量上限 +- Pulsar Producer 发送消息时的单个 batch 内的消息数量上限。 - 默认值：`1000` #### `batching-max-publish-delay` -- Pulsar Producer 消息攒批的时间间隔 +- Pulsar Producer 消息攒批的时间间隔。 - 默认值：`10`（毫秒） #### `send-timeout` -- Pulsar Producer 发送消息的超时时间 +- Pulsar Producer 发送消息的超时时间。 - 默认值：`30`（秒） #### `output-raw-change-event` -- 控制是否输出原始的数据变更事件 +- 控制是否输出原始的数据变更事件。更多信息，请参考[控制是否拆分主键或唯一键 `UPDATE` 事件](/ticdc/ticdc-split-update-behavior.md#控制是否拆分主键或唯一键-update-事件)。 - 默认值：`false` -### `sink.cloud-storage-config` +### sink.cloud-storage-config #### `worker-count` -- 向下游存储服务保存数据变更记录的并发度 +- 向下游存储服务保存数据变更记录的并发度。 - 默认值：`16` #### `flush-interval` -- 向下游存储服务保存数据变更记录的间隔 -- 默认值：`2s` +- 向下游存储服务保存数据变更记录的间隔。 +- 默认值：`"2s"` #### `file-size` -- 单个数据变更文件的字节数超过 `file-size` 时将其保存至存储服务中 -- 默认值：`67108864`（64 MiB） +- 单个数据变更文件的字节数超过 `file-size` 时将其保存至存储服务中。 +- 默认值：`67108864`，即 64 MiB #### `file-expiration-days` -- 文件保留的时长，仅在 date-separator 配置为 day 时生效 -- 默认值：`0`（表示禁用文件清理） -- 示例：假设 `file-expiration-days = 1` 且 `file-cleanup-cron-spec = "0 0 0 * * *"`，TiCDC 将在每天 00:00:00 时刻清理已保存超过 24 小时的文件。例如，2023/12/02 00:00:00 将清理 2023/12/01 之前（注意：不包括 2023/12/01）的文件 +- 文件保留的时长，仅在 `date-separator` 配置为 `day` 时生效。 +- 默认值：`0`，表示禁用文件清理 +- 假设 `file-expiration-days = 1` 且 `file-cleanup-cron-spec = "0 0 0 * * *"`，TiCDC 将在每天 00:00:00 时刻清理已保存超过 24 小时的文件。例如，2023/12/02 00:00:00 将清理 2023/12/01 之前（注意：不包括 2023/12/01）的文件。 #### `file-cleanup-cron-spec` -- 定时清理任务的运行周期，与 crontab 配置兼容 -- 格式：` ` -- 默认值：`0 0 2 * * *`（表示每天凌晨两点执行清理任务） +- 定时清理任务的运行周期，与 crontab 配置兼容。 +- 格式为 ` ` +- 默认值：`"0 0 2 * * *"`，表示每天凌晨两点执行清理任务 #### `flush-concurrency` -- 上传单个文件的并发数 -- 默认值：`1`（表示禁用并发） +- 上传单个文件的并发数。 +- 默认值：`1`，表示禁用并发 #### `output-raw-change-event` -- 控制是否输出原始的数据变更事件 +- 控制是否输出原始的数据变更事件。更多信息，请参考[控制是否拆分主键或唯一键 `UPDATE` 事件](/ticdc/ticdc-split-update-behavior.md#控制是否拆分主键或唯一键-update-事件)。 - 默认值：`false` \ No newline at end of file From 77fe5d2d3bd2773c8f7168583ec89bae07ddce80 Mon Sep 17 00:00:00 2001 From: Aolin Date: Mon, 9 Dec 2024 18:49:38 +0800 Subject: [PATCH 4/9] fix format --- ticdc/ticdc-changefeed-config.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index 4f1dfef9413b..13abe64b212a 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -315,7 +315,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl [//]: # (- 示例值 `true`) -#### sink.kafka-config.codec-config` +#### sink.kafka-config.codec-config ##### `encoding-format` @@ -476,7 +476,7 @@ token="xxxx" - 使用 token 进行 Pulsar 服务端的认证，此处为 token 的值。 -#### `token-from-file=` +#### `token-from-file` - 指定使用 token 进行 Pulsar 服务端的认证，此处为 token 所在文件的路径。 From 4cfc883be8f93cd44d42dbe04e140754868f9e11 Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 10 Dec 2024 17:39:53 +0800 Subject: [PATCH 5/9] fix format Co-authored-by: xixirangrang --- ticdc/ticdc-changefeed-config.md | 40 ++++++++++++++++---------------- ticdc/ticdc-server-config.md | 10 ++++---- 2 files changed, 25 insertions(+), 25 deletions(-) diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index 13abe64b212a..e935a729d11e 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -39,7 +39,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl ### `memory-quota` - 指定该 Changefeed 在 Capture Server 中内存配额的上限。对于超额使用部分，会在运行中被 Go runtime 优先回收。 -- 默认值：`1073741824`，即 1 GB +- 默认值：`1073741824`，即 1 GiB ### `case-sensitive` @@ -76,14 +76,14 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl ### `bdr-mode` -- 如果要使用 TiCDC 搭建 BDR 集群，需要将该参数设置为 true，同时要将 TiDB 集群设置为 BDR 模式。详情请参考 [TiCDC 双向复制](/ticdc/ticdc-bidirectional-replication.md#ticdc-双向复制) +- 如果要使用 TiCDC 搭建 BDR (Bidirectional replication) 集群，需要将该参数设置为 `true`，同时要将 TiDB 集群设置为 BDR 模式。详情请参考 [TiCDC 双向复制](/ticdc/ticdc-bidirectional-replication.md#ticdc-双向复制) - 默认值：`false`，表示不处于 BDR 模式 ### `changefeed-error-stuck-duration` -- changefeed 发生内部错误或异常时允许自动重试的时间。 -- 若 changefeed 发生内部错误或异常，且持续时间超过该参数设置的时间，changefeed 会进入 Failed 状态。 -- 当 changefeed 处于 failed 状态时，需要手动重启 changefeed 才能恢复。 +- Changefeed 发生内部错误或异常时允许自动重试的时间。 +- 若 Changefeed 发生内部错误或异常，且持续时间超过该参数设置的时间，Changefeed 会进入 Failed 状态。 +- 当 Changefeed 处于 Failed 状态时，需要手动重启 Changefeed 才能恢复。 - 配置格式为 `"h m s"`，例如 `"1h30m30s"` - 默认值：`"30m"` @@ -116,28 +116,28 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl ##### `ignore-event` -- `ignore-event = ["insert"]` 表示过滤掉 insert 事件。 -- `ignore-event = ["drop table", "delete"]` 表示忽略 drop table 的 DDL 事件和 delete 类型的 DML 事件。需要注意的是，在更新 TiDB 中聚簇索引的列值时，TiCDC 会将一个 UPDATE 事件拆分成为 DELETE 和 INSERT 事件，TiCDC 无法将该类事件识别为 UPDATE 事件，因此无法正确地进行过滤。 +- `ignore-event = ["insert"]` 表示过滤掉 `INSERT` 事件。 +- `ignore-event = ["drop table", "delete"]` 表示忽略 `DROP TABLE` 的 DDL 事件和 `DELETE` 类型的 DML 事件。需要注意的是，在更新 TiDB 中聚簇索引的列值时，TiCDC 会将一个 `UPDATE` 事件拆分成为 `DELETE` 和 `INSERT` 事件，TiCDC 无法将该类事件识别为 `UPDATE` 事件，因此无法正确地进行过滤。 ##### `ignore-sql` -- `ignore-sql = ["^drop", "add column"]` 表示过滤掉以 `drop` 开头或者包含 `add column` 的 DDL。 +- `ignore-sql = ["^drop", "add column"]` 表示过滤掉以 `DROP` 开头或者包含 `ADD COLUMN` 的 DDL。 ##### `ignore-delete-value-expr` -- `ignore-delete-value-expr = "name = 'john'"` 表示过滤掉包含 `name = 'john'` 条件的 delete DML。 +- `ignore-delete-value-expr = "name = 'john'"` 表示过滤掉包含 `name = 'john'` 条件的 `DELETE` DML。 ##### `ignore-insert-value-expr` -- `ignore-insert-value-expr = "id >= 100"` 表示过滤掉包含 id >= 100 条件的 insert DML。 +- `ignore-insert-value-expr = "id >= 100"` 表示过滤掉包含 id >= 100 条件的 `INSERT` DML。 ##### `ignore-update-old-value-expr` -- `ignore-update-old-value-expr = "age < 18"` 表示过滤掉旧值 `age < 18` 的 update DML。 +- `ignore-update-old-value-expr = "age < 18"` 表示过滤掉旧值 `age < 18` 的 `UPDATE` DML。 ##### `ignore-update-new-value-expr` -- `ignore-update-new-value-expr = "gender = 'male'"` 表示过滤掉新值 `gender = 'male'` 的 update DML。 +- `ignore-update-new-value-expr = "gender = 'male'"` 表示过滤掉新值 `gender = 'male'` 的 `UPDATE` DML。 ### scheduler @@ -147,8 +147,8 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl - 该功能只在 Kafka changefeed 上生效，暂不支持 MySQL changefeed。 - `enable-table-across-nodes` 开启后，有两种分配模式： - 1. 按 Region 的数量分配，即每个 CDC 节点处理 region 的个数基本相等。当某个表 Region 个数大于 `region-threshold` 值时，会将表分配到多个节点处理。`region-threshold` 默认值为 10000。 - 2. 按写入的流量分配，即每个 CDC 节点处理 region 总修改行数基本相当。只有当表中每分钟修改行数超过 `write-key-threshold` 值时，该表才会生效。 + 1. 按 Region 的数量分配，即每个 TiCDC 节点处理 Region 的个数基本相等。当某个表 Region 个数大于 `region-threshold` 值时，会将表分配到多个节点处理。`region-threshold` 默认值为 `10000`。 + 2. 按写入的流量分配，即每个 TiCDC 节点处理 Region 总修改行数基本相当。只有当表中每分钟修改行数超过 `write-key-threshold` 值时，该表才会生效。 两种方式配置一种即可生效，当 `region-threshold` 和 `write-key-threshold` 同时配置时，TiCDC 将优先采用按流量分配的模式，即 `write-key-threshold`。 @@ -173,7 +173,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl - 支持 partition 及 topic（从 v6.1 开始支持）两种 event 分发器。二者的详细说明见下一节。 - matcher 的匹配语法和过滤器规则语法相同，matcher 匹配规则的详细说明见下一节。 - 该参数只有当下游为消息队列时，才会生效。 -- 当下游 MQ 为 Pulsar 时，如果 partition 的路由规则未指定为 `ts`、`index-value`、`table`、`default` 中的任意一个，那么将会使用你设置的字符串作为每一条 Pulsar message 的 key 进行路由。例如，如果你指定的路由规则为 'code' 字符串，那么符合该 matcher 的所有 Pulsar message 都将会以 'code' 作为 key 进行路由。 +- 当下游 MQ 为 Pulsar 时，如果 partition 的路由规则未指定为 `ts`、`index-value`、`table`、`default` 中的任意一个，那么将会使用你设置的字符串作为每一条 Pulsar message 的 key 进行路由。例如，如果你指定的路由规则为 `'code'` 字符串，那么符合该 matcher 的所有 Pulsar message 都将会以 `'code'` 作为 key 进行路由。 #### `column-selectors` 从 v7.5.0 版本开始引入 @@ -306,7 +306,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl - 控制发送 bootstrap 的消息间隔，单位为消息数。 - 默认值：`10000`，即每张表每发送 10000 条行变更消息就发送一次 bootstrap 消息 -- 如果要关闭 bootstrap 消息的发送，则将 `send-bootstrap-interval-in-sec` 和 `send-bootstrap-in-msg-count` 均设置为 0。 +- 如果要关闭 bootstrap 消息的发送，则将 `send-bootstrap-interval-in-sec` 和 `send-bootstrap-in-msg-count` 均设置为 `0`。 #### `send-bootstrap-to-all-partition` @@ -319,7 +319,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl ##### `encoding-format` -- 用来控制 simple protocol 的消息的编码格式，目前支持 "json" 和 "avro" 两种格式。 +- 用来控制 simple protocol 的消息的编码格式，目前支持 `json` 和 `avro` 两种格式。 - 默认值：`json` - 可选值：`json`、`avro` @@ -327,14 +327,14 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl ##### `output-old-value` -- 是否输出行数据更改前的值。关闭后，Update 事件不会输出 "p" 字段的数据。 +- 是否输出行数据更改前的值。关闭后，UPDATE 事件不会输出 "p" 字段的数据。 - 默认值：`true` #### sink.debezium ##### `output-old-value` -- 是否输出行数据更改前的值。关闭后，Update 事件不会输出 "before" 字段的数据。 +- 是否输出行数据更改前的值。关闭后，UPDATE 事件不会输出 "before" 字段的数据。 - 默认值：`true` ### consistent @@ -439,7 +439,7 @@ consistent 中的字段用于配置 Changefeed 的数据一致性。详细信息 #### `sasl-oauth-grant-type` -- Kafka SASL OAUTHBEARER 认证机制中的 grant-type。默认值为 "client_credentials"。在使用该认证机制时，该参数可选填。 +- Kafka SASL OAUTHBEARER 认证机制中的 grant-type。默认值为 `"client_credentials"`。在使用该认证机制时，该参数可选填。 - 默认值：`"client_credentials"` #### `sasl-oauth-audience` diff --git a/ticdc/ticdc-server-config.md b/ticdc/ticdc-server-config.md index f7d1a3229bfc..55e5f632a25f 100644 --- a/ticdc/ticdc-server-config.md +++ b/ticdc/ticdc-server-config.md @@ -130,19 +130,19 @@ summary: 了解 TiCDC 详细的命令行参数和配置文件定义。 ##### `max-size` -- 单个 log 文件的最大文件大小。可选。 +- 单个日志文件的最大文件大小。可选。 - 默认值：`300` - 单位：MiB ##### `max-days` -- log 文件最长保留天数。可选。 +- 日志文件最长保留天数。可选。 - 默认值：`0`，代表永不删除 ##### `max-backups` -- log 文件的保留个数。可选。 -- 默认值：`0`，代表保留所有 log 文件 +- 日志文件的保留个数。可选。 +- 默认值：`0`，代表保留所有日志文件 ### sorter @@ -154,7 +154,7 @@ summary: 了解 TiCDC 详细的命令行参数和配置文件定义。 #### `sorter-dir` -- Sorter 文件相对于 data-dir 的目录。可选。 +- Sorter 文件相对于 `data-dir` 的目录。可选。 - 默认值：`"/tmp/sorter"` ### kv-client From f83431221dbc0912855427777ce962b3830eccc1 Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 11 Dec 2024 16:52:33 +0800 Subject: [PATCH 6/9] fix format Co-authored-by: xixirangrang --- ticdc/ticdc-changefeed-config.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index e935a729d11e..532a4246c591 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -288,8 +288,8 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl ##### `output-old-value` - 是否输出行数据更改前的值。 -- 开启后，Update 事件会输出两行数据：第一行为 Delete 事件，输出更改前的数据；第二行为 Insert 事件，输出更改后的数据。 -- 开启后，即当该参数设为 true 时，会在变更数据列前增加 "is-update" 列。该列用来标识当前行的变更数据是来自 Update 事件，还是原始的 Insert/Delete 事件。如果当前行的变更数据来自 Update 事件，则 "is-update" 列为 true，否则为 false。 +- 开启后，UPDATE 事件会输出两行数据：第一行为 DELETE 事件，输出更改前的数据；第二行为 INSERT 事件，输出更改后的数据。 +- 开启后，即当该参数设为 `true` 时，会在变更数据列前增加 `"is-update"` 列。该列用来标识当前行的变更数据是来自 Update 事件，还是原始的 INSERT/DELETE 事件。如果当前行的变更数据来自 UPDATE 事件，则 `"is-update"` 列为 `true`，否则为 `false`。 - 默认值：`false` 从 v8.0.0 开始，TiCDC 新增了 Simple Protocol 消息编码协议，以下为该协议的配置参数。关于该协议的详情，请参考 [TiCDC Simple Protocol](/ticdc/ticdc-simple-protocol.md)。 From 68b6f7a3ca91192ecb2731e516c648c6f6dc8fc1 Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 11 Dec 2024 16:56:36 +0800 Subject: [PATCH 7/9] update unit of max-log-size Co-authored-by: xixirangrang --- ticdc/ticdc-changefeed-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index 532a4246c591..26606cfe78d7 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -353,7 +353,7 @@ consistent 中的字段用于配置 Changefeed 的数据一致性。详细信息 - redo log 的最大日志大小。 - 默认值：`64` -- 单位：MB +- 单位：MiB #### `flush-interval` From af2164db108ff0e0a6a3f3e2e608d104845bff6f Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 11 Dec 2024 17:37:32 +0800 Subject: [PATCH 8/9] fix format Signed-off-by: Aolin --- ticdc/ticdc-server-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ticdc/ticdc-server-config.md b/ticdc/ticdc-server-config.md index 55e5f632a25f..5731ea4dfd60 100644 --- a/ticdc/ticdc-server-config.md +++ b/ticdc/ticdc-server-config.md @@ -67,7 +67,7 @@ summary: 了解 TiCDC 详细的命令行参数和配置文件定义。 ### `gc-tuner-memory-threshold` - 控制 GOGC Tuner 自动调节的最大内存阈值。设置较小的阈值会提高 GC 频率；设置较大的阈值会降低 GC 频率并使 TiCDC 进程占用更多的内存资源；超过阈值后 GOGC Tuner 会停止工作。 -- 默认值：`0`，表示禁用 GOGC Tuner。 +- 默认值：`0`，表示禁用 GOGC Tuner - 单位：Byte ### security From d6eb9fdcfd33077e070a946febcbbf679aea04e7 Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 11 Dec 2024 19:17:10 +0800 Subject: [PATCH 9/9] make ci happy Signed-off-by: Aolin --- ticdc/ticdc-changefeed-config.md | 35 ++++++++++++++++---------------- ticdc/ticdc-server-config.md | 4 ++-- 2 files changed, 20 insertions(+), 19 deletions(-) diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index 26606cfe78d7..5bb5dcb86e53 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -72,7 +72,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl ### `sql-mode` 从 v6.5.6、v7.1.3 和 v7.5.0 版本开始引入 - 用于设置解析 DDL 时使用的 [SQL 模式](/sql-mode.md)，多个模式之间用逗号分隔。 -- 默认值：`ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION`，与 TiDB 的默认 SQL 模式一致 +- 默认值：`"ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION"`，与 TiDB 的默认 SQL 模式一致 ### `bdr-mode` @@ -100,13 +100,13 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl - 忽略指定 start_ts 的事务。 -[//]: # (- 示例值：`[1, 2]`) + #### `rules` - 过滤器规则，过滤规则语法参考[表库过滤语法](/table-filter.md#表库过滤语法)。 -[//]: # (- 示例值：`['*.*', '!test.*']`) + #### filter.event-filters @@ -129,7 +129,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl ##### `ignore-insert-value-expr` -- `ignore-insert-value-expr = "id >= 100"` 表示过滤掉包含 id >= 100 条件的 `INSERT` DML。 +- `ignore-insert-value-expr = "id >= 100"` 表示过滤掉包含 `id >= 100` 条件的 `INSERT` DML。 ##### `ignore-update-old-value-expr` @@ -165,7 +165,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl ### sink -[//]: # (以下是 MQ 类型 sink 配置) + #### `dispatchers` @@ -187,7 +187,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl - 当下游类型是存储服务时，目前仅支持 canal-json、csv 两种协议。 - 注意：该参数只有当下游为 Kafka、Pulsar，或存储服务时，才会生效。 -[//]: # (- 示例值：`"canal-json"`) + #### `delete-only-output-handle-key-columns` 从 v7.2.0 版本开始引入 @@ -202,7 +202,8 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl - Schema 注册表的 URL。 - 该参数只有当下游为消息队列时，才会生效。 -- 示例值：`"http://localhost:80801/subjects/{subject-name}/versions/{version-number}/schema"` + + #### `encoder-concurrency` @@ -213,7 +214,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl #### `enable-kafka-sink-v2` - 是否开启 Kafka Sink V2。Kafka Sink V2 内部使用 kafka-go 实现。 -- 注意：该参数是一个实验特性，并且只有当下游为消息队列时才会生效。 +- 该参数是一个实验特性，并且只有当下游为消息队列时才会生效。 - 默认值：`false` #### `only-output-updated-columns` 从 v7.1.0 版本开始引入 @@ -288,8 +289,8 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl ##### `output-old-value` - 是否输出行数据更改前的值。 -- 开启后，UPDATE 事件会输出两行数据：第一行为 DELETE 事件，输出更改前的数据；第二行为 INSERT 事件，输出更改后的数据。 -- 开启后，即当该参数设为 `true` 时，会在变更数据列前增加 `"is-update"` 列。该列用来标识当前行的变更数据是来自 Update 事件，还是原始的 INSERT/DELETE 事件。如果当前行的变更数据来自 UPDATE 事件，则 `"is-update"` 列为 `true`，否则为 `false`。 +- 开启后，即当该参数设为 `true` 时，UPDATE 事件会输出两行数据：第一行为 DELETE 事件，输出更改前的数据；第二行为 INSERT 事件，输出更改后的数据。 +- 开启后，会在变更数据列前增加 `"is-update"` 列。该列用来标识当前行的变更数据是来自 Update 事件，还是原始的 INSERT/DELETE 事件。如果当前行的变更数据来自 UPDATE 事件，则 `"is-update"` 列为 `true`，否则为 `false`。 - 默认值：`false` 从 v8.0.0 开始，TiCDC 新增了 Simple Protocol 消息编码协议，以下为该协议的配置参数。关于该协议的详情，请参考 [TiCDC Simple Protocol](/ticdc/ticdc-simple-protocol.md)。 @@ -312,8 +313,7 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl - 控制是否发送 bootstrap 消息到所有的 partition。 - 如果设置为 `false`，则只发送 bootstrap 消息到对应表 topic 的第一个 partition。 - -[//]: # (- 示例值 `true`) +- 默认值：`true` #### sink.kafka-config.codec-config @@ -385,7 +385,7 @@ consistent 中的字段用于配置 Changefeed 的数据一致性。详细信息 - redo log 文件的压缩行为。 - 默认值：`""`，表示不进行压缩 -- 可选值：`""`、`lz4` +- 可选值：`""`、`"lz4"` #### `flush-concurrency` @@ -415,7 +415,7 @@ consistent 中的字段用于配置 Changefeed 的数据一致性。详细信息 - Kafka SASL 认证机制。 - 默认值：`""`，表示不使用 SASL 认证 -[//]: # (- 示例值：`OAUTHBEARER`) + #### `sasl-oauth-client-id` @@ -439,7 +439,7 @@ consistent 中的字段用于配置 Changefeed 的数据一致性。详细信息 #### `sasl-oauth-grant-type` -- Kafka SASL OAUTHBEARER 认证机制中的 grant-type。默认值为 `"client_credentials"`。在使用该认证机制时，该参数可选填。 +- Kafka SASL OAUTHBEARER 认证机制中的 grant-type。在使用该认证机制时，该参数可选填。 - 默认值：`"client_credentials"` #### `sasl-oauth-audience` @@ -447,7 +447,7 @@ consistent 中的字段用于配置 Changefeed 的数据一致性。详细信息 - Kafka SASL OAUTHBEARER 认证机制中的 audience。在使用该认证机制时，该参数可选填。 - 默认值：`""` -[//]: # (- 示例值：`"kafka"`) + #### `output-raw-change-event` @@ -527,7 +527,8 @@ token="xxxx" #### `pulsar-producer-cache-size` -- TiCDC 中缓存 Pulsar Producer 的个数，默认上限为 `10240` 个。每个 Pulsar Producer 对应一个 topic，如果你需要同步的 topic 数量大于默认值，则需要调大该数量。 +- TiCDC 中缓存 Pulsar Producer 的个数。每个 Pulsar Producer 对应一个 topic，如果你需要同步的 topic 数量大于默认值，则需要调大该数量。 +- 默认值：`10240` #### `compression-type` diff --git a/ticdc/ticdc-server-config.md b/ticdc/ticdc-server-config.md index 5731ea4dfd60..f447691a8cf6 100644 --- a/ticdc/ticdc-server-config.md +++ b/ticdc/ticdc-server-config.md @@ -30,7 +30,7 @@ summary: 了解 TiCDC 详细的命令行参数和配置文件定义。 对于 `cdc server` 命令中 `config` 参数指定的配置文件说明如下。你可以在 [`pkg/cmd/util/ticdc.toml`](https://github.com/pingcap/tiflow/blob/master/pkg/cmd/util/ticdc.toml) 找到默认值的配置文件。 -[//]: # (下面的字段的配置含义与命令行参数相同，但是命令行参数优先级更高) + ### `addr` @@ -99,7 +99,7 @@ summary: 了解 TiCDC 详细的命令行参数和配置文件定义。 - 指定可用于客户端鉴权的用户名，列表中不存在的用户的鉴权请求将被直接拒绝。 - 默认值：`null` -[//]: # (- 示例值：`["username_1", "username_2"]`) + ### `capture-session-ttl`