tidb: add document for external timestamp read

Signed-off-by: YangKeao <yangkeao@chunibyo.icu>

TOC.md

@@ -230,6 +230,7 @@
       - [Stale Read 使用场景介绍](/stale-read.md)
       - [使用 `AS OF TIMESTAMP` 语法读取历史数据](/as-of-timestamp.md)
       - [使用系统变量 `tidb_read_staleness` 读取历史数据](/tidb-read-staleness.md)
+      - [使用系统变量 `tidb_external_ts` 读取历史数据](/tidb-external-ts.md)
     - [使用系统变量 `tidb_snapshot` 读取历史数据](/read-historical-data.md)
   - 最佳实践
     - [TiDB 最佳实践](/best-practices/tidb-best-practices.md)

stale-read.md

@@ -22,3 +22,5 @@ TiDB 提供语句级别与会话级别的 Stale Read 使用方式，具体使用
     - 指定时间范围：如需 TiDB 读取在一个时间范围内尽可能新的数据并且不破坏隔离级别，你可以指定一个时间范围。在指定时间范围内，TiDB 会选择一个合适的时间戳，该时间戳能保证所访问的副本上不存在开始于这个时间戳之前且还没有提交的相关事务，即能保证在所访问的可用副本上可执行读取操作而且不会被阻塞。要使用该方式，请参阅 [`AS OF TIMESTAMP` 语法](/as-of-timestamp.md#语法方式)文档和该文档中 [`TIDB_BOUNDED_STALENESS` 函数](/as-of-timestamp.md#语法方式)部分的介绍。
 - 会话级别：
     - 指定时间范围：在会话级别中，如需 TiDB 在后续的查询中读取一个时间范围内尽可能新的数据并且不破坏隔离级别，你可以通过设置一个 session 变量 `tidb_read_staleness` 来指定一个时间范围。要使用该方式，请参阅[通过系统变量 `tidb_read_staleness` 读取历史数据](/tidb-read-staleness.md)。
+
+除此以外，你也可以通过设置系统变量 `tidb_external_ts` 来在某一会话或全局范围读取某一时间点前的历史数据。要使用该方式，请参阅[通过系统变量 `tidb_external_ts` 读取历史数据](/tidb-external-ts.md)。

system-variables.md

@@ -2705,3 +2705,18 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)
 - 是否持久化到集群：是
 - 默认值：`ON`
 - 这个变量用于控制计算窗口函数时是否采用高精度模式。
+
+
+### tidb_external_ts
+
+- 作用域: GLOBAL
+- 是否持久化到集群：是
+- 默认值: `0`
+- 当 `tidb_enable_external_ts_read` 设置为 `ON` 时, TiDB 会依据该时间戳读取历史数据。
+
+### tidb_enable_external_ts_read
+
+- 作用域: SESSION | GLOBAL
+- 是否持久化到集群：是
+- 默认值: `OFF`
+- 当此变量设置为 `ON` 时, TiDB 会读取 `tidb_external_ts` 指定时间戳前的历史数据。

tidb-external-ts.md

@@ -0,0 +1,106 @@
+---
+title: 通过系统变量 `tidb_external_ts` 读取历史数据
+summary: 了解如何通过系统变量 `tidb_external_ts` 读取历史数据。
+---
+
+# 通过系统变量 `tidb_external_ts` 读取历史数据
+
+为了支持出读取历史版本数据，TiDB 从 6.4 版本起引入了一个新的系统变量 `tidb_external_ts`。本文档介绍如何通过该系统变量读取历史数据，其中包括具体的操作流程。
+
+
+## 场景介绍
+
+通过配置让 TiDB 能够读取某一固定时间点的历史数据对于 TiCDC 等数据同步工具非常有用。在数据同步工具完成了某一时间点前的数据同步之后，可以通过设置下游 TiDB 的 `tidb_external_ts` 系统变量，使得下游 TiDB 的请求能够读取到该时间点前的数据。这将避免在同步过程中，下游 TiDB 读取到尚未完全同步而不一致的数据。
+
+## 示例
+
+系统变量 `tidb_external_ts` 用于指定该功能启用时，读取历史数据使用的时间戳。
+
+系统变量 `tidb_enable_external_ts_read` 控制着是否在当前会话或全局启用该功能。默认值为 `OFF`，这意味着该功能关闭，并且 `tidb_external_ts` 没有作用。当该变量被全局地设置为 `ON`，所有的请求都将读取到 `tidb_external_ts` 指定时间之前的历史数据。如果 `tidb_enable_external_ts_read` 仅在某一会话被设置为 `ON`，则只有该会话中的请求会读取到历史数据。
+
+以下是一个使用该功能的示例：
+
+```sql
+create table t (c int);
+```
+
+```
+Query OK, 0 rows affected (0.01 sec)
+```
+
+```sql
+insert into t values (1), (2), (3);
+```
+
+```
+Query OK, 3 rows affected (0.00 sec)
+```
+
+查看表中的数据:
+
+```sql
+select * from t;
+```
+
+```
++------+
+| c    |
++------+
+|    1 |
+|    2 |
+|    3 |
++------+
+3 rows in set (0.00 sec)
+```
+
+将 `tidb_external_ts` 设置为 `@@tidb_current_ts`:
+
+```sql
+start transaction;set global tidb_external_ts=@@tidb_current_ts;commit;
+```
+
+插入新的一行:
+
+```sql
+insert into t values (4);
+```
+
+```
+Query OK, 1 row affected (0.001 sec)
+```
+
+确认新的一行已经被插入:
+
+```sql
+select * from t;
+```
+
+```
++------+
+| id   |
++------+
+|    1 |
+|    2 |
+|    3 |
+|    4 |
++------+
+4 rows in set (0.00 sec)
+```
+
+然而，因为 `tidb_external_ts` 被设置为插入这一行之前的时间，在将 `tidb_enable_external_ts_read` 启动后，将读取不到新插入的行:
+
+```sql
+set tidb_enable_external_ts_read=ON;
+select * from t;
+```
+
+```
++------+
+| c    |
++------+
+|    1 |
+|    2 |
+|    3 |
++------+
+3 rows in set (0.00 sec)
+```