cherry pick pingcap#4862 to release-3.0

Signed-off-by: ti-srebot <[email protected]>

Author: TomShawn

auto-random.md

@@ -0,0 +1,147 @@
+---
+title: AUTO_RANDOM
+summary: 本文介绍了 TiDB 的 `AUTO_RANDOM` 列属性。
+aliases: ['/docs-cn/dev/auto-random/','/docs-cn/dev/reference/sql/attributes/auto-random/']
+---
+
+# AUTO_RANDOM <span class="version-mark">从 v3.1.0 版本开始引入</span>
+
+> **注意：**
+>
+> `AUTO_RANDOM` 属性已于 v4.0.3 版本成为正式功能。
+
+## 使用场景
+
+`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 也会为该列自动分配值。
+
+> **注意：**
+>
+> 从 v4.0.3 开始，要使用显式插入的功能，需要将系统变量 `@@allow_auto_random_explicit_insert` 的值设置为 `1`（默认值为 `0`）。默认不支持显式插入的具体原因请参考[使用限制](#使用限制)一节。
+
+自动分配值的计算方式如下：
+
+该行值在二进制形式下，除去符号位的最高五位（称为 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
+```
+
+```sql
++-------+------+----------------------------------------------------------+
+| Level | Code | Message                                                  |
++-------+------+----------------------------------------------------------+
+| Note  | 1105 | Available implicit allocation times: 1152921504606846976 |
++-------+------+----------------------------------------------------------+
+```
+
+> **注意：**
+>
+> 为保证可隐式分配的次数最大，从 v4.0.3 开始，`AUTO_RANDOM` 列类型只能为 `BIGINT`。
+
+另外，要查看某张含有 `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()
+```
+
+可能得到的结果如下：
+
+```sql
++------------+---+
+| 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` 的值为 `true` 时，即使是整型主键列，也不支持使用 `AUTO_RANDOM`。
+- 不支持使用 `ALTER TABLE` 来修改 `AUTO_RANDOM` 属性，包括添加或移除该属性。
+- 不支持修改含有 `AUTO_RANDOM` 属性的主键列的列类型。
+- 不支持与 `AUTO_INCREMENT` 同时指定在同一列上。
+- 不支持与列的默认值 `DEFAULT` 同时指定在同一列上。
+- 插入数据时，不建议自行显式指定含有 `AUTO_RANDOM` 列的值。不恰当地显式赋值，可能会导致该表提前耗尽用于自动分配的数值。

backup-and-restore-using-dumpling-lightning.md

