transactions: improve clarity of transactions (pingcap#3715)

* transactions: improve clarity of transactions

* Update pessimistic

* Update system-variables.md

Co-authored-by: Lilian Lee <lilin@pingcap.com>

* Update transaction-overview.md

Co-authored-by: Lilian Lee <lilin@pingcap.com>

* Update transaction-overview.md

Co-authored-by: Lilian Lee <lilin@pingcap.com>

* Update transaction-overview.md

Co-authored-by: Lilian Lee <lilin@pingcap.com>

* Update transaction-overview.md

Co-authored-by: Lilian Lee <lilin@pingcap.com>

* Update transaction-overview.md

Co-authored-by: Lilian Lee <lilin@pingcap.com>

* Update transaction-overview.md

Co-authored-by: Lilian Lee <lilin@pingcap.com>

optimistic-transaction.md

@@ -6,13 +6,13 @@ aliases: ['/docs/dev/optimistic-transaction/','/docs/dev/reference/transactions/
 
 # TiDB Optimistic Transaction Model
 
-This document introduces the principles of TiDB's optimistic transaction model and related features.
+With optimistic transactions, conflicting changes are detected as part of a transaction commit. This helps improve the performance when concurrent transactions are infrequently modifying the same rows, because the process of acquiring row locks can be skipped. In the case that concurrent transactions frequently modify the same rows (a conflict), optimistic transactions may perform worse than [Pessimistic Transactions](/pessimistic-transaction.md).
 
-In TiDB's optimistic transaction model, write-write conflicts are detected only at the two-phase transactional commit.
+Before enabling optimistic transactions, make sure that your application correctly handles that a `COMMIT` statement could return errors. If you are unsure of how your application handles this, it is recommended to instead use Pessimistic Transactions.
 
 > **Note:**
 >
-> Starting from v3.0.8, newly created TiDB clusters use the [pessimistic transaction model](/pessimistic-transaction.md) by default. However, this does not affect your existing cluster if you upgrade it from v3.0.7 or earlier to v3.0.8 or later. In other words, **only newly created clusters default to using the pessimistic transaction model**.
+> Starting from v3.0.8, TiDB uses the [pessimistic transaction model](/pessimistic-transaction.md) by default. However, this does not affect your existing cluster if you upgrade it from v3.0.7 or earlier to v3.0.8 or later. In other words, **only newly created clusters default to using the pessimistic transaction model**.
 
 ## Principles of optimistic transactions
 
@@ -35,14 +35,14 @@ To support distributed transactions, TiDB adopts two-phase commit (2PC) in optim
 
 4. The client issues a commit request.
 
-5. TiDB begins 2PC, and persist data in store while guaranteeing the atomicity of transactions.
+5. TiDB begins 2PC, and persists data in store while guaranteeing the atomicity of transactions.
 
     1. TiDB selects a Primary Key from the data to be written.
     2. TiDB receives the information of Region distribution from PD, and groups all keys by Region accordingly.
     3. TiDB sends prewrite requests to all TiKV nodes involved. Then, TiKV checks whether there are conflict or expired versions. Valid data is locked.
     4. TiDB receives all requests in the prewrite phase and the prewrite is successful.
     5. TiDB receives a commit version number from PD and marks it as `commit_ts`.
-    6. TiDB initiates the second commit to the TiKV node where Primary Key is located. TiKV checks the data, and clean the locks left in the prewrite phase.
+    6. TiDB initiates the second commit to the TiKV node where Primary Key is located. TiKV checks the data, and cleans the locks left in the prewrite phase.
     7. TiDB receives the message that reports the second phase is successfully finished.
 
 6. TiDB returns a message to inform the client that the transaction is successfully committed.
@@ -69,7 +69,7 @@ In the optimistic transaction model, transactions might fail to be committed bec
 
 ### Automatic retry
 
-If a write-write conflict occurs during the transaction commit, TiDB automatically retries the SQL statement that includes write operations. You can enable the automatic retry by setting `tidb_disable_txn_auto_retry` to `off` and set the retry limit by configuring `tidb_retry_limit`:
+If a write-write conflict occurs during the transaction commit, TiDB automatically retries the SQL statement that includes write operations. You can enable the automatic retry by setting `tidb_disable_txn_auto_retry` to `OFF` and set the retry limit by configuring `tidb_retry_limit`:
 
 ```toml
 # Whether to disable automatic retry. ("on" by default)
@@ -86,27 +86,27 @@ You can enable the automatic retry in either session level or global level:
     {{< copyable "sql" >}}
 
     ```sql
-    set @@tidb_disable_txn_auto_retry = off;
+    SET tidb_disable_txn_auto_retry = OFF;
     ```
 
     {{< copyable "sql" >}}
 
     ```sql
-    set @@tidb_retry_limit = 10;
+    SET tidb_retry_limit = 10;
     ```
 
 2. Global level:
 
     {{< copyable "sql" >}}
 
     ```sql
-    set @@global.tidb_disable_txn_auto_retry = off;
+    SET GLOBAL tidb_disable_txn_auto_retry = OFF;
     ```
 
     {{< copyable "sql" >}}
 
     ```sql
-    set @@global.tidb_retry_limit = 10;
+    SET GLOBAL tidb_retry_limit = 10;
     ```
 
 > **Note:**
@@ -138,8 +138,8 @@ The configuration is as follows:
 scheduler-concurrency = 2048000
 ```
 
-In addition, TiKV supports monitoring the time spent on waiting latches in scheduler.
+In addition, TiKV supports monitoring the time spent on waiting latches in the scheduler.
 
 ![Scheduler latch wait duration](/media/optimistic-transaction-metric.png)
 
-When `Scheduler latch wait duration` is high and there is no slow writes, it can be safely concluded that there are many write conflicts at this time.
+When `Scheduler latch wait duration` is high and there are no slow writes, it can be safely concluded that there are many write conflicts at this time.

pessimistic-transaction.md

@@ -19,7 +19,7 @@ You can set the transaction mode by configuring the [`tidb_txn_mode`](/system-va
 {{< copyable "sql" >}}
 
 ```sql
-set @@global.tidb_txn_mode = 'pessimistic';
+SET GLOBAL tidb_txn_mode = 'pessimistic';
 ```
 
 You can also explicitly enable the pessimistic transaction mode by executing the following SQL statements:
@@ -33,7 +33,7 @@ BEGIN PESSIMISTIC;
 {{< copyable "sql" >}}
 
 ```sql
-BEGIN /*!90000 PESSIMISTIC */;
+BEGIN /*T! PESSIMISTIC */;
 ```
 
 The `BEGIN PESSIMISTIC;` and `BEGIN OPTIMISTIC;` statements take precedence over the `tidb_txn_mode` system variable. Transactions started with these two statements ignore the system variable and support using both the pessimistic and optimistic transaction modes.
@@ -60,17 +60,38 @@ Pessimistic transactions in TiDB behave similarly to those in MySQL. See the min
 
 ## Difference with MySQL InnoDB
 
-1. When TiDB executes DML or `SELECT FOR UPDATE` statements that use range in the WHERE clause, the concurrent `INSERT` statements within the range are not blocked.
-
-    By implementing Gap Lock, InnoDB blocks the execution of concurrent `INSERT` statements within the range. It is mainly used to support statement-based binlog. Therefore, some applications lower the isolation level to Read Committed to avoid concurrency performance problems caused by Gap Lock. TiDB does not support Gap Lock, so there is no need to pay the concurrency performance cost.
+1. When TiDB executes DML or `SELECT FOR UPDATE` statements that use range in the WHERE clause, concurrent DML statements within the range are not blocked.
+
+    For example:
+
+    ```sql
+    CREATE TABLE t1 (
+     id INT NOT NULL PRIMARY KEY,
+     pad1 VARCHAR(100)
+    );
+    INSERT INTO t1 (id) VALUES (1),(5),(10);
+    ```
+
+    ```sql
+    BEGIN /*T! PESSIMISTIC */;
+    SELECT * FROM t1 WHERE id BETWEEN 1 AND 10 FOR UPDATE;
+    ```
+
+    ```sql
+    BEGIN /*T! PESSIMISTIC */;
+    INSERT INTO t1 (id) VALUES (6); -- blocks only in MySQL
+    UPDATE t1 SET pad1='new value' WHERE id = 5; -- blocks waiting in both MySQL and TiDB
+    ```
+
+    This behavior is because TiDB does not currently support _gap locking_.
 
 2. TiDB does not support `SELECT LOCK IN SHARE MODE`.
 
     When `SELECT LOCK IN SHARE MODE` is executed, it has the same effect as that without the lock, so the read or write operation of other transactions is not blocked.
 
 3. DDL may result in failure of the pessimistic transaction commit.
 
-    When DDL is executed in MySQL, it might be blocked by the transaction that is being executed. However, in this scenario, the DDL operation is not blocked in TiDB, which leads to failure of the pessimistic transaction commit: `ERROR 1105 (HY000): Information schema is changed. [try again later]`. TiDB executes the `TRUNCATE TABLE` statement during the transaction execution, which might result in the `table dosen't exist` error.
+    When DDL is executed in MySQL, it might be blocked by the transaction that is being executed. However, in this scenario, the DDL operation is not blocked in TiDB, which leads to failure of the pessimistic transaction commit: `ERROR 1105 (HY000): Information schema is changed. [try again later]`. TiDB executes the `TRUNCATE TABLE` statement during the transaction execution, which might result in the `table doesn't exist` error.
 
 4. After executing `START TRANSACTION WITH CONSISTENT SNAPSHOT`, MySQL can still read the tables that are created later in other transactions, while TiDB cannot.
 

system-variables.md

@@ -29,7 +29,7 @@ SET  GLOBAL tidb_distsql_scan_concurrency = 10;
 
 - Scope: SESSION | GLOBAL
 - Default value: ON
-- Whether automatically commit a transaction.
+- Controls whether statements should automatically commit when not in an explicit transaction. See [Transaction Overview](/transaction-overview.md#autocommit) for more information.
 
 ### `allow_auto_random_explicit_insert` <span class="version-mark">New in v4.0.3</span>