tidb: add document for external timestamp read

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

TOC-tidb-cloud.md

@@ -360,6 +360,7 @@
         - [Usage Scenarios of Stale Read](/stale-read.md)
         - [Perform Stale Read Using `As OF TIMESTAMP`](/as-of-timestamp.md)
         - [Perform Stale Read Using `tidb_read_staleness`](/tidb-read-staleness.md)
+        - [Perform Stale Read Using `tidb_external_ts`](/tidb-external-ts.md)
       - [Use the `tidb_snapshot` System Variable](/read-historical-data.md)
     - System Tables
       - [`mysql`](/mysql-schema.md)

TOC.md

@@ -235,6 +235,7 @@
       - [Usage Scenarios of Stale Read](/stale-read.md)
       - [Perform Stale Read Using `As OF TIMESTAMP`](/as-of-timestamp.md)
       - [Perform Stale Read Using `tidb_read_staleness`](/tidb-read-staleness.md)
+      - [Perform Stale Read Using `tidb_external_ts`](/tidb-external-ts.md)
     - [Use the `tidb_snapshot` System Variable](/read-historical-data.md)
   - Best Practices
     - [Use TiDB](/best-practices/tidb-best-practices.md)

stale-read.md

@@ -34,3 +34,5 @@ TiDB provides the methods of performing Stale Read at the statement level and th
     - Specifying a time range: If you need TiDB to read the data as new as possible within a time range without violating the isolation level, you can specify the time range in the query statement. Within the specified time range, TiDB selects a suitable timestamp to read the corresponding data. "Suitable" means there are no transactions that start before this timestamp and have not been committed on the accessed replica, that is, TiDB can perform read operations on the accessed replica and the read operations are not blocked. For detailed usage, refer to the introduction of the [`AS OF TIMESTAMP` Clause](/as-of-timestamp.md#syntax) and the [`TIDB_BOUNDED_STALENESS` function](/as-of-timestamp.md#syntax).
 - Session level
     - Specifying a time range: In a session, if you need TiDB to read the data as new as possible within a time range in subsequent queries without violating the isolation level, you can specify the time range by setting the `tidb_read_staleness` system variable. For detailed usage, refer to [`tidb_read_staleness`](/tidb-read-staleness.md).
+
+Besides, TiDB also provides a way to specify an exact point in time through `tidb_external_ts` variable on session or global level. For detailed usage, refer to [`tidb_external_ts`](/tidb-external-ts.md)

system-variables.md

@@ -3509,3 +3509,19 @@ Internally, the TiDB parser transforms the `SET TRANSACTION ISOLATION LEVEL [REA
 - Type: Boolean
 - Default value: `ON`
 - This variable controls whether to use the high precision mode when computing the window functions.
+
+### tidb_external_ts
+
+- Scope: GLOBAL
+- Persists to cluster: Yes
+- Type: Integer
+- Default value: `0`
+- If `tidb_enable_external_ts_read` is set to `ON`, TiDB will read data with this timestamp.
+
+### tidb_enable_external_ts_read
+
+- Scope: SESSION | GLOBAL
+- Persists to cluster: Yes
+- Type: Boolean
+- Default value: `OFF`
+- If this variable is set to `ON`, TiDB will read data with the timestamp specified by `tidb_external_ts`.

tidb-external-ts.md

@@ -0,0 +1,116 @@
+---
+title: Read Historical Data Using the `tidb_external_ts` Variable
+summary: Learn how to read historical data using the `tidb_external_ts` variable.
+---
+
+# Read Historical Data Using the `tidb_external_ts` Variable
+
+This document describes how to perform the [Stale Read](/stale-read.md) feature using the `tidb_external_ts` variable to read historical data in TiDB, including specific usage examples.
+
+> **Warning:**
+>
+> Currently, you cannot use Stale Read together with TiFlash. If your SQL query contains the `AS OF TIMESTAMP` clause and TiDB might read data from TiFlash replicas, you might encounter an error with a message like `ERROR 1105 (HY000): stale requests require tikv backend`.
+>
+> To fix the problem, disable TiFlash replicas for your Stale Read query. To do that, perform one of the following operations:
+>
+> - Use the `set session tidb_isolation_read_engines='tidb,tikv'` variable.
+> - Use the [hint](/optimizer-hints.md#read_from_storagetiflasht1_name--tl_name--tikvt2_name--tl_name-) to enforce TiDB to read data from TiKV.
+
+## Scenarios
+
+Read with an absolute timestamp is especially useful for data replication software (for example TiCDC). After the data replication software ensures that all data before a timestamp have been synchronized to the downstream, it can set the `tidb_external_ts` for the downstream TiDB, so that the read queries of the downstream TiDB can read consistent data.
+
+## Usage
+
+The `tidb_external_ts` variable is used to specify the timestamp of the historical data to be read. The value of the variable is a timestamp which can be obtained through `tidb_current_ts` variable in transaction, or an external utilities.
+
+The `tidb_enable_external_ts_read` controls whether TiDB will read with the `tidb_external_ts` variable. The default value is `OFF`, which means that the `tidb_external_ts` variable is ignored. If `tidb_enable_external_ts_read` is set `ON` globally, all the queries will read historical data. If `tidb_enable_external_ts_read` is set `ON` for a session, only the queries in the session will read historical data.
+
+When `tidb_enable_external_ts_read` is enabled, TiDB becomes read-only. All the write queries will fail with an error like `ERROR 1836 (HY000): Running in read-only mode`.
+
+Here is an example:
+
+```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)
+```
+
+View the data in the table:
+
+```sql
+select * from t;
+```
+
+```
++------+
+| c    |
++------+
+|    1 |
+|    2 |
+|    3 |
++------+
+3 rows in set (0.00 sec)
+```
+
+Set the `tidb_external_ts` to be `@@tidb_current_ts`:
+
+```sql
+start transaction;set global tidb_external_ts=@@tidb_current_ts;commit;
+```
+
+Insert a new row:
+
+```sql
+insert into t values (4);
+```
+
+```
+Query OK, 1 row affected (0.001 sec)
+```
+
+Confirm that the new row is inserted:
+
+```sql
+select * from t;
+```
+
+```
++------+
+| id   |
++------+
+|    1 |
+|    2 |
+|    3 |
+|    4 |
++------+
+4 rows in set (0.00 sec)
+```
+
+However, as `tidb_external_ts` is set to the timestamp before inserting the new row. After turning on the `tidb_enable_external_ts_read`, the new row will not be read:
+
+```sql
+set tidb_enable_external_ts_read=ON;
+select * from t;
+```
+
+```
++------+
+| c    |
++------+
+|    1 |
+|    2 |
+|    3 |
++------+
+3 rows in set (0.00 sec)
+```