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

* sql-statment: improve consistency, fix small errors

* Update sequences, use compatibility notes

* Fix COMMIT statement

* Address PR feedback

* Be more careful with default language.

* Address PR feedback

* Update sql-statements/sql-statement-begin.md

Co-authored-by: Zhang Jian <[email protected]>

* Update report bug link per reviewer

* Update constraints.md

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

* Update sql-statements/sql-statement-commit.md

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

* Update sql-statements/sql-statement-commit.md

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

* Update sql-statements/sql-statement-kill.md

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

* Update system-variables.md

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

Co-authored-by: Zhang Jian <[email protected]>
Co-authored-by: Lilian Lee <[email protected]>
Co-authored-by: ti-srebot <[email protected]>

Author: 4 people

constraints.md

@@ -80,7 +80,7 @@ SELECT * FROM users;
 
 ## UNIQUE KEY
 
-In TiDB's optimistic transaction mode, UNIQUE constraints are [checked lazily](/transaction-overview.md#lazy-check-of-constraints) by default. By batching checks when the transaction is committed, TiDB can reduce network overhead and improve performance.
+Depending on the transaction mode and the value of `tidb_constraint_check_in_place`, TiDB might check `UNIQUE` constraints [lazily](/transaction-overview.md#lazy-check-of-constraints). This helps improve performance by batching network access.
 
 For example:
 
@@ -96,23 +96,31 @@ CREATE TABLE users (
 INSERT INTO users (username) VALUES ('dave'), ('sarah'), ('bill');
 ```
 
+With the default of pessimistic locking:
+
 {{< 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'
 ```
 
+With optimistic locking and `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
 ```
@@ -138,9 +146,9 @@ COMMIT;
 ERROR 1062 (23000): Duplicate entry 'bill' for key 'username'
 ```
 
-The first `INSERT` statement will not cause duplicate key errors, which is consistent with MySQL's rules. This check will be delayed until the transaction is committed.
+In the optimistic example, the unique check was delayed until the transaction is committed. This resulted in a duplicate key error, because the value `bill` was already present.
 
-You can disable this behavior by setting  `tidb_constraint_check_in_place` to  `1`. This variable setting does not take effect on pessimistic transactions, because in the pessimistic transaction mode the constraints are always checked when the statement is executed. If this behavior is disabled, the unique constraint is checked when the statement is executed.
+You can disable this behavior by setting `tidb_constraint_check_in_place` to `1`. This variable setting does not take effect on pessimistic transactions, because in the pessimistic transaction mode the constraints are always checked when the statement is executed. When `tidb_constraint_check_in_place=1`, the unique constraint is checked when the statement is executed.
 
 For example:
 
@@ -167,7 +175,7 @@ Query OK, 0 rows affected (0.00 sec)
 {{< copyable "sql" >}}
 
 ```sql
-START TRANSACTION;
+BEGIN OPTIMISTIC;
 ```
 
 ```

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

@@ -30,6 +30,10 @@ alter_specification:
 
 The `alter_specification` option specifies the `CHARACTER SET` and `COLLATE` of a specified database. Currently, TiDB only supports some character sets and collations. See [Character Set and Collation Support](/character-set-and-collation.md) for details.
 
+## MySQL compatibility
+
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
+
 ## See also
 
 * [CREATE DATABASE](/sql-statements/sql-statement-create-database.md)

sql-statements/sql-statement-begin.md

@@ -34,7 +34,7 @@ Query OK, 0 rows affected (0.01 sec)
 
 ## MySQL compatibility
 
-You can add the `PESSIMISTIC` or `OPTIMISTIC` option to the `BEGIN` statement in TiDB to indicate the type of transaction that this statement starts.
+TiDB supports the syntax extension of `BEGIN PESSMISTIC` or `BEGIN OPTIMISTIC`. This enables you to override the default transactional model for your transaction.
 
 ## See also
 

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

@@ -62,7 +62,7 @@ SHOW DRAINER STATUS;
 
 ## MySQL compatibility
 
-MySQL dosen't support this statement.
+This statement is a TiDB extension to MySQL syntax.
 
 ## See also
 

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

@@ -62,7 +62,7 @@ SHOW PUMP STATUS;
 
 ## MySQL compatibility
 
-MySQL dosen't support this statement.
+This statement is a TiDB extension to MySQL syntax.
 
 ## See also
 

sql-statements/sql-statement-commit.md

@@ -38,8 +38,8 @@ Query OK, 0 rows affected (0.01 sec)
 
 ## MySQL compatibility
 
-* In MySQL, with the exception of Group Replication with multiple primaries, it is not typical that a `COMMIT` statement could result in an error. By contrast, TiDB uses optimistic concurrency control and conflicts may result in `COMMIT` returning an error.
-* Be default, `UNIQUE` and `PRIMARY KEY` constraint checks are deferred until statement commit. This behavior can be changed by setting `tidb_constraint_check_in_place=TRUE`.
+* By default, TiDB 3.0.8 and later versions use [Pessimistic Locking](/pessimistic-transaction.md). When using [Optimistic Locking](/optimistic-transaction.md), it is important to consider that a `COMMIT` statement might fail because rows have been modified by another transaction.
+* When Optimistic Locking is enabled, `UNIQUE` and `PRIMARY KEY` constraint checks are deferred until statement commit. This results in additional situations where a a `COMMIT` statement might fail. This behavior can be changed by setting `tidb_constraint_check_in_place=TRUE`.
 * TiDB only has syntactic support for `CompletionTypeWithinTransaction`. Closing the connection or continuing to open a new transaction after the transaction is committed is not supported.
 
 ## See also

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

@@ -134,7 +134,7 @@ mysql> EXPLAIN ANALYZE  SELECT * FROM t1 WHERE b = 123;
 
 ## MySQL compatibility
 
-This statement is a TiDB extension.
+This statement is a TiDB extension to MySQL syntax.
 
 ## See also
 

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

@@ -65,7 +65,7 @@ mysql> SHOW TABLES;
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

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

@@ -156,7 +156,7 @@ mysql> SHOW TABLES IN test;
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with roles, which are a feature of MySQL 8.0. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with roles, which are a feature of MySQL 8.0. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

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

@@ -298,9 +298,9 @@ You can control a sequence through the following expression functions:
 
 ## MySQL compatibility
 
-Currently, MySQL does not have the sequence option. The TiDB sequence is borrowed from MariaDB. Except for the `SETVAL` function, all other functions have the same progressions with those functions of MariaDB.
+This statement is a TiDB extension. The implementation is modeled on sequences available in MariaDB.
 
-Here "progression" means that the numbers in a sequence follow a certain arithmetic progression rule defined by the sequence. Although you can use `SETVAL` to set the current value of a sequence, the subsequent values of the sequence still follow the original progression rule.
+Except for the `SETVAL` function, all other functions have the same _progressions_ as MariaDB. Here "progression" means that the numbers in a sequence follow a certain arithmetic progression rule defined by the sequence. Although you can use `SETVAL` to set the current value of a sequence, the subsequent values of the sequence still follow the original progression rule.
 
 For example:
 

sql-statements/sql-statement-create-table-like.md

@@ -53,7 +53,7 @@ If the table to be copied is defined with the `PRE_SPLIT_REGIONS` attribute, the
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

sql-statements/sql-statement-deallocate.md

@@ -45,7 +45,7 @@ Query OK, 0 rows affected (0.00 sec)
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

sql-statements/sql-statement-delete.md

@@ -53,7 +53,7 @@ mysql> SELECT * FROM t1;
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

sql-statements/sql-statement-do.md

@@ -54,7 +54,7 @@ Query OK, 0 rows affected (2.50 sec)
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

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

@@ -133,7 +133,7 @@ Empty set (0.00 sec)
 
 ## MySQL compatibility
 
-This statement is a TiDB extension.
+This statement is a TiDB extension to MySQL syntax.
 
 ## See also
 

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

@@ -48,7 +48,7 @@ mysql> SHOW DATABASES;
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

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

@@ -200,7 +200,7 @@ ERROR 3530 (HY000): `analyticsteam`@`%` is is not granted to jennifer@%
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with roles, which are a feature of MySQL 8.0. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with roles, which are a feature of MySQL 8.0. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

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

@@ -50,7 +50,7 @@ Query OK, 0 rows affected (0.03 sec)
 
 ## MySQL compatibility
 
-Currently, sequence object is not supported by MySQL.
+This statement is a TiDB extension. The implementation is modeled on sequences available in MariaDB.
 
 ## See also
 

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 compatibility
+
+This statement is a TiDB extension to MySQL syntax.
+
 ## See also
 
 * [Introduction to Statistics](/statistics.md)

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

@@ -75,7 +75,7 @@ mysql> SELECT * FROM t1;
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

sql-statements/sql-statement-execute.md

@@ -37,7 +37,7 @@ Query OK, 0 rows affected (0.00 sec)
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

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

@@ -93,11 +93,11 @@ EXPLAIN ANALYZE SELECT * FROM t1;
 
 ## MySQL compatibility
 
-This statement is a TiDB extension to MySQL syntax.
+`EXPLAIN ANALYZE` is a feature of MySQL 8.0, but both the output format and the potential execution plans in TiDB differ substaintially from MySQL.
 
 ## See also
 
 * [Understanding the Query Execution Plan](/query-execution-plan.md)
 * [EXPLAIN](/sql-statements/sql-statement-explain.md)
 * [ANALYZE TABLE](/sql-statements/sql-statement-analyze-table.md)
-* [TRACE](/sql-statements/sql-statement-trace.md)
+* [TRACE](/sql-statements/sql-statement-trace.md)

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

@@ -100,3 +100,7 @@ From the above process, you can see that TiDB always operates on the metadata of
 > You cannot use `FLASHBACK` statements to restore the same deleted table multiple times, because the ID of the restored table is the same ID of the dropped table, and TiDB requires that all existing tables must have a globally unique table ID.
 
 The `FLASHBACK TABLE` operation is done by TiDB obtaining the table metadata through snapshot read, and then going through the process of table creation similar to `CREATE TABLE`. Therefore, `FLASHBACK TABLE` is, in essence, a kind of DDL operation.
+
+## MySQL compatibility
+
+This statement is a TiDB extension to MySQL syntax.

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

@@ -32,7 +32,7 @@ Query OK, 0 rows affected (0.01 sec)
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

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

@@ -50,8 +50,8 @@ ERROR 1105 (HY000): FLUSH TABLES WITH READ LOCK is not supported.  Please use @@
 
 ## MySQL compatibility
 
-* TiDB does not have a concept of table cache as in MySQL.  Thus, `FLUSH TABLES` is parsed but ignored in TiDB for compatibility.
-* The statement `FLUSH TABLES WITH READ LOCK` produces an error, as TiDB does not currently support locking tables. It is recommended to use [Historical reads] for this purpose instead.
+* TiDB does not have a concept of table cache as in MySQL. Thus, `FLUSH TABLES` is parsed but ignored in TiDB for compatibility.
+* The statement `FLUSH TABLES WITH READ LOCK` produces an error, as TiDB does not currently support locking tables. It is recommended to use [Historical reads](/read-historical-data.md) for this purpose instead.
 
 ## See also
 

sql-statements/sql-statement-grant-role.md

@@ -156,7 +156,7 @@ mysql> SHOW TABLES IN test;
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with roles, which are a feature of MySQL 8.0. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with roles, which are a feature of MySQL 8.0. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

sql-statements/sql-statement-insert.md

@@ -102,7 +102,7 @@ mysql> SELECT * FROM t2;
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

sql-statements/sql-statement-kill.md

@@ -8,8 +8,6 @@ aliases: ['/docs/dev/sql-statements/sql-statement-kill/','/docs/dev/reference/sq
 
 The statement `KILL TIDB` is used to terminate connections in TiDB.
 
-By design, this statement is not compatible with MySQL by default. This helps prevent against a case of a connection being terminated on the wrong TiDB server, since it is common to place multiple TiDB servers behind a load balancer.
-
 ## Synopsis
 
 **KillStmt:**
@@ -38,6 +36,7 @@ Query OK, 0 rows affected (0.00 sec)
 
 ## MySQL compatibility
 
+* By design, this statement is not compatible with MySQL by default. This helps prevent against a case of a connection being terminated on the wrong TiDB server, because it is common to place multiple TiDB servers behind a load balancer.
 * The `KILL TIDB` statement is a TiDB extension. If you are certain that the session you are attempting to kill is on the same TiDB server, set [`compatible-kill-query = true`](/tidb-configuration-file.md#compatible-kill-query) in your configuration file.
 
 ## See also

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

@@ -113,5 +113,4 @@ In the above example, `x'2c'` is the hexadecimal representation of the `,` chara
 ## See also
 
 * [INSERT](/sql-statements/sql-statement-insert.md)
-* [Optimistic Transaction Model](/optimistic-transaction.md)
 * [Import Example Database](/import-example-data.md)

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 compatibility
+
+This statement is a TiDB extension to MySQL syntax.
+
 ## See also
 
 * [Statistics](/statistics.md)

sql-statements/sql-statement-prepare.md

@@ -41,7 +41,7 @@ Query OK, 0 rows affected (0.00 sec)
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

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

@@ -123,3 +123,7 @@ When deleting a table, TiDB only deletes the table metadata, and writes the tabl
 Therefore, to recover a table, you only need to recover the table metadata and delete the corresponding row record in the `mysql.gc_delete_range` table before the GC Worker deletes the table data. You can use a snapshot read of TiDB to recover the table metadata. Refer to [Read Historical Data](/read-historical-data.md) for details.
 
 Table recovery is done by TiDB obtaining the table metadata through snapshot read, and then going through the process of table creation similar to `CREATE TABLE`. Therefore, `RECOVER TABLE` itself is, in essence, a kind of DDL operation.
+
+## MySQL compatibility
+
+This statement is a TiDB extension to MySQL syntax.

sql-statements/sql-statement-rename-index.md

@@ -52,7 +52,7 @@ Create Table: CREATE TABLE `t1` (
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

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

@@ -46,7 +46,7 @@ mysql> SHOW TABLES;
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also
 

sql-statements/sql-statement-replace.md

@@ -70,7 +70,7 @@ mysql> SELECT * FROM t1;
 
 ## MySQL compatibility
 
-This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](/report-issue.md) on GitHub.
+This statement is understood to be fully compatible with MySQL. Any compatibility differences should be [reported via an issue](https://github.com/pingcap/tidb/issues/new/choose) on GitHub.
 
 ## See also