cherry pick pingcap#3193 to release-3.0

tangenta · sre-bot · commit 512088607f5a · 2020-06-12T16:20:12.000+08:00
Signed-off-by: sre-bot &lt;sre-bot@pingcap.com&gt;
diff --git a/auto-random.md b/auto-random.md
@@ -0,0 +1,152 @@
+---
+title: AUTO_RANDOM
+category: reference
+summary: 本文介绍了 TiDB 的 `AUTO_RANDOM` 列属性。
+aliases: ['/docs-cn/dev/reference/sql/attributes/auto-random/']
+---
+
+# AUTO_RANDOM <span class="version-mark">从 v3.1.0 版本开始引入</span>
+
+> **警告：**
+>
+> 当前 `AUTO_RANDOM` 属性为实验功能，**不建议在生产环境中使用**。在后续版本中，`AUTO_RANDOM` 的语法或语义可能会变化。
+
+使用 `AUTO_RANDOM` 功能前，须在 TiDB 配置文件 `experimental` 部分设置 `allow-auto-random = true`。该参数详情可参见 [`allow-auto-random`](/tidb-configuration-file.md#allow-auto-random)。
+
+## 使用场景
+
+`AUTO_RANDOM` 用于解决大批量写数据入 TiDB 时因含有**整型自增主键列**的表而产生的热点问题。详情参阅 [TiDB 高并发写入场景最佳实践](/best-practices/high-concurrency-best-practices.md)。
+
+以下面语句建立的表为例：
+
+```sql
+create table t (a bigint primary key auto_increment, b varchar(255))
+```
+
+在以上语句所建的表上执行大量未指定主键值的 `INSERT` 语句，示例如下：
+
+```sql
+insert into t(b) values ('a'), ('b'), ('c')
+```
+
+如以上语句，由于未指定主键列的值（`a` 列），TiDB 会使用连续自增的行值作为行 ID，可能导致单个 TiKV 节点上产生写入热点，进而影响对外提供服务的性能。要避免这种性能下降，可以在执行建表语句时为 `a` 列指定 `AUTO_RANDOM` 属性而不是 `AUTO_INCREMENT` 属性。示例如下：
+
+{{< copyable "sql" >}}
+
+```sql
+create table t (a bigint primary key auto_random, b varchar(255))
+```
+
+或者
+
+{{< copyable "sql" >}}
+
+```sql
+create table t (a bigint auto_random, b varchar(255), primary key (a))
+```
+
+此时再执行形如 `INSERT INTO t(b) values...` 的 `INSERT` 语句。
+
++ 隐式分配：如果该 `INSERT` 语句没有指定整型主键列（`a` 列）的值，或者指定为 `NULL`，TiDB 会为该列自动分配值。该值不保证自增，不保证连续，只保证唯一，避免了连续的行 ID 带来的热点问题。
++ 显式插入：如果该 `INSERT` 语句显式指定了整型主键列的值，和 `AUTO_INCREMENT` 属性类似，TiDB 会保存该值。注意，如果未在系统变量 `@@sql_mode` 中设置 `NO_AUTO_VALUE_ON_ZERO`， 即使显式指定整型主键列的值为 `0`，TiDB 也会为该列自动分配值。
+
+自动分配值的计算方式如下：
+
+该行值在二进制形式下，除去符号位的最高五位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。
+
+若要使用一个不同的 shard bits 的数量，可以在 `AUTO_RANDOM` 后面加一对括号，并在括号中指定想要的 shard bits 数量。示例如下：
+
+{{< copyable "sql" >}}
+
+```sql
+create table t (a bigint primary key auto_random(3), b varchar(255))
+```
+
+以上建表语句中，shard bits 的数量为 `3`。shard bits 的数量的取值范围是 `[1, field_max_bits)`，其中 `field_max_bits` 为整型主键列类型占用的位长度。
+
+创建完表后，使用 `SHOW WARNINGS` 可以查看当前表可支持的最大隐式分配的次数：
+
+{{< copyable "sql" >}}
+
+```sql
+show warnings
+```
+
+```
++-------+------+----------------------------------------------------------+
+| Level | Code | Message                                                  |
++-------+------+----------------------------------------------------------+
+| Note  | 1105 | Available implicit allocation times: 1152921504606846976 |
++-------+------+----------------------------------------------------------+
+
+```
+
+> **警告：**
+>
+> 建议用户使用 `bigint` 作为 `AUTO_RANDOM` 列类型，以获得最大的可隐式分配次数。
+
+另外，要查看某张含有 `AUTO_RANDOM` 属性的表的 shard bits 数量，可以在系统表 `information_schema.tables` 中 `TIDB_ROW_ID_SHARDING_INFO` 一列看到模式为 `PK_AUTO_RANDOM_BITS=x` 的值，其中 `x` 为 shard bits 的数量。
+
+`AUTO RANDOM` 列隐式分配的值会影响 `last_insert_id()`。可以使用 `select last_insert_id()` 获取上一次 TiDB 隐式分配的 ID，例如：
+
+{{< copyable "sql" >}}
+
+```sql
+insert into t (b) values ("b")
+select * from t;
+select last_insert_id()
+```
+
+可能得到的结果如下：
+
+```
++------------+---+
+| a          | b |
++------------+---+
+| 1073741825 | b |
++------------+---+
+
++------------------+
+| last_insert_id() |
++------------------+
+| 1073741825       |
++------------------+
+```
+
+## 兼容性
+
+TiDB 支持解析版本注释语法。示例如下：
+
+{{< copyable "sql" >}}
+
+```sql
+create table t (a bigint primary key /*T![auto_rand] auto_random */)
+```
+
+{{< copyable "sql" >}}
+
+```sql
+create table t (a bigint primary key auto_random)
+```
+
+以上两个语句含义相同。
+
+在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个特性标识符，例如 `/*T![auto_rand] auto_random */`。其中 `auto_rand` 表示 `AUTO_RANDOM` 的特性标识符，只有实现了该标识符对应特性的 TiDB 版本才能够正常解析 SQL 语句片段。
+
+该功能支持向前兼容，即降级兼容。没有实现对应特性的 TiDB 版本则会忽略表（带有上述注释）的 `AUTO_RANDOM` 属性，因此能够使用含有该属性的表。
+
+## 使用限制
+
+目前在 TiDB 中使用 `AUTO_RANDOM` 有以下限制：
+
+- 该属性必须指定在整数类型的主键列上，否则会报错。例外情况见[关于 `alter-primary-key` 配置项的说明](#关于-alter-primary-key-配置项的说明)。
+- 不支持使用 `ALTER TABLE` 来修改 `AUTO_RANDOM` 属性，包括添加或移除该属性。
+- 不支持修改含有 `AUTO_RANDOM` 属性的主键列的列类型。
+- 不支持与 `AUTO_INCREMENT` 同时指定在同一列上。
+- 不支持与列的默认值 `DEFAULT` 同时指定在同一列上。
+- 插入数据时，不建议自行显式指定含有 `AUTO_RANDOM` 列的值。不恰当地显式赋值，可能会导致该表提前耗尽用于自动分配的数值。
+
+### 关于 `alter-primary-key` 配置项的说明
+
+- 当 `alter-primary-key = true` 时，即使是整型主键列，也不支持使用 `AUTO_RANDOM`。
+- 配置文件中的 `alter-primary-key` 和 `allow-auto-random` 两个配置项的值不允许同时为 `true`。
diff --git a/comment-syntax.md b/comment-syntax.md
@@ -1,105 +1,122 @@
 ---
 title: 注释语法
 category: reference
+<<<<<<< HEAD
 aliases: ['/docs-cn/v3.0/reference/sql/language-structure/comment-syntax/','/docs-cn/sql/comment-syntax/']
+=======
+summary: 本文介绍 TiDB 支持的注释语法。
+aliases: ['/docs-cn/dev/reference/sql/language-structure/comment-syntax/']
+>>>>>>> cd61a4c... update comment-syntax.md (#3193)
 ---
 
 # 注释语法
 
-TiDB 支持三种注释风格：
-
-* 用 `#` 注释一行
-* 用 `--` 注释一行，用 `--` 注释必须要在其之后留出至少一个空格。
-* 用 `/* */` 注释一块，可以注释多行。
-
-例：
-
-{{< copyable "sql" >}}
-
-```sql
-SELECT 1+1;     # 注释文字
-```
-
-```
-+------+
-| 1+1  |
-+------+
-|    2 |
-+------+
-1 row in set (0.00 sec)
-```
-
-{{< copyable "sql" >}}
-
-```sql
-SELECT 1+1;     -- 注释文字
-```
-
-```
-+------+
-| 1+1  |
-+------+
-|    2 |
-+------+
-1 row in set (0.00 sec)
-```
-
-{{< copyable "sql" >}}
-
-```sql
-SELECT 1 /* 这是行内注释文字 */ + 1;
-```
-
-```
-+--------+
-| 1  + 1 |
-+--------+
-|      2 |
-+--------+
-1 row in set (0.01 sec)
-```
-
-{{< copyable "sql" >}}
+本文档介绍 TiDB 支持的注释语法。
 
-```sql
-SELECT 1+
-    -> /*
-   /*> 这是一条
-   /*> 多行注释
-   /*> */
-    -> 1;
-```
+TiDB 支持三种注释风格：
 
-```
-+-------+
-| 1+
-
-1 |
-+-------+
-|     2 |
-+-------+
-1 row in set (0.00 sec)
-```
+* 用 `#` 注释一行：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+1;     # 注释文字
+    ```
+
+    ```
+    +------+
+    | 1+1  |
+    +------+
+    |    2 |
+    +------+
+    1 row in set (0.00 sec)
+    ```
+
+* 用 `--` 注释一行：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+1;     -- 注释文字
+    ```
+
+    ```
+    +------+
+    | 1+1  |
+    +------+
+    |    2 |
+    +------+
+    1 row in set (0.00 sec)
+    ```
+
+    用 `--` 注释时，必须要在其之后留出至少一个空格，否则注释不生效：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+1--1;
+    ```
+
+    ```
+    +--------+
+    | 1+1--1 |
+    +--------+
+    |      3 |
+    +--------+
+    1 row in set (0.01 sec)
+    ```
+
+* 用 `/* */` 注释一块，可以注释多行：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1 /* 这是行内注释文字 */ + 1;
+    ```
+
+    ```
+    +--------+
+    | 1  + 1 |
+    +--------+
+    |      2 |
+    +--------+
+    1 row in set (0.01 sec)
+    ```
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT 1+
+        -> /*
+    /*> 这是一条
+    /*> 多行注释
+    /*> */
+        -> 1;
+    ```
+
+    ```
+    +-------+
+    | 1+
+
+    1 |
+    +-------+
+    |     2 |
+    +-------+
+    1 row in set (0.00 sec)
+    ```
+
+## MySQL 兼容的注释语法
 
-{{< copyable "sql" >}}
-
-```sql
-SELECT 1+1--1;
-```
+TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体：
 
 ```
-+--------+
-| 1+1--1 |
-+--------+
-|      3 |
-+--------+
-1 row in set (0.01 sec)
+/*! Specific code */
 ```
 
-TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体：
+或者
 
 ```
-/*! Specific code */
+/*!50110 Specific code */
 ```
 
 在这种格式中，TiDB 会执行注释中的语句，这个语法是为了让这些 SQL 在其他的数据库中被忽略，而在 TiDB 中被执行。
@@ -108,7 +125,17 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体：
 
 在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...`
 
+<<<<<<< HEAD
 如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。
+=======
+如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。
+
+## TiDB 可执行的注释语法
+
+TiDB 也有独立的注释语法，称为 TiDB 可执行注释语法，格式为 `/*T![feature_id] XXX */`。只有在当前版本中实现了 `feature_id` 对应的功能特性的 TiDB，才会试图解析该注释里的 SQL 片段。例如 v3.1.1 中引入了 `AUTO_RANDOM` 特性，该版本能够将 `/*T![auto_rand] auto_random */` 解析为 `auto_random`；而 v3.0.0 中没有实现 `AUTO_RANDOM` 特性，则上述 SQL 语句片段会被忽略。
+
+## 优化器注释语法
+>>>>>>> cd61a4c... update comment-syntax.md (#3193)
 
 还有一种注释会被当做是优化器 Hint 特殊对待：
 
@@ -118,8 +145,16 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体：
 SELECT /*+ hint */ FROM ...;
 ```
 
+<<<<<<< HEAD
 由于 hint 包含在类似 /*+ xxx */ 的 comment 里，MySQL 客户端在 5.7.7 之前，会默认把 comment 清除掉，如果需要在旧的客户端使用 hint，需要在启动客户端时加上 --comments 选项，例如 mysql -h 127.0.0.1 -P 4000 -uroot --comments
 
 TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/optimizer-hints.md)
+=======
+TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/optimizer-hints.md)。
+>>>>>>> cd61a4c... update comment-syntax.md (#3193)
+
+> **注意**
+>
+> 由于 TiDB 可执行注释语法和优化器注释语法在 MySQL 客户端 5.7.7 之前的版本中，会被默认当成 comment 清除掉，如果需要在旧的客户端使用这两种语法，需要在启动客户端时加上 --comments 选项，例如 `mysql -h 127.0.0.1 -P 4000 -uroot --comments`。
 
-更多[细节](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。
+更多细节，请参考 [MySQL 文档](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。
