sql-statement: improve consistency, fix small errors (pingcap#4263)

* update 65 files

Signed-off-by: Ran <[email protected]>

* update 5 files

Signed-off-by: Ran <[email protected]>

* update system-variables.md

Signed-off-by: Ran <[email protected]>

* update wording

Signed-off-by: Ran <[email protected]>

* remove a ref that causes CI failure

* update sql-statement-use

Signed-off-by: Ran <[email protected]>

* Apply suggestions from code review

Co-authored-by: Lilian Lee <[email protected]>

* resolve conflicts

Signed-off-by: Ran <[email protected]>

* revert changes in constraints.md

Signed-off-by: Ran <[email protected]>

Co-authored-by: Lilian Lee <[email protected]>

constraints.md

@@ -93,23 +93,30 @@ CREATE TABLE users (
 INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill');
 ```
 
+默认的悲观事务模式下：
+
 {{< copyable "sql" >}}
 
 ```sql
-START TRANSACTION;
+BEGIN;
+INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill');
 ```
 
 ```
-Query OK, 0 rows affected (0.00 sec)
+ERROR 1062 (23000): Duplicate entry 'bill' for key 'username'
 ```
 
+乐观事务模式下且 `tidb_constraint_check_in_place=0`：
+
 {{< copyable "sql" >}}
 
 ```sql
+BEGIN OPTIMISTIC;
 INSERT INTO users (username) VALUES ('jane'), ('chris'), ('bill');
 ```
 
 ```
+Query OK, 0 rows affected (0.00 sec)
 Query OK, 3 rows affected (0.00 sec)
 Records: 3  Duplicates: 0  Warnings: 0
 ```
@@ -135,9 +142,9 @@ COMMIT;
 ERROR 1062 (23000): Duplicate entry 'bill' for key 'username'
 ```
 
-第一条 `INSERT` 语句不会导致重复键错误，这同 MySQL 的规则一致。该检查将推迟到事务提交时才会进行。
+在乐观事务的示例中，唯一约束的检查推迟到事务提交时才进行。由于 `bill` 值已经存在，这一行为导致了重复键错误。
 
-你可通过设置 `tidb_constraint_check_in_place` 为 `1` 停用此行为（该变量设置对悲观事务无效，悲观事务始终在语句执行时检查约束）。如果停用此行为，则会在执行语句时就对唯一约束进行检查。例如：
+你可通过设置 `tidb_constraint_check_in_place` 为 `1` 停用此行为（该变量设置对悲观事务无效，悲观事务始终在语句执行时检查约束）。当 `tidb_constraint_check_in_place` 设置为 `1` 时，则会在执行语句时就对唯一约束进行检查。例如：
 
 ```sql
 DROP TABLE IF EXISTS users;
@@ -162,7 +169,7 @@ Query OK, 0 rows affected (0.00 sec)
 {{< copyable "sql" >}}
 
 ```sql
-START TRANSACTION;
+BEGIN OPTIMISTIC;
 ```
 
 ```

sql-statements/sql-statement-alter-database.md

@@ -32,6 +32,10 @@ alter_specification:
 
 `alter_specification` 选项用于指定数据库具体的 `CHARACTER SET` 和 `COLLATE`。目前 TiDB 只支持部分的字符集和排序规则，请参照[字符集支持](/character-set-and-collation.md)。
 
+## MySQL 兼容性
+
+`ALTER DATABASE` 语句与 MySQL 完全兼容。如发现任何兼容性差异，请在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues/new/choose)。
+
 ## 另请参阅
 
 * [CREATE DATABASE](/sql-statements/sql-statement-create-database.md)

sql-statements/sql-statement-begin.md

@@ -60,7 +60,7 @@ Query OK, 0 rows affected (0.01 sec)
 
 ## MySQL 兼容性
 
-TiDB 在执行 `BEGIN` 语句时，可以带上 `PESSIMISTIC` 或者 `OPTIMISTIC` 选项表明此语句开启事务的类型。
+TiDB 支持 `BEGIN PESSIMISTIC` 或 `BEGIN OPTIMISTIC` 的语法扩展，用户可以为某一个事务覆盖默认的事务模型。
 
 ## 另请参阅
 

sql-statements/sql-statement-change-drainer.md

@@ -62,7 +62,7 @@ SHOW DRAINER STATUS;
 
 ## MySQL 兼容性
 
-MySQL 无此功能。
+该语句是 TiDB 对 MySQL 语法的扩展。
 
 ## 另请参阅
 

sql-statements/sql-statement-change-pump.md

@@ -62,7 +62,7 @@ SHOW PUMP STATUS;
 
 ## MySQL 兼容性
 
-MySQL 无此功能。
+该语句是 TiDB 对 MySQL 语法的扩展。
 
 ## 另请参阅
 

sql-statements/sql-statement-commit.md

@@ -64,8 +64,8 @@ Query OK, 0 rows affected (0.01 sec)
 
 ## MySQL 兼容性
 
-* 在 MySQL 中，除了有多个 primary 的群组复制以外，`COMMIT` 语句通常不会导致错误。相比之下，TiDB 使用乐观并发控制，冲突可能导致 `COMMIT` 返回错误。
-* 默认情况下，`UNIQUE` 和 `PRIMARY KEY` 约束检查将延迟直至语句提交。可通过设置 `tidb_constraint_check_in_place=TRUE` 来改变该行为。
+* TiDB 3.0.8 及更新版本默认使用[悲观事务模型](/pessimistic-transaction.md)。在[乐观事务模型](/optimistic-transaction.md)下，需要考虑到修改的行已被另一个事务修改，导致 `COMMIT` 语句可能执行失败的情况。
+* 启用乐观事务模型后，`UNIQUE` 和 `PRIMARY KEY` 约束检查将延迟直至语句提交。当 `COMMIT` 语句失败时，这可能导致其他问题。可通过设置 `tidb_constraint_check_in_place=TRUE` 来改变该行为。
 * TiDB 解析但忽略 `ROLLBACK AND [NO] RELEASE` 语法。在 MySQL 中，使用该语法可在提交事务后立即断开客户端会话。在 TiDB 中，建议使用客户端程序的 `mysql_close()` 来实现该功能。
 * TiDB 解析但忽略 `ROLLBACK AND [NO] CHAIN` 语法。在 MySQL 中，使用该语法可在提交当前事务时立即以相同的隔离级别开启新事务。在 TiDB 中，推荐直接开启新事务。
 

sql-statements/sql-statement-create-sequence.md

@@ -298,9 +298,9 @@ CREATE [TEMPORARY] SEQUENCE [IF NOT EXISTS] sequence_name
 
 ## MySQL 兼容性
 
-MySQL 暂无序列选项。TiDB 序列借鉴自 MariaDB。`SETVAL` 函数的步调是 TiDB 特有的，其他函数的步调与 MariaDB 保持一致。
+该语句是 TiDB 的扩展，序列的实现借鉴自 MariaDB。
 
-这里的步调是指，序列中的数在定义之后会产生一定的等差关系。`SETVAL` 虽然可以将序列的当前值进行移动设置，但是后续出现的值仍会遵循原有的等差关系。
+除了 `SETVAL` 函数外，其他函数的“步调 (progressions)” 与 MariaDB 一致。这里的步调是指，序列中的数在定义之后会产生一定的等差关系。`SETVAL` 虽然可以将序列的当前值进行移动设置，但是后续出现的值仍会遵循原有的等差关系。
 
 示例如下：
 

sql-statements/sql-statement-drop-sequence.md

@@ -50,7 +50,7 @@ Query OK, 0 rows affected (0.03 sec)
 
 ## MySQL 兼容性
 
-MySQL 暂无序列功能。
+该语句是 TiDB 的扩展，序列的实现借鉴自 MariaDB。
 
 ## 另请参阅
 

sql-statements/sql-statement-drop-stats.md

@@ -65,6 +65,10 @@ SHOW STATS_META WHERE db_name='test' and table_name='t';
 Empty set (0.00 sec)
 ```
 
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
 ## 另请参阅
 
 * [统计信息简介](/statistics.md)

sql-statements/sql-statement-explain-analyze.md

@@ -93,7 +93,7 @@ EXPLAIN ANALYZE SELECT * FROM t1;
 
 ## MySQL 兼容性
 
-该语句是 TiDB 对 MySQL 语法的扩展。
+`EXPLAIN ANALYZE` 是 MySQL 8.0 的功能，但该语句在 MySQL 中的输出格式和可能的执行计划都与 TiDB 有较大差异。
 
 ## 另请参阅
 

sql-statements/sql-statement-flashback-table.md

@@ -95,3 +95,7 @@ TiDB 在删除表时，实际上只删除了表的元信息，并将需要删除
 > 不能用 `FLASHBACK` 多次恢复同一个被删除的表，因为 `FLASHBACK` 所恢复表的 table ID 还是被删除表的 table ID，而 TiDB 要求所有还存在的表 table ID 必须全局唯一。
 
  `FLASHBACK TABLE` 是通过快照读获取表的元信息后，再走一次类似于 `CREATE TABLE` 的建表流程，所以 `FLASHBACK TABLE` 实际上也是一种 DDL 操作。
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。

sql-statements/sql-statement-flush-tables.md

@@ -63,7 +63,7 @@ ERROR 1105 (HY000): FLUSH TABLES WITH READ LOCK is not supported.  Please use @@
 ## MySQL 兼容性
 
 * TiDB 没有 MySQL 中的表缓存这一概念。所以，`FLUSH TABLES` 因 MySQL 兼容性会在 TiDB 中解析出但会被忽略掉。
-* 因为 TiDB 目前不支持锁表，所以`FLUSH TABLES WITH READ LOCK` 语句会产生错误。建议使用 [Historical reads] 来实现锁表。
+* 因为 TiDB 目前不支持锁表，所以`FLUSH TABLES WITH READ LOCK` 语句会产生错误。建议使用 [Historical reads](/read-historical-data.md) 来实现锁表。
 
 ## 另请参阅
 

sql-statements/sql-statement-kill.md

@@ -8,8 +8,6 @@ aliases: ['/docs-cn/dev/sql-statements/sql-statement-kill/','/docs-cn/dev/refere
 
 `KILL TIDB` 语句用于终止 TiDB 中的连接。
 
-按照设计，`KILL TIDB` 语句默认与 MySQL 不兼容。负载均衡器后面通常放有多个 TiDB 服务器，这种默认不兼容有助于防止在错误的 TiDB 服务器上终止连接。
-
 ## 语法图
 
 **KillStmt:**
@@ -50,6 +48,7 @@ Query OK, 0 rows affected (0.00 sec)
 
 ## MySQL 兼容性
 
+* 按照设计，`KILL TIDB` 语句默认与 MySQL 不兼容。负载均衡器后面通常放有多个 TiDB 服务器，这种默认不兼容有助于防止在错误的 TiDB 服务器上终止连接。
 * `KILL TIDB` 语句是 TiDB 的扩展语法。如果正尝试终止的会话位于同一个 TiDB 服务器上，可在配置文件里设置 [`compatible-kill-query = true`](/tidb-configuration-file.md#compatible-kill-query)。
 
 ## 另请参阅

sql-statements/sql-statement-load-stats.md

@@ -32,6 +32,10 @@ LOAD STATS '/tmp/stats.json';
 Query OK, 0 rows affected (0.00 sec)
 ```
 
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
 ## 另请参阅
 
 * [统计信息](/statistics.md)

sql-statements/sql-statement-recover-table.md

@@ -125,3 +125,7 @@ TiDB 在删除表时，实际上只删除了表的元信息，并将需要删除
 所以，RECOVER TABLE 只需要在 GC Worker 还没删除表数据前，恢复表的元信息并删除 `mysql.gc_delete_range` 表中相应的行记录就可以了。恢复表的元信息可以用 TiDB 的快照读实现。具体的快照读内容可以参考[读取历史数据](/read-historical-data.md)文档。
 
 TiDB 中表的恢复是通过快照读获取表的元信息后，再走一次类似于 `CREATE TABLE` 的建表流程，所以 `RECOVER TABLE` 实际上也是一种 DDL。
+
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。

sql-statements/sql-statement-show-analyze-status.md

@@ -44,6 +44,10 @@ show analyze status;
 8 rows in set (0.00 sec)
 ```
 
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
 ## 另请参阅
 
 * [ANALYZE_STATUS 表](/information-schema/information-schema-analyze-status.md)

sql-statements/sql-statement-show-builtins.md

@@ -300,4 +300,4 @@ SHOW BUILTINS;
 
 ## MySQL 兼容性
 
-`SHOW BUILTINS` 是 TiDB 新增语法，MySQL 中无此语法。
+该语句是 TiDB 对 MySQL 语法的扩展。

sql-statements/sql-statement-show-config.md

@@ -83,7 +83,7 @@ SHOW CONFIG LIKE 'tidb';
 
 ## MySQL 兼容性
 
-`SHOW CONFIG` 是 TiDB 的扩展语法，MySQL 没有对应的语法。
+该语句是 TiDB 对 MySQL 语法的扩展。
 
 ## 另请参阅
 

sql-statements/sql-statement-show-create-sequence.md

@@ -47,7 +47,7 @@ SHOW CREATE SEQUENCE seq;
 
 ## MySQL 兼容性
 
-MySQL 暂无序列选项。TiDB 序列部分借鉴自 MariaDB。`SETVAL` 函数的步调是 TiDB 特有的，其他函数的步调与 MariaDB 保持一致。
+该语句是 TiDB 的扩展，序列的实现借鉴自 MariaDB。
 
 ## 另请参阅
 

sql-statements/sql-statement-show-drainer-status.md

@@ -29,7 +29,7 @@ SHOW DRAINER STATUS;
 
 ## MySQL 兼容性
 
-MySQL 无此功能。
+该语句是 TiDB 对 MySQL 语法的扩展。
 
 ## 另请参阅
 

sql-statements/sql-statement-show-histograms.md

@@ -59,7 +59,7 @@ show stats_histograms where table_name = 't2';
 
 ## MySQL 兼容性
 
-`SHOW STATS_HISTOGRAMS` 是 TiDB 专有语法，因此不兼容 MySQL。
+该语句是 TiDB 对 MySQL 语法的扩展。
 
 ## 另请参阅
 

sql-statements/sql-statement-show-profiles.md

@@ -25,3 +25,7 @@ SHOW PROFILES
 ```
 Empty set (0.00 sec)
 ```
+
+## MySQL 兼容性
+
+该语句仅与 MySQL 兼容，无其他作用。执行 `SHOW PROFILES` 始终返回空结果。

sql-statements/sql-statement-show-pump-status.md

@@ -29,7 +29,7 @@ SHOW PUMP STATUS;
 
 ## MySQL 兼容性
 
-MySQL 无此功能。
+该语句是 TiDB 对 MySQL 语法的扩展。
 
 ## 另请参阅
 

sql-statements/sql-statement-show-stats-meta.md

@@ -75,7 +75,7 @@ show stats_meta where table_name = 't2';
 
 ## MySQL 兼容性
 
-`SHOW STATS_META` 是 TiDB 专有语法，因此不兼容 MySQL。
+该语句是 TiDB 对 MySQL 语法的扩展。
 
 ## 另请参阅
 

sql-statements/sql-statement-show-table-next-rowid.md

@@ -64,7 +64,7 @@ show table t next_row_id;
 
 ## MySQL 兼容性
 
-`SHOW TABLE NEXT_ROW_ID` 语句是 TiDB 特有的语法。
+该语句是 TiDB 对 MySQL 语法的扩展。
 
 ## 另请参阅
 

sql-statements/sql-statement-shutdown.md

@@ -32,4 +32,4 @@ Query OK, 0 rows affected (0.00 sec)
 >
 > 由于 TiDB 是分布式数据库，因此 TiDB 中的停机操作停止的是客户端连接的 TiDB 实例，而不是整个 TiDB 集群。
 
-`SHUTDOWN` 语句与 MySQL 不完全兼容。如发现任何其他兼容性差异，请在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues/new/choose)。
+`SHUTDOWN` 语句与 MySQL 不完全兼容。如发现任何其他兼容性差异，请在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues/new/choose)。

sql-statements/sql-statement-split-region.md

@@ -416,6 +416,10 @@ region3:   [ 2<<61     ,  3<<61 )
 region4:   [ 3<<61     ,  +inf  )
 ```
 
+## MySQL 兼容性
+
+该语句是 TiDB 对 MySQL 语法的扩展。
+
 ## 另请参阅
 
 * [SHOW TABLE REGIONS](/sql-statements/sql-statement-show-table-regions.md)

sql-statements/sql-statement-use.md

@@ -124,9 +124,7 @@ SHOW TABLES;
 
 ## MySQL 兼容性
 
-在 2.0 版本中，用户可以使用 `USE` 访问任意数据库。在 3.0 及以后的版本中 `USE` 会检查用户是否拥有访问数据库的权限。
-
-目前 `USE` 语句与 MySQL 完全兼容。如发现任何兼容性差异，请在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues/new/choose)。
+`USE` 语句与 MySQL 完全兼容。如发现任何兼容性差异，请在 GitHub 上提交 [issue](https://github.com/pingcap/tidb/issues/new/choose)。
 
 ## 另请参阅
 

system-variables.md

@@ -206,51 +206,48 @@ SET  GLOBAL tidb_distsql_scan_concurrency = 10;
 
 - 作用域：SESSION | GLOBAL
 - 默认值：0
-- TiDB 支持乐观事务模型，即在执行写入时，假设不存在冲突。冲突检查是在最后 commit 提交时才去检查。这里的检查指 unique key 检查。
-- 这个变量用来控制是否每次写入一行时就执行一次唯一性检查。注意，开启该变量后，在大批量写入场景下，对性能会有影响。
+- 该变量仅适用于乐观事务模型。当这个变量设置为 0 时，唯一索引的重复值检查会被推迟到事务提交时才进行。这有助于提高性能，但对于某些应用，可能导致非预期的行为。详情见[约束](/constraints.md)。
 
-示例：
+    - 乐观事务模型下将 `tidb_constraint_check_in_place` 设置为 0：
 
-- 默认关闭 `tidb_constraint_check_in_place` 时的行为：
+        {{< copyable "sql" >}}
 
-    {{< copyable "sql" >}}
+        ```sql
+        create table t (i int key);
+        insert into t values (1);
+        begin optimistic;
+        insert into t values (1);
+        ```
 
-    ```sql
-    create table t (i int key);
-    insert into t values (1);
-    begin;
-    insert into t values (1);
-    ```
+        ```
+        Query OK, 1 row affected
+        ```
 
-    ```
-    Query OK, 1 row affected
-    ```
+        {{< copyable "sql" >}}
 
-    commit 时才去做检查：
+        ```sql
+        tidb> commit; -- 事务提交时才检查
+        ```
 
-    {{< copyable "sql" >}}
+        ```
+        ERROR 1062 : Duplicate entry '1' for key 'PRIMARY'
+        ```
 
-    ```sql
-    commit;
-    ```
+    - 乐观事务模型下将 `tidb_constraint_check_in_place` 设置为 1：
 
-    ```
-    ERROR 1062 : Duplicate entry '1' for key 'PRIMARY'
-    ```
+        {{< copyable "sql" >}}
 
-- 打开 `tidb_constraint_check_in_place` 后：
-
-    {{< copyable "sql" >}}
+        ```sql
+        set @@tidb_constraint_check_in_place=1;
+        begin optimistic;
+        insert into t values (1);
+        ```
 
-    ```sql
-    set @@tidb_constraint_check_in_place=1;
-    begin;
-    insert into t values (1);
-    ```
+        ```
+        ERROR 1062 : Duplicate entry '1' for key 'PRIMARY'
+        ```
 
-    ```
-    ERROR 1062 : Duplicate entry '1' for key 'PRIMARY'
-    ```
+悲观事务模型中，始终默认执行约束检查。
 
 ### `tidb_current_ts`