Merge remote-tracking branch 'upstream/master'

Author: hfxsd

keywords.md

@@ -67,6 +67,7 @@ TiDB 从 v7.5.3 和 v7.6.0 开始提供 [`INFORMATION_SCHEMA.KEYWORDS`](/informa
 - ADMIN
 - ADVISE
 - AFTER
+- AFFINITY
 - AGAINST
 - AGO
 - ALGORITHM
@@ -420,6 +421,7 @@ TiDB 从 v7.5.3 和 v7.6.0 开始提供 [`INFORMATION_SCHEMA.KEYWORDS`](/informa
 
 <a id="M" class="letter" href="#M">M</a>
 
+- MASKING
 - MASTER
 - MATCH (R)
 - MAXVALUE (R)
@@ -526,6 +528,7 @@ TiDB 从 v7.5.3 和 v7.6.0 开始提供 [`INFORMATION_SCHEMA.KEYWORDS`](/informa
 - PLUGINS
 - POINT
 - POLICY
+- POLICIES
 - PRECEDING
 - PRECISION (R)
 - PREPARE
@@ -674,6 +677,7 @@ TiDB 从 v7.5.3 和 v7.6.0 开始提供 [`INFORMATION_SCHEMA.KEYWORDS`](/informa
 - STATS_BUCKETS
 - STATS_COL_CHOICE
 - STATS_COL_LIST
+- STATS_DELTA
 - STATS_EXTENDED
 - STATS_HEALTHY
 - STATS_HISTOGRAMS

ticdc/ticdc-faq.md

@@ -193,8 +193,12 @@ TiCDC 为 service GC safepoint 设置的默认存活有效期为 24 小时，即
 
 ||上游时区| TiCDC 时区| 下游时区 |
 | :-: | :-: | :-: | :-: |
-| 配置方式 | 见[时区支持](/configure-time-zone.md) | 启动 ticdc server 时的 `--tz` 参数 | sink-uri 中的 `time-zone` 参数 |
-| 说明 | 上游 TiDB 的时区，影响 timestamp 类型的 DML 操作和与 timestamp 类型列相关的 DDL 操作。 | TiCDC 会将假设上游 TiDB 的时区和 TiCDC 时区配置相同，对 timestamp 类型的列进行相关处理。 | 下游 MySQL 将按照下游的时区设置对 DML 和 DDL 操作中包含的 timestamp 进行处理。|
+| 配置方式 | 见[时区支持](/configure-time-zone.md) | 启动 ticdc server 时的 `--tz` 参数 | `sink-uri` 中的 `time-zone` 参数。仅当下游为 `mysql` 或 `tidb` sink 时生效。 |
+| 说明 | 上游 TiDB 的时区，影响 timestamp 类型的 DML 操作和与 timestamp 类型列相关的 DDL 操作。 | TiCDC 会假设上游 TiDB 的时区与 TiCDC 时区配置相同，并据此对 timestamp 类型的列进行相关处理。 | `mysql` 和 `tidb` 类型的下游会依据该连接会话的时区设置，对 DML 和 DDL 操作中包含的 timestamp 值进行处理。|
+
+> **注意：**
+>
+> `sink-uri` 中的 `time-zone` 参数仅对 `mysql` 和 `tidb` 类型的 sink 生效。对于 Kafka、Pulsar、Cloud Storage 等不涉及下游数据库会话时区的 sink，你只需要确保上游数据库时区与 TiCDC server 的 `--tz` 参数的设置保持一致，无需配置 `time-zone`。
 
 > **注意：**
 >

ticdc/ticdc-server-config.md

@@ -23,7 +23,7 @@ summary: 了解 TiCDC 详细的命令行参数和配置文件定义。
 - `cert`：TiCDC 创建 TLS 连接时使用的证书文件路径，PEM 格式，可选。
 - `cert-allowed-cn`：TiCDC 创建 TLS 连接时使用的通用名称文件路径，可选。
 - `key`：TiCDC 创建 TLS 连接时使用的证书密钥文件路径，PEM 格式，可选。
-- `tz`：TiCDC 服务使用的时区。TiCDC 在内部转换 `TIMESTAMP` 等时间数据类型和向下游同步数据时使用该时区，默认为进程运行本地时区。（注意如果同时指定 `tz` 参数和 `sink-uri` 中的 `time-zone` 参数，TiCDC 进程内部使用 `tz` 指定的时区，sink 向下游执行时使用 `time-zone` 指定的时区，请保持二者一致。）
+- `tz`：TiCDC 服务使用的时区。TiCDC 在内部转换 `TIMESTAMP` 等时间数据类型和向下游同步数据时使用该时区，默认为进程运行本地时区。注意 `sink-uri` 中的 `time-zone` 参数仅对 `mysql` 和 `tidb` sink 生效，用于设置下游连接会话的时区。如果同时指定 `tz` 参数和 `time-zone` 参数，请确保两个参数的设置相同，因为 TiCDC 进程内部使用 `tz` 指定的时区，而 MySQL 和 TiDB sink 向下游执行时使用 `time-zone` 指定的时区。
 - `cluster-id`：TiCDC 集群的 ID。可选，默认值为 `default`。`cluster-id` 是 TiCDC 集群的唯一标识，拥有相同 `cluster-id` 的 TiCDC 节点同属一个集群。长度最大为 128，需要符合正则表达式 `^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$`，且不能是以下值：`owner`，`capture`，`task`，`changefeed`，`job`，`meta`。
 
 ## `cdc server` 配置文件说明

ticdc/ticdc-sink-to-mysql.md

@@ -71,7 +71,7 @@ URI 中可配置的参数如下：
 | `ssl-ca`       | 连接下游 MySQL 实例所需的 CA 证书文件路径（可选）。 |
 | `ssl-cert`     | 连接下游 MySQL 实例所需的证书文件路径（可选）。 |
 | `ssl-key`      | 连接下游 MySQL 实例所需的证书密钥文件路径（可选）。 |
-| `time-zone`    | 连接下游 MySQL 实例时使用的时区名称，从 v4.0.8 开始生效。（可选。如果不指定该参数，使用 TiCDC 服务进程的时区；如果指定该参数但使用空值，例如：`time-zone=""`，则表示连接 MySQL 时不指定时区，使用下游默认时区）。 |
+| `time-zone`    | 连接下游 MySQL 和 TiDB 实例时使用的时区名称（即下游连接会话的 `time_zone`），从 v4.0.8 开始生效。（可选。如果不指定该参数，使用 TiCDC 服务进程的时区；如果指定该参数但使用空值，例如：`time-zone=""`，则表示连接时不指定会话时区，使用下游默认时区）。 |
 | `transaction-atomicity`      | 指定事务的原子性级别（可选，默认值为 `none`）。当该值为 `table` 时 TiCDC 保证单表事务的原子性，当该值为 `none` 时 TiCDC 会拆分单表事务。 |
 | `batch-dml-enable` | 开启 batch-dml 批量写入特性（可选，默认值为 `true`）。|
 | `read-timeout` | go-sql-driver 参数，[I/O 读取超时](https://pkg.go.dev/github.com/go-sql-driver/mysql#readme-readtimeout)（可选，默认值为 `2m`）。|
@@ -80,6 +80,11 @@ URI 中可配置的参数如下：
 | `tidb-txn-mode` | 设置环境变量 [`tidb_txn_mode`](/system-variables.md#tidb_txn_mode)（可选，默认值为 `optimistic`）。 |
 | `safe-mode` | 指定向下游同步数据时 `INSERT` 和 `UPDATE` 语句的处理方式。当设置为 `true` 时，TiCDC 会将上游所有的 `INSERT` 语句转换为 `REPLACE INTO` 语句，所有的 `UPDATE` 语句转换为 `DELETE` + `REPLACE INTO` 语句。在 v6.1.3 版本之前，该参数的默认值为 `true`。从 v6.1.3 版本开始，该参数的默认值调整为 `false`，TiCDC 在启动时会获取一个当前时间戳 `ThresholdTs`：<ul><li>对于 `CommitTs` 小于 `ThresholdTs` 的 `INSERT` 语句和 `UPDATE` 语句，TiCDC 会分别将其转换为 `REPLACE INTO` 语句和 `DELETE` + `REPLACE INTO` 语句。</li><li>对于 `CommitTs` 大于等于 `ThresholdTs` 的 `INSERT` 语句和 `UPDATE` 语句，`INSERT` 语句将直接同步到下游，`UPDATE` 语句的具体行为则参考 [TiCDC 拆分 UPDATE 事件行为说明](/ticdc/ticdc-split-update-behavior.md)。</li></ul> |
 
+> **注意：**
+>
+> - `time-zone` 仅对 `mysql` 和 `tidb` 类型的 sink 生效。TiCDC 在建立与下游的连接后，会设置该会话的 `time_zone`，用于下游在执行 DDL 和 DML 时解析 `TIMESTAMP` 等受时区影响的时间值。`DATETIME`、`DATE` 和 `TIME` 数据类型不受时区设置影响。
+> - 为避免因时区设置不一致导致数据不一致，建议显式设置 `time-zone`，并确保其值与 TiCDC Server 的 `--tz` 参数以及下游数据库的时区保持一致。
+
 若需要对 Sink URI 中的数据库密码使用 Base64 进行编码，可以参考如下命令：
 
 ```shell

ticdc/troubleshoot-ticdc.md

@@ -72,9 +72,9 @@ Warning: Unable to load '/usr/share/zoneinfo/zone.tab' as time zone. Skipping it
 Warning: Unable to load '/usr/share/zoneinfo/zone1970.tab' as time zone. Skipping it.
 ```
 
-如果下游是特殊的 MySQL 环境（某种公有云 RDS 或某些 MySQL 衍生版本等），使用上述方式导入时区失败，则可以通过设置 `time-zone` 为空值来使用下游默认时区，例如：`time-zone=""`。
+如果下游是特殊的 MySQL 环境（某种公有云 RDS 或某些 MySQL 衍生版本等），使用上述方式导入时区失败，则可以通过在 Sink URI 中设置 `time-zone` 为空值来使用下游默认时区，例如：`time-zone=""`。注意该参数仅对 `mysql` 和 `tidb` 类型的 sink 生效。
 
-在 TiCDC 中使用时区时，建议显式指定时区，例如：`time-zone="Asia/Shanghai"`。同时，请确保 TiCDC Server 的 `tz` 时区配置、Sink URI 中的 `time-zone` 时区配置和下游数据库的时区配置保持一致。这样可以避免因时区不一致导致的数据不一致问题。
+在使用 MySQL 和 TiDB sink 时，建议显式指定时区，例如：`time-zone="Asia/Shanghai"`。同时，请确保 TiCDC Server 的 `tz` 时区配置、Sink URI 中的 `time-zone` 时区配置和下游数据库的时区配置保持一致。这样可以避免因时区不一致导致数据不一致的问题。
 
 ## 如何处理升级 TiCDC 后配置文件不兼容的问题？