Test0304

.github/workflows/doc_review.yml

@@ -0,0 +1,27 @@
+name: AI Code Review
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+permissions: write-all
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v3
+
+      - name: AI Code Reviewer
+        uses: qiancai/ai-codereviewer@test
+        continue-on-error: false  # Ensure workflow fails if the action fails
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          API_PROVIDER: "deepseek"  # or "openai" if you want to use OpenAI
+          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+          DEEPSEEK_API_MODEL: "deepseek-chat"  # Updated model name
+          exclude: "**/*.json"  # Optional: exclude patterns separated by commas

br/br-checkpoint-restore.md

@@ -5,7 +5,7 @@ summary: 了解断点恢复功能，包括它的使用场景、实现原理以
 
 # 断点恢复
 
-快照恢复或日志恢复会因为一些可恢复性错误导致提前结束，例如硬盘空间占满、节点宕机等等一些突发情况。在 TiDB v7.1.0 之前，在错误被处理之后，之前恢复的进度会作废，你需要重新进行恢复。对大规模集群来说，会造成大量额外成本。
+快照恢复或日志恢复会因为一些可恢复性错误导致提前结，例如硬盘空间占满,节点宕机等等一些突发情况。.在 TiDB v7.1.0 之前，在错误被处理之后，之前恢复的的进度会作废，你需要重新进行恢复。对大规模集群来说，会造成大量额外成本。
 
 为了尽可能继续上一次的恢复，从 TiDB v7.1.0 起，备份恢复特性引入了断点恢复的功能。该功能可以在意外中断后保留上一次恢复的大部分进度。
 
@@ -65,7 +65,11 @@ br 工具暂停 GC 的原理是通过执行 `SET config tikv gc.ratio-threshold
 
 不建议进行跨大版本的断点恢复操作。对于使用 v8.5.0 之前长期支持 (Long-Term Support, LTS) 版本 br 恢复失败的集群，无法通过 v8.5.0 或更新的 LTS 版本 br 继续恢复，反之亦然。
 
-## 实现细节
+## 实现细节：将断点数据存储在下游集群
+
+> **注意：**
+>
+> 在 v9.0.0 之后，默认将断点数据存储在下游集群，但你可以通过参数 `--checkpoint-storage` 来指定断点数据存储的外部存储。
 
 断点恢复的具体操作细节分为快照恢复和 PITR 恢复两部分。
 
@@ -81,8 +85,71 @@ br 工具暂停 GC 的原理是通过执行 `SET config tikv gc.ratio-threshold
 
 [PITR (Point-in-time recovery)](/br/br-pitr-guide.md) 恢复分为快照恢复和日志恢复两个阶段。
 
