From 35fd9bb5595a6fb791bdcd8ef4ddbaa914e03dab Mon Sep 17 00:00:00 2001 From: tangenta Date: Tue, 4 Feb 2020 17:29:19 +0800 Subject: [PATCH 01/15] reference: add user documentation for auto_random feature --- .../best-practices/high-concurrency.md | 4 +- .../tidb-server/configuration-file.md | 8 ++ dev/reference/sql/attributes/auto-random.md | 88 +++++++++++++++++++ .../sql/language-structure/comment-syntax.md | 2 +- .../keywords-and-reserved-words.md | 1 + dev/reference/sql/statements/create-table.md | 3 +- 6 files changed, 103 insertions(+), 3 deletions(-) create mode 100644 dev/reference/sql/attributes/auto-random.md diff --git a/dev/reference/best-practices/high-concurrency.md b/dev/reference/best-practices/high-concurrency.md index aecbb59f5c9b..77b999ebfcc7 100644 --- a/dev/reference/best-practices/high-concurrency.md +++ b/dev/reference/best-practices/high-concurrency.md @@ -170,7 +170,7 @@ SPLIT TABLE TEST_HOTSPOT BETWEEN (0) AND (9223372036854775807) REGIONS 128; ### 更复杂的热点问题 -如果表没有主键或者主键不是 Int 类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 +如果表没有主键或者主键不是整数类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 要避免由 `_tidb_rowid` 带来的写入热点问题，可以在建表时，使用 `SHARD_ROW_ID_BITS` 和 `PRE_SPLIT_REGIONS` 这两个建表选项（参阅 [`PRE_SPLIT_REGIONS` 的详细说明](/dev/reference/sql/statements/split-region.md#pre_split_regions)）。 @@ -193,6 +193,8 @@ create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; 开始写数据进表 t 后，数据会被写入提前切分好的 8 个 Region 中，这样也避免了刚开始建表完后因为只有一个 Region 而存在的写热点问题。 +对于有整数类型主键，并且使用了 `AUTO_INCREMENT` 来保证唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用其行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS`。要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/dev/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整形主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 + ## 参数配置 TiDB 2.1 版本中在 SQL 层引入了 [latch 机制](/dev/reference/configuration/tidb-server/configuration-file.md#txn-local-latches)，用于在写入冲突比较频繁的场景中提前发现事务冲突，减少 TiDB 和 TiKV 事务提交时写写冲突导致的重试。通常，跑批场景使用的是存量数据，所以并不存在事务的写入冲突。可以把 TiDB 的 latch 功能关闭，以减少为细小对象分配内存： diff --git a/dev/reference/configuration/tidb-server/configuration-file.md b/dev/reference/configuration/tidb-server/configuration-file.md index 9f4118e05721..b0af8efbd7bc 100644 --- a/dev/reference/configuration/tidb-server/configuration-file.md +++ b/dev/reference/configuration/tidb-server/configuration-file.md @@ -430,3 +430,11 @@ TiDB 服务状态相关配置。 + `events_statement_summary_by_digest` 表中`DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 列的最大显示长度。 + 默认值：4096 + +## experimental 从 v4.0.0 版本开始引入 + +### `allow-auto-random` + ++ 用于控制是否允许使用 `AUTO_RANDOM`。 ++ 默认值：false ++ 默认情况下，不支持增删主键。将此变量被设置为 true 后，支持增删主键功能。不过对在此开关开启前已经存在的表，且主键是整型类型时，即使之后开启此开关也不支持对此列表删除主键。 diff --git a/dev/reference/sql/attributes/auto-random.md b/dev/reference/sql/attributes/auto-random.md new file mode 100644 index 000000000000..8f93cb5b20bb --- /dev/null +++ b/dev/reference/sql/attributes/auto-random.md @@ -0,0 +1,88 @@ +--- +title: AUTO_RANDOM +category: reference +--- + +# AUTO_RANDOM 从 v4.0.0 版本开始引入 + +注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中添加 `[experimental] allow-auto-shard = true` 的小节后，才能正常使用。 + +## 简介 + +auto_random 用于解决大批量写入含有『整型自增主键列』表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/dev/reference/best-practices/high-concurrency.md) + +例如下表 + +```sql +create table t (a int primary key auto_increment, b varchar(255)) +``` + +在执行大量的没有指定主键值（a 列）的 insert 语句时，由于连续自增的行值作为 row_id，可能导致单个 TiKV 节点上产生写入热点，进而影响对外提供服务的性能。如果不希望有这种性能下降，可以在执行建表语句时为 a 列指定 auto_random 而不是 auto_increment，即 + +{{< copyable "sql" >}} + +```sql +create table t (a int primary key auto_random, b varchar(255)) +``` + +或者 + +{{< copyable "sql" >}} + +```sql +create table t (a int auto_random, b varchar(255), primary key (a)) +``` + +此时，如果 insert 语句没有指定整形主键列（a 列）的值，TiDB 会自动分配一个，该值不保证自增，不保证连续，只保证唯一，避免了连续 row_id 带来的热点问题；而如果 insert 语句显式指定了整形主键列的值，和 auto_increment 类似，TiDB 会原封不动地保存该值。 + +自动分配值的计算方式是，二进制形式下的最高 5 位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。如果希望使用一个不同的 shard bits 的数量，可以使用以下建表语句： + +{{< copyable "sql" >}} + +```sql +create table t (a int primary key auto_random(3), b varchar(255)) +``` + +此时，shard_bits 的数量为 3。该数量的取值范围是 [1, field_max_bits)，其中 field_max_bits 为整形主键列类型占用的位长度。 + +含有 auto_random 的表在 `information_schema.tables` 中 `TIDB_ROW_ID_SHARDING_INFO` 一列的值为 `PK_AUTO_RANDOM_BITS=x`，`x` 为 shard_bits 的数量。 + +## 兼容性 + +TiDB 支持解析版本注释语法，例如 + +{{< copyable "sql" >}} + +```sql +create table t (a int primary key /*T!40000 auto_random */) +``` + +和 + +{{< copyable "sql" >}} + +```sql +create table t (a int primary key auto_random) +``` + +具有相同含义。 + +在 `show create table` 的结果中，auto_random 属性会被注释掉，注释会附带一个版本号，例如 `/*T!40000 auto_random */`，其中 40000 表示 4.0.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释 auto_random 属性。 + +向前兼容，即降级兼容，新版本 TiDB 建立的含有 auto_random 的表能够被旧版本 TiDB 所使用。 + +## 局限性 + +目前 TiDB 中的 auto_random 有以下局限性： + +- 必须指定在整数类型的主键列上（例外情况见『关于 alter-primary-key 配置项的说明』一节），否则报错。 +- 不支持使用 alter table (change/modify) 来修改 auto_random 属性，包括添加/移除该属性。 +- 不支持修改含有 auto_random 属性的主键列的列类型。 +- 不支持与 auto_increment 同时指定在同一列上。 +- 不支持与 default 指定在同一列上。 +- 插入数据时，不建议自行显式指定含有 auto_random 列的值。原因是 rebase 仅针对除 shard_bits 以外的位进行。如果没有考虑到这一点，可能会导致提前耗尽用于自动分配的数值。 + +## 关于 alter-primary-key 配置项的说明： + +- 当 alter-primary-key = true 时，不支持使用 auto_random。 +- 配置文件中的 alter-primary-key 和 allow-auto-random 两个配置项的值不允许同时为 true。 diff --git a/dev/reference/sql/language-structure/comment-syntax.md b/dev/reference/sql/language-structure/comment-syntax.md index 8c67a32a3196..267ed9508739 100644 --- a/dev/reference/sql/language-structure/comment-syntax.md +++ b/dev/reference/sql/language-structure/comment-syntax.md @@ -107,7 +107,7 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： 在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` -如果注释中指定了 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 中，这个版本号不会起作用，所有的 comment 都会处理。TiDB 有自己的版本化注释语法，格式为 `/*T!40000 XXX */`。 还有一种注释会被当做是优化器 Hint 特殊对待： diff --git a/dev/reference/sql/language-structure/keywords-and-reserved-words.md b/dev/reference/sql/language-structure/keywords-and-reserved-words.md index 30aa376fa563..24c3da37850d 100644 --- a/dev/reference/sql/language-structure/keywords-and-reserved-words.md +++ b/dev/reference/sql/language-structure/keywords-and-reserved-words.md @@ -72,6 +72,7 @@ Query OK, 0 rows affected (0.08 sec) - ASC (R) - ASCII - AUTO_INCREMENT +- AUTO_RANDOM - AVG - AVG_ROW_LENGTH diff --git a/dev/reference/sql/statements/create-table.md b/dev/reference/sql/statements/create-table.md index d1bc93424d8b..dd6742376a11 100644 --- a/dev/reference/sql/statements/create-table.md +++ b/dev/reference/sql/statements/create-table.md @@ -100,7 +100,8 @@ create_definition: ```sql column_definition: data_type [NOT NULL | NULL] [DEFAULT default_value] - [AUTO_INCREMENT] [UNIQUE [KEY] | [PRIMARY] KEY] + [AUTO_INCREMENT | AUTO_RANDOM [(length)]] + [UNIQUE [KEY] | [PRIMARY] KEY] [COMMENT 'string'] [reference_definition] | data_type [GENERATED ALWAYS] AS (expression) From 971912713cd3c2863f81fe4175ba7f677642e0ac Mon Sep 17 00:00:00 2001 From: tangenta Date: Tue, 4 Feb 2020 19:04:47 +0800 Subject: [PATCH 02/15] reference: fix config description and lint --- dev/reference/configuration/tidb-server/configuration-file.md | 2 +- dev/reference/sql/attributes/auto-random.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/dev/reference/configuration/tidb-server/configuration-file.md b/dev/reference/configuration/tidb-server/configuration-file.md index b0af8efbd7bc..4a0b6993e4f7 100644 --- a/dev/reference/configuration/tidb-server/configuration-file.md +++ b/dev/reference/configuration/tidb-server/configuration-file.md @@ -437,4 +437,4 @@ TiDB 服务状态相关配置。 + 用于控制是否允许使用 `AUTO_RANDOM`。 + 默认值：false -+ 默认情况下，不支持增删主键。将此变量被设置为 true 后，支持增删主键功能。不过对在此开关开启前已经存在的表，且主键是整型类型时，即使之后开启此开关也不支持对此列表删除主键。 ++ 默认情况下，不支持使用 `AUTO_RANDOM`。当该值为 true 时，不允许同时设置 alter-primary-key 为 true。 diff --git a/dev/reference/sql/attributes/auto-random.md b/dev/reference/sql/attributes/auto-random.md index 8f93cb5b20bb..182cc99f999f 100644 --- a/dev/reference/sql/attributes/auto-random.md +++ b/dev/reference/sql/attributes/auto-random.md @@ -82,7 +82,7 @@ create table t (a int primary key auto_random) - 不支持与 default 指定在同一列上。 - 插入数据时，不建议自行显式指定含有 auto_random 列的值。原因是 rebase 仅针对除 shard_bits 以外的位进行。如果没有考虑到这一点，可能会导致提前耗尽用于自动分配的数值。 -## 关于 alter-primary-key 配置项的说明： +## 关于 alter-primary-key 配置项的说明 - 当 alter-primary-key = true 时，不支持使用 auto_random。 - 配置文件中的 alter-primary-key 和 allow-auto-random 两个配置项的值不允许同时为 true。 From 86588d48be586739e276467174230fa51c640836 Mon Sep 17 00:00:00 2001 From: tangenta Date: Tue, 4 Feb 2020 19:08:42 +0800 Subject: [PATCH 03/15] reference/sql: fix config description --- dev/reference/sql/attributes/auto-random.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev/reference/sql/attributes/auto-random.md b/dev/reference/sql/attributes/auto-random.md index 182cc99f999f..ef1e3aa1f252 100644 --- a/dev/reference/sql/attributes/auto-random.md +++ b/dev/reference/sql/attributes/auto-random.md @@ -5,7 +5,7 @@ category: reference # AUTO_RANDOM 从 v4.0.0 版本开始引入 -注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中添加 `[experimental] allow-auto-shard = true` 的小节后，才能正常使用。 +注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-shard = true` 后，才能正常使用。 ## 简介 From 67875fb670d716b5cfdbe426b7ffd8c1f3975a79 Mon Sep 17 00:00:00 2001 From: tangenta Date: Sun, 9 Feb 2020 23:17:13 +0800 Subject: [PATCH 04/15] reference: apply changes to v3.1 --- .../best-practices/high-concurrency.md | 4 +- .../tidb-server/configuration-file.md | 8 ++ v3.1/reference/sql/attributes/auto-random.md | 88 +++++++++++++++++++ .../sql/language-structure/comment-syntax.md | 2 +- .../keywords-and-reserved-words.md | 1 + v3.1/reference/sql/statements/create-table.md | 3 +- 6 files changed, 103 insertions(+), 3 deletions(-) create mode 100644 v3.1/reference/sql/attributes/auto-random.md diff --git a/v3.1/reference/best-practices/high-concurrency.md b/v3.1/reference/best-practices/high-concurrency.md index 8afbb297066c..17979ec3c97f 100644 --- a/v3.1/reference/best-practices/high-concurrency.md +++ b/v3.1/reference/best-practices/high-concurrency.md @@ -170,7 +170,7 @@ SPLIT TABLE TEST_HOTSPOT BETWEEN (0) AND (9223372036854775807) REGIONS 128; ### 更复杂的热点问题 -如果表没有主键或者主键不是 Int 类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 +如果表没有主键或者主键不是整数类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 要避免由 `_tidb_rowid` 带来的写入热点问题，可以在建表时，使用 `SHARD_ROW_ID_BITS` 和 `PRE_SPLIT_REGIONS` 这两个建表选项（参阅 [`PRE_SPLIT_REGIONS` 的详细说明](/v3.1/reference/sql/statements/split-region.md#pre_split_regions)）。 @@ -193,6 +193,8 @@ create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; 开始写数据进表 t 后，数据会被写入提前切分好的 8 个 Region 中，这样也避免了刚开始建表完后因为只有一个 Region 而存在的写热点问题。 +对于有整数类型主键，并且使用了 `AUTO_INCREMENT` 来保证唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用其行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS`。要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/v3.1/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整形主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 + ## 参数配置 TiDB 2.1 版本中在 SQL 层引入了 [latch 机制](/v3.1/reference/configuration/tidb-server/configuration-file.md#txn-local-latches)，用于在写入冲突比较频繁的场景中提前发现事务冲突，减少 TiDB 和 TiKV 事务提交时写写冲突导致的重试。通常，跑批场景使用的是存量数据，所以并不存在事务的写入冲突。可以把 TiDB 的 latch 功能关闭，以减少为细小对象分配内存： diff --git a/v3.1/reference/configuration/tidb-server/configuration-file.md b/v3.1/reference/configuration/tidb-server/configuration-file.md index 2ba6d379f2d2..1f58ed91a5a7 100644 --- a/v3.1/reference/configuration/tidb-server/configuration-file.md +++ b/v3.1/reference/configuration/tidb-server/configuration-file.md @@ -408,3 +408,11 @@ TiDB 服务状态相关配置。 + `events_statement_summary_by_digest` 表中`DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 列的最大显示长度。 + 默认值：4096 + +## experimental 从 v4.0.0 版本开始引入 + +### `allow-auto-random` + ++ 用于控制是否允许使用 `AUTO_RANDOM`。 ++ 默认值：false ++ 默认情况下，不支持使用 `AUTO_RANDOM`。当该值为 true 时，不允许同时设置 alter-primary-key 为 true。 diff --git a/v3.1/reference/sql/attributes/auto-random.md b/v3.1/reference/sql/attributes/auto-random.md new file mode 100644 index 000000000000..aff6fd378b55 --- /dev/null +++ b/v3.1/reference/sql/attributes/auto-random.md @@ -0,0 +1,88 @@ +--- +title: AUTO_RANDOM +category: reference +--- + +# AUTO_RANDOM 从 v4.0.0 版本开始引入 + +注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-shard = true` 后，才能正常使用。 + +## 简介 + +auto_random 用于解决大批量写入含有『整型自增主键列』表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/v3.1/reference/best-practices/high-concurrency.md) + +例如下表 + +```sql +create table t (a int primary key auto_increment, b varchar(255)) +``` + +在执行大量的没有指定主键值（a 列）的 insert 语句时，由于连续自增的行值作为 row_id，可能导致单个 TiKV 节点上产生写入热点，进而影响对外提供服务的性能。如果不希望有这种性能下降，可以在执行建表语句时为 a 列指定 auto_random 而不是 auto_increment，即 + +{{< copyable "sql" >}} + +```sql +create table t (a int primary key auto_random, b varchar(255)) +``` + +或者 + +{{< copyable "sql" >}} + +```sql +create table t (a int auto_random, b varchar(255), primary key (a)) +``` + +此时，如果 insert 语句没有指定整形主键列（a 列）的值，TiDB 会自动分配一个，该值不保证自增，不保证连续，只保证唯一，避免了连续 row_id 带来的热点问题；而如果 insert 语句显式指定了整形主键列的值，和 auto_increment 类似，TiDB 会原封不动地保存该值。 + +自动分配值的计算方式是，二进制形式下的最高 5 位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。如果希望使用一个不同的 shard bits 的数量，可以使用以下建表语句： + +{{< copyable "sql" >}} + +```sql +create table t (a int primary key auto_random(3), b varchar(255)) +``` + +此时，shard_bits 的数量为 3。该数量的取值范围是 [1, field_max_bits)，其中 field_max_bits 为整形主键列类型占用的位长度。 + +含有 auto_random 的表在 `information_schema.tables` 中 `TIDB_ROW_ID_SHARDING_INFO` 一列的值为 `PK_AUTO_RANDOM_BITS=x`，`x` 为 shard_bits 的数量。 + +## 兼容性 + +TiDB 支持解析版本注释语法，例如 + +{{< copyable "sql" >}} + +```sql +create table t (a int primary key /*T!40000 auto_random */) +``` + +和 + +{{< copyable "sql" >}} + +```sql +create table t (a int primary key auto_random) +``` + +具有相同含义。 + +在 `show create table` 的结果中，auto_random 属性会被注释掉，注释会附带一个版本号，例如 `/*T!40000 auto_random */`，其中 40000 表示 4.0.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释 auto_random 属性。 + +向前兼容，即降级兼容，新版本 TiDB 建立的含有 auto_random 的表能够被旧版本 TiDB 所使用。 + +## 局限性 + +目前 TiDB 中的 auto_random 有以下局限性： + +- 必须指定在整数类型的主键列上（例外情况见『关于 alter-primary-key 配置项的说明』一节），否则报错。 +- 不支持使用 alter table (change/modify) 来修改 auto_random 属性，包括添加/移除该属性。 +- 不支持修改含有 auto_random 属性的主键列的列类型。 +- 不支持与 auto_increment 同时指定在同一列上。 +- 不支持与 default 指定在同一列上。 +- 插入数据时，不建议自行显式指定含有 auto_random 列的值。原因是 rebase 仅针对除 shard_bits 以外的位进行。如果没有考虑到这一点，可能会导致提前耗尽用于自动分配的数值。 + +## 关于 alter-primary-key 配置项的说明 + +- 当 alter-primary-key = true 时，不支持使用 auto_random。 +- 配置文件中的 alter-primary-key 和 allow-auto-random 两个配置项的值不允许同时为 true。 diff --git a/v3.1/reference/sql/language-structure/comment-syntax.md b/v3.1/reference/sql/language-structure/comment-syntax.md index 2c29acb67fb6..6d375a543e36 100644 --- a/v3.1/reference/sql/language-structure/comment-syntax.md +++ b/v3.1/reference/sql/language-structure/comment-syntax.md @@ -107,7 +107,7 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： 在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` -如果注释中指定了 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 中，这个版本号不会起作用，所有的 comment 都会处理。TiDB 有自己的版本化注释语法，格式为 `/*T!40000 XXX */`。 还有一种注释会被当做是优化器 Hint 特殊对待： diff --git a/v3.1/reference/sql/language-structure/keywords-and-reserved-words.md b/v3.1/reference/sql/language-structure/keywords-and-reserved-words.md index 75b1ea3ec5b7..717af63c6f8e 100644 --- a/v3.1/reference/sql/language-structure/keywords-and-reserved-words.md +++ b/v3.1/reference/sql/language-structure/keywords-and-reserved-words.md @@ -72,6 +72,7 @@ Query OK, 0 rows affected (0.08 sec) - ASC (R) - ASCII - AUTO_INCREMENT +- AUTO_RANDOM - AVG - AVG_ROW_LENGTH diff --git a/v3.1/reference/sql/statements/create-table.md b/v3.1/reference/sql/statements/create-table.md index 892296a700ee..dc937e606ddd 100644 --- a/v3.1/reference/sql/statements/create-table.md +++ b/v3.1/reference/sql/statements/create-table.md @@ -100,7 +100,8 @@ create_definition: ```sql column_definition: data_type [NOT NULL | NULL] [DEFAULT default_value] - [AUTO_INCREMENT] [UNIQUE [KEY] | [PRIMARY] KEY] + [AUTO_INCREMENT | AUTO_RANDOM [(length)]] + [UNIQUE [KEY] | [PRIMARY] KEY] [COMMENT 'string'] [reference_definition] | data_type [GENERATED ALWAYS] AS (expression) From 4aa3348fe94088c3f010e3cdca8a54a47b3901be Mon Sep 17 00:00:00 2001 From: tangenta Date: Mon, 10 Feb 2020 13:18:02 +0800 Subject: [PATCH 05/15] reference: fix typo --- dev/reference/sql/attributes/auto-random.md | 4 ++-- v3.1/reference/sql/attributes/auto-random.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/dev/reference/sql/attributes/auto-random.md b/dev/reference/sql/attributes/auto-random.md index ef1e3aa1f252..c6e68f79d3f8 100644 --- a/dev/reference/sql/attributes/auto-random.md +++ b/dev/reference/sql/attributes/auto-random.md @@ -5,11 +5,11 @@ category: reference # AUTO_RANDOM 从 v4.0.0 版本开始引入 -注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-shard = true` 后，才能正常使用。 +注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-random = true` 后，才能正常使用。 ## 简介 -auto_random 用于解决大批量写入含有『整型自增主键列』表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/dev/reference/best-practices/high-concurrency.md) +auto_random 用于解决大批量写入含有__整型自增主键列__的表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/dev/reference/best-practices/high-concurrency.md) 例如下表 diff --git a/v3.1/reference/sql/attributes/auto-random.md b/v3.1/reference/sql/attributes/auto-random.md index aff6fd378b55..c0b221ff1842 100644 --- a/v3.1/reference/sql/attributes/auto-random.md +++ b/v3.1/reference/sql/attributes/auto-random.md @@ -5,11 +5,11 @@ category: reference # AUTO_RANDOM 从 v4.0.0 版本开始引入 -注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-shard = true` 后，才能正常使用。 +注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-random = true` 后，才能正常使用。 ## 简介 -auto_random 用于解决大批量写入含有『整型自增主键列』表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/v3.1/reference/best-practices/high-concurrency.md) +auto_random 用于解决大批量写入含有__整型自增主键列__的表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/v3.1/reference/best-practices/high-concurrency.md) 例如下表 From 86a8552f226945dc25800b92aa1945425c08c8df Mon Sep 17 00:00:00 2001 From: tangenta Date: Wed, 12 Feb 2020 13:43:10 +0800 Subject: [PATCH 06/15] reference: fix typo and style --- .../tidb-server/configuration-file.md | 2 + dev/reference/sql/attributes/auto-random.md | 67 +++++++++++------- .../sql/language-structure/comment-syntax.md | 2 +- patch.diff | 18 +++++ .../tidb-server/configuration-file.md | 4 +- v3.1/reference/sql/attributes/auto-random.md | 69 +++++++++++-------- .../sql/language-structure/comment-syntax.md | 2 +- 7 files changed, 108 insertions(+), 56 deletions(-) create mode 100644 patch.diff diff --git a/dev/reference/configuration/tidb-server/configuration-file.md b/dev/reference/configuration/tidb-server/configuration-file.md index 4a0b6993e4f7..dc2ca96ace2a 100644 --- a/dev/reference/configuration/tidb-server/configuration-file.md +++ b/dev/reference/configuration/tidb-server/configuration-file.md @@ -433,6 +433,8 @@ TiDB 服务状态相关配置。 ## experimental 从 v4.0.0 版本开始引入 +TiDB 实验功能相关配置。 + ### `allow-auto-random` + 用于控制是否允许使用 `AUTO_RANDOM`。 diff --git a/dev/reference/sql/attributes/auto-random.md b/dev/reference/sql/attributes/auto-random.md index c6e68f79d3f8..31816c02ba8c 100644 --- a/dev/reference/sql/attributes/auto-random.md +++ b/dev/reference/sql/attributes/auto-random.md @@ -5,19 +5,29 @@ category: reference # AUTO_RANDOM 从 v4.0.0 版本开始引入 -注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-random = true` 后，才能正常使用。 +> **警告：** +> +> 当前 `AUTO_RANDOM` 属性为实验功能，**不建议在生产环境中使用**。在后续版本中，`AUTO_RANDOM` 的语法或语义可能会变化。 -## 简介 +使用 `AUTO_RANDOM` 功能前，须在 TiDB 配置文件 `experimental` 部分设置 `allow-auto-random = true`。该参数详情可参见 [`allow-auto-random`](/dev/reference/configuration/tidb-server/configuration-file.md#allow-auto-random)。 -auto_random 用于解决大批量写入含有__整型自增主键列__的表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/dev/reference/best-practices/high-concurrency.md) +## 使用场景 -例如下表 +`AUTO_RANDOM` 用于解决大批量写数据入 TiDB 时因含有**整型自增主键列**的表而产生的热点问题。详情参阅 [TiDB 高并发写入场景最佳实践](/dev/reference/best-practices/high-concurrency.md)。 + +以下面语句建立的表为例： ```sql create table t (a int primary key auto_increment, b varchar(255)) ``` -在执行大量的没有指定主键值（a 列）的 insert 语句时，由于连续自增的行值作为 row_id，可能导致单个 TiKV 节点上产生写入热点，进而影响对外提供服务的性能。如果不希望有这种性能下降，可以在执行建表语句时为 a 列指定 auto_random 而不是 auto_increment，即 +对这样的表执行大量的未指定主键值的 `INSERT` 语句时，如 + +```sql +insert into t(b) values ('a'), ('b'), ('c') +``` + +由于未指定主键列的值（`a` 列），TiDB 会使用连续自增的行值作为行 ID，可能导致单个 TiKV 节点上产生写入热点，进而影响对外提供服务的性能。要避免这种性能下降，可以在执行建表语句时为 `a` 列指定 `AUTO_RANDOM` 属性而不是 `AUTO_INCREMENT` 属性。示例如下： {{< copyable "sql" >}} @@ -33,9 +43,16 @@ create table t (a int primary key auto_random, b varchar(255)) create table t (a int auto_random, b varchar(255), primary key (a)) ``` -此时，如果 insert 语句没有指定整形主键列（a 列）的值，TiDB 会自动分配一个，该值不保证自增，不保证连续，只保证唯一，避免了连续 row_id 带来的热点问题；而如果 insert 语句显式指定了整形主键列的值，和 auto_increment 类似，TiDB 会原封不动地保存该值。 +此时再执行形如 `INSERT INTO t(b) values...` 的 `INSERT` 语句， -自动分配值的计算方式是，二进制形式下的最高 5 位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。如果希望使用一个不同的 shard bits 的数量，可以使用以下建表语句： ++ 如果该 `INSERT` 语句没有指定整形主键列（`a` 列）的值，TiDB 会为该列自动分配值。该值不保证自增，不保证连续，只保证唯一，避免了连续的行 ID 带来的热点问题。 ++ 如果该 `INSERT` 语句显式指定了整形主键列的值，和 `AUTO_INCREMENT` 属性类似，TiDB 会原封不动地保存该值。 + +自动分配值的计算方式如下： + +二进制形式下的最高 5 位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。 + +如果希望使用一个不同的 shard bits 的数量，可以在 `AUTO_RANDOM` 后面加一对括号，并在括号中指定，例如： {{< copyable "sql" >}} @@ -43,13 +60,13 @@ create table t (a int auto_random, b varchar(255), primary key (a)) create table t (a int primary key auto_random(3), b varchar(255)) ``` -此时，shard_bits 的数量为 3。该数量的取值范围是 [1, field_max_bits)，其中 field_max_bits 为整形主键列类型占用的位长度。 +以上建表语句中，shard bits 的数量为 `3`。shard bits 的数量的取值范围是 `[1, field_max_bits)`，其中 `field_max_bits` 为整形主键列类型占用的位长度。 -含有 auto_random 的表在 `information_schema.tables` 中 `TIDB_ROW_ID_SHARDING_INFO` 一列的值为 `PK_AUTO_RANDOM_BITS=x`，`x` 为 shard_bits 的数量。 +含有 `AUTO_RANDOM` 属性的表在 `information_schema.tables` 中 `TIDB_ROW_ID_SHARDING_INFO` 一列的值为 `PK_AUTO_RANDOM_BITS=x`，其中 `x` 为 shard bits 的数量。 ## 兼容性 -TiDB 支持解析版本注释语法，例如 +TiDB 支持解析版本注释语法。示例如下： {{< copyable "sql" >}} @@ -57,32 +74,30 @@ TiDB 支持解析版本注释语法，例如 create table t (a int primary key /*T!40000 auto_random */) ``` -和 - {{< copyable "sql" >}} ```sql create table t (a int primary key auto_random) ``` -具有相同含义。 +以上两个语句含义相同。 -在 `show create table` 的结果中，auto_random 属性会被注释掉，注释会附带一个版本号，例如 `/*T!40000 auto_random */`，其中 40000 表示 4.0.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释 auto_random 属性。 +在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个版本号，例如 `/*T!40000 auto_random */`。其中 `40000` 表示 v4.0.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释的 `AUTO_RANDOM` 属性。 -向前兼容，即降级兼容，新版本 TiDB 建立的含有 auto_random 的表能够被旧版本 TiDB 所使用。 +该功能支持向前兼容，即降级兼容。新版本 TiDB 建立的含有 `AUTO_RANDOM` 的表可以被旧版本 TiDB 所使用。 -## 局限性 +## 使用限制 -目前 TiDB 中的 auto_random 有以下局限性： +目前在 TiDB 中使用 `AUTO_RANDOM` 有以下限制： -- 必须指定在整数类型的主键列上（例外情况见『关于 alter-primary-key 配置项的说明』一节），否则报错。 -- 不支持使用 alter table (change/modify) 来修改 auto_random 属性，包括添加/移除该属性。 -- 不支持修改含有 auto_random 属性的主键列的列类型。 -- 不支持与 auto_increment 同时指定在同一列上。 -- 不支持与 default 指定在同一列上。 -- 插入数据时，不建议自行显式指定含有 auto_random 列的值。原因是 rebase 仅针对除 shard_bits 以外的位进行。如果没有考虑到这一点，可能会导致提前耗尽用于自动分配的数值。 +- 该属性必须指定在整数类型的主键列上，否则会报错。例外情况见[关于 `alter-primary-key` 配置项的说明](#关于-alter-primary-key-配置项的说明)。 +- 不支持使用 `ALTER TABLE` 来修改 `AUTO_RANDOM` 属性，包括添加/移除该属性。 +- 不支持修改含有 `AUTO_RANDOM` 属性的主键列的列类型。 +- 不支持与 `AUTO_INCREMENT` 同时指定在同一列上。 +- 不支持与 `DEFAULT` 同时指定在同一列上。 +- 插入数据时，不建议自行显式指定含有 `AUTO_RANDOM` 列的值。不恰当地显式赋值，可能会导致该表提前耗尽用于自动分配的数值。因为用于保证唯一性的 rebase 仅针对除 shard bits 以外的位进行。 -## 关于 alter-primary-key 配置项的说明 +## 关于 `alter-primary-key` 配置项的说明 -- 当 alter-primary-key = true 时，不支持使用 auto_random。 -- 配置文件中的 alter-primary-key 和 allow-auto-random 两个配置项的值不允许同时为 true。 +- 当 `alter-primary-key = true` 时，不支持使用 `AUTO_RANDOM`。 +- 配置文件中的 `alter-primary-key` 和 `allow-auto-random` 两个配置项的值不允许同时为 `true`。 diff --git a/dev/reference/sql/language-structure/comment-syntax.md b/dev/reference/sql/language-structure/comment-syntax.md index 267ed9508739..6849fa24d5aa 100644 --- a/dev/reference/sql/language-structure/comment-syntax.md +++ b/dev/reference/sql/language-structure/comment-syntax.md @@ -107,7 +107,7 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： 在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。TiDB 有自己的版本化注释语法，格式为 `/*T!40000 XXX */`。 +如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!40000 XXX */`。 还有一种注释会被当做是优化器 Hint 特殊对待： diff --git a/patch.diff b/patch.diff new file mode 100644 index 000000000000..62cc51eaa304 --- /dev/null +++ b/patch.diff @@ -0,0 +1,18 @@ +diff --git a/v3.1/reference/sql/attributes/auto-random.md b/v3.1/reference/sql/attributes/auto-random.md +index ef1e3aa1..c6e68f79 100644 +--- a/v3.1/reference/sql/attributes/auto-random.md ++++ b/v3.1/reference/sql/attributes/auto-random.md +@@ -5,11 +5,11 @@ category: reference + + # AUTO_RANDOM 从 v4.0.0 版本开始引入 + +-注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-shard = true` 后，才能正常使用。 ++注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-random = true` 后，才能正常使用。 + + ## 简介 + +-auto_random 用于解决大批量写入含有『整型自增主键列』表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/v3.1/reference/best-practices/high-concurrency.md) ++auto_random 用于解决大批量写入含有__整型自增主键列__的表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/v3.1/reference/best-practices/high-concurrency.md) + + 例如下表 + diff --git a/v3.1/reference/configuration/tidb-server/configuration-file.md b/v3.1/reference/configuration/tidb-server/configuration-file.md index 1f58ed91a5a7..6cf362e6ed82 100644 --- a/v3.1/reference/configuration/tidb-server/configuration-file.md +++ b/v3.1/reference/configuration/tidb-server/configuration-file.md @@ -409,7 +409,9 @@ TiDB 服务状态相关配置。 + `events_statement_summary_by_digest` 表中`DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 列的最大显示长度。 + 默认值：4096 -## experimental 从 v4.0.0 版本开始引入 +## experimental 从 v3.0.1 版本开始引入 + +TiDB 实验功能相关配置。 ### `allow-auto-random` diff --git a/v3.1/reference/sql/attributes/auto-random.md b/v3.1/reference/sql/attributes/auto-random.md index c0b221ff1842..a7774603a10a 100644 --- a/v3.1/reference/sql/attributes/auto-random.md +++ b/v3.1/reference/sql/attributes/auto-random.md @@ -3,21 +3,31 @@ title: AUTO_RANDOM category: reference --- -# AUTO_RANDOM 从 v4.0.0 版本开始引入 +# AUTO_RANDOM 从 v3.1.0 版本开始引入 -注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-random = true` 后，才能正常使用。 +> **警告：** +> +> 当前 `AUTO_RANDOM` 属性为实验功能，**不建议在生产环境中使用**。在后续版本中，`AUTO_RANDOM` 的语法或语义可能会变化。 -## 简介 +使用 `AUTO_RANDOM` 功能前，须在 TiDB 配置文件 `experimental` 部分设置 `allow-auto-random = true`。该参数详情可参见 [`allow-auto-random`](/dev/reference/configuration/tidb-server/configuration-file.md#allow-auto-random)。 -auto_random 用于解决大批量写入含有__整型自增主键列__的表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/v3.1/reference/best-practices/high-concurrency.md) +## 使用场景 -例如下表 +`AUTO_RANDOM` 用于解决大批量写数据入 TiDB 时因含有**整型自增主键列**的表而产生的热点问题。详情参阅 [TiDB 高并发写入场景最佳实践](/v3.1/reference/best-practices/high-concurrency.md)。 + +以下面语句建立的表为例： ```sql create table t (a int primary key auto_increment, b varchar(255)) ``` -在执行大量的没有指定主键值（a 列）的 insert 语句时，由于连续自增的行值作为 row_id，可能导致单个 TiKV 节点上产生写入热点，进而影响对外提供服务的性能。如果不希望有这种性能下降，可以在执行建表语句时为 a 列指定 auto_random 而不是 auto_increment，即 +对这样的表执行大量的未指定主键值的 `INSERT` 语句时，如 + +```sql +insert into t(b) values ('a'), ('b'), ('c') +``` + +由于未指定主键列的值（`a` 列），TiDB 会使用连续自增的行值作为行 ID，可能导致单个 TiKV 节点上产生写入热点，进而影响对外提供服务的性能。要避免这种性能下降，可以在执行建表语句时为 `a` 列指定 `AUTO_RANDOM` 属性而不是 `AUTO_INCREMENT` 属性。示例如下： {{< copyable "sql" >}} @@ -33,9 +43,16 @@ create table t (a int primary key auto_random, b varchar(255)) create table t (a int auto_random, b varchar(255), primary key (a)) ``` -此时，如果 insert 语句没有指定整形主键列（a 列）的值，TiDB 会自动分配一个，该值不保证自增，不保证连续，只保证唯一，避免了连续 row_id 带来的热点问题；而如果 insert 语句显式指定了整形主键列的值，和 auto_increment 类似，TiDB 会原封不动地保存该值。 +此时再执行形如 `INSERT INTO t(b) values...` 的 `INSERT` 语句， -自动分配值的计算方式是，二进制形式下的最高 5 位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。如果希望使用一个不同的 shard bits 的数量，可以使用以下建表语句： ++ 如果该 `INSERT` 语句没有指定整形主键列（`a` 列）的值，TiDB 会为该列自动分配值。该值不保证自增，不保证连续，只保证唯一，避免了连续的行 ID 带来的热点问题。 ++ 如果该 `INSERT` 语句显式指定了整形主键列的值，和 `AUTO_INCREMENT` 属性类似，TiDB 会原封不动地保存该值。 + +自动分配值的计算方式如下： + +二进制形式下的最高 5 位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。 + +如果希望使用一个不同的 shard bits 的数量，可以在 `AUTO_RANDOM` 后面加一对括号，并在括号中指定，例如： {{< copyable "sql" >}} @@ -43,13 +60,13 @@ create table t (a int auto_random, b varchar(255), primary key (a)) create table t (a int primary key auto_random(3), b varchar(255)) ``` -此时，shard_bits 的数量为 3。该数量的取值范围是 [1, field_max_bits)，其中 field_max_bits 为整形主键列类型占用的位长度。 +以上建表语句中，shard bits 的数量为 `3`。shard bits 的数量的取值范围是 `[1, field_max_bits)`，其中 `field_max_bits` 为整形主键列类型占用的位长度。 -含有 auto_random 的表在 `information_schema.tables` 中 `TIDB_ROW_ID_SHARDING_INFO` 一列的值为 `PK_AUTO_RANDOM_BITS=x`，`x` 为 shard_bits 的数量。 +含有 `AUTO_RANDOM` 属性的表在 `information_schema.tables` 中 `TIDB_ROW_ID_SHARDING_INFO` 一列的值为 `PK_AUTO_RANDOM_BITS=x`，其中 `x` 为 shard bits 的数量。 ## 兼容性 -TiDB 支持解析版本注释语法，例如 +TiDB 支持解析版本注释语法。示例如下： {{< copyable "sql" >}} @@ -57,32 +74,30 @@ TiDB 支持解析版本注释语法，例如 create table t (a int primary key /*T!40000 auto_random */) ``` -和 - {{< copyable "sql" >}} ```sql create table t (a int primary key auto_random) ``` -具有相同含义。 +以上两个语句含义相同。 -在 `show create table` 的结果中，auto_random 属性会被注释掉，注释会附带一个版本号，例如 `/*T!40000 auto_random */`，其中 40000 表示 4.0.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释 auto_random 属性。 +在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个版本号，例如 `/*T!40000 auto_random */`。其中 `40000` 表示 v4.0.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释的 `AUTO_RANDOM` 属性。 -向前兼容，即降级兼容，新版本 TiDB 建立的含有 auto_random 的表能够被旧版本 TiDB 所使用。 +该功能支持向前兼容，即降级兼容。新版本 TiDB 建立的含有 `AUTO_RANDOM` 的表可以被旧版本 TiDB 所使用。 -## 局限性 +## 使用限制 -目前 TiDB 中的 auto_random 有以下局限性： +目前在 TiDB 中使用 `AUTO_RANDOM` 有以下限制： -- 必须指定在整数类型的主键列上（例外情况见『关于 alter-primary-key 配置项的说明』一节），否则报错。 -- 不支持使用 alter table (change/modify) 来修改 auto_random 属性，包括添加/移除该属性。 -- 不支持修改含有 auto_random 属性的主键列的列类型。 -- 不支持与 auto_increment 同时指定在同一列上。 -- 不支持与 default 指定在同一列上。 -- 插入数据时，不建议自行显式指定含有 auto_random 列的值。原因是 rebase 仅针对除 shard_bits 以外的位进行。如果没有考虑到这一点，可能会导致提前耗尽用于自动分配的数值。 +- 该属性必须指定在整数类型的主键列上，否则会报错。例外情况见[关于 `alter-primary-key` 配置项的说明](#关于-alter-primary-key-配置项的说明)。 +- 不支持使用 `ALTER TABLE` 来修改 `AUTO_RANDOM` 属性，包括添加/移除该属性。 +- 不支持修改含有 `AUTO_RANDOM` 属性的主键列的列类型。 +- 不支持与 `AUTO_INCREMENT` 同时指定在同一列上。 +- 不支持与 `DEFAULT` 同时指定在同一列上。 +- 插入数据时，不建议自行显式指定含有 `AUTO_RANDOM` 列的值。不恰当地显式赋值，可能会导致该表提前耗尽用于自动分配的数值。因为用于保证唯一性的 rebase 仅针对除 shard bits 以外的位进行。 -## 关于 alter-primary-key 配置项的说明 +## 关于 `alter-primary-key` 配置项的说明 -- 当 alter-primary-key = true 时，不支持使用 auto_random。 -- 配置文件中的 alter-primary-key 和 allow-auto-random 两个配置项的值不允许同时为 true。 +- 当 `alter-primary-key = true` 时，不支持使用 `AUTO_RANDOM`。 +- 配置文件中的 `alter-primary-key` 和 `allow-auto-random` 两个配置项的值不允许同时为 `true`。 diff --git a/v3.1/reference/sql/language-structure/comment-syntax.md b/v3.1/reference/sql/language-structure/comment-syntax.md index 6d375a543e36..c38c7c975ebf 100644 --- a/v3.1/reference/sql/language-structure/comment-syntax.md +++ b/v3.1/reference/sql/language-structure/comment-syntax.md @@ -107,7 +107,7 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： 在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。TiDB 有自己的版本化注释语法，格式为 `/*T!40000 XXX */`。 +如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!40000 XXX */`。 还有一种注释会被当做是优化器 Hint 特殊对待： From eb741a4d62976d572411dd78ee6dc694fe3a5a3b Mon Sep 17 00:00:00 2001 From: tangenta Date: Wed, 12 Feb 2020 13:46:54 +0800 Subject: [PATCH 07/15] add sql/attributes/auto_random.md link to TOC.md --- dev/TOC.md | 2 ++ v3.1/TOC.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/dev/TOC.md b/dev/TOC.md index 31257a6a02e0..3e7f2301cda2 100644 --- a/dev/TOC.md +++ b/dev/TOC.md @@ -83,6 +83,8 @@ - [用户自定义变量](/dev/reference/sql/language-structure/user-defined-variables.md) - [表达式语法](/dev/reference/sql/language-structure/expression-syntax.md) - [注释语法](/dev/reference/sql/language-structure/comment-syntax.md) + + 表属性和列属性 + - [`AUTO_RANDOM`](/dev/reference/sql/attributes/auto-random.md) + 数据类型 - [概述](/dev/reference/sql/data-types/overview.md) - [默认值](/dev/reference/sql/data-types/default-values.md) diff --git a/v3.1/TOC.md b/v3.1/TOC.md index 5aadf13899bc..4e5907cfc8ed 100644 --- a/v3.1/TOC.md +++ b/v3.1/TOC.md @@ -84,6 +84,8 @@ - [用户自定义变量](/v3.1/reference/sql/language-structure/user-defined-variables.md) - [表达式语法](/v3.1/reference/sql/language-structure/expression-syntax.md) - [注释语法](/v3.1/reference/sql/language-structure/comment-syntax.md) + + 表属性和列属性 + - [`AUTO_RANDOM`](/v3.1/reference/sql/attributes/auto-random.md) + 数据类型 - [概述](/v3.1/reference/sql/data-types/overview.md) - [默认值](/v3.1/reference/sql/data-types/default-values.md) From f58ec2c9c81c165a0dfecd8c94459109ac161889 Mon Sep 17 00:00:00 2001 From: tangenta Date: Wed, 12 Feb 2020 15:55:49 +0800 Subject: [PATCH 08/15] reference/sql: fix dead link --- v3.1/reference/sql/attributes/auto-random.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/v3.1/reference/sql/attributes/auto-random.md b/v3.1/reference/sql/attributes/auto-random.md index a7774603a10a..30684592bbac 100644 --- a/v3.1/reference/sql/attributes/auto-random.md +++ b/v3.1/reference/sql/attributes/auto-random.md @@ -9,7 +9,7 @@ category: reference > > 当前 `AUTO_RANDOM` 属性为实验功能，**不建议在生产环境中使用**。在后续版本中，`AUTO_RANDOM` 的语法或语义可能会变化。 -使用 `AUTO_RANDOM` 功能前，须在 TiDB 配置文件 `experimental` 部分设置 `allow-auto-random = true`。该参数详情可参见 [`allow-auto-random`](/dev/reference/configuration/tidb-server/configuration-file.md#allow-auto-random)。 +使用 `AUTO_RANDOM` 功能前，须在 TiDB 配置文件 `experimental` 部分设置 `allow-auto-random = true`。该参数详情可参见 [`allow-auto-random`](/v3.1/reference/configuration/tidb-server/configuration-file.md#allow-auto-random)。 ## 使用场景 From f9e773085b88b4543c16e81c1394754b21769794 Mon Sep 17 00:00:00 2001 From: tangenta Date: Sun, 16 Feb 2020 14:31:17 +0800 Subject: [PATCH 09/15] reference/sql: refinerauto_random description --- dev/reference/sql/attributes/auto-random.md | 8 ++++---- v3.1/reference/sql/attributes/auto-random.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/dev/reference/sql/attributes/auto-random.md b/dev/reference/sql/attributes/auto-random.md index 31816c02ba8c..1e2e1f50f60c 100644 --- a/dev/reference/sql/attributes/auto-random.md +++ b/dev/reference/sql/attributes/auto-random.md @@ -50,7 +50,7 @@ create table t (a int auto_random, b varchar(255), primary key (a)) 自动分配值的计算方式如下： -二进制形式下的最高 5 位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。 +该行值在二进制形式下的最高 5 位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。 如果希望使用一个不同的 shard bits 的数量，可以在 `AUTO_RANDOM` 后面加一对括号，并在括号中指定，例如： @@ -84,17 +84,17 @@ create table t (a int primary key auto_random) 在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个版本号，例如 `/*T!40000 auto_random */`。其中 `40000` 表示 v4.0.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释的 `AUTO_RANDOM` 属性。 -该功能支持向前兼容，即降级兼容。新版本 TiDB 建立的含有 `AUTO_RANDOM` 的表可以被旧版本 TiDB 所使用。 +该功能支持向前兼容，即降级兼容。v4.0.0 以前的 TiDB 会忽略表（带有上述注释）的 `AUTO_RANDOM` 属性，因此能够使用含有该属性的表。 ## 使用限制 目前在 TiDB 中使用 `AUTO_RANDOM` 有以下限制： - 该属性必须指定在整数类型的主键列上，否则会报错。例外情况见[关于 `alter-primary-key` 配置项的说明](#关于-alter-primary-key-配置项的说明)。 -- 不支持使用 `ALTER TABLE` 来修改 `AUTO_RANDOM` 属性，包括添加/移除该属性。 +- 不支持使用 `ALTER TABLE` 来修改 `AUTO_RANDOM` 属性，包括添加或移除该属性。 - 不支持修改含有 `AUTO_RANDOM` 属性的主键列的列类型。 - 不支持与 `AUTO_INCREMENT` 同时指定在同一列上。 -- 不支持与 `DEFAULT` 同时指定在同一列上。 +- 不支持与列的默认值 `DEFAULT` 同时指定在同一列上。 - 插入数据时，不建议自行显式指定含有 `AUTO_RANDOM` 列的值。不恰当地显式赋值，可能会导致该表提前耗尽用于自动分配的数值。因为用于保证唯一性的 rebase 仅针对除 shard bits 以外的位进行。 ## 关于 `alter-primary-key` 配置项的说明 diff --git a/v3.1/reference/sql/attributes/auto-random.md b/v3.1/reference/sql/attributes/auto-random.md index 30684592bbac..07b5d2f10563 100644 --- a/v3.1/reference/sql/attributes/auto-random.md +++ b/v3.1/reference/sql/attributes/auto-random.md @@ -50,7 +50,7 @@ create table t (a int auto_random, b varchar(255), primary key (a)) 自动分配值的计算方式如下： -二进制形式下的最高 5 位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。 +该行值在二进制形式下的最高 5 位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。 如果希望使用一个不同的 shard bits 的数量，可以在 `AUTO_RANDOM` 后面加一对括号，并在括号中指定，例如： @@ -84,17 +84,17 @@ create table t (a int primary key auto_random) 在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个版本号，例如 `/*T!40000 auto_random */`。其中 `40000` 表示 v4.0.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释的 `AUTO_RANDOM` 属性。 -该功能支持向前兼容，即降级兼容。新版本 TiDB 建立的含有 `AUTO_RANDOM` 的表可以被旧版本 TiDB 所使用。 +该功能支持向前兼容，即降级兼容。v3.1.0 以前的 TiDB 会忽略表（带有上述注释）的 `AUTO_RANDOM` 属性，因此能够使用含有该属性的表。 ## 使用限制 目前在 TiDB 中使用 `AUTO_RANDOM` 有以下限制： - 该属性必须指定在整数类型的主键列上，否则会报错。例外情况见[关于 `alter-primary-key` 配置项的说明](#关于-alter-primary-key-配置项的说明)。 -- 不支持使用 `ALTER TABLE` 来修改 `AUTO_RANDOM` 属性，包括添加/移除该属性。 +- 不支持使用 `ALTER TABLE` 来修改 `AUTO_RANDOM` 属性，包括添加或移除该属性。 - 不支持修改含有 `AUTO_RANDOM` 属性的主键列的列类型。 - 不支持与 `AUTO_INCREMENT` 同时指定在同一列上。 -- 不支持与 `DEFAULT` 同时指定在同一列上。 +- 不支持与列的默认值 `DEFAULT` 同时指定在同一列上。 - 插入数据时，不建议自行显式指定含有 `AUTO_RANDOM` 列的值。不恰当地显式赋值，可能会导致该表提前耗尽用于自动分配的数值。因为用于保证唯一性的 rebase 仅针对除 shard bits 以外的位进行。 ## 关于 `alter-primary-key` 配置项的说明 From 4f8dd59271c1a68ce79e4e26d9509815d6e3e306 Mon Sep 17 00:00:00 2001 From: tangenta Date: Mon, 17 Feb 2020 15:01:24 +0800 Subject: [PATCH 10/15] reference/sql: refine auto_random description --- .../best-practices/high-concurrency.md | 6 ++++-- dev/reference/sql/attributes/auto-random.md | 4 ++-- .../sql/language-structure/comment-syntax.md | 2 +- patch.diff | 18 ------------------ .../best-practices/high-concurrency.md | 6 ++++-- v3.1/reference/sql/attributes/auto-random.md | 4 ++-- .../sql/language-structure/comment-syntax.md | 2 +- 7 files changed, 14 insertions(+), 28 deletions(-) delete mode 100644 patch.diff diff --git a/dev/reference/best-practices/high-concurrency.md b/dev/reference/best-practices/high-concurrency.md index 77b999ebfcc7..1b67bcd46378 100644 --- a/dev/reference/best-practices/high-concurrency.md +++ b/dev/reference/best-practices/high-concurrency.md @@ -170,7 +170,7 @@ SPLIT TABLE TEST_HOTSPOT BETWEEN (0) AND (9223372036854775807) REGIONS 128; ### 更复杂的热点问题 -如果表没有主键或者主键不是整数类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 +**问题一：**如果表没有主键或者主键不是整数类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 要避免由 `_tidb_rowid` 带来的写入热点问题，可以在建表时，使用 `SHARD_ROW_ID_BITS` 和 `PRE_SPLIT_REGIONS` 这两个建表选项（参阅 [`PRE_SPLIT_REGIONS` 的详细说明](/dev/reference/sql/statements/split-region.md#pre_split_regions)）。 @@ -193,7 +193,9 @@ create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; 开始写数据进表 t 后，数据会被写入提前切分好的 8 个 Region 中，这样也避免了刚开始建表完后因为只有一个 Region 而存在的写热点问题。 -对于有整数类型主键，并且使用了 `AUTO_INCREMENT` 来保证唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用其行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS`。要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/dev/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整形主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 +**问题二：**如果表的主键为整数类型，并且该表使用了 `AUTO_INCREMENT` 来保证主键唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用主键行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS` 来打散热点。 + +要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/dev/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整形主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 ## 参数配置 diff --git a/dev/reference/sql/attributes/auto-random.md b/dev/reference/sql/attributes/auto-random.md index 1e2e1f50f60c..733a8d56b8bd 100644 --- a/dev/reference/sql/attributes/auto-random.md +++ b/dev/reference/sql/attributes/auto-random.md @@ -97,7 +97,7 @@ create table t (a int primary key auto_random) - 不支持与列的默认值 `DEFAULT` 同时指定在同一列上。 - 插入数据时，不建议自行显式指定含有 `AUTO_RANDOM` 列的值。不恰当地显式赋值，可能会导致该表提前耗尽用于自动分配的数值。因为用于保证唯一性的 rebase 仅针对除 shard bits 以外的位进行。 -## 关于 `alter-primary-key` 配置项的说明 +### 关于 `alter-primary-key` 配置项的说明 -- 当 `alter-primary-key = true` 时，不支持使用 `AUTO_RANDOM`。 +- 当 `alter-primary-key = true` 时，即使是整形主键列，也不支持使用 `AUTO_RANDOM`。 - 配置文件中的 `alter-primary-key` 和 `allow-auto-random` 两个配置项的值不允许同时为 `true`。 diff --git a/dev/reference/sql/language-structure/comment-syntax.md b/dev/reference/sql/language-structure/comment-syntax.md index 6849fa24d5aa..39164309d1b2 100644 --- a/dev/reference/sql/language-structure/comment-syntax.md +++ b/dev/reference/sql/language-structure/comment-syntax.md @@ -107,7 +107,7 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： 在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!40000 XXX */`。 +如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!40000 XXX */`。 还有一种注释会被当做是优化器 Hint 特殊对待： diff --git a/patch.diff b/patch.diff deleted file mode 100644 index 62cc51eaa304..000000000000 --- a/patch.diff +++ /dev/null @@ -1,18 +0,0 @@ -diff --git a/v3.1/reference/sql/attributes/auto-random.md b/v3.1/reference/sql/attributes/auto-random.md -index ef1e3aa1..c6e68f79 100644 ---- a/v3.1/reference/sql/attributes/auto-random.md -+++ b/v3.1/reference/sql/attributes/auto-random.md -@@ -5,11 +5,11 @@ category: reference - - # AUTO_RANDOM 从 v4.0.0 版本开始引入 - --注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-shard = true` 后，才能正常使用。 -+注意：该功能处于实验阶段，不排除后续版本修改语法或语义的可能，__不建议在生产环境直接使用__。另外，auto_random 属性必须在配置文件中设置开关 `[experimental] allow-auto-random = true` 后，才能正常使用。 - - ## 简介 - --auto_random 用于解决大批量写入含有『整型自增主键列』表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/v3.1/reference/best-practices/high-concurrency.md) -+auto_random 用于解决大批量写入含有__整型自增主键列__的表时的热点问题。参考：[TiDB 高并发写入场景最佳实践](/v3.1/reference/best-practices/high-concurrency.md) - - 例如下表 - diff --git a/v3.1/reference/best-practices/high-concurrency.md b/v3.1/reference/best-practices/high-concurrency.md index 17979ec3c97f..39a62c626bf6 100644 --- a/v3.1/reference/best-practices/high-concurrency.md +++ b/v3.1/reference/best-practices/high-concurrency.md @@ -170,7 +170,7 @@ SPLIT TABLE TEST_HOTSPOT BETWEEN (0) AND (9223372036854775807) REGIONS 128; ### 更复杂的热点问题 -如果表没有主键或者主键不是整数类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 +**问题一：**如果表没有主键或者主键不是整数类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 要避免由 `_tidb_rowid` 带来的写入热点问题，可以在建表时，使用 `SHARD_ROW_ID_BITS` 和 `PRE_SPLIT_REGIONS` 这两个建表选项（参阅 [`PRE_SPLIT_REGIONS` 的详细说明](/v3.1/reference/sql/statements/split-region.md#pre_split_regions)）。 @@ -193,7 +193,9 @@ create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; 开始写数据进表 t 后，数据会被写入提前切分好的 8 个 Region 中，这样也避免了刚开始建表完后因为只有一个 Region 而存在的写热点问题。 -对于有整数类型主键，并且使用了 `AUTO_INCREMENT` 来保证唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用其行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS`。要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/v3.1/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整形主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 +**问题二：**如果表的主键为整数类型，并且该表使用了 `AUTO_INCREMENT` 来保证主键唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用主键行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS` 来打散热点。 + +要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/v3.1/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整形主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 ## 参数配置 diff --git a/v3.1/reference/sql/attributes/auto-random.md b/v3.1/reference/sql/attributes/auto-random.md index 07b5d2f10563..0ffffdb8faf8 100644 --- a/v3.1/reference/sql/attributes/auto-random.md +++ b/v3.1/reference/sql/attributes/auto-random.md @@ -97,7 +97,7 @@ create table t (a int primary key auto_random) - 不支持与列的默认值 `DEFAULT` 同时指定在同一列上。 - 插入数据时，不建议自行显式指定含有 `AUTO_RANDOM` 列的值。不恰当地显式赋值，可能会导致该表提前耗尽用于自动分配的数值。因为用于保证唯一性的 rebase 仅针对除 shard bits 以外的位进行。 -## 关于 `alter-primary-key` 配置项的说明 +### 关于 `alter-primary-key` 配置项的说明 -- 当 `alter-primary-key = true` 时，不支持使用 `AUTO_RANDOM`。 +- 当 `alter-primary-key = true` 时，即使是整形主键列，也不支持使用 `AUTO_RANDOM`。 - 配置文件中的 `alter-primary-key` 和 `allow-auto-random` 两个配置项的值不允许同时为 `true`。 diff --git a/v3.1/reference/sql/language-structure/comment-syntax.md b/v3.1/reference/sql/language-structure/comment-syntax.md index c38c7c975ebf..7bfea86e55e5 100644 --- a/v3.1/reference/sql/language-structure/comment-syntax.md +++ b/v3.1/reference/sql/language-structure/comment-syntax.md @@ -107,7 +107,7 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： 在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个版本号不会起作用，所有的 comment 都会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!40000 XXX */`。 +如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!40000 XXX */`。 还有一种注释会被当做是优化器 Hint 特殊对待： From dc59efc0956f875a6fe4c2ebf1cffb3402af83c3 Mon Sep 17 00:00:00 2001 From: tangenta Date: Thu, 20 Feb 2020 11:09:34 +0800 Subject: [PATCH 11/15] correct TiDB-style executable comment version number --- .../best-practices/high-concurrency.md | 4 ++-- .../tidb-server/configuration-file.md | 2 +- dev/reference/sql/attributes/auto-random.md | 18 +++++++++--------- .../sql/language-structure/comment-syntax.md | 2 +- .../best-practices/high-concurrency.md | 2 +- .../best-practices/high-concurrency.md | 4 ++-- v3.1/reference/sql/attributes/auto-random.md | 14 +++++++------- .../sql/language-structure/comment-syntax.md | 2 +- 8 files changed, 24 insertions(+), 24 deletions(-) diff --git a/dev/reference/best-practices/high-concurrency.md b/dev/reference/best-practices/high-concurrency.md index 1b67bcd46378..7036bf5d25db 100644 --- a/dev/reference/best-practices/high-concurrency.md +++ b/dev/reference/best-practices/high-concurrency.md @@ -124,7 +124,7 @@ SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] ![Table Region Range](/media/best-practices/table-Region-range.png) -从上图可知，根据行数据 key 的编码规则，行 ID (rowID) 是行数据中唯一可变的部分。在 TiDB 中，rowID 是一个 Int64 整形。但是用户不一定能将 Int64 整形范围均匀切分成需要的份数，然后均匀分布在不同的节点上，还需要结合实际情况。 +从上图可知，根据行数据 key 的编码规则，行 ID (rowID) 是行数据中唯一可变的部分。在 TiDB 中，rowID 是一个 Int64 整型。但是用户不一定能将 Int64 整型范围均匀切分成需要的份数，然后均匀分布在不同的节点上，还需要结合实际情况。 如果行 ID 的写入是完全离散的，那么上述方式是可行的。如果行 ID 或者索引有固定的范围或者前缀（例如，只在 `[2000w, 5000w)` 的范围内离散插入数据），这种写入依然在业务上不产生热点，但是如果按上面的方式进行切分，那么有可能一开始数据仍只写入到某个 Region 上。 @@ -195,7 +195,7 @@ create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; **问题二：**如果表的主键为整数类型，并且该表使用了 `AUTO_INCREMENT` 来保证主键唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用主键行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS` 来打散热点。 -要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/dev/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整形主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 +要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/dev/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整型主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 ## 参数配置 diff --git a/dev/reference/configuration/tidb-server/configuration-file.md b/dev/reference/configuration/tidb-server/configuration-file.md index dc2ca96ace2a..65211ab47777 100644 --- a/dev/reference/configuration/tidb-server/configuration-file.md +++ b/dev/reference/configuration/tidb-server/configuration-file.md @@ -431,7 +431,7 @@ TiDB 服务状态相关配置。 + `events_statement_summary_by_digest` 表中`DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 列的最大显示长度。 + 默认值：4096 -## experimental 从 v4.0.0 版本开始引入 +## experimental 从 v3.1.0 版本开始引入 TiDB 实验功能相关配置。 diff --git a/dev/reference/sql/attributes/auto-random.md b/dev/reference/sql/attributes/auto-random.md index 733a8d56b8bd..2951bf4dc1d0 100644 --- a/dev/reference/sql/attributes/auto-random.md +++ b/dev/reference/sql/attributes/auto-random.md @@ -3,7 +3,7 @@ title: AUTO_RANDOM category: reference --- -# AUTO_RANDOM 从 v4.0.0 版本开始引入 +# AUTO_RANDOM 从 v3.1.0 版本开始引入 > **警告：** > @@ -45,8 +45,8 @@ create table t (a int auto_random, b varchar(255), primary key (a)) 此时再执行形如 `INSERT INTO t(b) values...` 的 `INSERT` 语句， -+ 如果该 `INSERT` 语句没有指定整形主键列（`a` 列）的值，TiDB 会为该列自动分配值。该值不保证自增，不保证连续，只保证唯一，避免了连续的行 ID 带来的热点问题。 -+ 如果该 `INSERT` 语句显式指定了整形主键列的值，和 `AUTO_INCREMENT` 属性类似，TiDB 会原封不动地保存该值。 ++ 如果该 `INSERT` 语句没有指定整型主键列（`a` 列）的值，TiDB 会为该列自动分配值。该值不保证自增，不保证连续，只保证唯一，避免了连续的行 ID 带来的热点问题。 ++ 如果该 `INSERT` 语句显式指定了整型主键列的值，和 `AUTO_INCREMENT` 属性类似，TiDB 会原封不动地保存该值。 自动分配值的计算方式如下： @@ -60,7 +60,7 @@ create table t (a int auto_random, b varchar(255), primary key (a)) create table t (a int primary key auto_random(3), b varchar(255)) ``` -以上建表语句中，shard bits 的数量为 `3`。shard bits 的数量的取值范围是 `[1, field_max_bits)`，其中 `field_max_bits` 为整形主键列类型占用的位长度。 +以上建表语句中，shard bits 的数量为 `3`。shard bits 的数量的取值范围是 `[1, field_max_bits)`，其中 `field_max_bits` 为整型主键列类型占用的位长度。 含有 `AUTO_RANDOM` 属性的表在 `information_schema.tables` 中 `TIDB_ROW_ID_SHARDING_INFO` 一列的值为 `PK_AUTO_RANDOM_BITS=x`，其中 `x` 为 shard bits 的数量。 @@ -71,7 +71,7 @@ TiDB 支持解析版本注释语法。示例如下： {{< copyable "sql" >}} ```sql -create table t (a int primary key /*T!40000 auto_random */) +create table t (a int primary key /*T!30100 auto_random */) ``` {{< copyable "sql" >}} @@ -82,9 +82,9 @@ create table t (a int primary key auto_random) 以上两个语句含义相同。 -在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个版本号，例如 `/*T!40000 auto_random */`。其中 `40000` 表示 v4.0.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释的 `AUTO_RANDOM` 属性。 +在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个版本号，例如 `/*T!30100 auto_random */`。其中 `30100` 表示 v3.1.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释的 `AUTO_RANDOM` 属性。 -该功能支持向前兼容，即降级兼容。v4.0.0 以前的 TiDB 会忽略表（带有上述注释）的 `AUTO_RANDOM` 属性，因此能够使用含有该属性的表。 +该功能支持向前兼容，即降级兼容。v3.1.0 以前的 TiDB 会忽略表（带有上述注释）的 `AUTO_RANDOM` 属性，因此能够使用含有该属性的表。 ## 使用限制 @@ -94,10 +94,10 @@ create table t (a int primary key auto_random) - 不支持使用 `ALTER TABLE` 来修改 `AUTO_RANDOM` 属性，包括添加或移除该属性。 - 不支持修改含有 `AUTO_RANDOM` 属性的主键列的列类型。 - 不支持与 `AUTO_INCREMENT` 同时指定在同一列上。 -- 不支持与列的默认值 `DEFAULT` 同时指定在同一列上。 +- 不支持与列的默认值 `DEFAULT` 同时指定在同一列上。 - 插入数据时，不建议自行显式指定含有 `AUTO_RANDOM` 列的值。不恰当地显式赋值，可能会导致该表提前耗尽用于自动分配的数值。因为用于保证唯一性的 rebase 仅针对除 shard bits 以外的位进行。 ### 关于 `alter-primary-key` 配置项的说明 -- 当 `alter-primary-key = true` 时，即使是整形主键列，也不支持使用 `AUTO_RANDOM`。 +- 当 `alter-primary-key = true` 时，即使是整型主键列，也不支持使用 `AUTO_RANDOM`。 - 配置文件中的 `alter-primary-key` 和 `allow-auto-random` 两个配置项的值不允许同时为 `true`。 diff --git a/dev/reference/sql/language-structure/comment-syntax.md b/dev/reference/sql/language-structure/comment-syntax.md index 39164309d1b2..2d4d2aed638c 100644 --- a/dev/reference/sql/language-structure/comment-syntax.md +++ b/dev/reference/sql/language-structure/comment-syntax.md @@ -107,7 +107,7 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： 在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!40000 XXX */`。 +如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!30100 XXX */`。 还有一种注释会被当做是优化器 Hint 特殊对待： diff --git a/v3.0/reference/best-practices/high-concurrency.md b/v3.0/reference/best-practices/high-concurrency.md index fc2f5e946014..1b7e3b823e73 100644 --- a/v3.0/reference/best-practices/high-concurrency.md +++ b/v3.0/reference/best-practices/high-concurrency.md @@ -124,7 +124,7 @@ SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] ![Table Region Range](/media/best-practices/table-Region-range.png) -从上图可知，根据行数据 key 的编码规则，行 ID (rowID) 是行数据中唯一可变的部分。在 TiDB 中，rowID 是一个 Int64 整形。但是用户不一定能将 Int64 整形范围均匀切分成需要的份数，然后均匀分布在不同的节点上，还需要结合实际情况。 +从上图可知，根据行数据 key 的编码规则，行 ID (rowID) 是行数据中唯一可变的部分。在 TiDB 中，rowID 是一个 Int64 整型。但是用户不一定能将 Int64 整型范围均匀切分成需要的份数，然后均匀分布在不同的节点上，还需要结合实际情况。 如果行 ID 的写入是完全离散的，那么上述方式是可行的。如果行 ID 或者索引有固定的范围或者前缀（例如，只在 `[2000w, 5000w)` 的范围内离散插入数据），这种写入依然在业务上不产生热点，但是如果按上面的方式进行切分，那么有可能一开始数据仍只写入到某个 Region 上。 diff --git a/v3.1/reference/best-practices/high-concurrency.md b/v3.1/reference/best-practices/high-concurrency.md index 39a62c626bf6..244c9efebf70 100644 --- a/v3.1/reference/best-practices/high-concurrency.md +++ b/v3.1/reference/best-practices/high-concurrency.md @@ -124,7 +124,7 @@ SPLIT TABLE table_name [INDEX index_name] BY (value_list) [, (value_list)] ![Table Region Range](/media/best-practices/table-Region-range.png) -从上图可知，根据行数据 key 的编码规则，行 ID (rowID) 是行数据中唯一可变的部分。在 TiDB 中，rowID 是一个 Int64 整形。但是用户不一定能将 Int64 整形范围均匀切分成需要的份数，然后均匀分布在不同的节点上，还需要结合实际情况。 +从上图可知，根据行数据 key 的编码规则，行 ID (rowID) 是行数据中唯一可变的部分。在 TiDB 中，rowID 是一个 Int64 整型。但是用户不一定能将 Int64 整型范围均匀切分成需要的份数，然后均匀分布在不同的节点上，还需要结合实际情况。 如果行 ID 的写入是完全离散的，那么上述方式是可行的。如果行 ID 或者索引有固定的范围或者前缀（例如，只在 `[2000w, 5000w)` 的范围内离散插入数据），这种写入依然在业务上不产生热点，但是如果按上面的方式进行切分，那么有可能一开始数据仍只写入到某个 Region 上。 @@ -195,7 +195,7 @@ create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; **问题二：**如果表的主键为整数类型，并且该表使用了 `AUTO_INCREMENT` 来保证主键唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用主键行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS` 来打散热点。 -要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/v3.1/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整形主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 +要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/v3.1/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整型主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 ## 参数配置 diff --git a/v3.1/reference/sql/attributes/auto-random.md b/v3.1/reference/sql/attributes/auto-random.md index 0ffffdb8faf8..1827a8389ffc 100644 --- a/v3.1/reference/sql/attributes/auto-random.md +++ b/v3.1/reference/sql/attributes/auto-random.md @@ -45,8 +45,8 @@ create table t (a int auto_random, b varchar(255), primary key (a)) 此时再执行形如 `INSERT INTO t(b) values...` 的 `INSERT` 语句， -+ 如果该 `INSERT` 语句没有指定整形主键列（`a` 列）的值，TiDB 会为该列自动分配值。该值不保证自增，不保证连续，只保证唯一，避免了连续的行 ID 带来的热点问题。 -+ 如果该 `INSERT` 语句显式指定了整形主键列的值，和 `AUTO_INCREMENT` 属性类似，TiDB 会原封不动地保存该值。 ++ 如果该 `INSERT` 语句没有指定整型主键列（`a` 列）的值，TiDB 会为该列自动分配值。该值不保证自增，不保证连续，只保证唯一，避免了连续的行 ID 带来的热点问题。 ++ 如果该 `INSERT` 语句显式指定了整型主键列的值，和 `AUTO_INCREMENT` 属性类似，TiDB 会原封不动地保存该值。 自动分配值的计算方式如下： @@ -60,7 +60,7 @@ create table t (a int auto_random, b varchar(255), primary key (a)) create table t (a int primary key auto_random(3), b varchar(255)) ``` -以上建表语句中，shard bits 的数量为 `3`。shard bits 的数量的取值范围是 `[1, field_max_bits)`，其中 `field_max_bits` 为整形主键列类型占用的位长度。 +以上建表语句中，shard bits 的数量为 `3`。shard bits 的数量的取值范围是 `[1, field_max_bits)`，其中 `field_max_bits` 为整型主键列类型占用的位长度。 含有 `AUTO_RANDOM` 属性的表在 `information_schema.tables` 中 `TIDB_ROW_ID_SHARDING_INFO` 一列的值为 `PK_AUTO_RANDOM_BITS=x`，其中 `x` 为 shard bits 的数量。 @@ -71,7 +71,7 @@ TiDB 支持解析版本注释语法。示例如下： {{< copyable "sql" >}} ```sql -create table t (a int primary key /*T!40000 auto_random */) +create table t (a int primary key /*T!30100 auto_random */) ``` {{< copyable "sql" >}} @@ -82,7 +82,7 @@ create table t (a int primary key auto_random) 以上两个语句含义相同。 -在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个版本号，例如 `/*T!40000 auto_random */`。其中 `40000` 表示 v4.0.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释的 `AUTO_RANDOM` 属性。 +在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个版本号，例如 `/*T!30100 auto_random */`。其中 `30100` 表示 v3.1.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释的 `AUTO_RANDOM` 属性。 该功能支持向前兼容，即降级兼容。v3.1.0 以前的 TiDB 会忽略表（带有上述注释）的 `AUTO_RANDOM` 属性，因此能够使用含有该属性的表。 @@ -94,10 +94,10 @@ create table t (a int primary key auto_random) - 不支持使用 `ALTER TABLE` 来修改 `AUTO_RANDOM` 属性，包括添加或移除该属性。 - 不支持修改含有 `AUTO_RANDOM` 属性的主键列的列类型。 - 不支持与 `AUTO_INCREMENT` 同时指定在同一列上。 -- 不支持与列的默认值 `DEFAULT` 同时指定在同一列上。 +- 不支持与列的默认值 `DEFAULT` 同时指定在同一列上。 - 插入数据时，不建议自行显式指定含有 `AUTO_RANDOM` 列的值。不恰当地显式赋值，可能会导致该表提前耗尽用于自动分配的数值。因为用于保证唯一性的 rebase 仅针对除 shard bits 以外的位进行。 ### 关于 `alter-primary-key` 配置项的说明 -- 当 `alter-primary-key = true` 时，即使是整形主键列，也不支持使用 `AUTO_RANDOM`。 +- 当 `alter-primary-key = true` 时，即使是整型主键列，也不支持使用 `AUTO_RANDOM`。 - 配置文件中的 `alter-primary-key` 和 `allow-auto-random` 两个配置项的值不允许同时为 `true`。 diff --git a/v3.1/reference/sql/language-structure/comment-syntax.md b/v3.1/reference/sql/language-structure/comment-syntax.md index 7bfea86e55e5..7c1ec99c8c4f 100644 --- a/v3.1/reference/sql/language-structure/comment-syntax.md +++ b/v3.1/reference/sql/language-structure/comment-syntax.md @@ -107,7 +107,7 @@ TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： 在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!40000 XXX */`。 +如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!30100 XXX */`。 还有一种注释会被当做是优化器 Hint 特殊对待： From 904f113a5fe8c0336dde7fc667779146bfee7464 Mon Sep 17 00:00:00 2001 From: tangenta Date: Thu, 20 Feb 2020 12:32:06 +0800 Subject: [PATCH 12/15] fix typo --- v3.1/reference/configuration/tidb-server/configuration-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/v3.1/reference/configuration/tidb-server/configuration-file.md b/v3.1/reference/configuration/tidb-server/configuration-file.md index 6cf362e6ed82..c18ad24614f3 100644 --- a/v3.1/reference/configuration/tidb-server/configuration-file.md +++ b/v3.1/reference/configuration/tidb-server/configuration-file.md @@ -409,7 +409,7 @@ TiDB 服务状态相关配置。 + `events_statement_summary_by_digest` 表中`DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 列的最大显示长度。 + 默认值：4096 -## experimental 从 v3.0.1 版本开始引入 +## experimental 从 v3.1.0 版本开始引入 TiDB 实验功能相关配置。 From 1537c81f31b146933a5bbefde04aac8adad5d245 Mon Sep 17 00:00:00 2001 From: TomShawn <1135243111@qq.com> Date: Thu, 20 Feb 2020 12:34:02 +0800 Subject: [PATCH 13/15] minor typo fixes --- dev/reference/best-practices/high-concurrency.md | 8 ++++++-- .../configuration/tidb-server/configuration-file.md | 4 ++-- dev/reference/sql/attributes/auto-random.md | 4 ++-- v3.1/reference/best-practices/high-concurrency.md | 8 ++++++-- .../configuration/tidb-server/configuration-file.md | 4 ++-- v3.1/reference/sql/attributes/auto-random.md | 4 ++-- 6 files changed, 20 insertions(+), 12 deletions(-) diff --git a/dev/reference/best-practices/high-concurrency.md b/dev/reference/best-practices/high-concurrency.md index 7036bf5d25db..ae2f55f5293c 100644 --- a/dev/reference/best-practices/high-concurrency.md +++ b/dev/reference/best-practices/high-concurrency.md @@ -170,7 +170,9 @@ SPLIT TABLE TEST_HOTSPOT BETWEEN (0) AND (9223372036854775807) REGIONS 128; ### 更复杂的热点问题 -**问题一：**如果表没有主键或者主键不是整数类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 +**问题一：** + +如果表没有主键或者主键不是整数类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 要避免由 `_tidb_rowid` 带来的写入热点问题，可以在建表时，使用 `SHARD_ROW_ID_BITS` 和 `PRE_SPLIT_REGIONS` 这两个建表选项（参阅 [`PRE_SPLIT_REGIONS` 的详细说明](/dev/reference/sql/statements/split-region.md#pre_split_regions)）。 @@ -193,7 +195,9 @@ create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; 开始写数据进表 t 后，数据会被写入提前切分好的 8 个 Region 中，这样也避免了刚开始建表完后因为只有一个 Region 而存在的写热点问题。 -**问题二：**如果表的主键为整数类型，并且该表使用了 `AUTO_INCREMENT` 来保证主键唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用主键行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS` 来打散热点。 +**问题二：** + +如果表的主键为整数类型，并且该表使用了 `AUTO_INCREMENT` 来保证主键唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用主键行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS` 来打散热点。 要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/dev/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整型主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 diff --git a/dev/reference/configuration/tidb-server/configuration-file.md b/dev/reference/configuration/tidb-server/configuration-file.md index 65211ab47777..f19d7a78885c 100644 --- a/dev/reference/configuration/tidb-server/configuration-file.md +++ b/dev/reference/configuration/tidb-server/configuration-file.md @@ -431,11 +431,11 @@ TiDB 服务状态相关配置。 + `events_statement_summary_by_digest` 表中`DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 列的最大显示长度。 + 默认值：4096 -## experimental 从 v3.1.0 版本开始引入 +## experimental TiDB 实验功能相关配置。 -### `allow-auto-random` +### `allow-auto-random` 从 v3.1.0 版本开始引入 + 用于控制是否允许使用 `AUTO_RANDOM`。 + 默认值：false diff --git a/dev/reference/sql/attributes/auto-random.md b/dev/reference/sql/attributes/auto-random.md index 2951bf4dc1d0..355b27ab0e10 100644 --- a/dev/reference/sql/attributes/auto-random.md +++ b/dev/reference/sql/attributes/auto-random.md @@ -21,13 +21,13 @@ category: reference create table t (a int primary key auto_increment, b varchar(255)) ``` -对这样的表执行大量的未指定主键值的 `INSERT` 语句时，如 +在以上语句所建的表上执行大量未指定主键值的 `INSERT` 语句时，示例如下： ```sql insert into t(b) values ('a'), ('b'), ('c') ``` -由于未指定主键列的值（`a` 列），TiDB 会使用连续自增的行值作为行 ID，可能导致单个 TiKV 节点上产生写入热点，进而影响对外提供服务的性能。要避免这种性能下降，可以在执行建表语句时为 `a` 列指定 `AUTO_RANDOM` 属性而不是 `AUTO_INCREMENT` 属性。示例如下： +在该情况下，由于未指定主键列的值（`a` 列），TiDB 会使用连续自增的行值作为行 ID，可能导致单个 TiKV 节点上产生写入热点，进而影响对外提供服务的性能。要避免这种性能下降，可以在执行建表语句时为 `a` 列指定 `AUTO_RANDOM` 属性而不是 `AUTO_INCREMENT` 属性。示例如下： {{< copyable "sql" >}} diff --git a/v3.1/reference/best-practices/high-concurrency.md b/v3.1/reference/best-practices/high-concurrency.md index 244c9efebf70..3df03050d594 100644 --- a/v3.1/reference/best-practices/high-concurrency.md +++ b/v3.1/reference/best-practices/high-concurrency.md @@ -170,7 +170,9 @@ SPLIT TABLE TEST_HOTSPOT BETWEEN (0) AND (9223372036854775807) REGIONS 128; ### 更复杂的热点问题 -**问题一：**如果表没有主键或者主键不是整数类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 +**问题一：** + +如果表没有主键或者主键不是整数类型，而且用户也不想自己生成一个随机分布的主键 ID 的话，TiDB 内部有一个隐式的 `_tidb_rowid` 列作为行 ID。在不使用 `SHARD_ROW_ID_BITS` 的情况下，`_tidb_rowid` 列的值基本也为单调递增，此时也会有写热点存在（参阅 [`SHARD_ROW_ID_BITS` 的详细说明](/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md#shard_row_id_bits)）。 要避免由 `_tidb_rowid` 带来的写入热点问题，可以在建表时，使用 `SHARD_ROW_ID_BITS` 和 `PRE_SPLIT_REGIONS` 这两个建表选项（参阅 [`PRE_SPLIT_REGIONS` 的详细说明](/v3.1/reference/sql/statements/split-region.md#pre_split_regions)）。 @@ -193,7 +195,9 @@ create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; 开始写数据进表 t 后，数据会被写入提前切分好的 8 个 Region 中，这样也避免了刚开始建表完后因为只有一个 Region 而存在的写热点问题。 -**问题二：**如果表的主键为整数类型，并且该表使用了 `AUTO_INCREMENT` 来保证主键唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用主键行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS` 来打散热点。 +**问题二：** + +如果表的主键为整数类型，并且该表使用了 `AUTO_INCREMENT` 来保证主键唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用主键行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS` 来打散热点。 要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/v3.1/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整型主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 diff --git a/v3.1/reference/configuration/tidb-server/configuration-file.md b/v3.1/reference/configuration/tidb-server/configuration-file.md index 6cf362e6ed82..e8c6bd9aee81 100644 --- a/v3.1/reference/configuration/tidb-server/configuration-file.md +++ b/v3.1/reference/configuration/tidb-server/configuration-file.md @@ -409,11 +409,11 @@ TiDB 服务状态相关配置。 + `events_statement_summary_by_digest` 表中`DIGEST_TEXT` 和 `QUERY_SAMPLE_TEXT` 列的最大显示长度。 + 默认值：4096 -## experimental 从 v3.0.1 版本开始引入 +## experimental TiDB 实验功能相关配置。 -### `allow-auto-random` +### `allow-auto-random` 从 v3.1.0 版本开始引入 + 用于控制是否允许使用 `AUTO_RANDOM`。 + 默认值：false diff --git a/v3.1/reference/sql/attributes/auto-random.md b/v3.1/reference/sql/attributes/auto-random.md index 1827a8389ffc..7034a02a2f1c 100644 --- a/v3.1/reference/sql/attributes/auto-random.md +++ b/v3.1/reference/sql/attributes/auto-random.md @@ -21,13 +21,13 @@ category: reference create table t (a int primary key auto_increment, b varchar(255)) ``` -对这样的表执行大量的未指定主键值的 `INSERT` 语句时，如 +在以上语句所建的表上执行大量未指定主键值的 `INSERT` 语句时，示例如下： ```sql insert into t(b) values ('a'), ('b'), ('c') ``` -由于未指定主键列的值（`a` 列），TiDB 会使用连续自增的行值作为行 ID，可能导致单个 TiKV 节点上产生写入热点，进而影响对外提供服务的性能。要避免这种性能下降，可以在执行建表语句时为 `a` 列指定 `AUTO_RANDOM` 属性而不是 `AUTO_INCREMENT` 属性。示例如下： +在该情况下，由于未指定主键列的值（`a` 列），TiDB 会使用连续自增的行值作为行 ID，可能导致单个 TiKV 节点上产生写入热点，进而影响对外提供服务的性能。要避免这种性能下降，可以在执行建表语句时为 `a` 列指定 `AUTO_RANDOM` 属性而不是 `AUTO_INCREMENT` 属性。示例如下： {{< copyable "sql" >}} From c3ee66982d90ce6823b7698f5a168b0d2b420579 Mon Sep 17 00:00:00 2001 From: TomShawn <1135243111@qq.com> Date: Thu, 20 Feb 2020 12:46:07 +0800 Subject: [PATCH 14/15] reference/configuration: add description for experimental section --- dev/reference/configuration/tidb-server/configuration-file.md | 2 +- v3.1/reference/configuration/tidb-server/configuration-file.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/dev/reference/configuration/tidb-server/configuration-file.md b/dev/reference/configuration/tidb-server/configuration-file.md index f19d7a78885c..3106fd42ab95 100644 --- a/dev/reference/configuration/tidb-server/configuration-file.md +++ b/dev/reference/configuration/tidb-server/configuration-file.md @@ -433,7 +433,7 @@ TiDB 服务状态相关配置。 ## experimental -TiDB 实验功能相关配置。 +experimental 部分为 TiDB 实验功能相关的配置。该部分从 v3.1.0 开始引入。 ### `allow-auto-random` 从 v3.1.0 版本开始引入 diff --git a/v3.1/reference/configuration/tidb-server/configuration-file.md b/v3.1/reference/configuration/tidb-server/configuration-file.md index e8c6bd9aee81..fcda0f0a76bf 100644 --- a/v3.1/reference/configuration/tidb-server/configuration-file.md +++ b/v3.1/reference/configuration/tidb-server/configuration-file.md @@ -411,7 +411,7 @@ TiDB 服务状态相关配置。 ## experimental -TiDB 实验功能相关配置。 +experimental 部分为 TiDB 实验功能相关的配置。该部分从 v3.1.0 开始引入。 ### `allow-auto-random` 从 v3.1.0 版本开始引入 From 383443a43dbfda42c8c250e1f886de719409feaf Mon Sep 17 00:00:00 2001 From: yikeke Date: Sun, 23 Feb 2020 13:41:20 +0800 Subject: [PATCH 15/15] make the same changes as before --- TOC.md | 2 + dev/TOC.md | 492 ------------------ .../sql/language-structure/comment-syntax.md | 124 ----- reference/best-practices/high-concurrency.md | 2 +- .../sql/attributes/auto-random.md | 4 +- v3.1/reference/sql/attributes/auto-random.md | 103 ---- 6 files changed, 5 insertions(+), 722 deletions(-) delete mode 100644 dev/TOC.md delete mode 100644 dev/reference/sql/language-structure/comment-syntax.md rename {dev/reference => reference}/sql/attributes/auto-random.md (95%) delete mode 100644 v3.1/reference/sql/attributes/auto-random.md diff --git a/TOC.md b/TOC.md index 013f601a2131..e3e95c428331 100644 --- a/TOC.md +++ b/TOC.md @@ -81,6 +81,8 @@ - [用户自定义变量](/reference/sql/language-structure/user-defined-variables.md) - [表达式语法](/reference/sql/language-structure/expression-syntax.md) - [注释语法](/reference/sql/language-structure/comment-syntax.md) + + 表属性和列属性 + - [`AUTO_RANDOM`](/reference/sql/attributes/auto-random.md) + 数据类型 - [概述](/reference/sql/data-types/overview.md) - [默认值](/reference/sql/data-types/default-values.md) diff --git a/dev/TOC.md b/dev/TOC.md deleted file mode 100644 index 221eeaa8479d..000000000000 --- a/dev/TOC.md +++ /dev/null @@ -1,492 +0,0 @@ -# TiDB 中文用户文档 - - - - -## 目录 - -+ 关于 TiDB - - [TiDB 简介](/dev/overview.md) - + Benchmark 测试 - - [如何用 Sysbench 测试 TiDB](/dev/benchmark/how-to-run-sysbench.md) - - [如何对 TiDB 进行 TPC-C 测试](/dev/benchmark/how-to-run-tpcc.md) - - [Sysbench 性能对比 - v3.0 对比 v2.1](/dev/benchmark/sysbench-v4.md) - - [TPC-C 性能对比 - v3.0 对比 v2.1](/dev/benchmark/tpcc.md) - - [线上负载与 `Add Index` 相互影响测试](/dev/benchmark/add-index-with-load.md) - - [TiDB in Kubernetes Sysbench 性能测试](/dev/benchmark/sysbench-in-k8s.md) - - [DM 1.0-GA 性能测试](/dev/benchmark/dm-v1.0-ga.md) -+ 主要概念 - - [整体架构](/dev/architecture.md) - + 核心特性 - - [水平扩展](/dev/key-features.md#水平扩展) - - [高可用](/dev/key-features.md#高可用) -+ 操作指南 - + 快速上手 - - [使用 Docker Compose 部署 TiDB](/dev/how-to/get-started/deploy-tidb-from-docker-compose.md) - - [SQL 基本操作](/dev/how-to/get-started/explore-sql.md) - - [读取历史数据](/dev/how-to/get-started/read-historical-data.md) - - [TiDB Binlog 教程](/dev/how-to/get-started/tidb-binlog.md) - - [TiDB Data Migration 教程](/dev/how-to/get-started/data-migration.md) - - [TiDB Lightning 教程](/dev/how-to/get-started/tidb-lightning.md) - - [TiSpark 教程](/dev/how-to/get-started/tispark.md) - + 部署 - - [软硬件环境需求](/dev/how-to/deploy/hardware-recommendations.md) - + 集群部署方式 - - [使用 Ansible 部署（推荐）](/dev/how-to/deploy/orchestrated/ansible.md) - - [使用 Ansible 离线部署](/dev/how-to/deploy/orchestrated/offline-ansible.md) - - [使用 Docker 部署](/dev/how-to/deploy/orchestrated/docker.md) - + 跨地域冗余 - - [跨数据中心部署方案](/dev/how-to/deploy/geographic-redundancy/overview.md) - - [配置集群拓扑](/dev/how-to/deploy/geographic-redundancy/location-awareness.md) - - [使用 Ansible 部署 DM 集群](/dev/how-to/deploy/data-migration-with-ansible.md) - + 配置 - - [时区](/dev/how-to/configure/time-zone.md) - - [内存控制](/dev/how-to/configure/memory-control.md) - + 安全 - + 安全传输层协议 (TLS) - - [为 MySQL 客户端开启 TLS](/dev/how-to/secure/enable-tls-clients.md) - - [为 TiDB 组件间开启 TLS](/dev/how-to/secure/enable-tls-between-components.md) - - [生成自签名证书](/dev/how-to/secure/generate-self-signed-certificates.md) - + 监控 - - [概述](/dev/how-to/monitor/overview.md) - - [监控 TiDB 集群](/dev/how-to/monitor/monitor-a-cluster.md) - + 迁移 - - [迁移工具使用指南](/dev/reference/tools/user-guide.md) - + 从 MySQL 迁移 - - [以 Amazon Aurora MySQL 为例](/dev/how-to/migrate/from-mysql-aurora.md) - - [从 CSV 迁移](/dev/reference/tools/tidb-lightning/csv.md) - + 运维 - - [Ansible 常见运维操作](/dev/how-to/maintain/ansible-operations.md) - + 备份与恢复 - - [使用 Mydumper/TiDB Lightning 进行备份与恢复](/dev/how-to/maintain/backup-and-restore/mydumper-lightning.md) - - [使用 BR 进行备份与恢复](/dev/reference/tools/br/br.md) - - [BR 备份与恢复场景示例](/dev/reference/tools/br/use-cases.md) - + 定位异常查询 - - [定位慢查询](/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md) - - [定位消耗系统资源多的查询](/dev/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md) - + 扩容缩容 - - [使用 Ansible 扩容缩容](/dev/how-to/scale/with-ansible.md) - + 升级 - - [升级至最新开发版](/dev/how-to/upgrade/from-previous-version.md) - + 故障诊断 - - [集群配置诊断](/dev/how-to/troubleshoot/cluster-setup.md) - - [TiDB Lightning 故障诊断](/dev/how-to/troubleshoot/tidb-lightning.md) -+ 参考手册 - + SQL - - [与 MySQL 兼容性对比](/dev/reference/mysql-compatibility.md) - + SQL 语言结构 - - [字面值](/dev/reference/sql/language-structure/literal-values.md) - - [Schema 对象名](/dev/reference/sql/language-structure/schema-object-names.md) - - [关键字和保留字](/dev/reference/sql/language-structure/keywords-and-reserved-words.md) - - [用户自定义变量](/dev/reference/sql/language-structure/user-defined-variables.md) - - [表达式语法](/dev/reference/sql/language-structure/expression-syntax.md) - - [注释语法](/dev/reference/sql/language-structure/comment-syntax.md) - + 表属性和列属性 - - [`AUTO_RANDOM`](/dev/reference/sql/attributes/auto-random.md) - + 数据类型 - - [概述](/dev/reference/sql/data-types/overview.md) - - [默认值](/dev/reference/sql/data-types/default-values.md) - + 数值类型 - - [`BIT`](/dev/reference/sql/data-types/numeric.md#bit-类型) - - [`BOOL|BOOLEAN`](/dev/reference/sql/data-types/numeric.md#boolean-类型) - - [`TINYINT`](/dev/reference/sql/data-types/numeric.md#tinyint-类型) - - [`SMALLINT`](/dev/reference/sql/data-types/numeric.md#smallint-类型) - - [`MEDIUMINT`](/dev/reference/sql/data-types/numeric.md#mediumint-类型) - - [`INT|INTEGER`](/dev/reference/sql/data-types/numeric.md#integer-类型) - - [`BIGINT`](/dev/reference/sql/data-types/numeric.md#bigint-类型) - - [`DECIMAL`](/dev/reference/sql/data-types/numeric.md#decimal-类型) - - [`FLOAT`](/dev/reference/sql/data-types/numeric.md#float-类型) - - [`DOUBLE`](/dev/reference/sql/data-types/numeric.md#double-类型) - + 日期和时间类型 - - [`DATE`](/dev/reference/sql/data-types/date-and-time.md#date-类型) - - [`DATETIME`](/dev/reference/sql/data-types/date-and-time.md#datetime-类型) - - [`TIMESTAMP`](/dev/reference/sql/data-types/date-and-time.md#timestamp-类型) - - [`TIME`](/dev/reference/sql/data-types/date-and-time.md#time-类型) - - [`YEAR`](/dev/reference/sql/data-types/date-and-time.md#year-类型) - + 字符串类型 - - [`CHAR`](/dev/reference/sql/data-types/string.md#char-类型) - - [`VARCHAR`](/dev/reference/sql/data-types/string.md#varchar-类型) - - [`TEXT`](/dev/reference/sql/data-types/string.md#text-类型) - - [`LONGTEXT`](/dev/reference/sql/data-types/string.md#longtext-类型) - - [`BINARY`](/dev/reference/sql/data-types/string.md#binary-类型) - - [`VARBINARY`](/dev/reference/sql/data-types/string.md#varbinary-类型) - - [`TINYBLOB`](/dev/reference/sql/data-types/string.md#tinyblob-类型) - - [`BLOB`](/dev/reference/sql/data-types/string.md#blob-类型) - - [`MEDIUMBLOB`](/dev/reference/sql/data-types/string.md#mediumblob-类型) - - [`LONGBLOB`](/dev/reference/sql/data-types/string.md#longblob-类型) - - [`ENUM`](/dev/reference/sql/data-types/string.md#enum-类型) - - [`SET`](/dev/reference/sql/data-types/string.md#set-类型) - - [JSON Type](/dev/reference/sql/data-types/json.md) - + 函数与操作符 - - [函数与操作符概述](/dev/reference/sql/functions-and-operators/reference.md) - - [表达式求值的类型转换](/dev/reference/sql/functions-and-operators/type-conversion.md) - - [操作符](/dev/reference/sql/functions-and-operators/operators.md) - - [控制流程函数](/dev/reference/sql/functions-and-operators/control-flow-functions.md) - - [字符串函数](/dev/reference/sql/functions-and-operators/string-functions.md) - - [数值函数与操作符](/dev/reference/sql/functions-and-operators/numeric-functions-and-operators.md) - - [日期和时间函数](/dev/reference/sql/functions-and-operators/date-and-time-functions.md) - - [位函数和操作符](/dev/reference/sql/functions-and-operators/bit-functions-and-operators.md) - - [Cast 函数和操作符](/dev/reference/sql/functions-and-operators/cast-functions-and-operators.md) - - [加密和压缩函数](/dev/reference/sql/functions-and-operators/encryption-and-compression-functions.md) - - [信息函数](/dev/reference/sql/functions-and-operators/information-functions.md) - - [JSON 函数](/dev/reference/sql/functions-and-operators/json-functions.md) - - [GROUP BY 聚合函数](/dev/reference/sql/functions-and-operators/aggregate-group-by-functions.md) - - [窗口函数](/dev/reference/sql/functions-and-operators/window-functions.md) - - [其它函数](/dev/reference/sql/functions-and-operators/miscellaneous-functions.md) - - [精度数学](/dev/reference/sql/functions-and-operators/precision-math.md) - - [下推到 TiKV 的表达式列表](/dev/reference/sql/functions-and-operators/expressions-pushed-down.md) - + SQL 语句 - - [`ADD COLUMN`](/dev/reference/sql/statements/add-column.md) - - [`ADD INDEX`](/dev/reference/sql/statements/add-index.md) - - [`ADMIN`](/dev/reference/sql/statements/admin.md) - - [`ALTER DATABASE`](/dev/reference/sql/statements/alter-database.md) - - [`ALTER TABLE`](/dev/reference/sql/statements/alter-table.md) - - [`ALTER USER`](/dev/reference/sql/statements/alter-user.md) - - [`ANALYZE TABLE`](/dev/reference/sql/statements/analyze-table.md) - - [`BEGIN`](/dev/reference/sql/statements/begin.md) - - [`COMMIT`](/dev/reference/sql/statements/commit.md) - - [`CREATE DATABASE`](/dev/reference/sql/statements/create-database.md) - - [`CREATE INDEX`](/dev/reference/sql/statements/create-index.md) - - [`CREATE TABLE LIKE`](/dev/reference/sql/statements/create-table-like.md) - - [`CREATE TABLE`](/dev/reference/sql/statements/create-table.md) - - [`CREATE USER`](/dev/reference/sql/statements/create-user.md) - - [`CREATE VIEW`](/dev/reference/sql/statements/create-view.md) - - [`DEALLOCATE`](/dev/reference/sql/statements/deallocate.md) - - [`DELETE`](/dev/reference/sql/statements/delete.md) - - [`DESC`](/dev/reference/sql/statements/desc.md) - - [`DESCRIBE`](/dev/reference/sql/statements/describe.md) - - [`DO`](/dev/reference/sql/statements/do.md) - - [`DROP COLUMN`](/dev/reference/sql/statements/drop-column.md) - - [`DROP DATABASE`](/dev/reference/sql/statements/drop-database.md) - - [`DROP INDEX`](/dev/reference/sql/statements/drop-index.md) - - [`DROP TABLE`](/dev/reference/sql/statements/drop-table.md) - - [`DROP USER`](/dev/reference/sql/statements/drop-user.md) - - [`DROP VIEW`](/dev/reference/sql/statements/drop-view.md) - - [`EXECUTE`](/dev/reference/sql/statements/execute.md) - - [`EXPLAIN ANALYZE`](/dev/reference/sql/statements/explain-analyze.md) - - [`EXPLAIN`](/dev/reference/sql/statements/explain.md) - - [`FLUSH PRIVILEGES`](/dev/reference/sql/statements/flush-privileges.md) - - [`FLUSH STATUS`](/dev/reference/sql/statements/flush-status.md) - - [`FLUSH TABLES`](/dev/reference/sql/statements/flush-tables.md) - - [`GRANT `](/dev/reference/sql/statements/grant-privileges.md) - - [`INSERT`](/dev/reference/sql/statements/insert.md) - - [`KILL [TIDB]`](/dev/reference/sql/statements/kill.md) - - [`LOAD DATA`](/dev/reference/sql/statements/load-data.md) - - [`MODIFY COLUMN`](/dev/reference/sql/statements/modify-column.md) - - [`PREPARE`](/dev/reference/sql/statements/prepare.md) - - [`RECOVER TABLE`](/dev/reference/sql/statements/recover-table.md) - - [`RENAME INDEX`](/dev/reference/sql/statements/rename-index.md) - - [`RENAME TABLE`](/dev/reference/sql/statements/rename-table.md) - - [`REPLACE`](/dev/reference/sql/statements/replace.md) - - [`REVOKE `](/dev/reference/sql/statements/revoke-privileges.md) - - [`ROLLBACK`](/dev/reference/sql/statements/rollback.md) - - [`SELECT`](/dev/reference/sql/statements/select.md) - - [`SET [NAMES|CHARACTER SET]`](/dev/reference/sql/statements/set-names.md) - - [`SET PASSWORD`](/dev/reference/sql/statements/set-password.md) - - [`SET TRANSACTION`](/dev/reference/sql/statements/set-transaction.md) - - [`SET [GLOBAL|SESSION] `](/dev/reference/sql/statements/set-variable.md) - - [`SHOW CHARACTER SET`](/dev/reference/sql/statements/show-character-set.md) - - [`SHOW COLLATION`](/dev/reference/sql/statements/show-collation.md) - - [`SHOW [FULL] COLUMNS FROM`](/dev/reference/sql/statements/show-columns-from.md) - - [`SHOW CREATE TABLE`](/dev/reference/sql/statements/show-create-table.md) - - [`SHOW CREATE USER`](/dev/reference/sql/statements/show-create-user.md) - - [`SHOW DATABASES`](/dev/reference/sql/statements/show-databases.md) - - [`SHOW ENGINES`](/dev/reference/sql/statements/show-engines.md) - - [`SHOW ERRORS`](/dev/reference/sql/statements/show-errors.md) - - [`SHOW [FULL] FIELDS FROM`](/dev/reference/sql/statements/show-fields-from.md) - - [`SHOW GRANTS`](/dev/reference/sql/statements/show-grants.md) - - [`SHOW INDEXES [FROM|IN]`](/dev/reference/sql/statements/show-indexes.md) - - [`SHOW INDEX [FROM|IN]`](/dev/reference/sql/statements/show-index.md) - - [`SHOW KEYS [FROM|IN]`](/dev/reference/sql/statements/show-keys.md) - - [`SHOW PRIVILEGES`](/dev/reference/sql/statements/show-privileges.md) - - [`SHOW [FULL] PROCESSSLIST`](/dev/reference/sql/statements/show-processlist.md) - - [`SHOW SCHEMAS`](/dev/reference/sql/statements/show-schemas.md) - - [`SHOW [FULL] TABLES`](/dev/reference/sql/statements/show-tables.md) - - [`SHOW TABLE REGIONS`](/dev/reference/sql/statements/show-table-regions.md) - - [`SHOW TABLE STATUS`](/dev/reference/sql/statements/show-table-status.md) - - [`SHOW [GLOBAL|SESSION] VARIABLES`](/dev/reference/sql/statements/show-variables.md) - - [`SHOW WARNINGS`](/dev/reference/sql/statements/show-warnings.md) - - [`SPLIT REGION`](/dev/reference/sql/statements/split-region.md) - - [`START TRANSACTION`](/dev/reference/sql/statements/start-transaction.md) - - [`TRACE`](/dev/reference/sql/statements/trace.md) - - [`TRUNCATE`](/dev/reference/sql/statements/truncate.md) - - [`UPDATE`](/dev/reference/sql/statements/update.md) - - [`USE`](/dev/reference/sql/statements/use.md) - - [约束](/dev/reference/sql/constraints.md) - - [生成列](/dev/reference/sql/generated-columns.md) - - [分区表](/dev/reference/sql/partitioning.md) - - [字符集](/dev/reference/sql/character-set.md) - - [SQL 模式](/dev/reference/sql/sql-mode.md) - - [视图](/dev/reference/sql/view.md) - + 配置 - + tidb-server - - [MySQL 系统变量](/dev/reference/configuration/tidb-server/mysql-variables.md) - - [TiDB 特定系统变量](/dev/reference/configuration/tidb-server/tidb-specific-variables.md) - - [配置参数](/dev/reference/configuration/tidb-server/configuration.md) - - [配置文件描述](/dev/reference/configuration/tidb-server/configuration-file.md) - + pd-server - - [配置参数](/dev/reference/configuration/pd-server/configuration.md) - - [配置文件描述](/dev/reference/configuration/pd-server/configuration-file.md) - + tikv-server - - [配置参数](/dev/reference/configuration/tikv-server/configuration.md) - - [配置文件描述](/dev/reference/configuration/tikv-server/configuration-file.md) - + 安全 - - [与 MySQL 的安全特性差异](/dev/reference/security/compatibility.md) - - [TiDB 数据库权限管理](/dev/reference/security/privilege-system.md) - - [TiDB 用户账户管理](/dev/reference/security/user-account-management.md) - - [基于角色的访问控制](/dev/reference/security/role-based-access-control.md) - - [TiDB 证书鉴权使用指南](/dev/reference/security/cert-based-authentication.md) - + 事务 - - [事务语句](/dev/reference/transactions/overview.md) - - [事务模型](/dev/reference/transactions/transaction-model.md) - - [隔离级别](/dev/reference/transactions/transaction-isolation.md) - - [悲观事务](/dev/reference/transactions/transaction-pessimistic.md) - + 系统数据库 - - [`mysql`](/dev/reference/system-databases/mysql.md) - - [`information_schema`](/dev/reference/system-databases/information-schema.md) - - [错误码](/dev/reference/error-codes.md) - - [支持的连接器和 API](/dev/reference/supported-clients.md) - + 垃圾回收 (GC) - - [GC 机制简介](/dev/reference/garbage-collection/overview.md) - - [GC 配置](/dev/reference/garbage-collection/configuration.md) - + 性能调优 - - [SQL 优化流程](/dev/reference/performance/sql-optimizer-overview.md) - - [理解 TiDB 执行计划](/dev/reference/performance/understanding-the-query-execution-plan.md) - - [执行计划绑定](/dev/reference/performance/execution-plan-bind.md) - - [统计信息概述](/dev/reference/performance/statistics.md) - - [Optimizer Hints](/dev/reference/performance/optimizer-hints.md) - - [Follower Read](/dev/reference/performance/follower-read.md) - - [使用 SQL 语句检查 TiDB 集群状态](/dev/reference/performance/check-cluster-status-using-sql-statements.md) - - [Statement Summary Table](/dev/reference/performance/statement-summary.md) - - [TiKV 调优](/dev/reference/performance/tune-tikv.md) - - [TiDB 最佳实践](https://pingcap.com/blog-cn/tidb-best-practice/) - + 监控指标 - - [Overview 面板](/dev/reference/key-monitoring-metrics/overview-dashboard.md) - - [TiDB 面板](/dev/reference/key-monitoring-metrics/tidb-dashboard.md) - - [PD 面板](/dev/reference/key-monitoring-metrics/pd-dashboard.md) - - [TiKV 面板](/dev/reference/key-monitoring-metrics/tikv-dashboard.md) - - [报警规则](/dev/reference/alert-rules.md) - + 最佳实践 - - [HAProxy 最佳实践](/dev/reference/best-practices/haproxy.md) - - [Java 应用开发最佳实践](/dev/reference/best-practices/java-app.md) - - [高并发写入场景最佳实践](/dev/reference/best-practices/high-concurrency.md) - - [Grafana 监控最佳实践](/dev/reference/best-practices/grafana-monitor.md) - - [PD 调度策略最佳实践](/dev/reference/best-practices/pd-scheduling.md) - - [海量 Region 集群调优最佳实践](/dev/reference/best-practices/massive-regions.md) - - [乐观锁事务最佳实践](/dev/reference/best-practices/optimistic-transaction.md) - + [TiSpark 使用指南](/dev/reference/tispark.md) - + TiDB Binlog - - [概述](/dev/reference/tidb-binlog/overview.md) - - [部署使用](/dev/reference/tidb-binlog/deploy.md) - - [运维管理](/dev/reference/tidb-binlog/maintain.md) - - [版本升级](/dev/reference/tidb-binlog/upgrade.md) - - [监控告警](/dev/reference/tidb-binlog/monitor.md) - - [增量恢复](/dev/reference/tidb-binlog/reparo.md) - - [Kafka 自定义开发](/dev/reference/tidb-binlog/binlog-slave-client.md) - - [TiDB Binlog Relay Log](/dev/reference/tidb-binlog/relay-log.md) - - [术语表](/dev/reference/tidb-binlog/glossary.md) - + 故障诊断 - - [故障诊断](/dev/reference/tidb-binlog/troubleshoot/binlog.md) - - [常见错误修复](/dev/reference/tidb-binlog/troubleshoot/error-handling.md) - - [FAQ](/dev/reference/tidb-binlog/faq.md) - + 周边工具 - - [工具使用指南](/dev/reference/tools/user-guide.md) - - [Mydumper](/dev/reference/tools/mydumper.md) - - [Loader](/dev/reference/tools/loader.md) - - [Syncer](/dev/reference/tools/syncer.md) - + Data Migration - + 概述 - - [DM 架构](/dev/reference/tools/data-migration/overview.md#dm-架构) - - [同步功能介绍](/dev/reference/tools/data-migration/overview.md#同步功能介绍) - - [使用限制](/dev/reference/tools/data-migration/overview.md#使用限制) - - [DM-worker 简介](/dev/reference/tools/data-migration/dm-worker-intro.md) - - [DM Relay Log](/dev/reference/tools/data-migration/relay-log.md) - + 核心特性 - - [Table Routing](/dev/reference/tools/data-migration/features/overview.md#table-routing) - - [Black & White Lists](/dev/reference/tools/data-migration/features/overview.md#black--white-table-lists) - - [Binlog Event Filter](/dev/reference/tools/data-migration/features/overview.md#binlog-event-filter) - - [同步延迟监控](/dev/reference/tools/data-migration/features/overview.md#同步延迟监控) - + Shard Support - - [简介](/dev/reference/tools/data-migration/features/shard-merge.md) - - [使用限制](/dev/reference/tools/data-migration/features/shard-merge.md#使用限制) - - [手动处理 Sharding DDL Lock](/dev/reference/tools/data-migration/features/manually-handling-sharding-ddl-locks.md) - + 使用场景 - - [简单的从库同步场景](/dev/reference/tools/data-migration/usage-scenarios/simple-synchronization.md) - - [分库分表合并场景](/dev/reference/tools/data-migration/usage-scenarios/shard-merge.md) - - [分表合并数据迁移最佳实践](/dev/reference/tools/data-migration/usage-scenarios/best-practice-dm-shard.md) - - [DM-worker 在上游 MySQL 主从间切换](/dev/reference/tools/data-migration/usage-scenarios/master-slave-switch.md) - + [部署使用](/dev/reference/tools/data-migration/deploy.md) - + 配置 - - [概述](/dev/reference/tools/data-migration/configure/overview.md) - - [DM-master 配置](/dev/reference/tools/data-migration/configure/dm-master-configuration-file.md) - - [DM-worker 配置](/dev/reference/tools/data-migration/configure/dm-worker-configuration-file.md) - - [任务配置](/dev/reference/tools/data-migration/configure/task-configuration-file.md) - + DM 集群管理 - - [集群操作](/dev/reference/tools/data-migration/cluster-operations.md) - - [集群升级](/dev/reference/tools/data-migration/dm-upgrade.md) - + DM 同步任务管理 - - [管理数据同步任务](/dev/reference/tools/data-migration/manage-tasks.md) - - [任务前置检查](/dev/reference/tools/data-migration/precheck.md) - - [任务状态查询](/dev/reference/tools/data-migration/query-status.md) - - [跳过或替代执行异常的 SQL 语句](/dev/reference/tools/data-migration/skip-replace-sqls.md) - - [监控 DM 集群](/dev/reference/tools/data-migration/monitor.md) - + 从与 MySQL 兼容的数据库迁移数据 - - [从 MySQL/Amazon Aurora MySQL 迁移数据](/dev/how-to/migrate/from-mysql-aurora.md) - - [DM Portal](/dev/reference/tools/data-migration/dm-portal.md) - + DM 故障诊断 - - [故障诊断](/dev/reference/tools/data-migration/troubleshoot/dm.md) - - [错误含义](/dev/reference/tools/data-migration/troubleshoot/error-system.md) - - [常见错误修复](/dev/reference/tools/data-migration/troubleshoot/error-handling.md) - - [DM FAQ](/dev/reference/tools/data-migration/faq.md) - + 版本发布历史 - + v1.0 - - [1.0.2](/dev/reference/tools/data-migration/releases/1.0.2.md) - - [1.0.3](/dev/reference/tools/data-migration/releases/1.0.3.md) - - [TiDB DM 术语表](/dev/reference/tools/data-migration/glossary.md) - + TiDB Lightning - - [概述](/dev/reference/tools/tidb-lightning/overview.md) - - [部署执行](/dev/reference/tools/tidb-lightning/deployment.md) - - [参数说明](/dev/reference/tools/tidb-lightning/config.md) - - [断点续传](/dev/reference/tools/tidb-lightning/checkpoints.md) - - [表库过滤](/dev/reference/tools/tidb-lightning/table-filter.md) - - [CSV 支持](/dev/reference/tools/tidb-lightning/csv.md) - - [TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md) - - [Web 界面](/dev/reference/tools/tidb-lightning/web.md) - - [监控告警](/dev/reference/tools/tidb-lightning/monitor.md) - - [故障诊断](/dev/how-to/troubleshoot/tidb-lightning.md) - - [FAQ](/dev/faq/tidb-lightning.md) - - [术语表](/dev/reference/tools/tidb-lightning/glossary.md) - - [sync-diff-inspector](/dev/reference/tools/sync-diff-inspector/overview.md) - - [PD Control](/dev/reference/tools/pd-control.md) - - [PD Recover](/dev/reference/tools/pd-recover.md) - - [TiKV Control](/dev/reference/tools/tikv-control.md) - - [TiDB Controller](/dev/reference/tools/tidb-control.md) - - [工具下载](/dev/reference/tools/download.md) -+ TiDB in Kubernetes - - [TiDB Operator 简介](/dev/tidb-in-kubernetes/tidb-operator-overview.md) - + 快速上手 - - [kind](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-kind.md) - - [GKE](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-gke.md) - - [Minikube](/dev/tidb-in-kubernetes/get-started/deploy-tidb-from-kubernetes-minikube.md) - + 部署 - - [集群环境要求](/dev/tidb-in-kubernetes/deploy/prerequisites.md) - - [部署 TiDB Operator](/dev/tidb-in-kubernetes/deploy/tidb-operator.md) - - [标准 Kubernetes 上的 TiDB 集群](/dev/tidb-in-kubernetes/deploy/general-kubernetes.md) - - [AWS EKS 上的 TiDB 集群](/dev/tidb-in-kubernetes/deploy/aws-eks.md) - - [GCP 上的 TiDB 集群](/dev/tidb-in-kubernetes/deploy/gcp-gke.md) - - [阿里云上的 TiDB 集群](/dev/tidb-in-kubernetes/deploy/alibaba-cloud.md) - - [访问 Kubernetes 上的 TiDB 集群](/dev/tidb-in-kubernetes/deploy/access-tidb.md) - + 配置 - - [初始化集群](/dev/tidb-in-kubernetes/initialize-cluster.md) - - [监控](/dev/tidb-in-kubernetes/monitor/tidb-in-kubernetes.md) - + 运维 - - [销毁 TiDB 集群](/dev/tidb-in-kubernetes/maintain/destroy-tidb-cluster.md) - - [维护 TiDB 集群所在节点](/dev/tidb-in-kubernetes/maintain/kubernetes-node.md) - - [备份与恢复](/dev/tidb-in-kubernetes/maintain/backup-and-restore.md) - - [恢复 Kubernetes 上的 TiDB 集群数据](/dev/tidb-in-kubernetes/maintain/lightning.md) - - [收集日志](/dev/tidb-in-kubernetes/maintain/log-collecting.md) - - [集群故障自动转移](/dev/tidb-in-kubernetes/maintain/auto-failover.md) - - [TiDB Binlog](/dev/tidb-in-kubernetes/maintain/tidb-binlog.md) - - [重启 TiDB 集群](/dev/tidb-in-kubernetes/maintain/restart.md) - - [扩缩容](/dev/tidb-in-kubernetes/scale-in-kubernetes.md) - + 升级 - - [TiDB 集群](/dev/tidb-in-kubernetes/upgrade/tidb-cluster.md) - - [TiDB Operator](/dev/tidb-in-kubernetes/upgrade/tidb-operator.md) - + 参考信息 - + 配置 - - [集群配置](/dev/tidb-in-kubernetes/reference/configuration/tidb-cluster.md) - - [备份配置](/dev/tidb-in-kubernetes/reference/configuration/backup.md) - - [PV 配置](/dev/tidb-in-kubernetes/reference/configuration/storage-class.md) - - [TiDB Drainer](/dev/tidb-in-kubernetes/reference/configuration/tidb-drainer.md) - + 工具 - - [tkctl](/dev/tidb-in-kubernetes/reference/tools/tkctl.md) - - [相关工具使用](/dev/tidb-in-kubernetes/reference/tools/in-kubernetes.md) - - [故障诊断](/dev/tidb-in-kubernetes/troubleshoot.md) - - [常见问题](/dev/tidb-in-kubernetes/faq.md) -+ 常见问题 (FAQ) - - [TiDB FAQ](/dev/faq/tidb.md) - - [TiDB Lightning FAQ](/dev/faq/tidb-lightning.md) - - [升级 FAQ](/dev/faq/upgrade.md) -+ 技术支持 - - [支持渠道](/dev/support-resources.md) - - [反馈问题](/dev/report-issue.md) -+ [贡献](/dev/contribute.md) - - [贡献代码](/dev/contribute.md#成为-tidb-的贡献者) - - [改进文档](/dev/contribute.md#改进文档) -+ [TiDB 路线图](/dev/roadmap.md) -+ [版本发布历史](/dev/releases/rn.md) - + v4.0 - - [4.0.0-beta](/dev/releases/4.0.0-beta.md) - + v3.1 - - [3.1.0-beta.1](/dev/releases/3.1.0-beta.1.md) - - [3.1.0-beta](/dev/releases/3.1.0-beta.md) - + v3.0 - - [3.0.9](/dev/releases/3.0.9.md) - - [3.0.8](/dev/releases/3.0.8.md) - - [3.0.7](/dev/releases/3.0.7.md) - - [3.0.6](/dev/releases/3.0.6.md) - - [3.0.5](/dev/releases/3.0.5.md) - - [3.0.4](/dev/releases/3.0.4.md) - - [3.0.3](/dev/releases/3.0.3.md) - - [3.0.2](/dev/releases/3.0.2.md) - - [3.0.1](/dev/releases/3.0.1.md) - - [3.0 GA](/dev/releases/3.0-ga.md) - - [3.0.0-rc.3](/dev/releases/3.0.0-rc.3.md) - - [3.0.0-rc.2](/dev/releases/3.0.0-rc.2.md) - - [3.0.0-rc.1](/dev/releases/3.0.0-rc.1.md) - - [3.0.0-beta.1](/dev/releases/3.0.0-beta.1.md) - - [3.0.0-beta](/dev/releases/3.0beta.md) - + v2.1 - - [2.1.19](/dev/releases/2.1.19.md) - - [2.1.18](/dev/releases/2.1.18.md) - - [2.1.17](/dev/releases/2.1.17.md) - - [2.1.16](/dev/releases/2.1.16.md) - - [2.1.15](/dev/releases/2.1.15.md) - - [2.1.14](/dev/releases/2.1.14.md) - - [2.1.13](/dev/releases/2.1.13.md) - - [2.1.12](/dev/releases/2.1.12.md) - - [2.1.11](/dev/releases/2.1.11.md) - - [2.1.10](/dev/releases/2.1.10.md) - - [2.1.9](/dev/releases/2.1.9.md) - - [2.1.8](/dev/releases/2.1.8.md) - - [2.1.7](/dev/releases/2.1.7.md) - - [2.1.6](/dev/releases/2.1.6.md) - - [2.1.5](/dev/releases/2.1.5.md) - - [2.1.4](/dev/releases/2.1.4.md) - - [2.1.3](/dev/releases/2.1.3.md) - - [2.1.2](/dev/releases/2.1.2.md) - - [2.1.1](/dev/releases/2.1.1.md) - - [2.1 GA](/dev/releases/2.1ga.md) - - [2.1 RC5](/dev/releases/21rc5.md) - - [2.1 RC4](/dev/releases/21rc4.md) - - [2.1 RC3](/dev/releases/21rc3.md) - - [2.1 RC2](/dev/releases/21rc2.md) - - [2.1 RC1](/dev/releases/21rc1.md) - - [2.1 Beta](/dev/releases/21beta.md) - + v2.0 - - [2.0.11](/dev/releases/2.0.11.md) - - [2.0.10](/dev/releases/2.0.10.md) - - [2.0.9](/dev/releases/209.md) - - [2.0.8](/dev/releases/208.md) - - [2.0.7](/dev/releases/207.md) - - [2.0.6](/dev/releases/206.md) - - [2.0.5](/dev/releases/205.md) - - [2.0.4](/dev/releases/204.md) - - [2.0.3](/dev/releases/203.md) - - [2.0.2](/dev/releases/202.md) - - [2.0.1](/dev/releases/201.md) - - [2.0](/dev/releases/2.0ga.md) - - [2.0 RC5](/dev/releases/2rc5.md) - - [2.0 RC4](/dev/releases/2rc4.md) - - [2.0 RC3](/dev/releases/2rc3.md) - - [2.0 RC1](/dev/releases/2rc1.md) - - [1.1 Beta](/dev/releases/11beta.md) - - [1.1 Alpha](/dev/releases/11alpha.md) - + v1.0 - - [1.0](/dev/releases/ga.md) - - [Pre-GA](/dev/releases/prega.md) - - [RC4](/dev/releases/rc4.md) - - [RC3](/dev/releases/rc3.md) - - [RC2](/dev/releases/rc2.md) - - [RC1](/dev/releases/rc1.md) -+ [术语表](/dev/glossary.md) diff --git a/dev/reference/sql/language-structure/comment-syntax.md b/dev/reference/sql/language-structure/comment-syntax.md deleted file mode 100644 index 2d4d2aed638c..000000000000 --- a/dev/reference/sql/language-structure/comment-syntax.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: 注释语法 -category: reference ---- - -# 注释语法 - -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" >}} - -```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) -``` - -TiDB 也跟 MySQL 保持一致，支持一种 C 风格注释的变体： - -``` -/*! Specific code */ -``` - -在这种格式中，TiDB 会执行注释中的语句，这个语法是为了让这些 SQL 在其他的数据库中被忽略，而在 TiDB 中被执行。 - -例如：`SELECT /*! STRAIGHT_JOIN */ col1 FROM table1,table2 WHERE ...` - -在 TiDB 中，这种写法等价于 `SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ...` - -如果注释中指定了 Server 版本号，例如 `/*!50110 KEY_BLOCK_SIZE=1024 */`，在 MySQL 中表示只有 MySQL 的版本大于等于 5.1.10 才会处理这个 comment 中的内容。但是在 TiDB 中，这个 MySQL 版本号不会起作用，所有的 comment 都被会处理。TiDB 有自己的版本号注释语法，格式为 `/*T!30100 XXX */`。 - -还有一种注释会被当做是优化器 Hint 特殊对待： - -{{< copyable "sql" >}} - -```sql -SELECT /*+ hint */ FROM ...; -``` - -由于 hint 包含在类似 /*+ xxx */ 的 comment 里，MySQL 客户端在 5.7.7 之前，会默认把 comment 清除掉，如果需要在旧的客户端使用 hint，需要在启动客户端时加上 --comments 选项，例如 mysql -h 127.0.0.1 -P 4000 -uroot --comments - -TiDB 支持的相关优化器 hint 详见 [Optimizer Hints](/dev/reference/performance/optimizer-hints.md)。 - -更多[细节](https://dev.mysql.com/doc/refman/5.7/en/comments.html)。 diff --git a/reference/best-practices/high-concurrency.md b/reference/best-practices/high-concurrency.md index 30cd8045a89d..fb64b5f7a41b 100644 --- a/reference/best-practices/high-concurrency.md +++ b/reference/best-practices/high-concurrency.md @@ -199,7 +199,7 @@ create table t (a int, b int) shard_row_id_bits = 4 pre_split_regions=·3; 如果表的主键为整数类型，并且该表使用了 `AUTO_INCREMENT` 来保证主键唯一性（不需要连续或递增）的表而言，由于 TiDB 直接使用主键行值作为 `_tidb_rowid`，此时无法使用 `SHARD_ROW_ID_BITS` 来打散热点。 -要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/dev/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整型主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 +要解决上述热点问题，可以利用 `AUTO_RANDOM` 列属性（参阅 [`AUTO_RANDOM` 的详细说明](/reference/sql/attributes/auto-random.md)），将 `AUTO_INCREMENT` 改为 `AUTO_RANDOM`，插入数据时让 TiDB 自动为整型主键列分配一个值，消除行 ID 的连续性，从而达到打散热点的目的。 ## 参数配置 diff --git a/dev/reference/sql/attributes/auto-random.md b/reference/sql/attributes/auto-random.md similarity index 95% rename from dev/reference/sql/attributes/auto-random.md rename to reference/sql/attributes/auto-random.md index 355b27ab0e10..61340211cc1d 100644 --- a/dev/reference/sql/attributes/auto-random.md +++ b/reference/sql/attributes/auto-random.md @@ -9,11 +9,11 @@ category: reference > > 当前 `AUTO_RANDOM` 属性为实验功能，**不建议在生产环境中使用**。在后续版本中，`AUTO_RANDOM` 的语法或语义可能会变化。 -使用 `AUTO_RANDOM` 功能前，须在 TiDB 配置文件 `experimental` 部分设置 `allow-auto-random = true`。该参数详情可参见 [`allow-auto-random`](/dev/reference/configuration/tidb-server/configuration-file.md#allow-auto-random)。 +使用 `AUTO_RANDOM` 功能前，须在 TiDB 配置文件 `experimental` 部分设置 `allow-auto-random = true`。该参数详情可参见 [`allow-auto-random`](/reference/configuration/tidb-server/configuration-file.md#allow-auto-random)。 ## 使用场景 -`AUTO_RANDOM` 用于解决大批量写数据入 TiDB 时因含有**整型自增主键列**的表而产生的热点问题。详情参阅 [TiDB 高并发写入场景最佳实践](/dev/reference/best-practices/high-concurrency.md)。 +`AUTO_RANDOM` 用于解决大批量写数据入 TiDB 时因含有**整型自增主键列**的表而产生的热点问题。详情参阅 [TiDB 高并发写入场景最佳实践](/reference/best-practices/high-concurrency.md)。 以下面语句建立的表为例： diff --git a/v3.1/reference/sql/attributes/auto-random.md b/v3.1/reference/sql/attributes/auto-random.md deleted file mode 100644 index 7034a02a2f1c..000000000000 --- a/v3.1/reference/sql/attributes/auto-random.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: AUTO_RANDOM -category: reference ---- - -# AUTO_RANDOM 从 v3.1.0 版本开始引入 - -> **警告：** -> -> 当前 `AUTO_RANDOM` 属性为实验功能，**不建议在生产环境中使用**。在后续版本中，`AUTO_RANDOM` 的语法或语义可能会变化。 - -使用 `AUTO_RANDOM` 功能前，须在 TiDB 配置文件 `experimental` 部分设置 `allow-auto-random = true`。该参数详情可参见 [`allow-auto-random`](/v3.1/reference/configuration/tidb-server/configuration-file.md#allow-auto-random)。 - -## 使用场景 - -`AUTO_RANDOM` 用于解决大批量写数据入 TiDB 时因含有**整型自增主键列**的表而产生的热点问题。详情参阅 [TiDB 高并发写入场景最佳实践](/v3.1/reference/best-practices/high-concurrency.md)。 - -以下面语句建立的表为例： - -```sql -create table t (a int 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 int primary key auto_random, b varchar(255)) -``` - -或者 - -{{< copyable "sql" >}} - -```sql -create table t (a int auto_random, b varchar(255), primary key (a)) -``` - -此时再执行形如 `INSERT INTO t(b) values...` 的 `INSERT` 语句， - -+ 如果该 `INSERT` 语句没有指定整型主键列（`a` 列）的值，TiDB 会为该列自动分配值。该值不保证自增，不保证连续，只保证唯一，避免了连续的行 ID 带来的热点问题。 -+ 如果该 `INSERT` 语句显式指定了整型主键列的值，和 `AUTO_INCREMENT` 属性类似，TiDB 会原封不动地保存该值。 - -自动分配值的计算方式如下： - -该行值在二进制形式下的最高 5 位（称为 shard bits）由当前事务的开始时间决定，剩下的位数按照自增的顺序分配。 - -如果希望使用一个不同的 shard bits 的数量，可以在 `AUTO_RANDOM` 后面加一对括号，并在括号中指定，例如： - -{{< copyable "sql" >}} - -```sql -create table t (a int primary key auto_random(3), b varchar(255)) -``` - -以上建表语句中，shard bits 的数量为 `3`。shard bits 的数量的取值范围是 `[1, field_max_bits)`，其中 `field_max_bits` 为整型主键列类型占用的位长度。 - -含有 `AUTO_RANDOM` 属性的表在 `information_schema.tables` 中 `TIDB_ROW_ID_SHARDING_INFO` 一列的值为 `PK_AUTO_RANDOM_BITS=x`，其中 `x` 为 shard bits 的数量。 - -## 兼容性 - -TiDB 支持解析版本注释语法。示例如下： - -{{< copyable "sql" >}} - -```sql -create table t (a int primary key /*T!30100 auto_random */) -``` - -{{< copyable "sql" >}} - -```sql -create table t (a int primary key auto_random) -``` - -以上两个语句含义相同。 - -在 `show create table` 的结果中，`AUTO_RANDOM` 属性会被注释掉。注释会附带一个版本号，例如 `/*T!30100 auto_random */`。其中 `30100` 表示 v3.1.0 引入该功能，低版本的 TiDB 能够忽略带有上述注释的 `AUTO_RANDOM` 属性。 - -该功能支持向前兼容，即降级兼容。v3.1.0 以前的 TiDB 会忽略表（带有上述注释）的 `AUTO_RANDOM` 属性，因此能够使用含有该属性的表。 - -## 使用限制 - -目前在 TiDB 中使用 `AUTO_RANDOM` 有以下限制： - -- 该属性必须指定在整数类型的主键列上，否则会报错。例外情况见[关于 `alter-primary-key` 配置项的说明](#关于-alter-primary-key-配置项的说明)。 -- 不支持使用 `ALTER TABLE` 来修改 `AUTO_RANDOM` 属性，包括添加或移除该属性。 -- 不支持修改含有 `AUTO_RANDOM` 属性的主键列的列类型。 -- 不支持与 `AUTO_INCREMENT` 同时指定在同一列上。 -- 不支持与列的默认值 `DEFAULT` 同时指定在同一列上。 -- 插入数据时，不建议自行显式指定含有 `AUTO_RANDOM` 列的值。不恰当地显式赋值，可能会导致该表提前耗尽用于自动分配的数值。因为用于保证唯一性的 rebase 仅针对除 shard bits 以外的位进行。 - -### 关于 `alter-primary-key` 配置项的说明 - -- 当 `alter-primary-key = true` 时，即使是整型主键列，也不支持使用 `AUTO_RANDOM`。 -- 配置文件中的 `alter-primary-key` 和 `allow-auto-random` 两个配置项的值不允许同时为 `true`。