@@ -0,0 +1,83 @@
+---
+title: 使用 Dumpling/TiDB Lightning 进行备份与恢复
+aliases: ['/docs-cn/dev/backup-and-restore-using-dumpling-lightning/','/docs-cn/dev/export-or-backup-using-dumpling/','/zh/tidb/dev/export-or-backup-using-dumpling']
+---
+
+# 使用 Dumpling/TiDB Lightning 进行备份与恢复
+
+本文档将详细介绍如何使用 Dumpling/TiDB Lightning 对 TiDB 进行全量备份与恢复。增量备份和同步可使用 [TiDB Binlog](/tidb-binlog/tidb-binlog-overview.md)。
+
+这里假定 TiDB 服务器信息如下：
+
+|服务器名称|服务器地址|端口|用户名|密码|
+|----|-------|----|----|--------|
+|TiDB|127.0.0.1|4000|root|*|
+
+在这个备份恢复过程中，会用到下面的工具：
+
+- [Dumpling](/dumpling-overview.md)：从 TiDB 导出数据
+- [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md)：导入数据到 TiDB
+
+## Dumpling/TiDB Lightning 全量备份恢复最佳实践
+
+为了快速地备份恢复数据（特别是数据量巨大的库），可以参考以下建议：
+
+* 导出来的数据文件应当尽可能的小，可以通过设置选项 `-F` 来控制导出来的文件大小。如果后续使用 TiDB Lightning 对备份文件进行恢复，建议把 `dumpling` -F 选项的值设置为 `256m`。
+* 如果导出的表中有些表的行数非常多，可以通过设置选项 `-r` 来开启表内并发。
+
+## 从 TiDB 备份数据
+
+使用 `dumpling` 从 TiDB 备份数据的命令如下:
+
+{{< copyable "shell-regular" >}}
+
+```bash
+./bin/dumpling -h 127.0.0.1 -P 4000 -u root -t 32 -F 256m -T test.t1 -T test.t2 -o ./var/test
+```
+
+上述命令中，用 `-T test.t1 -T test.t2` 表明只导出 `test`.`t1`，`test`.`t2` 两张表。更多导出数据筛选方式可以参考[筛选导出的数据](/dumpling-overview.md#筛选导出的数据)。
+
+`-t 32` 表明使用 32 个线程来导出数据。`-F 256m` 是将实际的表切分成一定大小的 chunk，这里的 chunk 大小为 256MB。
+
+从 v4.0.0 版本开始，Dumpling 可以自动延长 GC 时间（Dumpling 需要访问 TiDB 集群的 PD 地址），而 v4.0.0 之前的版本，需要手动调整 GC 时间，否则 `dumpling` 备份时可能出现以下报错：
+
+```log
+Could not read data from testSchema.testTable: GC life time is shorter than transaction duration, transaction starts at 2019-08-05 21:10:01.451 +0800 CST, GC safe point is 2019-08-05 21:14:53.801 +0800 CST
+```
+
+手动调整 GC 时间的步骤如下：
+
+1. 执行 `dumpling` 命令前，查询 TiDB 集群的 [GC](/garbage-collection-overview.md) 值并在 MySQL 客户端执行下列语句将其调整为合适的值：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    SELECT * FROM mysql.tidb WHERE VARIABLE_NAME = 'tikv_gc_life_time';
+    ```
+
+    ```sql
+    +-----------------------+------------------------------------------------------------------------------------------------+
+    | VARIABLE_NAME         | VARIABLE_VALUE                                                                                 |
+    +-----------------------+------------------------------------------------------------------------------------------------+
+    | tikv_gc_life_time     | 10m0s                                                                                          |
+    +-----------------------+------------------------------------------------------------------------------------------------+
+    1 rows in set (0.02 sec)
+    ```
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    UPDATE mysql.tidb SET VARIABLE_VALUE = '720h' WHERE VARIABLE_NAME = 'tikv_gc_life_time';
+    ```
+
+2. 执行 `dumpling` 命令后，将 TiDB 集群的 GC 值恢复到第 1 步中的初始值：
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    UPDATE mysql.tidb SET VARIABLE_VALUE = '10m' WHERE VARIABLE_NAME = 'tikv_gc_life_time';
+    ```
+
+## 向 TiDB 恢复数据
+
+使用 TiDB Lightning 将之前导出的数据导入到 TiDB，完成恢复操作。具体的使用方法见 [TiDB Lightning 使用文档](/tidb-lightning/tidb-lightning-backends.md)

backup-and-restore-using-mydumper-lightning.md

@@ -78,15 +78,15 @@ aliases: ['/docs-cn/v3.0/backup-and-restore-using-mydumper-lightning/','/docs-cn
     {{< copyable "sql" >}}
 
     ```sql
-    update mysql.tidb set VARIABLE_VALUE = '720h' where VARIABLE_NAME = 'tikv_gc_life_time';
+    UPDATE mysql.tidb SET VARIABLE_VALUE = '720h' WHERE VARIABLE_NAME = 'tikv_gc_life_time';
     ```
 
 2. 执行 `mydumper` 命令后，将 TiDB 集群的 GC 值恢复到第 1 步中的初始值：
 
     {{< copyable "sql" >}}
 
     ```sql
-    update mysql.tidb set VARIABLE_VALUE = '10m' where VARIABLE_NAME = 'tikv_gc_life_time';
+    UPDATE mysql.tidb SET VARIABLE_VALUE = '10m' WHERE VARIABLE_NAME = 'tikv_gc_life_time';
     ```
 
 ## 向 TiDB 恢复数据

basic-sql-operations.md

@@ -40,7 +40,11 @@ SHOW DATABASES;
 {{< copyable "sql" >}}
 
 ```sql
+<<<<<<< HEAD
 DROP DATABASE samp_db;
+=======
+USE mysql;
+>>>>>>> 43758a91... Capitalize sql keywords in several files (#4862)
 ```
 
 ## 创建、查看和删除表
@@ -106,7 +110,11 @@ DROP TABLE person;
 {{< copyable "sql" >}}
 
 ```sql
+<<<<<<< HEAD
 DROP TABLE IF EXISTS person;
+=======
+SHOW CREATE TABLE person;
+>>>>>>> 43758a91... Capitalize sql keywords in several files (#4862)
 ```
 
 使用 `SHOW TABLES` 语句查看数据库中的所有表。例如：
@@ -156,7 +164,7 @@ ALTER TABLE person ADD UNIQUE person_num (number);
 {{< copyable "sql" >}}
 
 ```sql
-SHOW INDEX from person;
+SHOW INDEX FROM person;
 ```
 
 使用 `ALTER TABLE` 或 `DROP INDEX` 语句来删除索引。与 `CREATE INDEX` 语句类似，`DROP INDEX` 也可以嵌入 `ALTER TABLE` 语句。例如：
@@ -232,7 +240,11 @@ DELETE FROM person WHERE number=1;
 {{< copyable "sql" >}}
 
 ```sql
+<<<<<<< HEAD
 SELECT * FROM person;
+=======
+SELECT * FROM person WHERE id<5;
+>>>>>>> 43758a91... Capitalize sql keywords in several files (#4862)
 ```
 
 ```