From 3e8de58e2e35c9e84006e978e5b868963a2135b0 Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 19 Oct 2022 15:44:19 +0800 Subject: [PATCH] review: fix format --- stale-read.md | 2 +- system-variables.md | 30 +++---- tidb-external-ts.md | 190 ++++++++++++++++++++++---------------------- 3 files changed, 113 insertions(+), 109 deletions(-) diff --git a/stale-read.md b/stale-read.md index 881285bdeae86..4d36cc0218d66 100644 --- a/stale-read.md +++ b/stale-read.md @@ -15,7 +15,7 @@ summary: 介绍 Stale Read 功能和使用场景。 ## 使用方法 -TiDB 提供语句级别与会话级别的 Stale Read 使用方式，具体使用方法如下： +TiDB 提供语句级别、会话级别以及全局级别的 Stale Read 使用方式，具体使用方法如下： - 语句级别： - 指定一个精确的时间点（**推荐**）：如需 TiDB 读取一个时间点上保证全局事务记录一致性的数据并且不破坏隔离级别，你可以指定这个时间点对应的时间戳。要使用该方式，请参阅 [`AS OF TIMESTAMP` 语法](/as-of-timestamp.md#语法方式)文档。 diff --git a/system-variables.md b/system-variables.md index 100bb8444a549..578b1ff9e991f 100644 --- a/system-variables.md +++ b/system-variables.md @@ -953,7 +953,7 @@ MPP 是 TiFlash 引擎提供的分布式计算框架，允许节点之间的数 - 作用域：GLOBAL - 是否持久化到集群：是 - 默认值：`ON` -- 这个变量用于控制是否让 TiDB 使用并发 DDL 语句。在开启并发 DDL 语句后，DDL 语句的执行流程有所改变，DDL 语句不容易被其他 DDL 语句阻塞，并且能够同时添加多个索引。 +- 这个变量用于控制是否让 TiDB 使用并发 DDL 语句。在开启并发 DDL 语句后，DDL 语句的执行流程有所改变，DDL 语句不容易被其他 DDL 语句阻塞，并且能够同时添加多个索引。 ### `tidb_enable_enhanced_security` @@ -966,6 +966,20 @@ MPP 是 TiFlash 引擎提供的分布式计算框架，允许节点之间的数 - `RESTRICTED_VARIABLES_ADMIN`：能够在 `SHOW [GLOBAL] VARIABLES` 和 `SET` 命令中查看和设置包含敏感内容的变量。 - `RESTRICTED_USER_ADMIN`：能够阻止其他用户更改或删除用户帐户。 +### `tidb_enable_external_ts_read` 从 v6.4.0 版本开始引入 + +- 作用域：SESSION | GLOBAL +- 是否持久化到集群：是 +- 默认值：`OFF` +- 当此变量设置为 `ON` 时，TiDB 会读取 [`tidb_external_ts`](#tidb_external_ts-从-v640-版本开始引入) 指定时间戳前的历史数据。 + +### `tidb_external_ts` 从 v6.4.0 版本开始引入 + +- 作用域：GLOBAL +- 是否持久化到集群：是 +- 默认值：`0` +- 当 [`tidb_enable_external_ts_read`](#tidb_enable_external_ts_read-从-v640-版本开始引入) 设置为 `ON` 时，TiDB 会依据该变量指定的时间戳读取历史数据。 + ### `tidb_restricted_read_only` 从 v5.2.0 版本开始引入 - 作用域：GLOBAL @@ -2705,17 +2719,3 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) - 是否持久化到集群：是 - 默认值：`ON` - 这个变量用于控制计算窗口函数时是否采用高精度模式。 - -### tidb_external_ts 从 v6.4.0 版本开始引入 - -- 作用域：GLOBAL -- 是否持久化到集群：是 -- 默认值：`0` -- 当 [`tidb_enable_external_ts_read`](#tidb_enable_external_ts_read-从-v640-版本开始引入) 设置为 `ON` 时，TiDB 会依据该时间戳读取历史数据。 - -### tidb_enable_external_ts_read 从 v6.4.0 版本开始引入 - -- 作用域：SESSION | GLOBAL -- 是否持久化到集群：是 -- 默认值：`OFF` -- 当此变量设置为 `ON` 时，TiDB 会读取 [`tidb_external_ts`](#tidb_external_ts-从-v640-版本开始引入) 指定时间戳前的历史数据。 \ No newline at end of file diff --git a/tidb-external-ts.md b/tidb-external-ts.md index be9f71912f05f..955c43d8f244b 100644 --- a/tidb-external-ts.md +++ b/tidb-external-ts.md @@ -9,110 +9,114 @@ summary: 了解如何通过系统变量 `tidb_external_ts` 读取历史数据。 > **警告：** > -> 目前 Stale Read 特性无法和 TiFlash 一起使用。如果你在查询时将 [`tidb_enable_external_ts_read`](/system-variables.md#tidb_enable_external_ts_read-从-v640-版本开始引入) 设置为 `ON` 并且 TiDB 可能从 TiFlash 副本读取数据，你可能会遇到 `ERROR 1105 (HY000): stale requests require tikv backend` 报错信息。 +> 目前 Stale Read 特性无法和 TiFlash 一起使用。如果你在查询时将 [`tidb_enable_external_ts_read`](/system-variables.md#tidb_enable_external_ts_read-从-v640-版本开始引入) 设置为 `ON`，并且 TiDB 可能从 TiFlash 副本读取数据，你可能会遇到 `ERROR 1105 (HY000): stale requests require tikv backend` 报错信息。 > > 要解决该问题，你需要为使用 Stale Read 特性的查询禁用 TiFlash 副本。要禁用 TiFlash 副本，你可以使用以下任一方法： > -> + 通过设置变量来禁用 TiFlash 副本 `SET SESSION tidb_isolation_read_engines='tidb,tikv'`。 -> + 使用 [`READ_FROM_STORAGE`](/optimizer-hints.md#read_from_storagetiflasht1_name--tl_name--tikvt2_name--tl_name-) 强制 TiDB 从 TiKV 读取数据。 +> - 通过设置 `tidb_isolation_read_engines` 变量来禁用 TiFlash 副本 `SET SESSION tidb_isolation_read_engines='tidb,tikv'`。 +> - 使用 [`READ_FROM_STORAGE`](/optimizer-hints.md#read_from_storagetiflasht1_name--tl_name--tikvt2_name--tl_name-) hint 强制 TiDB 从 TiKV 读取数据。 ## 场景介绍 通过配置让 TiDB 能够读取某一固定时间点的历史数据对于 TiCDC 等数据同步工具非常有用。在数据同步工具完成了某一时间点前的数据同步之后，可以通过设置下游 TiDB 的 `tidb_external_ts` 系统变量，使得下游 TiDB 的请求能够读取到该时间点前的数据。这将避免在同步过程中，下游 TiDB 读取到尚未完全同步而不一致的数据。 -## 示例 +## 功能介绍 + +系统变量 [`tidb_external_ts`](/system-variables.md#tidb_external_ts-从-v640-版本开始引入) 用于指定启用 `tidb_enable_external_ts_read` 时，读取历史数据使用的时间戳。 -系统变量 [`tidb_external_ts`](/system-variables.md#tidb_external_ts-从-v640-版本开始引入) 用于指定该功能启用时，读取历史数据使用的时间戳。 +系统变量 [`tidb_enable_external_ts_read`](/system-variables.md#tidb_enable_external_ts_read-从-v640-版本开始引入) 控制着是否在当前会话或全局启用读取历史数据的功能。默认值为 `OFF`，这意味着该功能关闭，并且设置 `tidb_external_ts` 没有作用。当该变量被全局地设置为 `ON` 时，所有的请求都将读取到 `tidb_external_ts` 指定时间之前的历史数据。如果 `tidb_enable_external_ts_read` 仅在某一会话被设置为 `ON`，则只有该会话中的请求会读取到历史数据。 -系统变量 [`tidb_enable_external_ts_read`](/system-variables.md#tidb_enable_external_ts_read-从-v640-版本开始引入) 控制着是否在当前会话或全局启用该功能。默认值为 `OFF`，这意味着该功能关闭，并且 `tidb_external_ts` 没有作用。当该变量被全局地设置为 `ON`，所有的请求都将读取到 `tidb_external_ts` 指定时间之前的历史数据。如果 `tidb_enable_external_ts_read` 仅在某一会话被设置为 `ON`，则只有该会话中的请求会读取到历史数据。 +当 `tidb_enable_external_ts_read` 被设置为 `ON` 时，TiDB 会进入只读模式，任何写请求都会失败并且返回错误 `ERROR 1836 (HY000): Running in read-only mode`。 -当 `tidb_enable_external_ts_read` 被设置为 `ON` 时，TiDB 会进入只读模式。任何写请求都会失败并且返回错误 `ERROR 1836 (HY000): Running in read-only mode`. +## 示例 以下是一个使用该功能的示例： -```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) -``` \ No newline at end of file +1. 创建一个表后，在表中插入几行数据： + + ```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) + ``` + +2. 查看表中的数据： + + ```sql + SELECT * FROM t; + ``` + + ``` + +------+ + | c | + +------+ + | 1 | + | 2 | + | 3 | + +------+ + 3 rows in set (0.00 sec) + ``` + +3. 将 `tidb_external_ts` 设置为 `@@tidb_current_ts`： + + ```sql + START TRANSACTION; + SET GLOBAL tidb_external_ts = @@tidb_current_ts; + COMMIT; + ``` + +4. 插入新的一行并确认新的一行已经被插入： + + ```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) + ``` + +5. 将 `tidb_enable_external_ts_read` 设置为 `ON` 后，再次查询表中的数据： + + ```sql + SET tidb_enable_external_ts_read = ON; + SELECT * FROM t; + ``` + + ``` + +------+ + | c | + +------+ + | 1 | + | 2 | + | 3 | + +------+ + 3 rows in set (0.00 sec) + ``` + + 因为 `tidb_external_ts` 被设置为插入这一行之前的时间，在启动 `tidb_enable_external_ts_read` 后，将读取不到新插入的行。