tidb: add document for external timestamp read

TOC.md

@@ -237,6 +237,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

@@ -27,10 +27,16 @@ If a transaction only involves read operations and is tolerant of data staleness
 
 ## Usages
 
-TiDB provides the methods of performing Stale Read at the statement level and the session level as follows:
+TiDB provides the methods of performing Stale Read at the statement level, the session level and the global level as follows:
 
 - Statement level
     - Specifying an exact point in time (**recommended**): If you need TiDB to read data that is globally consistent from a specific point in time without violating the isolation level, you can specify the corresponding timestamp of that point in time in the query statement. For detailed usage, see [`AS OF TIMESTAMP` clause](/as-of-timestamp.md#syntax).
     - 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).
+
+<CustomContent platform="tidb">
+
+Besides, TiDB provides a way to specify an exact point in time by setting the [`tidb_external_ts`](/system-variables.md#tidb_external_ts-new-in-v640) system variable on session or global level. For detailed usage, refer to [Perform Stale Read Using `tidb_external_ts`](/tidb-external-ts.md).
+
+</CustomContent>

system-variables.md

@@ -884,7 +884,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a
 - This variable only applies to optimistic transactions. For pessimistic transactions, use [`tidb_constraint_check_in_place_pessimistic`](#tidb_constraint_check_in_place_pessimistic-new-in-v630) instead.
 - When this variable is set to `OFF`, checking for duplicate values in unique indexes is deferred until the transaction commits. This helps improve performance but might be an unexpected behavior for some applications. See [Constraints](/constraints.md#optimistic-transactions) for details.
 
-    - When setting `tidb_constraint_check_in_place` to `OFF` and using optimistic transactions：
+    - When setting `tidb_constraint_check_in_place` to `OFF` and using optimistic transactions:
 
         ```sql
         tidb> create table t (i int key);
@@ -922,7 +922,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a
 
 - When this variable is disabled, committing a pessimistic transaction might return a `Write conflict` or `Duplicate entry` error. When such an error occurs, TiDB rolls back the current transaction.
 
-    - When setting `tidb_constraint_check_in_place_pessimistic` to `OFF` and using pessimistic transactions：
+    - When setting `tidb_constraint_check_in_place_pessimistic` to `OFF` and using pessimistic transactions:
 
         {{< copyable "sql" >}}
 
@@ -946,7 +946,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a
         ERROR 1062 : Duplicate entry '1' for key 'PRIMARY'
         ```
 
-    - When setting `tidb_constraint_check_in_place_pessimistic` to `ON` and using pessimistic transactions：
+    - When setting `tidb_constraint_check_in_place_pessimistic` to `ON` and using pessimistic transactions:
 
         ```sql
         set @@tidb_constraint_check_in_place_pessimistic=ON;
@@ -1338,6 +1338,22 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a
 
 </CustomContent>
 
+### tidb_enable_external_ts_read <span class="version-mark">New in v6.4.0</span>
+
+- Scope: SESSION | GLOBAL
+- Persists to cluster: Yes
+- Type: Boolean
+- Default value: `OFF`
+- If this variable is set to `ON`, TiDB reads data with the timestamp specified by [`tidb_external_ts`](#tidb_external_ts-new-in-v640).
+
+### tidb_external_ts <span class="version-mark">New in v6.4.0</span>
+
+- Scope: GLOBAL
+- Persists to cluster: Yes
+- Type: Integer
+- Default value: `0`
+- If [`tidb_enable_external_ts_read`](#tidb_enable_external_ts_read-new-in-v640) is set to `ON`, TiDB reads data with the timestamp specified by this variable.
+
 ### tidb_enable_fast_analyze
 
 > **Warning:**
@@ -2238,7 +2254,8 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified
 
 ### `tidb_last_plan_replayer_token` <span class="version-mark">New in v6.3.0</span>
 
-- Scope：SESSION
+- Scope: SESSION
+- Persists to cluster: No
 - Type: String
 - This variable is read-only and is used to obtain the result of the last `PLAN REPLAYER DUMP` execution in the current session.
 

tidb-external-ts.md

@@ -0,0 +1,122 @@
+---
+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
+
+To support reading the historical data, TiDB v6.4.0 introduces a system variable [`tidb_external_ts`](/system-variables.md#tidb_external_ts-new-in-v640). This document describes how to read historical data through this system variable, including detailed usage examples.
+
+> **Warning:**
+>
+> Currently, you cannot use Stale Read together with TiFlash. If you enable [`tidb_enable_external_ts_read`](/system-variables.md#tidb_enable_external_ts_read-new-in-v640) in a query and TiDB might read data from TiFlash replicas, you might encounter the error message `ERROR 1105 (HY000): stale requests require tikv backend`.
+>
+> To fix this problem, disable TiFlash replicas for your Stale Read query by performing one of the following operations:
+>
+> - Use the `tidb_isolation_read_engines` variable to disable TiFlash replicas: `SET SESSION tidb_isolation_read_engines='tidb,tikv'`.
+> - Use the [READ_FROM_STORAGE](/optimizer-hints.md#read_from_storagetiflasht1_name--tl_name--tikvt2_name--tl_name-) hint to enforce TiDB to read data from TiKV.
+
+## Scenarios
+
+Read historical data from a specified point in time is very useful for data replication tools such as TiCDC. After the data replication tool completes the data replication before a certain point in time, you can set the `tidb_external_ts` system variable of the downstream TiDB to read the data before that point in time. This prevents the data inconsistency caused by data replication.
+
+## Feature description
+
+The system variable [`tidb_external_ts`](/system-variables.md#tidb_external_ts-new-in-v640) specifies the timestamp of the historical data to be read when `tidb_enable_external_ts_read` is enabled.
+
+The system variable [`tidb_enable_external_ts_read`](/system-variables.md#tidb_enable_external_ts_read-new-in-v640) controls whether to read historical data in the current session or globally. The default value is `OFF`, which means the feature of reading historical data is disabled, and the `tidb_external_ts` value is ignored. When `tidb_enable_external_ts_read` is set to `ON` globally, all queries read historical data before the time specified by `tidb_external_ts`. If `tidb_enable_external_ts_read` is set to `ON` only for a certain session, only queries in that session read historical data.
+
+When the `tidb_enable_external_ts_read` is enabled, TiDB becomes read-only. All write queries will fail with an error like `ERROR 1836 (HY000): Running in read-only mode`.
+
+## Usage examples
+
+This section describes how to use the `tidb_external_ts` variable to read historical data with examples.
+
+1. Create a table and insert some rows into the table:
+
+    ```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. View the data in the table:
+
+    ```sql
+    SELECT * FROM t;
+    ```
+
+    ```
+    +------+
+    | c    |
+    +------+
+    |    1 |
+    |    2 |
+    |    3 |
+    +------+
+    3 rows in set (0.00 sec)
+    ```
+
+3. Set `tidb_external_ts` to `@@tidb_current_ts`:
+
+    ```sql
+    START TRANSACTION;
+    SET GLOBAL tidb_external_ts=@@tidb_current_ts;
+    COMMIT;
+    ```
+
+4. Insert a new row and confirm that it is inserted:
+
+    ```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. Set `tidb_enable_external_ts_read` to `ON` and then view data in the table:
+
+    ```sql
+    SET tidb_enable_external_ts_read=ON;
+    SELECT * FROM t;
+    ```
+
+    ```
+    +------+
+    | c    |
+    +------+
+    |    1 |
+    |    2 |
+    |    3 |
+    +------+
+    3 rows in set (0.00 sec)
+    ```
+
+    Because `tidb_external_ts` is set to the timestamp before the new row is inserted, the newly inserted row is not returned after the `tidb_enable_external_ts_read` is enabled.