From f40c5c11303973a7d5677b23f2fab42226136b80 Mon Sep 17 00:00:00 2001 From: ireneontheway Date: Thu, 9 Jul 2020 20:06:40 +0800 Subject: [PATCH 01/19] Update tidb-specific-system-variables.md --- tidb-specific-system-variables.md | 196 ++++++++++++++++++++++++++---- 1 file changed, 169 insertions(+), 27 deletions(-) diff --git a/tidb-specific-system-variables.md b/tidb-specific-system-variables.md index 8978a7859fcc2..28c648757f9dc 100644 --- a/tidb-specific-system-variables.md +++ b/tidb-specific-system-variables.md @@ -29,14 +29,6 @@ set @@global.tidb_distsql_scan_concurrency = 10 - Default value: "" - This variable is used to set the time point at which the data is read by the session. For example, when you set the variable to "2017-11-11 20:20:20" or a TSO number like "400036290571534337", the current session reads the data of this moment. -### tidb_import_data - -- Scope: SESSION -- Default value: 0 -- This variable indicates whether to import data from the dump file currently. -- To speed up importing, the unique index constraint is not checked when the variable is set to 1. -- This variable is only used by Lightning. Do not modify it. - ### tidb_opt_agg_push_down - Scope: SESSION @@ -373,21 +365,6 @@ mysql> desc select count(distinct a) from test.t; - Default value: 0 - This variable is used to set whether to allow `insert`, `replace` and `update` statements to operate on the column `_tidb_rowid`. It is not allowed by default. This variable can be used only when importing data with TiDB tools. -## SHARD_ROW_ID_BITS - -For the tables with non-integer PK or without PK, TiDB uses an implicit auto-increment ROW ID. When a large number of `INSERT` operations occur, the data is written into a single Region, causing a write hot spot. - -To mitigate the hot spot issue, you can configure `SHARD_ROW_ID_BITS`. The ROW ID is scattered and the data is written into multiple different Regions. But setting an overlarge value might lead to an excessively large number of RPC requests, which increases the CPU and network overheads. - -- `SHARD_ROW_ID_BITS = 4` indicates 16 shards -- `SHARD_ROW_ID_BITS = 6` indicates 64 shards -- `SHARD_ROW_ID_BITS = 0` indicates the default 1 shard - -Usage of statements: - -- `CREATE TABLE`: `CREATE TABLE t (c int) SHARD_ROW_ID_BITS = 4;` -- `ALTER TABLE`: `ALTER TABLE t SHARD_ROW_ID_BITS = 4;` - ### tidb_row_format_version - Scope: GLOBAL @@ -396,11 +373,17 @@ Usage of statements: - If you upgrade from a TiDB version earlier than 4.0.0 to 4.0.0, the format version is not changed, and TiDB continues to use the old format of version `1` to write data to the table, which means that **only newly created clusters use the new data format by default**. - Note that modifying this variable does not affect the old data that has been saved, but applies the corresponding version format only to the newly written data after modifying this variable. +### tidb_enable_slow_log + +- Scope: SESSION +- Default value: `1` +- This variable is used to control whether to enable the slow log feature. It is enabled by default. + ### tidb_record_plan_in_slow_log - Scope: SESSION - Default value: `1` -- Controls whether to include the execution plan of slow queries in the slow log. +- This variable is used to control whether to include the execution plan of slow queries in the slow log. ## tidb_slow_log_threshold @@ -563,8 +546,38 @@ set tidb_query_log_max_len = 20 ### tidb_enable_stmt_summary New in v3.0.4 - Scope: SESSION | GLOBAL -- Default value: 0 -- This variable is used to enable or disable the statement summary feature. If enabled, SQL execution information like time consumption is recorded to the `performance_schema.events_statements_summary_by_digest` table to identify and troubleshoot SQL performance issues. +- Default value: 1 (the value of the default configuration file) +- This variable is used to control whether to enable the statement summary feature. If enabled, SQL execution information like time consumption is recorded to the `performance_schema.events_statements_summary_by_digest` table to identify and troubleshoot SQL performance issues. + +### tidb_stmt_summary_internal_query New in v4.0 + +- Scope: SESSION | GLOBAL +- Default value: 0 (the value of the default configuration file) +- This variable is used to control whether to include the SQL information of TiDB in the statement summary. + +### tidb_stmt_summary_refresh_interval New in v4.0 + +- Scope: SESSION | GLOBAL +- Default value: 1800 (the value of the default configuration file) +- This variable is used to set the refresh time of the statement summary. The unit is second. + +### tidb_stmt_summary_history_size New in v4.0 + +- Scope: SESSION | GLOBAL +- Default value: 24 (the value of the default configuration file) +- This variable is used to set the history capacity of the statement summary. + +### tidb_stmt_summary_max_stmt_count New in v4.0 + +- Scope: SESSION | GLOBAL +- Default value: 200 (the value of the default configuration file) +- This variable is used to set the maximum number of the statement that the statement summary holds in memory. + +### tidb_stmt_summary_max_sql_length New in v4.0 + +- Scope: SESSION | GLOBAL +- Default value: 4096 (the value of the default configuration file) +- This variable is used to control the length of the SQL string in the statement summary. ### tidb_enable_chunk_rpc New in v4.0 @@ -578,6 +591,81 @@ set tidb_query_log_max_len = 20 - Default value: 0 - This variable is used to show whether the execution plan used in the previous `execute` statement is taken directly from the plan cache. +### ddl_slow_threshold + +- Scope:SESSION +- Default value:300 +- Ddl operations will be output to the log if its time consumption exceeds the threshold value. The unit is millisecond. + +### tidb_pprof_sql_cpu New in v4.0 + +- Scope:SESSION +- Default value:0 +- This variable is used to control whether to mark the corresponding SQL statement in the profile output to identify and troubleshoot performance issues. + +### tidb_skip_isolation_level_check + +- Scope:SESSION +- Default value:0 +- After this switch is enabled, if an isolation level not supported by TiDB is assigned to `tx_isolation`, no error will be reported. + + +### tidb_low_resolution_tso + +- Scope:SESSION +- Default value:0 +- This variable is used to set whether to enable the low precision tso feature. After this feature is enabled, new transactions will use a ts updated every 2s to read data +- The main scenario is to reduce the overhead of acquiring tso for small read-only transactions when old data can be tolerated. + +### tidb_replica_read New in v4.0 + +- Scope:SESSION +- Default value: leader +- This variable is used to control where TiDB reads data. Here are three options: + - leader: Read only from leader node + - follower: Read only from follower node + - leader-and-follower: Read from leader or follower node + +### tidb_use_plan_baselines New in v4.0 + +- Scope:SESSION | GLOBAL +- Default value: on +- This variable is used to control whether to enable the execution plan binding feature. It is enabled by default, and can be disabled by assigning the value off. For the use of the execution plan binding, see [Execution Plan Binding](/execution-plan-binding.md#创建绑定). + +### tidb_capture_plan_baselines New in v4.0 + +- Scope:SESSION | GLOBAL +- Default value: off +- This variable is used to control whether to enable the automatic binding feature. This feature depends on the Statement Summary, so you need to turn on the Statement Summary before using automatic binding. +- After this feature is enabled, the historical SQL statements in the Statement Summary will be traversed periodically, and bindings will be automatically created for SQL statements that appear at least twice. + +### tidb_evolve_plan_baselines New in v4.0 + +- Scope:SESSION | GLOBAL +- Default value: off +- This variable is used to control whether to enable the baseline evolution feature. For more details, see [Baseline Evolution](/execution-plan-binding.md#自动演进绑定). +- To reduce the impact of automatic evolution on the cluster, use the following configurations: + - Set `tidb_evolve_plan_task_max_time` to limit the maximum execution time of each execution plan.The default value is 600s + - Set `tidb_evolve_plan_task_start_time` and `tidb_evolve_plan_task_end_time` to limit the time window. The default values are respectively `00:00 +0000` and `23:59 +0000`. + +### tidb_evolve_plan_task_max_time New in v4.0 + +- Scope:GLOBAL +- Default value:600 +- This variable is used to limit the maximum execution time of each execution plan in the baseline evolution feature.The unit is second. + +### tidb_evolve_plan_task_start_time New in v4.0 + +- Scope:GLOBAL +- Default value:00:00 +0000 +- This variable is used to set the start time of automatic evolution in a day. + +### tidb_evolve_plan_task_end_time New in v4.0 + +- Scope:GLOBAL +- Default value:23:59 +0000 +- This variable is used to set the end time of automatic evolution in a day. + ### tidb_allow_batch_cop New in v4.0 version - Scope: SESSION | GLOBAL @@ -588,8 +676,62 @@ set tidb_query_log_max_len = 20 * `1`: Aggregation and join requests are sent in batches * `2`: All coprocessor requests are sent in batches +### tidb_enable_cascades_planner + +- Scope:SESSION | GLOBAL +- Default value: 0 +- This variable is used to control whether to enabled the cascades planner feature. + +### tidb_window_concurrency New in v4.0 + +- Scope:SESSION | GLOBAL +- Default value: 4 +- This variable is used to set the concurrency degree of the window operator. + +### tidb_enable_vectorized_expression New in v4.0 + +- Scope:SESSION | GLOBAL +- Default value: 1 +- This variable is used to control whether to enable vectorized execution. + +### tidb_enable_index_merge New in v4.0 + +- Scope:SESSION | GLOBAL +- Default value: 0 +- This variable is used to control whether to enable the index merge feature. + +### tidb_enable_noop_functions New in v4.0 + +- Scope:SESSION | GLOBAL +- Default value: 0 +- This variable is used to control whether to enable `get_lock` and `release_lock` functions. These two functions are not implemented, and always return 1 in the current version of TiDB,. + +### tidb_isolation_read_engines New in v4.0 + +- Scope:SESSION +- Default value: tikv, tiflash, tidb +- This variable is used to set the storage engine list that TiDB can use when reading data. + +### tidb_store_limit New in v3.0.4 and v4.0 + +- Scope:SESSION | GLOBAL +- Default value: 0 +- This variable is used to limit the maximum number of requests TiDB can send to TiKV at the same time. 0 means no limit. + +### tidb_metric_query_step New in v4.0 + +- Scope:SESSION +- Default value: 60 +- This variable is used to set the step of the Prometheus statement generated when querying METRIC_SCHEMA. The unit is second. + +### tidb_metric_query_range_duration New in v4.0 + +- Scope:SESSION +- Default value: 60 +- This variable is used to set the range duration of the Prometheus statement generated when querying METRIC_SCHEMA. The unit is second. + ### tidb_enable_telemetry New in v4.0.2 version - Scope: GLOBAL - Default value: 1 -- This variable dynamically controls whether the telemetry collection in TiDB is enabled. By setting the value to `0`, the telemetry collection is disabled. If the [`enable-telemetry`](/tidb-configuration-file.md#enable-telemetry-new-in-v402) TiDB configuration item is set to `false` on all TiDB instances, the telemetry collection is always disabled and this system variable will not take effect. See [Telemetry](/telemetry.md) for details. +- This variable is used to dynamically control whether the telemetry collection in TiDB is enabled. By setting the value to `0`, the telemetry collection is disabled. If the [`enable-telemetry`](/tidb-configuration-file.md#enable-telemetry-new-in-v402) TiDB configuration item is set to `false` on all TiDB instances, the telemetry collection is always disabled and this system variable will not take effect. See [Telemetry](/telemetry.md) for details. From ffac826fb8b94a095a9034e63e86279d0d266487 Mon Sep 17 00:00:00 2001 From: ireneontheway Date: Fri, 10 Jul 2020 10:55:08 +0800 Subject: [PATCH 02/19] Update tidb-specific-system-variables.md adjust the format of markdown --- tidb-specific-system-variables.md | 68 +++++++++++++++---------------- 1 file changed, 33 insertions(+), 35 deletions(-) diff --git a/tidb-specific-system-variables.md b/tidb-specific-system-variables.md index 28c648757f9dc..09a459f851033 100644 --- a/tidb-specific-system-variables.md +++ b/tidb-specific-system-variables.md @@ -307,9 +307,9 @@ mysql> desc select count(distinct a) from test.t; - Scope: SESSION | GLOBAL - Default value: "on" - This variable is used to set whether to enable the `TABLE PARTITION` feature. - - `off` indicates disabling the `TABLE PARTITION` feature. In this case, the syntax that creates a partition table can be executed, but the table created is not a partitioned one. - - `on` indicates enabling the `TABLE PARTITION` feature for the supported partition types. Currently, it indicates enabling range partition, hash partition and range column partition with one single column. - - `auto` functions the same way as `on` does. + - `off` indicates disabling the `TABLE PARTITION` feature. In this case, the syntax that creates a partition table can be executed, but the table created is not a partitioned one. + - `on` indicates enabling the `TABLE PARTITION` feature for the supported partition types. Currently, it indicates enabling range partition, hash partition and range column partition with one single column. + - `auto` functions the same way as `on` does. - Currently, TiDB only supports range partition and hash partition. @@ -330,8 +330,8 @@ mysql> desc select count(distinct a) from test.t; - Scope: GLOBAL - Default value: 256 - This variable is used to set the batch size during the `re-organize` phase of the DDL operation. For example, when TiDB executes the `ADD INDEX` operation, the index data needs to backfilled by `tidb_ddl_reorg_worker_cnt` (the number) concurrent workers. Each worker backfills the index data in batches. - - If many updating operations such as `UPDATE` and `REPLACE` exist during the `ADD INDEX` operation, a larger batch size indicates a larger probability of transaction conflicts. In this case, you need to adjust the batch size to a smaller value. The minimum value is 32. - - If the transaction conflict does not exist, you can set the batch size to a large value. The maximum value is 10240. This can increase the speed of the backfilling data, but the write pressure on TiKV also becomes higher. + - If many updating operations such as `UPDATE` and `REPLACE` exist during the `ADD INDEX` operation, a larger batch size indicates a larger probability of transaction conflicts. In this case, you need to adjust the batch size to a smaller value. The minimum value is 32. + - If the transaction conflict does not exist, you can set the batch size to a large value. The maximum value is 10240. This can increase the speed of the backfilling data, but the write pressure on TiKV also becomes higher. ### tidb_ddl_reorg_priority @@ -423,27 +423,26 @@ set tidb_query_log_max_len = 20 - Default value: 0 - TiDB supports the optimistic transaction model. This means that conflict check (unique key check) is performed when the transaction is committed. This variable is used to set whether to do a unique key check each time a row of data is written. - If this variable is enabled, the performance might be affected in a scenario where a large batch of data is written. For example: + - When this variable is disabled: - - When this variable is disabled: - - ```sql - tidb >create table t (i int key) - tidb >insert into t values (1); - tidb >begin - tidb >insert into t values (1); - Query OK, 1 row affected - tidb >commit; -- Check only when a transaction is committed. - ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' - ``` + ```sql + tidb >create table t (i int key) + tidb >insert into t values (1); + tidb >begin + tidb >insert into t values (1); + Query OK, 1 row affected + tidb >commit; -- Check only when a transaction is committed. + ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' + ``` - - After this variable is enabled: + - After this variable is enabled: - ```sql - tidb >set @@tidb_constraint_check_in_place=1 - tidb >begin - tidb >insert into t values (1); - ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' - ``` + ```sql + tidb >set @@tidb_constraint_check_in_place=1 + tidb >begin + tidb >insert into t values (1); + ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' + ``` ### tidb_check_mb4_value_in_utf8 @@ -486,10 +485,10 @@ set tidb_query_log_max_len = 20 - Scope: SESSION | GLOBAL - Default value: 1 - When the method that estimates the number of rows based on column order correlation is not available, the heuristic estimation method is used. This variable is used to control the behavior of the heuristic method. - - When the value is 0, the heuristic method is not used. - - When the value is greater than 0: - - A larger value indicates that an index scan will probably be used in the heuristic method. - - A smaller value indicates that a table scan will probably be used in the heuristic method. + - When the value is 0, the heuristic method is not used. + - When the value is greater than 0: + - A larger value indicates that an index scan will probably be used in the heuristic method. + - A smaller value indicates that a table scan will probably be used in the heuristic method. ### tidb_enable_window_function @@ -515,8 +514,8 @@ set tidb_query_log_max_len = 20 - Scope: SERVER - Default value: 60 - This variable is used to set the threshold value that determines whether to print expensive query logs. The unit is second. The difference between expensive query logs and slow query logs is: - - Slow logs are printed after the statement is executed. - - Expensive query logs print the statements that are being executed, with execution time exceeding the threshold value, and their related information. + - Slow logs are printed after the statement is executed. + - Expensive query logs print the statements that are being executed, with execution time exceeding the threshold value, and their related information. ### tidb_wait_split_region_finish @@ -645,8 +644,8 @@ set tidb_query_log_max_len = 20 - Default value: off - This variable is used to control whether to enable the baseline evolution feature. For more details, see [Baseline Evolution](/execution-plan-binding.md#自动演进绑定). - To reduce the impact of automatic evolution on the cluster, use the following configurations: - - Set `tidb_evolve_plan_task_max_time` to limit the maximum execution time of each execution plan.The default value is 600s - - Set `tidb_evolve_plan_task_start_time` and `tidb_evolve_plan_task_end_time` to limit the time window. The default values are respectively `00:00 +0000` and `23:59 +0000`. + - Set `tidb_evolve_plan_task_max_time` to limit the maximum execution time of each execution plan.The default value is 600s + - Set `tidb_evolve_plan_task_start_time` and `tidb_evolve_plan_task_end_time` to limit the time window. The default values are respectively `00:00 +0000` and `23:59 +0000`. ### tidb_evolve_plan_task_max_time New in v4.0 @@ -671,10 +670,9 @@ set tidb_query_log_max_len = 20 - Scope: SESSION | GLOBAL - Default value: 0 - This variable is used to control how TiDB sends a coprocessor request to TiFlash. It has the following values: - - * `0`: Never send requests in batches - * `1`: Aggregation and join requests are sent in batches - * `2`: All coprocessor requests are sent in batches + - `0`: Never send requests in batches + - `1`: Aggregation and join requests are sent in batches + - `2`: All coprocessor requests are sent in batches ### tidb_enable_cascades_planner From 165ea3df2a1db71452e0dad7427b9e96c578ed7d Mon Sep 17 00:00:00 2001 From: ireneontheway Date: Fri, 10 Jul 2020 11:02:01 +0800 Subject: [PATCH 03/19] Update tidb-specific-system-variables.md --- tidb-specific-system-variables.md | 79 +++++++++++++++---------------- 1 file changed, 39 insertions(+), 40 deletions(-) diff --git a/tidb-specific-system-variables.md b/tidb-specific-system-variables.md index 09a459f851033..1804d36e4e341 100644 --- a/tidb-specific-system-variables.md +++ b/tidb-specific-system-variables.md @@ -307,9 +307,9 @@ mysql> desc select count(distinct a) from test.t; - Scope: SESSION | GLOBAL - Default value: "on" - This variable is used to set whether to enable the `TABLE PARTITION` feature. - - `off` indicates disabling the `TABLE PARTITION` feature. In this case, the syntax that creates a partition table can be executed, but the table created is not a partitioned one. - - `on` indicates enabling the `TABLE PARTITION` feature for the supported partition types. Currently, it indicates enabling range partition, hash partition and range column partition with one single column. - - `auto` functions the same way as `on` does. + - `off` indicates disabling the `TABLE PARTITION` feature. In this case, the syntax that creates a partition table can be executed, but the table created is not a partitioned one. + - `on` indicates enabling the `TABLE PARTITION` feature for the supported partition types. Currently, it indicates enabling range partition, hash partition and range column partition with one single column. + - `auto` functions the same way as `on` does. - Currently, TiDB only supports range partition and hash partition. @@ -330,8 +330,8 @@ mysql> desc select count(distinct a) from test.t; - Scope: GLOBAL - Default value: 256 - This variable is used to set the batch size during the `re-organize` phase of the DDL operation. For example, when TiDB executes the `ADD INDEX` operation, the index data needs to backfilled by `tidb_ddl_reorg_worker_cnt` (the number) concurrent workers. Each worker backfills the index data in batches. - - If many updating operations such as `UPDATE` and `REPLACE` exist during the `ADD INDEX` operation, a larger batch size indicates a larger probability of transaction conflicts. In this case, you need to adjust the batch size to a smaller value. The minimum value is 32. - - If the transaction conflict does not exist, you can set the batch size to a large value. The maximum value is 10240. This can increase the speed of the backfilling data, but the write pressure on TiKV also becomes higher. + - If many updating operations such as `UPDATE` and `REPLACE` exist during the `ADD INDEX` operation, a larger batch size indicates a larger probability of transaction conflicts. In this case, you need to adjust the batch size to a smaller value. The minimum value is 32. + - If the transaction conflict does not exist, you can set the batch size to a large value. The maximum value is 10240. This can increase the speed of the backfilling data, but the write pressure on TiKV also becomes higher. ### tidb_ddl_reorg_priority @@ -423,26 +423,26 @@ set tidb_query_log_max_len = 20 - Default value: 0 - TiDB supports the optimistic transaction model. This means that conflict check (unique key check) is performed when the transaction is committed. This variable is used to set whether to do a unique key check each time a row of data is written. - If this variable is enabled, the performance might be affected in a scenario where a large batch of data is written. For example: - - When this variable is disabled: - - ```sql - tidb >create table t (i int key) - tidb >insert into t values (1); - tidb >begin - tidb >insert into t values (1); - Query OK, 1 row affected - tidb >commit; -- Check only when a transaction is committed. - ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' - ``` - - - After this variable is enabled: - - ```sql - tidb >set @@tidb_constraint_check_in_place=1 - tidb >begin - tidb >insert into t values (1); - ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' - ``` + - When this variable is disabled: + + ```sql + tidb >create table t (i int key) + tidb >insert into t values (1); + tidb >begin + tidb >insert into t values (1); + Query OK, 1 row affected + tidb >commit; -- Check only when a transaction is committed. + ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' + ``` + + - After this variable is enabled: + + ```sql + tidb >set @@tidb_constraint_check_in_place=1 + tidb >begin + tidb >insert into t values (1); + ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' + ``` ### tidb_check_mb4_value_in_utf8 @@ -485,10 +485,10 @@ set tidb_query_log_max_len = 20 - Scope: SESSION | GLOBAL - Default value: 1 - When the method that estimates the number of rows based on column order correlation is not available, the heuristic estimation method is used. This variable is used to control the behavior of the heuristic method. - - When the value is 0, the heuristic method is not used. - - When the value is greater than 0: - - A larger value indicates that an index scan will probably be used in the heuristic method. - - A smaller value indicates that a table scan will probably be used in the heuristic method. + - When the value is 0, the heuristic method is not used. + - When the value is greater than 0: + - A larger value indicates that an index scan will probably be used in the heuristic method. + - A smaller value indicates that a table scan will probably be used in the heuristic method. ### tidb_enable_window_function @@ -514,8 +514,8 @@ set tidb_query_log_max_len = 20 - Scope: SERVER - Default value: 60 - This variable is used to set the threshold value that determines whether to print expensive query logs. The unit is second. The difference between expensive query logs and slow query logs is: - - Slow logs are printed after the statement is executed. - - Expensive query logs print the statements that are being executed, with execution time exceeding the threshold value, and their related information. + - Slow logs are printed after the statement is executed. + - Expensive query logs print the statements that are being executed, with execution time exceeding the threshold value, and their related information. ### tidb_wait_split_region_finish @@ -608,7 +608,6 @@ set tidb_query_log_max_len = 20 - Default value:0 - After this switch is enabled, if an isolation level not supported by TiDB is assigned to `tx_isolation`, no error will be reported. - ### tidb_low_resolution_tso - Scope:SESSION @@ -621,9 +620,9 @@ set tidb_query_log_max_len = 20 - Scope:SESSION - Default value: leader - This variable is used to control where TiDB reads data. Here are three options: - - leader: Read only from leader node - - follower: Read only from follower node - - leader-and-follower: Read from leader or follower node + - leader: Read only from leader node + - follower: Read only from follower node + - leader-and-follower: Read from leader or follower node ### tidb_use_plan_baselines New in v4.0 @@ -644,8 +643,8 @@ set tidb_query_log_max_len = 20 - Default value: off - This variable is used to control whether to enable the baseline evolution feature. For more details, see [Baseline Evolution](/execution-plan-binding.md#自动演进绑定). - To reduce the impact of automatic evolution on the cluster, use the following configurations: - - Set `tidb_evolve_plan_task_max_time` to limit the maximum execution time of each execution plan.The default value is 600s - - Set `tidb_evolve_plan_task_start_time` and `tidb_evolve_plan_task_end_time` to limit the time window. The default values are respectively `00:00 +0000` and `23:59 +0000`. + - Set `tidb_evolve_plan_task_max_time` to limit the maximum execution time of each execution plan.The default value is 600s + - Set `tidb_evolve_plan_task_start_time` and `tidb_evolve_plan_task_end_time` to limit the time window. The default values are respectively `00:00 +0000` and `23:59 +0000`. ### tidb_evolve_plan_task_max_time New in v4.0 @@ -670,9 +669,9 @@ set tidb_query_log_max_len = 20 - Scope: SESSION | GLOBAL - Default value: 0 - This variable is used to control how TiDB sends a coprocessor request to TiFlash. It has the following values: - - `0`: Never send requests in batches - - `1`: Aggregation and join requests are sent in batches - - `2`: All coprocessor requests are sent in batches + - `0`: Never send requests in batches + - `1`: Aggregation and join requests are sent in batches + - `2`: All coprocessor requests are sent in batches ### tidb_enable_cascades_planner From 945074c3018dcacb1969347de9b918653fca02fb Mon Sep 17 00:00:00 2001 From: ireneontheway Date: Fri, 10 Jul 2020 11:05:30 +0800 Subject: [PATCH 04/19] Update tidb-specific-system-variables.md --- tidb-specific-system-variables.md | 1 - 1 file changed, 1 deletion(-) diff --git a/tidb-specific-system-variables.md b/tidb-specific-system-variables.md index 1804d36e4e341..261c7e020d23f 100644 --- a/tidb-specific-system-variables.md +++ b/tidb-specific-system-variables.md @@ -609,7 +609,6 @@ set tidb_query_log_max_len = 20 - After this switch is enabled, if an isolation level not supported by TiDB is assigned to `tx_isolation`, no error will be reported. ### tidb_low_resolution_tso - - Scope:SESSION - Default value:0 - This variable is used to set whether to enable the low precision tso feature. After this feature is enabled, new transactions will use a ts updated every 2s to read data From d6eb450884f3658b54f9b8b674b575dbf3e1bd3f Mon Sep 17 00:00:00 2001 From: ireneontheway Date: Fri, 10 Jul 2020 11:07:44 +0800 Subject: [PATCH 05/19] Update tidb-specific-system-variables.md --- tidb-specific-system-variables.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tidb-specific-system-variables.md b/tidb-specific-system-variables.md index 261c7e020d23f..e691896b9d095 100644 --- a/tidb-specific-system-variables.md +++ b/tidb-specific-system-variables.md @@ -487,8 +487,8 @@ set tidb_query_log_max_len = 20 - When the method that estimates the number of rows based on column order correlation is not available, the heuristic estimation method is used. This variable is used to control the behavior of the heuristic method. - When the value is 0, the heuristic method is not used. - When the value is greater than 0: - - A larger value indicates that an index scan will probably be used in the heuristic method. - - A smaller value indicates that a table scan will probably be used in the heuristic method. + - A larger value indicates that an index scan will probably be used in the heuristic method. + - A smaller value indicates that a table scan will probably be used in the heuristic method. ### tidb_enable_window_function @@ -609,6 +609,7 @@ set tidb_query_log_max_len = 20 - After this switch is enabled, if an isolation level not supported by TiDB is assigned to `tx_isolation`, no error will be reported. ### tidb_low_resolution_tso + - Scope:SESSION - Default value:0 - This variable is used to set whether to enable the low precision tso feature. After this feature is enabled, new transactions will use a ts updated every 2s to read data From b79d6611e9caea089b747a271fe1a449f5f98243 Mon Sep 17 00:00:00 2001 From: yikeke Date: Fri, 10 Jul 2020 11:57:52 +0800 Subject: [PATCH 06/19] fix indent --- tidb-specific-system-variables.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/tidb-specific-system-variables.md b/tidb-specific-system-variables.md index e691896b9d095..7b540e35d8d6d 100644 --- a/tidb-specific-system-variables.md +++ b/tidb-specific-system-variables.md @@ -423,26 +423,27 @@ set tidb_query_log_max_len = 20 - Default value: 0 - TiDB supports the optimistic transaction model. This means that conflict check (unique key check) is performed when the transaction is committed. This variable is used to set whether to do a unique key check each time a row of data is written. - If this variable is enabled, the performance might be affected in a scenario where a large batch of data is written. For example: + - When this variable is disabled: - ```sql - tidb >create table t (i int key) - tidb >insert into t values (1); - tidb >begin - tidb >insert into t values (1); - Query OK, 1 row affected - tidb >commit; -- Check only when a transaction is committed. - ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' - ``` + ```sql + tidb >create table t (i int key) + tidb >insert into t values (1); + tidb >begin + tidb >insert into t values (1); + Query OK, 1 row affected + tidb >commit; -- Check only when a transaction is committed. + ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' + ``` - After this variable is enabled: - ```sql - tidb >set @@tidb_constraint_check_in_place=1 - tidb >begin - tidb >insert into t values (1); - ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' - ``` + ```sql + tidb >set @@tidb_constraint_check_in_place=1 + tidb >begin + tidb >insert into t values (1); + ERROR 1062 : Duplicate entry '1' for key 'PRIMARY' + ``` ### tidb_check_mb4_value_in_utf8 From 9eb59928ba1bc2261f4bd727a9d9dc6ef9edf1c5 Mon Sep 17 00:00:00 2001 From: ireneontheway <48651140+ireneontheway@users.noreply.github.com> Date: Fri, 10 Jul 2020 13:09:56 +0800 Subject: [PATCH 07/19] Apply suggestions from code review Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com> --- tidb-specific-system-variables.md | 58 +++++++++++++++---------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/tidb-specific-system-variables.md b/tidb-specific-system-variables.md index 7b540e35d8d6d..d39742be9e6d5 100644 --- a/tidb-specific-system-variables.md +++ b/tidb-specific-system-variables.md @@ -547,7 +547,7 @@ set tidb_query_log_max_len = 20 - Scope: SESSION | GLOBAL - Default value: 1 (the value of the default configuration file) -- This variable is used to control whether to enable the statement summary feature. If enabled, SQL execution information like time consumption is recorded to the `performance_schema.events_statements_summary_by_digest` table to identify and troubleshoot SQL performance issues. +- This variable is used to control whether to enable the statement summary feature. If enabled, SQL execution information like time consumption is recorded to the `performance_schema.events_statements_summary_by_digest` system table to identify and troubleshoot SQL performance issues. ### tidb_stmt_summary_internal_query New in v4.0 @@ -571,7 +571,7 @@ set tidb_query_log_max_len = 20 - Scope: SESSION | GLOBAL - Default value: 200 (the value of the default configuration file) -- This variable is used to set the maximum number of the statement that the statement summary holds in memory. +- This variable is used to set the maximum number of statements that the statement summary stores in memory. ### tidb_stmt_summary_max_sql_length New in v4.0 @@ -593,32 +593,32 @@ set tidb_query_log_max_len = 20 ### ddl_slow_threshold -- Scope:SESSION -- Default value:300 -- Ddl operations will be output to the log if its time consumption exceeds the threshold value. The unit is millisecond. +- Scope: SESSION +- Default value: 300 +- DDL operations whose execution time exceeds the threshold value are output to the log. The unit is millisecond. ### tidb_pprof_sql_cpu New in v4.0 -- Scope:SESSION -- Default value:0 +- Scope: SESSION +- Default value: 0 - This variable is used to control whether to mark the corresponding SQL statement in the profile output to identify and troubleshoot performance issues. ### tidb_skip_isolation_level_check -- Scope:SESSION -- Default value:0 -- After this switch is enabled, if an isolation level not supported by TiDB is assigned to `tx_isolation`, no error will be reported. +- Scope: SESSION +- Default value: 0 +- After this switch is enabled, if an isolation level unsupported by TiDB is assigned to `tx_isolation`, no error is reported. ### tidb_low_resolution_tso -- Scope:SESSION -- Default value:0 -- This variable is used to set whether to enable the low precision tso feature. After this feature is enabled, new transactions will use a ts updated every 2s to read data -- The main scenario is to reduce the overhead of acquiring tso for small read-only transactions when old data can be tolerated. +- Scope: SESSION +- Default value: 0 +- This variable is used to set whether to enable the low precision TSO feature. After this feature is enabled, new transactions use a timestamp updated every 2 seconds to read data. +- The main applicable scenario is to reduce the overhead of acquiring TSO for small read-only transactions when reading old data is acceptable. ### tidb_replica_read New in v4.0 -- Scope:SESSION +- Scope: SESSION - Default value: leader - This variable is used to control where TiDB reads data. Here are three options: - leader: Read only from leader node @@ -627,43 +627,43 @@ set tidb_query_log_max_len = 20 ### tidb_use_plan_baselines New in v4.0 -- Scope:SESSION | GLOBAL +- Scope: SESSION | GLOBAL - Default value: on -- This variable is used to control whether to enable the execution plan binding feature. It is enabled by default, and can be disabled by assigning the value off. For the use of the execution plan binding, see [Execution Plan Binding](/execution-plan-binding.md#创建绑定). +- This variable is used to control whether to enable the execution plan binding feature. It is enabled by default, and can be disabled by assigning the `off` value. For the use of the execution plan binding, see [Execution Plan Binding](/sql-plan-management.md#create-a-binding). ### tidb_capture_plan_baselines New in v4.0 -- Scope:SESSION | GLOBAL +- Scope: SESSION | GLOBAL - Default value: off -- This variable is used to control whether to enable the automatic binding feature. This feature depends on the Statement Summary, so you need to turn on the Statement Summary before using automatic binding. -- After this feature is enabled, the historical SQL statements in the Statement Summary will be traversed periodically, and bindings will be automatically created for SQL statements that appear at least twice. +- This variable is used to control whether to enable the [baseline capturing](/sql-plan-management.md#baseline-capturing) feature. This feature depends on the statement summary, so you need to enable the statement summary before you use baseline capturing. +- After this feature is enabled, the historical SQL statements in the statement summary are traversed periodically, and bindings are automatically created for SQL statements that appear at least twice. ### tidb_evolve_plan_baselines New in v4.0 -- Scope:SESSION | GLOBAL +- Scope: SESSION | GLOBAL - Default value: off -- This variable is used to control whether to enable the baseline evolution feature. For more details, see [Baseline Evolution](/execution-plan-binding.md#自动演进绑定). -- To reduce the impact of automatic evolution on the cluster, use the following configurations: - - Set `tidb_evolve_plan_task_max_time` to limit the maximum execution time of each execution plan.The default value is 600s +- This variable is used to control whether to enable the baseline evolution feature. For detailed introduction or usage , see [Baseline Evolution](/sql-plan-management.md#baseline-evolution). +- To reduce the impact of baseline evolution on the cluster, use the following configurations: + - Set `tidb_evolve_plan_task_max_time` to limit the maximum execution time of each execution plan. The default value is 600s. - Set `tidb_evolve_plan_task_start_time` and `tidb_evolve_plan_task_end_time` to limit the time window. The default values are respectively `00:00 +0000` and `23:59 +0000`. ### tidb_evolve_plan_task_max_time New in v4.0 - Scope:GLOBAL - Default value:600 -- This variable is used to limit the maximum execution time of each execution plan in the baseline evolution feature.The unit is second. +- This variable is used to limit the maximum execution time of each execution plan in the baseline evolution feature. The unit is second. ### tidb_evolve_plan_task_start_time New in v4.0 - Scope:GLOBAL - Default value:00:00 +0000 -- This variable is used to set the start time of automatic evolution in a day. +- This variable is used to set the start time of baseline evolution in a day. ### tidb_evolve_plan_task_end_time New in v4.0 - Scope:GLOBAL - Default value:23:59 +0000 -- This variable is used to set the end time of automatic evolution in a day. +- This variable is used to set the end time of baseline evolution in a day. ### tidb_allow_batch_cop New in v4.0 version @@ -678,7 +678,7 @@ set tidb_query_log_max_len = 20 - Scope:SESSION | GLOBAL - Default value: 0 -- This variable is used to control whether to enabled the cascades planner feature. +- This variable is used to control whether to enable the cascades planner feature. ### tidb_window_concurrency New in v4.0 @@ -702,7 +702,7 @@ set tidb_query_log_max_len = 20 - Scope:SESSION | GLOBAL - Default value: 0 -- This variable is used to control whether to enable `get_lock` and `release_lock` functions. These two functions are not implemented, and always return 1 in the current version of TiDB,. +- This variable is used to control whether to enable `get_lock` and `release_lock` functions. These two functions are not implemented, and always return 1 in the current version of TiDB. ### tidb_isolation_read_engines New in v4.0 From 0ace8d806bebe6c2d4f62348efdf2c180a6c8444 Mon Sep 17 00:00:00 2001 From: ireneontheway Date: Fri, 10 Jul 2020 13:20:02 +0800 Subject: [PATCH 08/19] Update tidb-specific-system-variables.md add space --- tidb-specific-system-variables.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/tidb-specific-system-variables.md b/tidb-specific-system-variables.md index d39742be9e6d5..1f399c3a723e1 100644 --- a/tidb-specific-system-variables.md +++ b/tidb-specific-system-variables.md @@ -649,19 +649,19 @@ set tidb_query_log_max_len = 20 ### tidb_evolve_plan_task_max_time New in v4.0 -- Scope:GLOBAL +- Scope: GLOBAL - Default value:600 - This variable is used to limit the maximum execution time of each execution plan in the baseline evolution feature. The unit is second. ### tidb_evolve_plan_task_start_time New in v4.0 -- Scope:GLOBAL +- Scope: GLOBAL - Default value:00:00 +0000 - This variable is used to set the start time of baseline evolution in a day. ### tidb_evolve_plan_task_end_time New in v4.0 -- Scope:GLOBAL +- Scope: GLOBAL - Default value:23:59 +0000 - This variable is used to set the end time of baseline evolution in a day. @@ -676,55 +676,55 @@ set tidb_query_log_max_len = 20 ### tidb_enable_cascades_planner -- Scope:SESSION | GLOBAL +- Scope: SESSION | GLOBAL - Default value: 0 - This variable is used to control whether to enable the cascades planner feature. ### tidb_window_concurrency New in v4.0 -- Scope:SESSION | GLOBAL +- Scope: SESSION | GLOBAL - Default value: 4 - This variable is used to set the concurrency degree of the window operator. ### tidb_enable_vectorized_expression New in v4.0 -- Scope:SESSION | GLOBAL +- Scope: SESSION | GLOBAL - Default value: 1 - This variable is used to control whether to enable vectorized execution. ### tidb_enable_index_merge New in v4.0 -- Scope:SESSION | GLOBAL +- Scope: SESSION | GLOBAL - Default value: 0 - This variable is used to control whether to enable the index merge feature. ### tidb_enable_noop_functions New in v4.0 -- Scope:SESSION | GLOBAL +- Scope: SESSION | GLOBAL - Default value: 0 - This variable is used to control whether to enable `get_lock` and `release_lock` functions. These two functions are not implemented, and always return 1 in the current version of TiDB. ### tidb_isolation_read_engines New in v4.0 -- Scope:SESSION +- Scope: SESSION - Default value: tikv, tiflash, tidb - This variable is used to set the storage engine list that TiDB can use when reading data. ### tidb_store_limit New in v3.0.4 and v4.0 -- Scope:SESSION | GLOBAL +- Scope: SESSION | GLOBAL - Default value: 0 - This variable is used to limit the maximum number of requests TiDB can send to TiKV at the same time. 0 means no limit. ### tidb_metric_query_step New in v4.0 -- Scope:SESSION +- Scope: SESSION - Default value: 60 - This variable is used to set the step of the Prometheus statement generated when querying METRIC_SCHEMA. The unit is second. ### tidb_metric_query_range_duration New in v4.0 -- Scope:SESSION +- Scope: SESSION - Default value: 60 - This variable is used to set the range duration of the Prometheus statement generated when querying METRIC_SCHEMA. The unit is second. From d1c7d992e5da09ed35219301ea2d4668bc42b9a2 Mon Sep 17 00:00:00 2001 From: yikeke Date: Fri, 10 Jul 2020 14:46:10 +0800 Subject: [PATCH 09/19] add a space --- tidb-specific-system-variables.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tidb-specific-system-variables.md b/tidb-specific-system-variables.md index 1f399c3a723e1..362218a3dd71b 100644 --- a/tidb-specific-system-variables.md +++ b/tidb-specific-system-variables.md @@ -650,19 +650,19 @@ set tidb_query_log_max_len = 20 ### tidb_evolve_plan_task_max_time New in v4.0 - Scope: GLOBAL -- Default value:600 +- Default value: 600 - This variable is used to limit the maximum execution time of each execution plan in the baseline evolution feature. The unit is second. ### tidb_evolve_plan_task_start_time New in v4.0 - Scope: GLOBAL -- Default value:00:00 +0000 +- Default value: 00:00 +0000 - This variable is used to set the start time of baseline evolution in a day. ### tidb_evolve_plan_task_end_time New in v4.0 - Scope: GLOBAL -- Default value:23:59 +0000 +- Default value: 23:59 +0000 - This variable is used to set the end time of baseline evolution in a day. ### tidb_allow_batch_cop New in v4.0 version From 6c6881848e3f021430801aa209c41f05e1343f18 Mon Sep 17 00:00:00 2001 From: ireneontheway Date: Fri, 10 Jul 2020 15:24:03 +0800 Subject: [PATCH 10/19] Update comment-syntax.md --- comment-syntax.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/comment-syntax.md b/comment-syntax.md index f8e32adcc7c4c..2f33fac1cf4a0 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -70,7 +70,7 @@ Similar to MySQL, TiDB supports a variant of C comment style: /*! Specific code */ ``` -In this comment style, TiDB runs the statements in the comment. The syntax is used to make these SQL statements ignored in other databases and run only in TiDB. +The same as MySQL, TiDB runs the statements in the comment. For example: @@ -84,7 +84,12 @@ In TiDB, you can also use another version: SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ... ``` -If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number does not work and all contents in the comment are processed. TiDB has its own comment syntax for the version number. The format of this syntax is `/*T!30100 XXX */`. +If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number does not work and all contents in the comment are processed. + +TiDB has its own comment syntax for the version number， which can be divided into the following two types: + +* `/*T! Specific code */`: This syntax can only be parsed and executed by TiDB, and be ignored in other databases. +* `/*T![feature_id] Specific code */`: This syntax is used to ensure compatibility between different versions of TiDB. TiDB can parse the SQL fragment in this comment only if it implements the corresponding feature of `feature_id` in the current version. For example, as the `AUTO_RANDOM` feature is introduced in v3.1.1, this version can parse `/*T![auto_rand] auto_random */` into `auto_random`. While the `AUTO_RANDOM` feature is not implemented in v3.0.0, the SQL statement fragment above is ignored. Another type of comment is specially treated as the Hint optimizer: From 22612e1dcff741f366e9538e508208f048b26fed Mon Sep 17 00:00:00 2001 From: ireneontheway Date: Fri, 10 Jul 2020 15:34:35 +0800 Subject: [PATCH 11/19] Revert "Update comment-syntax.md" This reverts commit 6c6881848e3f021430801aa209c41f05e1343f18. --- comment-syntax.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/comment-syntax.md b/comment-syntax.md index 2f33fac1cf4a0..f8e32adcc7c4c 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -70,7 +70,7 @@ Similar to MySQL, TiDB supports a variant of C comment style: /*! Specific code */ ``` -The same as MySQL, TiDB runs the statements in the comment. +In this comment style, TiDB runs the statements in the comment. The syntax is used to make these SQL statements ignored in other databases and run only in TiDB. For example: @@ -84,12 +84,7 @@ In TiDB, you can also use another version: SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ... ``` -If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number does not work and all contents in the comment are processed. - -TiDB has its own comment syntax for the version number， which can be divided into the following two types: - -* `/*T! Specific code */`: This syntax can only be parsed and executed by TiDB, and be ignored in other databases. -* `/*T![feature_id] Specific code */`: This syntax is used to ensure compatibility between different versions of TiDB. TiDB can parse the SQL fragment in this comment only if it implements the corresponding feature of `feature_id` in the current version. For example, as the `AUTO_RANDOM` feature is introduced in v3.1.1, this version can parse `/*T![auto_rand] auto_random */` into `auto_random`. While the `AUTO_RANDOM` feature is not implemented in v3.0.0, the SQL statement fragment above is ignored. +If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number does not work and all contents in the comment are processed. TiDB has its own comment syntax for the version number. The format of this syntax is `/*T!30100 XXX */`. Another type of comment is specially treated as the Hint optimizer: From 1bb1b630c8f45f2e11678a187c62db9d69bf6e82 Mon Sep 17 00:00:00 2001 From: Null not nil <67764674+nullnotnil@users.noreply.github.com> Date: Fri, 10 Jul 2020 06:23:20 -0600 Subject: [PATCH 12/19] Temporarily add back SHARD_ROW_ID_BITS Allow CI to pass. --- tidb-specific-system-variables.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/tidb-specific-system-variables.md b/tidb-specific-system-variables.md index 362218a3dd71b..a17245841d3c6 100644 --- a/tidb-specific-system-variables.md +++ b/tidb-specific-system-variables.md @@ -365,6 +365,21 @@ mysql> desc select count(distinct a) from test.t; - Default value: 0 - This variable is used to set whether to allow `insert`, `replace` and `update` statements to operate on the column `_tidb_rowid`. It is not allowed by default. This variable can be used only when importing data with TiDB tools. +## SHARD_ROW_ID_BITS + +For the tables with non-integer PK or without PK, TiDB uses an implicit auto-increment ROW ID. When a large number of `INSERT` operations occur, the data is written into a single Region, causing a write hot spot. + +To mitigate the hot spot issue, you can configure `SHARD_ROW_ID_BITS`. The ROW ID is scattered and the data is written into multiple different Regions. But setting an overlarge value might lead to an excessively large number of RPC requests, which increases the CPU and network overheads. + +- `SHARD_ROW_ID_BITS = 4` indicates 16 shards +- `SHARD_ROW_ID_BITS = 6` indicates 64 shards +- `SHARD_ROW_ID_BITS = 0` indicates the default 1 shard + +Usage of statements: + +- `CREATE TABLE`: `CREATE TABLE t (c int) SHARD_ROW_ID_BITS = 4;` +- `ALTER TABLE`: `ALTER TABLE t SHARD_ROW_ID_BITS = 4;` + ### tidb_row_format_version - Scope: GLOBAL From f451f611c4ee549ced1fc51631e6dc2c469823ec Mon Sep 17 00:00:00 2001 From: ireneontheway Date: Fri, 10 Jul 2020 21:03:09 +0800 Subject: [PATCH 13/19] comment-syntax: add TiDB-specific comment syntax --- comment-syntax.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/comment-syntax.md b/comment-syntax.md index f8e32adcc7c4c..2f33fac1cf4a0 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -70,7 +70,7 @@ Similar to MySQL, TiDB supports a variant of C comment style: /*! Specific code */ ``` -In this comment style, TiDB runs the statements in the comment. The syntax is used to make these SQL statements ignored in other databases and run only in TiDB. +The same as MySQL, TiDB runs the statements in the comment. For example: @@ -84,7 +84,12 @@ In TiDB, you can also use another version: SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ... ``` -If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number does not work and all contents in the comment are processed. TiDB has its own comment syntax for the version number. The format of this syntax is `/*T!30100 XXX */`. +If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number does not work and all contents in the comment are processed. + +TiDB has its own comment syntax for the version number， which can be divided into the following two types: + +* `/*T! Specific code */`: This syntax can only be parsed and executed by TiDB, and be ignored in other databases. +* `/*T![feature_id] Specific code */`: This syntax is used to ensure compatibility between different versions of TiDB. TiDB can parse the SQL fragment in this comment only if it implements the corresponding feature of `feature_id` in the current version. For example, as the `AUTO_RANDOM` feature is introduced in v3.1.1, this version can parse `/*T![auto_rand] auto_random */` into `auto_random`. While the `AUTO_RANDOM` feature is not implemented in v3.0.0, the SQL statement fragment above is ignored. Another type of comment is specially treated as the Hint optimizer: From 3128e88613d0541acc70ec051b3a672614ffc992 Mon Sep 17 00:00:00 2001 From: ireneontheway <48651140+ireneontheway@users.noreply.github.com> Date: Mon, 13 Jul 2020 09:24:14 +0800 Subject: [PATCH 14/19] Apply suggestions from code review Co-authored-by: Null not nil <67764674+nullnotnil@users.noreply.github.com> --- comment-syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/comment-syntax.md b/comment-syntax.md index 2f33fac1cf4a0..e5574837e3135 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -84,7 +84,7 @@ In TiDB, you can also use another version: SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ... ``` -If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number does not work and all contents in the comment are processed. +If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number is ignored, resulting in `KEY_BLOCK_SIZE=1024`. TiDB has its own comment syntax for the version number， which can be divided into the following two types: From cd795c2b8ea29866a37e32d49bf18f335eb24d9d Mon Sep 17 00:00:00 2001 From: ireneontheway Date: Mon, 13 Jul 2020 11:40:29 +0800 Subject: [PATCH 15/19] Update comment-syntax.md --- comment-syntax.md | 173 +++++++++++++++++++++++++++++----------------- 1 file changed, 110 insertions(+), 63 deletions(-) diff --git a/comment-syntax.md b/comment-syntax.md index e5574837e3135..6a89bc8fb7931 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -1,76 +1,119 @@ --- title: Comment Syntax -summary: Learn about the three comment styles in TiDB. category: reference +summary: This document introduces the comment syntax supported by TiDB. aliases: ['/docs/dev/comment-syntax/','/docs/dev/reference/sql/language-structure/comment-syntax/'] --- # Comment Syntax +This document describes the comment syntax supported by TiDB. TiDB supports three comment styles: -- Use `#` to comment a line. -- Use `--` to comment a line, and this style requires at least one whitespace after `--`. -- Use `/* */` to comment a block or multiple lines. +- Use `#` to comment a line: + + {{< copyable "sql" >}} + + ```sql + SELECT 1+1; # comments + ``` + + ``` + +------+ + | 1+1 | + +------+ + | 2 | + +------+ + 1 row in set (0.00 sec) + ``` + +- Use `--` to comment a line: + + {{< copyable "sql" >}} + + ```sql + SELECT 1+1; -- comments + ``` + + ``` + +------+ + | 1+1 | + +------+ + | 2 | + +------+ + 1 row in set (0.00 sec) + ``` + +And this style requires at least one whitespace after `--`: + + {{< copyable "sql" >}} + + ```sql + SELECT 1+1--1; + ``` + + ``` + +--------+ + | 1+1--1 | + +--------+ + | 3 | + +--------+ + 1 row in set (0.01 sec) + ``` + +- Use `/* */` to comment a block or multiple lines: + + {{< copyable "sql" >}} + + ```sql + SELECT 1 /* this is an in-line comment */ + 1; + ``` + + ``` + +--------+ + | 1 + 1 | + +--------+ + | 2 | + +--------+ + 1 row in set (0.01 sec) + ``` + + {{< copyable "sql" >}} + + ```sql + SELECT 1+ + -> /* + /*> this is a + /*> multiple-line comment + /*> */ + -> 1; + ``` + + ``` + +-------+ + | 1+ + 1 | + +-------+ + | 2 | + +-------+ + 1 row in set (0.00 sec) + ``` + +## Comment syntax compatible with MySQL + +The same as MySQL, TiDB supports a variant of C comment style: -Example: - -```sql -mysql> SELECT 1+1; # This comment continues to the end of line -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) - -mysql> SELECT 1+1; -- This comment continues to the end of line -+------+ -| 1+1 | -+------+ -| 2 | -+------+ -1 row in set (0.00 sec) - -mysql> SELECT 1 /* this is an in-line comment */ + 1; -+--------+ -| 1 + 1 | -+--------+ -| 2 | -+--------+ -1 row in set (0.01 sec) - -mysql> SELECT 1+ - -> /* - /*> this is a - /*> multiple-line comment - /*> */ - -> 1; -+-------+ -| 1+ - -1 | -+-------+ -| 2 | -+-------+ -1 row in set (0.00 sec) - -mysql> SELECT 1+1--1; -+--------+ -| 1+1--1 | -+--------+ -| 3 | -+--------+ -1 row in set (0.01 sec) +``` +/*! Specific code */ ``` -Similar to MySQL, TiDB supports a variant of C comment style: +or ``` -/*! Specific code */ +/*!50110 Specific code */ ``` -The same as MySQL, TiDB runs the statements in the comment. +In this style, TiDB runs the statements in the comment. This syntax is to make these SQLs ignored in other databases and executed in TiDB. For example: @@ -86,23 +129,27 @@ SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ... If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number is ignored, resulting in `KEY_BLOCK_SIZE=1024`. +## TiDB comment syntax + TiDB has its own comment syntax for the version number， which can be divided into the following two types: * `/*T! Specific code */`: This syntax can only be parsed and executed by TiDB, and be ignored in other databases. * `/*T![feature_id] Specific code */`: This syntax is used to ensure compatibility between different versions of TiDB. TiDB can parse the SQL fragment in this comment only if it implements the corresponding feature of `feature_id` in the current version. For example, as the `AUTO_RANDOM` feature is introduced in v3.1.1, this version can parse `/*T![auto_rand] auto_random */` into `auto_random`. While the `AUTO_RANDOM` feature is not implemented in v3.0.0, the SQL statement fragment above is ignored. -Another type of comment is specially treated as the Hint optimizer: +## Optimizer comment syntax -``` -SELECT /*+ hint */ FROM ...; -``` +Another type of comment is specially treated as the Hint optimizer: -Since Hint is involved in comments like `/*+ xxx */`, the MySQL client clears the comment by default in versions earlier than 5.7.7. To use Hint in those earlier versions, add the `--comments` option when you start the client. For example: +{{< copyable "sql" >}} -``` -mysql -h 127.0.0.1 -P 4000 -uroot --comments +```sql +SELECT /*+ hint */ FROM ...; ``` For details about the optimizer hints that TiDB supports, see [Optimizer hints](/optimizer-hints.md). +> **Note** +> +> TiDB comment syntax and optimizer comment syntax in MySQL client before 5.7.7 will be cleared as comments by default. So if you need to use these two syntaxes in the old client, add the --comments option when starting the client. For example, `mysql -h 127.0.0.1 -P 4000 -uroot --comments`. + For more information, see [Comment Syntax](https://dev.mysql.com/doc/refman/5.7/en/comments.html). From 9890654499a34a913287d8007e17f035d4842972 Mon Sep 17 00:00:00 2001 From: ireneontheway Date: Mon, 13 Jul 2020 12:13:44 +0800 Subject: [PATCH 16/19] Update comment-syntax.md change markdown format --- comment-syntax.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/comment-syntax.md b/comment-syntax.md index 6a89bc8fb7931..883ddc9def188 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -43,8 +43,8 @@ TiDB supports three comment styles: +------+ 1 row in set (0.00 sec) ``` - -And this style requires at least one whitespace after `--`: + + And this style requires at least one whitespace after `--`: {{< copyable "sql" >}} From 283705c49a1227ceaa79ff2327406a9e0b198743 Mon Sep 17 00:00:00 2001 From: ireneontheway <48651140+ireneontheway@users.noreply.github.com> Date: Mon, 13 Jul 2020 17:29:38 +0800 Subject: [PATCH 17/19] Update comment-syntax.md Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com> --- comment-syntax.md | 1 - 1 file changed, 1 deletion(-) diff --git a/comment-syntax.md b/comment-syntax.md index 883ddc9def188..263f0d3cc4085 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -1,6 +1,5 @@ --- title: Comment Syntax -category: reference summary: This document introduces the comment syntax supported by TiDB. aliases: ['/docs/dev/comment-syntax/','/docs/dev/reference/sql/language-structure/comment-syntax/'] --- From f0b8d508a4074cc675feaec2119c0631e7100b7b Mon Sep 17 00:00:00 2001 From: ireneontheway <48651140+ireneontheway@users.noreply.github.com> Date: Mon, 13 Jul 2020 17:30:17 +0800 Subject: [PATCH 18/19] Update comment-syntax.md Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com> --- comment-syntax.md | 1 + 1 file changed, 1 insertion(+) diff --git a/comment-syntax.md b/comment-syntax.md index 263f0d3cc4085..c60a21e9dd99c 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -7,6 +7,7 @@ aliases: ['/docs/dev/comment-syntax/','/docs/dev/reference/sql/language-structur # Comment Syntax This document describes the comment syntax supported by TiDB. + TiDB supports three comment styles: - Use `#` to comment a line: From c0916e488f706205fd38dd2749d88f7bf27c8608 Mon Sep 17 00:00:00 2001 From: ireneontheway <48651140+ireneontheway@users.noreply.github.com> Date: Mon, 13 Jul 2020 17:36:29 +0800 Subject: [PATCH 19/19] Apply suggestions from code review Co-authored-by: Keke Yi <40977455+yikeke@users.noreply.github.com> --- comment-syntax.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/comment-syntax.md b/comment-syntax.md index c60a21e9dd99c..0996baa4a6deb 100644 --- a/comment-syntax.md +++ b/comment-syntax.md @@ -99,7 +99,7 @@ TiDB supports three comment styles: 1 row in set (0.00 sec) ``` -## Comment syntax compatible with MySQL +## MySQL-compatible comment syntax The same as MySQL, TiDB supports a variant of C comment style: @@ -113,7 +113,7 @@ or /*!50110 Specific code */ ``` -In this style, TiDB runs the statements in the comment. This syntax is to make these SQLs ignored in other databases and executed in TiDB. +In this style, TiDB runs the statements in the comment. For example: @@ -127,18 +127,18 @@ In TiDB, you can also use another version: SELECT STRAIGHT_JOIN col1 FROM table1,table2 WHERE ... ``` -If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment is processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number is ignored, resulting in `KEY_BLOCK_SIZE=1024`. +If the server version number is specified in the comment, for example, `/*!50110 KEY_BLOCK_SIZE=1024 */`, in MySQL it means that the contents in this comment are processed only when the MySQL version is or higher than 5.1.10. But in TiDB, the MySQL version number does not work and all contents in the comment are processed. -## TiDB comment syntax +## TiDB specific comment syntax -TiDB has its own comment syntax for the version number， which can be divided into the following two types: +TiDB has its own comment syntax (that is, TiDB specific comment syntax), which can be divided into the following two types: * `/*T! Specific code */`: This syntax can only be parsed and executed by TiDB, and be ignored in other databases. -* `/*T![feature_id] Specific code */`: This syntax is used to ensure compatibility between different versions of TiDB. TiDB can parse the SQL fragment in this comment only if it implements the corresponding feature of `feature_id` in the current version. For example, as the `AUTO_RANDOM` feature is introduced in v3.1.1, this version can parse `/*T![auto_rand] auto_random */` into `auto_random`. While the `AUTO_RANDOM` feature is not implemented in v3.0.0, the SQL statement fragment above is ignored. +* `/*T![feature_id] Specific code */`: This syntax is used to ensure compatibility between different versions of TiDB. TiDB can parse the SQL fragment in this comment only if it implements the corresponding feature of `feature_id` in the current version. For example, as the `AUTO_RANDOM` feature is introduced in v3.1.1, this version of TiDB can parse `/*T![auto_rand] auto_random */` into `auto_random`. Because the `AUTO_RANDOM` feature is not implemented in v3.0.0, the SQL statement fragment above is ignored. ## Optimizer comment syntax -Another type of comment is specially treated as the Hint optimizer: +Another type of comment is specially treated as an optimizer hint: {{< copyable "sql" >}} @@ -150,6 +150,6 @@ For details about the optimizer hints that TiDB supports, see [Optimizer hints]( > **Note** > -> TiDB comment syntax and optimizer comment syntax in MySQL client before 5.7.7 will be cleared as comments by default. So if you need to use these two syntaxes in the old client, add the --comments option when starting the client. For example, `mysql -h 127.0.0.1 -P 4000 -uroot --comments`. +> In MySQL client before 5.7.7, TiDB specific comment syntax and optimizer comment syntax are treated as comments and cleared by default. To use the two syntaxes in the old client, add the `--comments` option when you start the client. For example, `mysql -h 127.0.0.1 -P 4000 -uroot --comments`. For more information, see [Comment Syntax](https://dev.mysql.com/doc/refman/5.7/en/comments.html).