ticdc: update description about time-zone in sink uri#21379
Merged
ti-chi-bot[bot] merged 6 commits intomasterfrom Mar 2, 2026
Merged
ticdc: update description about time-zone in sink uri#21379ti-chi-bot[bot] merged 6 commits intomasterfrom
ti-chi-bot[bot] merged 6 commits intomasterfrom
Conversation
ti-chi-bot
Bot
added
missing-translation-status
lidezhu
changed the title
hfxsd
added
translation/doing
Collaborator
|
/bot-review |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| | :-: | :-: | :-: | :-: | | ||
| | 配置方式 | 见[时区支持](/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` 参数 |（仅当下游为 `mysql`/`tidb` sink）sink-uri 中的 `time-zone` 参数 | |
There was a problem hiding this comment.
表格标题行中列数（4列）与内容行（3列）不匹配，缺少了第四列的标题。
Suggested change
| | 配置方式 | 见[时区支持](/configure-time-zone.md) | 启动 ticdc server 时的 `--tz` 参数 |（仅当下游为 `mysql`/`tidb` sink）sink-uri 中的 `time-zone` 参数 | | |
| ||上游时区| 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` 参数 |（仅当下游为 `mysql`/`tidb` sink）sink-uri 中的 `time-zone` 参数 | | ||
| | 说明 | 上游 TiDB 的时区，影响 timestamp 类型的 DML 操作和与 timestamp 类型列相关的 DDL 操作。 | TiCDC 会假设上游 TiDB 的时区与 TiCDC 时区配置相同，并据此对 timestamp 类型的列进行相关处理。 | `mysql`/`tidb` 下游会依据该连接会话的时区设置，对 DML 和 DDL 操作中包含的 timestamp 值进行处理。| |
There was a problem hiding this comment.
对下游时区配置方式的描述不够清晰，且括号内的说明打断了句子结构。建议将说明移至表格下方的说明部分，使表格内容更简洁。
Suggested change
| | 说明 | 上游 TiDB 的时区，影响 timestamp 类型的 DML 操作和与 timestamp 类型列相关的 DDL 操作。 | TiCDC 会假设上游 TiDB 的时区与 TiCDC 时区配置相同，并据此对 timestamp 类型的列进行相关处理。 | `mysql`/`tidb` 下游会依据该连接会话的时区设置，对 DML 和 DDL 操作中包含的 timestamp 值进行处理。| | |
| | 配置方式 | 见[时区支持](/configure-time-zone.md) | 启动 ticdc server 时的 `--tz` 参数 | sink-uri 中的 `time-zone` 参数 | |
|
|
||
| > **说明：** | ||
| > | ||
| > `sink-uri` 中的 `time-zone` 参数仅对 `mysql`/`tidb` sink 生效。对于 Kafka、Pulsar、Cloud Storage 等 sink，不涉及下游数据库会话时区，此时无需配置 `time-zone`，只需关注上游数据库时区与 TiCDC server 的 `--tz` 设置。 |
There was a problem hiding this comment.
说明部分内容冗长，且与表格内容有部分重复。建议简化表述，并明确指出 time-zone 参数仅对 mysql/tidb sink 生效。
Suggested change
| > `sink-uri` 中的 `time-zone` 参数仅对 `mysql`/`tidb` sink 生效。对于 Kafka、Pulsar、Cloud Storage 等 sink，不涉及下游数据库会话时区，此时无需配置 `time-zone`，只需关注上游数据库时区与 TiCDC server 的 `--tz` 设置。 | |
| > **说明：** | |
| > | |
| > `sink-uri` 中的 `time-zone` 参数仅对 `mysql`/`tidb` sink 生效。对于 Kafka、Pulsar、Cloud Storage 等 sink，不涉及下游数据库会话时区，因此无需配置该参数。 |
| - `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` 指定的时区，请保持二者一致。） |
There was a problem hiding this comment.
修改后的句子较长，且括号内的说明信息量较大，建议将括号内的内容拆分为更清晰的句子，以提升可读性。同时，原文中‘sink 向下游执行时’的表述可以更精确。
Suggested change
| - `tz`：TiCDC 服务使用的时区。TiCDC 在内部转换 `TIMESTAMP` 等时间数据类型和向下游同步数据时使用该时区，默认为进程运行本地时区。（注意：`sink-uri` 中的 `time-zone` 参数仅对 `mysql`/`tidb` sink 生效，用于设置下游连接会话的时区。如果同时指定 `tz` 参数和 `time-zone` 参数，TiCDC 进程内部使用 `tz` 指定的时区，而 MySQL/TiDB sink 向下游执行时使用 `time-zone` 指定的时区，请保持二者一致。） | |
| - `tz`：TiCDC 服务使用的时区。TiCDC 在内部转换 `TIMESTAMP` 等时间数据类型和向下游同步数据时使用该时区，默认为进程运行本地时区。（注意：`sink-uri` 中的 `time-zone` 参数仅对 `mysql`/`tidb` sink 生效，用于设置下游连接会话的时区。如果同时指定 `tz` 参数和 `time-zone` 参数，TiCDC 进程内部使用 `tz` 指定的时区，而 MySQL/TiDB sink 向下游写入数据时使用 `time-zone` 指定的时区，请保持二者一致。） |
| | `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=""`，则表示连接时不指定会话时区，使用下游默认时区）。 | |
There was a problem hiding this comment.
修改后的描述在括号内增加了对 time_zone 的解释，但括号内的内容较长，且‘即下游连接会话的 time_zone’这一解释可以更清晰地融入主句。同时，括号内关于空值的描述‘连接时不指定会话时区’与主句‘连接下游 MySQL/TiDB 实例时使用的时区名称’存在逻辑跳跃，建议调整语序使逻辑更连贯。
Suggested change
| | `time-zone` | 连接下游 MySQL/TiDB 实例时使用的时区名称（即下游连接会话的 `time_zone`），从 v4.0.8 开始生效。（可选。如果不指定该参数，使用 TiCDC 服务进程的时区；如果指定该参数但使用空值，例如：`time-zone=""`，则表示连接时不指定会话时区，使用下游默认时区）。 | | |
| | `time-zone` | 连接下游 MySQL/TiDB 实例时，用于设置下游连接会话 `time_zone` 的时区名称，从 v4.0.8 开始生效。（可选。如果不指定该参数，则使用 TiCDC 服务进程的时区；如果指定该参数但使用空值，例如 `time-zone=""`，则表示连接时不设置会话时区，使用下游数据库的默认时区）。 | |
|
|
||
| > **说明：** | ||
| > | ||
| > `time-zone` 仅对 `mysql`/`tidb` sink 生效。TiCDC 会在建立到下游的连接后设置该连接会话的 `time_zone`，用于下游执行 DDL/DML 时解析 `TIMESTAMP` 等受时区影响的时间值（`DATETIME`、`DATE`、`TIME` 不受影响）。为避免因时区不一致导致的数据不一致，建议显式设置并保持与 TiCDC server 的 `--tz` 以及下游数据库时区一致。 |
There was a problem hiding this comment.
该说明的表述可以更清晰。原文中‘用于下游执行 DDL/DML 时解析 TIMESTAMP 等受时区影响的时间值（DATETIME、DATE、TIME 不受影响）’这句话的括号内容容易引起误解，因为 DATETIME、DATE、TIME 类型本身确实不受时区转换影响，但这里强调的是 time-zone 参数的作用范围。建议调整语序，先明确说明该参数设置的是连接会话的时区，再解释其用途和影响。同时，关于与 --tz 保持一致的建议，可以更明确地指出这是为了避免潜在的数据不一致问题。
Suggested change
| > `time-zone` 仅对 `mysql`/`tidb` sink 生效。TiCDC 会在建立到下游的连接后设置该连接会话的 `time_zone`，用于下游执行 DDL/DML 时解析 `TIMESTAMP` 等受时区影响的时间值（`DATETIME`、`DATE`、`TIME` 不受影响）。为避免因时区不一致导致的数据不一致，建议显式设置并保持与 TiCDC server 的 `--tz` 以及下游数据库时区一致。 | |
| > **说明：** | |
| > | |
| > `time-zone` 参数仅对 `mysql`/`tidb` sink 生效。TiCDC 会在建立到下游的连接后，设置该连接会话的 `time_zone` 系统变量。此设置主要用于下游数据库在执行 DDL/DML 时，正确解析 `TIMESTAMP` 这类受时区影响的时间类型值（注意：`DATETIME`、`DATE`、`TIME` 类型值的存储和解释通常与时区无关）。为避免因上游 TiCDC、下游数据库以及该参数设置之间的时区不一致而导致数据不一致，建议将此参数的值设置为与 TiCDC server 的 `--tz` 参数以及下游数据库的时区保持一致。 |
| ``` | ||
|
|
||
| 如果下游是特殊的 MySQL 环境（某种公有云 RDS 或某些 MySQL 衍生版本等），使用上述方式导入时区失败，则可以通过设置 `time-zone` 为空值来使用下游默认时区，例如：`time-zone=""`。 | ||
| 如果下游是特殊的 MySQL 环境（某种公有云 RDS 或某些 MySQL 衍生版本等），使用上述方式导入时区失败，则可以通过在 Sink URI 中设置 `time-zone` 为空值来使用下游默认时区，例如：`time-zone=""`（该参数仅对 `mysql`/`tidb` sink 生效）。 |
There was a problem hiding this comment.
原文中‘某种公有云 RDS 或某些 MySQL 衍生版本等’的表述可以更具体，以增强文档的指导性。同时，补充说明该参数仅对 mysql/tidb sink 生效是必要的，但建议将生效范围说明放在更合适的位置，或调整措辞使其更自然。
Suggested change
| 如果下游是特殊的 MySQL 环境（某种公有云 RDS 或某些 MySQL 衍生版本等），使用上述方式导入时区失败，则可以通过在 Sink URI 中设置 `time-zone` 为空值来使用下游默认时区，例如：`time-zone=""`（该参数仅对 `mysql`/`tidb` sink 生效）。 | |
| 如果下游是特殊的 MySQL 环境（例如某些公有云 RDS 或 MySQL 衍生版本），使用上述方式导入时区失败，则可以在 Sink URI 中设置 `time-zone=""` 来使用下游默认时区。该参数仅对 `mysql` 和 `tidb` 类型的 sink 生效。 |
| 如果下游是特殊的 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` 时区配置和下游数据库的时区配置保持一致。这样可以避免因时区不一致导致的数据不一致问题。 |
There was a problem hiding this comment.
原文‘在使用 MySQL/TiDB sink 时’的表述不够精确，因为前文已说明该参数仅对 mysql/tidb sink 生效，此处建议保持与上文一致的术语。同时，关于时区配置一致性的建议是重要的，但可以更清晰地说明三者分别是什么。
Suggested change
| 在使用 MySQL/TiDB sink 时，建议显式指定时区，例如：`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` 参数以及下游数据库的时区设置保持一致，以避免因时区不一致导致的数据问题。 |
|
✅ AI review completed, 9 comments generated. |
flowbehappy
approved these changes
Feb 25, 2026
|
@flowbehappy: adding LGTM is restricted to approvers and reviewers in OWNERS files. DetailsIn response to this: Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
hfxsd
reviewed
Feb 25, 2026
hfxsd
reviewed
Feb 25, 2026
hfxsd
reviewed
Feb 25, 2026
hfxsd
reviewed
Feb 25, 2026
hfxsd
reviewed
Feb 25, 2026
hfxsd
reviewed
Feb 25, 2026
hfxsd
reviewed
Feb 25, 2026
14 tasks
github-actions Bot
added a commit
to hfxsd/docs
that referenced
this pull request
Feb 27, 2026
Synced from: pingcap/docs-cn#21379 Target PR: pingcap#22506 AI Provider: gemini Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
hfxsd
reviewed
Feb 27, 2026
hfxsd
reviewed
Feb 27, 2026
hfxsd
reviewed
Feb 27, 2026
hfxsd
added
translation/done
qiancai
approved these changes
Feb 28, 2026
[LGTM Timeline notifier]Timeline:
|
qiancai
reviewed
Feb 28, 2026
Co-authored-by: Grace Cai <qqzczy@126.com>
hfxsd
added
the
needs-cherry-pick-release-8.5
Collaborator
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: hfxsd The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
ti-chi-bot
pushed a commit
to ti-chi-bot/docs
that referenced
this pull request
Mar 2, 2026
Synced from: pingcap/docs-cn#21379 Target PR: pingcap#22506 AI Provider: gemini Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
14 tasks
Member
|
In response to a cherrypick label: new pull request created to branch |
14 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First-time contributors' checklist
What is changed, added or deleted? (Required)
Which TiDB version(s) do your changes apply to? (Required)
Tips for choosing the affected version(s):
By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.
For details, see tips for choosing the affected versions (in Chinese).
What is the related PR or file link(s)?
Do your changes match any of the following descriptions?