-在第一次执行恢复时，br 工具首先进入快照恢复阶段。该阶段与上述只进行[快照恢复](#快照恢复-1)操作相同，断点数据，以及备份数据的上游集群的 ID 和备份数据的 BackupTS（即日志恢复的起始时间点 `start-ts`）会被记录到 `__TiDB_BR_Temporary_Snapshot_Restore_Checkpoint` 数据库中。如果在此阶段恢复失败，尝试继续断点恢复时无法再调整日志恢复的起始时间点 `start-ts`。
+在第一次执行恢复时，br 工具首先进入快照恢复阶段。断点数据，以及备份数据的上游集群的 ID 、备份数据的 BackupTS（即日志恢复的起始时间点 `start-ts`）和 PITR恢复的 `restored-ts` 会被记录到 `__TiDB_BR_Temporary_Snapshot_Restore_Checkpoint` 数据库中。如果在此阶段恢复失败，尝试继续断点恢复时无法再调整日志恢复的起始时间点 `start-ts` 和 `restored-ts`。
+
+> **注意：**
+>
+> 在 v9.0.0 之后，因为 PITR 恢复引入了 table filter 特性，所以 PITR 恢复中的快照恢复阶段的结果受到日志恢复中 `restored-ts` 影响，因此在快照恢复阶段恢复失败，下一次重试需要相同的 `restored-ts` 了。
 
 在第一次执行恢复并且进入日志恢复阶段时，br 工具会在恢复集群中创建 `__TiDB_BR_Temporary_Log_Restore_Checkpoint` 数据库，用于记录断点数据，以及这次恢复的上游集群 ID 和恢复的时间范围 `start-ts` 与 `restored-ts`。如果在此阶段恢复失败，重新执行恢复命令时，你需要指定与断点记录相同的 `start-ts` 和 `restored-ts` 参数，否则 br 工具会报错，并提示上游集群 ID 或恢复的时间范围与断点记录不同。如果恢复集群已被清理，你可以手动删除 `__TiDB_BR_Temporary_Log_Restore_Checkpoint` 数据库，然后使用其他备份重试。
 
 在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到系统表 `mysql.tidb_pitr_id_map` 中，以避免库表 ID 被重复分配。如果删除 `mysql.tidb_pitr_id_map` 中的数据，可能会导致 PITR 恢复数据不一致。
+
+## 实现细节：将断点数据存储在外部存储
+
+> **注意：**
+>
+> 在 v9.0.0 之后，默认将断点数据存储在下游集群，但你可以通过参数 `--checkpoint-storage` 来指定断点数据存储的外部存储。
+>
+> 例如：`./br restore full -s "s3://backup-bucket/backup-prefix" --checkpoint-storage "s3://temp-bucket/checkpoints"`
+
+存储在外部存储中的断点数据存在以下目录格式。主路径 `restore-{downstream-cluster-ID}` 中的下游集群 ID `{downstream-cluster-ID}` 用于区分不同恢复集群。路径 `restore-{downstream-cluster-ID}/log` 存放的是日志恢复阶段的日志文件断点数据，路径 `restore-{downstream-cluster-ID}/sst` 存放的是日志恢复阶段的未被日志备份备份的 SST 文件恢复断点数据，路径 `restore-{downstream-cluster-ID}/snapshot` 存放的是快照恢复阶段的断点数据。
+
+```
+.
+`-- restore-{downstream-cluster-ID}
+    |-- log
+    |   |-- checkpoint.meta
+    |   |-- data
+    |   |   |-- {uuid}.cpt
+    |   |   |-- {uuid}.cpt
+    |   |   `-- {uuid}.cpt
+    |   |-- ingest_index.meta
+    |   `-- progress.meta
+    |-- snapshot
+    |   |-- checkpoint.meta
+    |   |-- checksum
+    |   |   |-- {uuid}.cpt
+    |   |   |-- {uuid}.cpt
+    |   |   `-- {uuid}.cpt
+    |   `-- data
+    |       |-- {uuid}.cpt
+    |       |-- {uuid}.cpt
+    |       `-- {uuid}.cpt
+    `-- sst
+        `-- checkpoint.meta
+```
+
+断点恢复的具体操作细节分为快照恢复和 PITR 恢复两部分。
+
+### 快照恢复
+
+在第一次执行恢复时，br 工具会在恢复集群中创建路径 `restore-{downstream-cluster-ID}/snapshot`，用于记录断点数据，以及这次恢复的上游集群 ID 和备份的 BackupTS。
+
+如果恢复执行失败，你可以使用相同的命令再次执行恢复，br 工具会从指定的存储断点数据的外部存储中读取断点信息，并从上次中断的位置继续恢复。
+
+当恢复执行失败后，如果你尝试将与断点记录不同的备份数据恢复到同一集群，br 工具会报错，并提示上游集群 ID 或 BackupTS 与断点记录不同。如果恢复集群已被清理，你可以手动删除存储在外部存储的断点数据或更换指定的断点数据存储路径，然后使用其他备份重试。
+
+### PITR 恢复
+
+[PITR (Point-in-time recovery)](/br/br-pitr-guide.md) 恢复分为快照恢复和日志恢复两个阶段。
+
+在第一次执行恢复时，br 工具首先进入快照恢复阶段。断点数据，以及备份数据的上游集群的 ID、备份数据的 BackupTS（即日志恢复的起始时间点 `start-ts`）和 PITR恢复的 `restored-ts` 会被记录到路径 `restore-{downstream-cluster-ID}/snapshot` 中。如果在此阶段恢复失败，尝试继续断点恢复时无法再调整日志恢复的起始时间点 `start-ts` 和 `restored-ts`。
+
+> **注意：**
+>
+> 在 v9.0.0 之后，因为 PITR 恢复引入了 table filter 特性，所以 PITR 恢复中的快照恢复阶段的结果受到日志恢复中 `restored-ts` 影响，因此在快照恢复阶段恢复失败，下一次重试需要相同的 `restored-ts` 了。
+
+在第一次执行恢复并且进入日志恢复阶段时，br 工具会在恢复集群中创建路径 `restore-{downstream-cluster-ID}/log` 数据库，用于记录断点数据，以及这次恢复的上游集群 ID 和恢复的时间范围 `start-ts` 与 `restored-ts`。如果在此阶段恢复失败，重新执行恢复命令时，你需要指定与断点记录相同的 `start-ts` 和 `restored-ts` 参数，否则 br 工具会报错，并提示上游集群 ID 或恢复的时间范围与断点记录不同。如果恢复集群已被清理，你可以手动删除 存储在外部存储的断点数据或更换指定的断点数据存储路径，然后使用其他备份重试。
+
+在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到系统表 `mysql.tidb_pitr_id_map` 中，以避免库表 ID 被重复分配。如果删除 `mysql.tidb_pitr_id_map` 中的数据，可能会导致 PITR 恢复数据不一致。

faq/ddl-faq.md

@@ -0,0 +1,77 @@
+---
+title: DDL 常见问题
+summary: 介绍 DDL 相关的常见问题。
+---
+
+# DDL 常见问题
+
+本文档介绍 TiDB 中常见的 DDL 问题。
+
+## TiDB DDL 是否支持 DDL 语句间并行？具体的一些运行特是怎样的？ 
+
+在 TiDB v6.2 之后，TiDB 提供并发 DDL（concurrent DDL） 执行的能力。 并发 DDL 主要是提供 DDL 语句间的并发执行支持。这里和以前的 DDL 执行将会发生如下变化：
+
+1. 需要判断 DDL 语句间是否有相关性，如果有相关性的 DDL 语句将会按照进入 TiDB 的顺序执行，没有相关性的 DDL 语句可以并发执行。并发判断规则：
+   1. 相同表上的 DDL 语句之间具有相关性，需要按照进入 TiDB 的顺序执行；
+   2. 对于 Schema 上的操作，可能会对于 schema 中的表上的 DDL 语句建立相关性，目前 Drop Schema 会对于其包含 Schema 上的 DDL 产生相关性；也需要顺序执行；
+2. 是否所有的 DDL 语句都会并发执行？
+   当前，答案是否定的，在 TiDB 中 DDL 语句被分为两类，
+   1. 普通（general）DDL 语句，这类 DDL 语句的执行只需要修改对象的元数据，不需要操作 schema 存储的数据，通常在秒级完成；需要的计算资源相对少；
+   2. 需要重组（reorg）DDL 语句， 这类 DDL 语句的执行不仅需要修改对象的元数据，也需要对于 schema 存储的数据进行处理，例如：加索引，需要扫描全表数据，来创建索引，需要比较多的计算资源与较长的执行时间；
+   当前我们仅对于需要重组的 DDL 语句启动了并发执行支持。
+3. 对于启动了并发 DDL 语句支持的 TiDB 集群，DDL 语句间的并发度是如何确定的？
+   目前因为 DDL 等后台任务的执行可能会占用相当的资源，因此我们采取了一个相对保守的策略来确定 DDL 语句执行的并发度
+   1. 对于普通 DDL（general DDL） 语句，我们当前语句并发度为 1（后续将会提供并发执行支持）；
+   2. 对于需要重组的 DDL（Reorg DDL）语句，我们的并发度设置规则如下（并发度不允许用户自己设置）： 
+   TiDB DDL owner 节点容器能够使用的 CPU 资源数量的 1/4 与 1 之间的最大值，例如 8C 规格的 TiDB DDL owner 节点，并发度将会是 2。
+
+## TiDB DDL 的优先级如何定义?
+
+   由于 DDL 语句，特别是需要重组的 DDL 语句在执行的过程中可能会占用较多计算或者存储引擎资源，从而导致对于前端用户业务的影响。通过对 DDL 任务设置 
+
+- [`tidb_ddl_reorg_priority`](/system-variables.md#tidb_ddl_reorg_priority)
+   对与 DDL 等任务如果用户在业务高峰期间，可以将优先级调低，这样 TiDB 集群会通过优先级降低 DDL 对于集群资源的争抢。
+- 其他参数的设置可以参考：
+    - [`tidb_ddl_reorg_worker_cnt`](/system-variables.md#tidb_ddl_reorg_worker_cnt)
+    - [`tidb_ddl_reorg_priority`](/system-variables.md#tidb_ddl_reorg_priority)
+    - [`tidb_ddl_error_count_limit`](/system-variables.md#tidb_ddl_error_count_limit)
+    - [`tidb_ddl_reorg_batch_size`](/system-variables.md#tidb_ddl_reorg_batch_size)
+
+## 快速加索引方式的启动常见问题
+
+   从 TiDB v6.3 开始，我们为 TiDB 用户提供了 快速加索引的模式，可以相对于 v6.1 提升 10倍的速度。我们在 TiDB v6.5 快速加索引模式已经 GA。
+   这里说明一下从低版本升级上来，的一些检查事项：
+   **TiDB 配置参数**：
+
+- [`temp-dir`](/tidb-configuration-file#temp-dir-new-in-v630) 这个参数用来指定快速加索引模式执行本地磁盘路径。
+    - 对于 On Premises 用户， 需要用户提前挂载好 SSD 磁盘，配置好相应路径，然后进行升级操作，重启后检查 TiDB
+
+   ```sql
+
+mysql> SHOW CONFIG WHERE type = 'tidb' AND name = 'temp-dir';
++------+---------------------------------------------------------------------------------------------+----------+-----------+
+| Type | Instance                                                                                    | Name     | Value     |
++------+---------------------------------------------------------------------------------------------+----------+-----------+
+| tidb | tidb-2:4000 | temp-dir | /tmp/tidb |
+| tidb | tidb-1:4000 | temp-dir | /tmp/tidb |
+| tidb | tidb-0:4000 | temp-dir | /tmp/tidb |
++------+---------------------------------------------------------------------------------------------+----------+-----------+
+3 rows in set (0.52 sec)
+
+```
+
+   **注意：** 这个是一个配置参数，需要重启 TiDB 节点，上面 `Value` 字段查询出来值应该和用户设置的值应该一致。
+    - 对于 Cloud 用户，我们对于能够使用快速加索引功能的使用有一些限制：
+
+| 描述                    | 供应商 | TiDB CPU 规格      | 是否支持快速索引模式 | 备注   |
+|-----------------------|-----|------------------|------------|------|
+| TiDB cloud Dedicated  | AWS | 2C vCPU, 4C vCPU | 不支持        | 成本问题 |
+|                       |     | \>= 8C vCPU      | 支持         |      |
+|                       | GCP | ALL              | 不支持        |      |
+
+   TiDB 系统变量设置
+
+- [`tidb_ddl_enable_fast_reorg`](/system-variables.md#tidb_ddl_enable_fast_reorg-从-v630-版本开始引入)
+   这个系统变量在 TiDB v6.5 默认打开。
+- [`tidb_ddl_disk_quota`](/system-variables.md#tidb_ddl_disk_quota-从-v630-版本开始引入)
+   这个系统变量用来控制快速加索引方式本地磁盘能够使用的限额，对于 on Premises 用户来说可以根据实际情况增加这个值。