ticdc: fix sink uri for storage sink (#13654)

ticdc/ticdc-changefeed-config.md

@@ -118,8 +118,8 @@ protocol = "canal-json"
 terminator = ''
 # 文件路径的日期分隔类型。可选类型有 `none`、`year`、`month` 和 `day`。默认值为 `none`，即不使用日期分隔。详见 <https://docs.pingcap.com/zh/tidb/dev/ticdc-sink-to-cloud-storage#数据变更记录>。
 date-separator = 'none'
-# 是否使用 partition 作为分隔字符串。默认值为 false，即一张表中各个 partition 的数据不会分不同的目录来存储。详见 <https://docs.pingcap.com/zh/tidb/dev/ticdc-sink-to-cloud-storage#数据变更记录>。
-enable-partition-separator = false
+# 是否使用 partition 作为分隔字符串。默认值为 true，即一张表中各个 partition 的数据会分不同的目录来存储。详见 <https://docs.pingcap.com/zh/tidb/dev/ticdc-sink-to-cloud-storage#数据变更记录>。
+enable-partition-separator = true
 
 # 从 v6.5.0 开始，TiCDC 支持以 CSV 格式将数据变更记录保存至存储服务中，在 MQ 和 MySQL 类 sink 中无需设置。
 [sink.csv]

ticdc/ticdc-sink-to-cloud-storage.md

@@ -35,34 +35,59 @@ Info: {"upstream_id":7171388873935111376,"namespace":"default","id":"simple-repl
 
 ## 配置 Sink URI
 
-本章节介绍如何在 Changefeed URI 中配置存储服务 Amazon S3、Azure Blob Storage 和 NFS。
-
-### 配置外部存储
-
-Amazon S3、GCS 以及 Azure Blob Storage 的 URI 参数与 BR 中这三种存储的 URI 参数相同。详细参数说明请参考 [BR 备份存储服务的 URI 格式](/br/backup-and-restore-storages.md#格式说明)。
-
-### 配置 NFS
-
-NFS 配置样例如下：
+本章节介绍如何在 Sink URI 中配置存储服务 Amazon S3、GCS、Azure Blob Storage 以及 NFS。Sink URI 用于指定 TiCDC 下游系统的连接信息，遵循以下格式：
 
 ```shell
---sink-uri="file:///my-directory/prefix"
+[scheme]://[host]/[path]?[query_parameters]
 ```
 
-### 可选配置
-
-URI 中其他可配置的参数如下：
+URI 的 `[query_parameters]` 中可配置的参数如下：
 
 | 参数              | 描述                                                   | 默认值      | 取值范围                 |
 | :--------------- | :----------------------------------------------------- | :--------- | :--------------------- |
 | `worker-count`   | 向下游存储服务保存数据变更记录的并发度                       | `16`       | `[1, 512]`             |
 | `flush-interval` | 向下游存储服务保存数据变更记录的间隔                         | `5s`       | `[2s, 10m]`            |
 | `file-size`      | 单个数据变更文件的字节数超过 `file-size` 时将其保存至存储服务中| `67108864` | `[1048576, 536870912]` |
 | `protocol`       | 输出到存储服务的消息协议                                  | N/A         | `canal-json` 和 `csv`  |
+| `enable-tidb-extension` | `protocol` 参数为 `canal-json` 时，如果该值为 `true`，TiCDC 会发送 [WATERMARK 事件](/ticdc/ticdc-canal-json.md#watermark-event)，并在 canal-json 消息中添加 [TiDB 扩展字段](/ticdc/ticdc-canal-json.md#tidb-扩展字段)。 | `false` | `false` 和 `true` |
 
 > **注意：**
 >
 > `flush-interval` 与 `file-size` 二者只要满足其一就会向下游写入数据变更文件。
+> 
+> `protocol` 是必选配置，如果 TiCDC 在创建 changefeed 时未解析到该配置，将会返回 `CDC:ErrSinkUnknownProtocol` 错误。
+
+### 配置外部存储
+
+Amazon S3 配置样例如下：
+
+```shell
+--sink-uri="s3://bucket/prefix?protocol=canal-json"
+```
+
+GCS 配置样例如下：
+
+```shell
+--sink-uri="gcs://bucket/prefix?protocol=canal-json"
+```
+
+Azure Blob Storage 配置样例如下：
+
+```shell
+--sink-uri="azure://bucket/prefix?protocol=canal-json"
+```
+
+> **建议：**
+> 
+> Amazon S3、GCS 以及 Azure Blob Storage 的 URI 参数与 BR 中这三种外部存储的 URI 参数相同。详细参数说明请参考 [BR 备份存储服务的 URI 格式](/br/backup-and-restore-storages.md#格式说明)。
+
+### 配置 NFS
+
+NFS 配置样例如下：
+
+```shell
+--sink-uri="file:///my-directory/prefix?protocol=canal-json"
+```
 
 ## 存储路径组织结构
 
@@ -76,7 +101,7 @@ URI 中其他可配置的参数如下：
 {scheme}://{prefix}/{schema}/{table}/{table-version-separator}/{partition-separator}/{date-separator}/CDC{num}.{extension}
 ```
 
-- `scheme`：数据传输协议，即存储类型。例如：<code>**s3**://xxxxx</code>。
+- `scheme`：存储服务类型。例如：`s3`、`gcs`、`azure`、`file`。
 - `prefix`：用户指定的父目录。例如：<code>s3://**bucket/bbb/ccc**</code>。
 - `schema`：表所属的库名。例如：<code>s3://bucket/bbb/ccc/**test**</code>。
 - `table`：表名。例如：<code>s3://bucket/bbb/ccc/test/**table1**</code>。
@@ -92,10 +117,11 @@ URI 中其他可配置的参数如下：
 
 > **注意：**
 >
-> 表的版本会在以下两种情况下发生变化：
+> 表的版本可能在以下三种情况下发生变化：
 >
 > - 发生 DDL 操作后，表的版本为该 DDL 在上游 TiDB 执行结束的 TSO。但是，表版本的变化并不意味着表结构的变化。例如，在表中的某一列添加注释，不会导致 `schema.json` 文件内容发生变化。
 > - 进程重启，表的版本为进程重启时 Changefeed 的 checkpoint TSO。在有很多表的情况下，重启时需要遍历所有目录并找到上一次重启时每张表写入的位置，这样的操作耗时较长。因此，TiCDC 选择在一个以 checkpoint TSO 为版本的新目录下写入数据，而不是在旧版本的目录下继续写入数据。
+> - 发生表调度后，表的版本为该表调度到当前节点时 Changefeed 的 checkpoint TSO。
 
 ### Index 文件
 

ticdc/ticdc-sink-to-kafka.md

@@ -60,7 +60,7 @@ URI 中可配置的的参数如下：
 | `compression`        | 设置发送消息时使用的压缩算法（可选值为 `none`、`lz4`、`gzip`、`snappy` 和 `zstd`，默认值为 `none`）。|
 | `protocol` | 输出到 Kafka 的消息协议，可选值有 `canal-json`、`open-protocol`、`canal`、`avro`、`maxwell`。 |
 | `auto-create-topic` | 当传入的 `topic-name` 在 Kafka 集群不存在时，TiCDC 是否要自动创建该 topic（可选，默认值 `true`）。 |
-| `enable-tidb-extension` | 可选，默认值是 `false`。当输出协议为 `canal-json` 时，如果该值为 `true`，TiCDC 会发送 [Resolved 事件](/ticdc/ticdc-canal-json.md#watermark-event)，并在 Kafka 消息中添加 TiDB 扩展字段。从 6.1.0 开始，该参数也可以和输出协议 `avro` 一起使用。如果该值为 `true`，TiCDC 会在 Kafka 消息中添加[三个 TiDB 扩展字段](/ticdc/ticdc-avro-protocol.md#tidb-扩展字段)。|
+| `enable-tidb-extension` | 可选，默认值是 `false`。当输出协议为 `canal-json` 时，如果该值为 `true`，TiCDC 会发送 [WATERMARK 事件](/ticdc/ticdc-canal-json.md#watermark-event)，并在 Kafka 消息中添加 TiDB 扩展字段。从 6.1.0 开始，该参数也可以和输出协议 `avro` 一起使用。如果该值为 `true`，TiCDC 会在 Kafka 消息中添加[三个 TiDB 扩展字段](/ticdc/ticdc-avro-protocol.md#tidb-扩展字段)。|
 | `max-batch-size` |  从 v4.0.9 开始引入。当消息协议支持把多条变更记录输出至一条 Kafka 消息时，该参数用于指定这一条 Kafka 消息中变更记录的最多数量。目前，仅当 Kafka 消息的 `protocol` 为 `open-protocol` 时有效（可选，默认值 `16`）。|
 | `enable-tls` | 连接下游 Kafka 实例是否使用 TLS（可选，默认值 `false`）。 |
 | `ca`       | 连接下游 Kafka 实例所需的 CA 证书文件路径（可选）。 |