update async commit related documentation

releases/release-5.0.0-rc.md

@@ -103,7 +103,7 @@ However, when async commit is enabled, the external consistency of transactions
 
 Users can enable this feature by setting the global variable `tidb_enable_async_commit = ON`.
 
-+ [User document](/system-variables.md#tidb_enable_async_commit-new-in-v500-rc)
++ [User document](/system-variables.md#tidb_enable_async_commit-new-in-v50-rc)
 + Related issue: [#8316](https://github.com/tikv/tikv/issues/8316)
 
 ### Improve the optimizer's stability in index selection (experimental)

sql-statements/sql-statement-start-transaction.md

@@ -14,7 +14,11 @@ In the absence of a `START TRANSACTION` statement, every statement will by defau
 
 **BeginTransactionStmt:**
 
-![BeginTransactionStmt](/media/sqlgram/BeginTransactionStmt.png)
+```ebnf+diagram
+BeginTransactionStmt ::= 
+    'BEGIN' ( 'PESSIMISTIC' | 'OPTIMISTIC' )?
+|   'START' 'TRANSACTION' ( 'READ' ( 'WRITE' | 'ONLY' ( 'WITH' 'TIMESTAMP' 'BOUND' TimestampBound )? ) | 'WITH' 'CONSISTENT' 'SNAPSHOT' | 'WITH' 'CAUSAL' 'CONSISTENCY' 'ONLY' )?
+```
 
 ## Examples
 
@@ -43,3 +47,4 @@ Query OK, 0 rows affected (0.01 sec)
 * [COMMIT](/sql-statements/sql-statement-commit.md)
 * [ROLLBACK](/sql-statements/sql-statement-rollback.md)
 * [BEGIN](/sql-statements/sql-statement-begin.md)
+* [START TRANSACTION WITH CAUSAL CONSISTENCY ONLY](/transaction-overview.md#causal-consistency)

system-variables.md

@@ -356,23 +356,25 @@ Constraint checking is always performed in place for pessimistic transactions (d
 >
 > Currently, this feature is incompatible with TiDB Binlog in some scenarios and might cause semantic changes on a transaction. For more usage precautions of this feature, refer to [Incompatibility issues about transaction semantic](https://github.com/pingcap/tidb/issues/21069) and [Incompatibility issues about TiDB Binlog](https://github.com/pingcap/tidb/issues/20996).
 
-### tidb_enable_async_commit <span class="version-mark">New in v5.0.0-rc</span>
+### tidb_enable_async_commit <span class="version-mark">New in v5.0 RC</span>
 
-> **Warning:**
+- Scope: SESSION | GLOBAL
+- Default value: `ON` for newly created clusters. If your cluster before upgrade was v5.0 RC or later, the variable value stays unchanged. If your cluster before upgrade was v4.0 or earlier, the variable value defaults to `OFF` after the upgrade.
+- This variable controls whether to enable the async commit feature for the second phase of the two-phase transaction commit to perform asynchronously in the background. Enabling this feature can reduce the latency of transaction commit.
+
+> **Note:**
 >
-> Async commit is still an experimental feature. It is not recommended to use this feature in the production environment. Currently, the following incompatible issues are found, and be aware of them if you need to use this feature:
+> If you have enabled TiDB Binlog, enabling this variable cannot improve the performance. To improve the performance, it is recommended to use [TiCDC](/ticdc/ticdc-overview.md) instead.
 
-> - This feature is incompatible with [TiCDC](/ticdc/ticdc-overview.md) and might cause TiCDC to run abnormally.
-> - This feature is incompatible with [Compaction Filter](/tikv-configuration-file.md#enable-compaction-filter-new-in-v500-rc). If you use the two features at the same time, write loss might occur.
-> - This feature is incompatible with TiDB Binlog and does not take effect when TiDB Binlog is enabled.
+### tidb_enable_1pc <span class="version-mark">New in v5.0 RC</span>
 
 - Scope: SESSION | GLOBAL
-- Default value: OFF
-- This variable controls whether to enable the async commit feature for the second phase of the two-phase transaction commit to perform asynchronously in the background. Enabling this feature can reduce the latency of transaction commit.
+- Default value: `ON` for newly created clusters. If your cluster before upgrade was v5.0 RC or later, the variable value stays unchanged. If your cluster before upgrade was v4.0 or earlier, the variable value defaults to `OFF` after the upgrade.
+- This variable is used to specify whether to enable the one-phase commit feature for transactions that only affect one Region. Compared with the often-used two-phase commit, one-phase commit can greatly reduce the latency of transaction commit and increase the throughput.
 
-> **Warning:**
+> **Note:**
 >
-> When async commit is enabled, the external consistency of transactions cannot be guaranteed. For details, refer to [`tidb_guarantee_external_consistency`](#tidb_guarantee_external_consistency-new-in-v500-rc).
+> If you have enabled TiDB Binlog, enabling this variable cannot improve the performance. To improve the performance, it is recommended to use [TiCDC](/ticdc/ticdc-overview.md) instead.
 
 ### tidb_enable_cascades_planner
 
@@ -635,12 +637,6 @@ For a system upgraded to v5.0.0-rc from an earlier version, if you have not modi
     - `txn_mode`: The transactional mode. Value options are `OPTIMISTIC` and `PESSIMISTIC`.
     - `sql`: The SQL statement corresponding to the current query.
 
-### tidb_guarantee_external_consistency <span class="version-mark">New in v5.0.0-rc</span>
-
-- Scope: SESSION | GLOBAL
-- Default value: OFF
-- This variable controls whether the external consistency needs to be guaranteed when the async commit <!-- and one-phase commit--> feature is enabled. When this option is disabled, if the modifications made in two transactions do not have overlapping parts, the commit order that other transactions observe might not be consistent with the actual commit order. When the async commit <!-- or one-phase commit--> feature is disabled, the external consistency can be guaranteed no matter whether this configuration is enabled or disabled.
-
 ### tidb_hash_join_concurrency
 
 > **Warning:**

tidb-configuration-file.md

@@ -485,19 +485,6 @@ The Plan Cache configuration of the `PREPARE` statement.
 - The threshold of the TiKV load. If the TiKV load exceeds this threshold, more `batch` packets are collected to relieve the pressure of TiKV. It is valid only when the value of `tikv-client.max-batch-size` is greater than `0`. It is recommended not to modify this value.
 - Default value: `200`
 
-## tikv-client.async-commit <span class="version-mark">New in v5.0.0-rc</span>
-
-### `keys-limit`
-
-- Specifies the upper limit of the number of keys in an async commit transaction. The async commit feature is **NOT** suitable for transactions that are too large. Transactions that exceed this limit will use the two-phase commit.
-- Default value: `256`
-
-### `total-key-size-limit`
-
-- Specifies the upper limit of the total size of keys in an async commit transaction. The async commit feature is **NOT** suitable for transactions in which the involved key ranges are too long. Transactions that exceed this limit will use the two-phase commit.
-- Default value: `4096`
-- Unit: byte
-
 ## tikv-client.copr-cache <span class="version-mark">New in v4.0.0</span>
 
 This section introduces configuration items related to the Coprocessor Cache feature.

transaction-overview.md

@@ -42,6 +42,12 @@ START TRANSACTION;
 START TRANSACTION WITH CONSISTENT SNAPSHOT;
 ```
 
+{{< copyable "sql" >}}
+
+```sql
+START TRANSACTION WITH CAUSAL CONSISTENCY ONLY;
+```
+
 If the current session is in the process of a transaction when one of these statements is executed, TiDB automatically commits the current transaction before starting a new transaction.
 
 > **Note:**
@@ -298,3 +304,73 @@ TiDB previously limited the total number of key-value pairs for a single transac
 > Usually, TiDB Binlog is enabled to replicate data to the downstream. In some scenarios, message middleware such as Kafka is used to consume binlogs that are replicated to the downstream.
 >
 > Taking Kafka as an example, the upper limit of Kafka's single message processing capability is 1 GB. Therefore, when `txn-total-size-limit` is set to more than 1 GB, it might happen that the transaction is successfully executed in TiDB, but the downstream Kafka reports an error. To avoid this situation, you need to decide the actual value of `txn-total-size-limit` according to the limit of the end consumer. For example, if Kafka is used downstream, `txn-total-size-limit` must not exceed 1 GB.
+
+## Causal consistency
+
+> **Note:**
+>
+> Transactions with causal consistency take effect only when the async commit and one-phase commit features are enabled. For details of the two features, see [`tidb_enable_async_commit`](/system-variables.md#tidb_enable_async_commit-new-in-v50-rc) and [`tidb_enable_1pc`](/system-variables.md#tidb_enable_1pc-new-in-v50-rc).
+
+TiDB supports enabling causal consistency for transactions. Transactions with causal consistency, when committed, do not need to get timestamp from PD and have lower commit latency. The syntax to enable causal consistency is as follows:
+
+{{< copyable "sql" >}}
+
+```sql
+START TRANSACTION WITH CAUSAL CONSISTENCY ONLY;
+```
+
+By default, TiDB guarantees linear consistency. In the case of linear consistency, if transaction 2 is committed after transaction 1 is committed, logically, transaction 2 should occur after transaction 1. Causal consistency is weaker than linear consistency. In the case of causal consistency, the commit order and occurrence order of two transactions can be guaranteed consistent only when the data locked or written by transaction 1 and transaction 2 have an intersection, which means that the two transactions have a causal relationship known to the database. Currently, TiDB does not support passing in external causal relationship.
+
+Two transactions with causal consistency enabled have the following characteristics:
+
++ [Transactions with potential causal relationship have the consistent logical order and physical commit order](#transactions-with-potential-causal-relationship-have-the-consistent-logical-order-and-physical-commit-order)
++ [Transactions with no causal relationship do not guarantee consistent logical order and physical commit order](#transactions-with-no-causal-relationship-do-not-guarantee-consistent-logical-order-and-physical-commit-order)
++ [Reads without lock do not create causal relationship](#reads-without-lock-do-not-create-causal-relationship)
+
+### Transactions with potential causal relationship have the consistent logical order and physical commit order
+
+Assume that both transaction 1 and transaction 2 adopt causal consistency and have the following statements executed:
+
+| Transaction 1 | Transaction 2 |
+|-------|-------|
+| START TRANSACTION WITH CAUSAL CONSISTENCY ONLY | START TRANSACTION WITH CAUSAL CONSISTENCY ONLY |
+| x = SELECT v FROM t WHERE id = 1 FOR UPDATE | |
+| UPDATE t set v = $(x + 1) WHERE id = 2 | |
+| COMMIT | |
+| | UPDATE t SET v = 2 WHERE id = 1 |
+| | COMMIT |
+
+In the example above, transaction 1 locks the `id = 1` record and transaction 2 modifies the `id = 1` record. Therefore, transaction 1 and transaction 2 have a potential causal relationship. Even with the causal consistency enabled, as long as transaction 2 is committed after transaction 1 is successfully committed, logically, transaction 2 must occur after transaction 1. Therefore, it is impossible that a transaction reads transaction 2's modification on the `id = 1` record without reading transaction 1's modification on the `id = 2` record.
+
+### Transactions with no causal relationship do not guarantee consistent logical order and physical commit order
+
+Assume that the initial values of `id = 1` and `id = 2` are both `0`. Assume that both transaction 1 and transaction 2 adopt causal consistency and have the following statements executed:
+
+| Transaction 1 | Transaction 2 | Transaction 3 |
+|-------|-------|-------|
+| START TRANSACTION WITH CAUSAL CONSISTENCY ONLY | START TRANSACTION WITH CAUSAL CONSISTENCY ONLY | |
+| UPDATE t set v = 3 WHERE id = 2 | | |
+| | UPDATE t SET v = 2 WHERE id = 1 | |
+| | | BEGIN |
+| COMMIT | | |
+| | COMMIT | |
+| | | SELECT v FROM t WHERE id IN (1, 2) |
+
+In the example above, transaction 1 does not read the `id = 1` record, so transaction 1 and transaction 2 have no causal relationship known to the database. With causal consistency enabled for the transactions, even if transaction 2 is committed after transaction 1 is committed in terms of physical time order, TiDB does not guarantee that transaction 2 logically occurs after transaction 1.
+
+If transaction 3 begins before transaction 1 is committed, and if transaction 3 reads the `id = 1` and `id = 2` records after transaction 2 is committed, transaction 3 might read the value of `id = 1` to be `2` but the value of `id = 2` to be `0`.
+
+### Reads without lock do not create causal relationship
+
+Assume that both transaction 1 and transaction 2 adopt causal consistency and have the following statements executed:
+
+| Transaction 1 | Transaction 2 |
+|-------|-------|
+| START TRANSACTION WITH CAUSAL CONSISTENCY ONLY | START TRANSACTION WITH CAUSAL CONSISTENCY ONLY |
+| | UPDATE t SET v = 2 WHERE id = 1 |
+| SELECT v FROM t WHERE id = 1 | |
+| UPDATE t set v = 3 WHERE id = 2 | |
+| | COMMIT |
+| COMMIT | |
+
+In the example above, reads without lock do not create causal relationship. Transaction 1 and transaction 2 have created write skew. In this case, it would have been unreasonable if the two transactions still had causal relationship. Therefore, the two transactions with causal consistency enabled have no definite logical order.