From 3b8e8e464a2935ac1add0d18a739660687145e76 Mon Sep 17 00:00:00 2001 From: Morgan Tocker Date: Mon, 21 Mar 2022 21:11:16 -0600 Subject: [PATCH 01/10] docs for instance scoped system variables --- system-variables.md | 155 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 145 insertions(+), 10 deletions(-) diff --git a/system-variables.md b/system-variables.md index 3c80b670ee7c7..babe8d39f40b7 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6,13 +6,11 @@ aliases: ['/tidb/dev/tidb-specific-system-variables','/docs/dev/system-variables # System Variables -TiDB system variables behave similar to MySQL with some differences, in that settings might apply on a `SESSION`, `INSTANCE`, or `GLOBAL` scope, or on a scope that combines `SESSION`, `INSTANCE`, or `GLOBAL`. +TiDB system variables behave similar to MySQL, in that settings apply on a `SESSION` or `GLOBAL` scope: -- Changes to `GLOBAL` scoped variables **only apply to new connection sessions with TiDB**. Currently active connection sessions are not affected. These changes are persisted and valid after restarts. -- Changes to `INSTANCE` scoped variables apply to all active or new connection sessions with the current TiDB instance immediately after the changes are made. Other TiDB instances are not affected. These changes are not persisted and become invalid after TiDB restarts. -- Variables can also have `NONE` scope. These variables are read-only, and are typically used to convey static information that will not change after a TiDB server has started. - -Variables can be set with the [`SET` statement](/sql-statements/sql-statement-set-variable.md) on a per-session, instance or global basis: +- Changes on a `SESSION` scope will only affect the current session. +- Changes on a `GLOBAL` scope apply immediately, provided that the variable is not also `SESSION` scoped. In which case all sessions (including your session) will continue to use their current session value. +- Changes are made using the [`SET` statement](/sql-statements/sql-statement-set-variable.md): ```sql # These two identical statements change a session variable @@ -26,9 +24,9 @@ SET GLOBAL tidb_distsql_scan_concurrency = 10; > **Note:** > -> Executing `SET GLOBAL` applies immediately on the TiDB server where the statement was issued. A notification is then sent to all TiDB servers to refresh their system variable cache, which will start immediately as a background operation. Because there is a risk that some TiDB servers might miss the notification, the system variable cache is also refreshed automatically every 30 seconds. This helps ensure that all servers are operating with the same configuration. +> Several `GLOBAL` variables persist to the TiDB cluster. For variables that specify `Persists to cluster: Yes` a notification is sent to all TiDB servers to refresh their system variable cache when the global variable is changed. Adding additional TiDB servers (or restarting existing TiDB servers) will automatically use the persisted configuration value. For variables that specify `Persists to cluster: No` any changes only apply to the local TiDB instance that you are connected to. In order to retain any values set, you will need to specify them in your `tidb.toml` configuration file. > -> TiDB differs from MySQL in that `GLOBAL` scoped variables **persist** through TiDB server restarts. Additionally, TiDB presents several MySQL variables as both readable and settable. This is required for compatibility, because it is common for both applications and connectors to read MySQL variables. For example, JDBC connectors both read and set query cache settings, despite not relying on the behavior. +> Additionally, TiDB presents several MySQL variables as both readable and settable. This is required for compatibility, because it is common for both applications and connectors to read MySQL variables. For example, JDBC connectors both read and set query cache settings, despite not relying on the behavior. > **Note:** > @@ -47,12 +45,14 @@ SET GLOBAL tidb_distsql_scan_concurrency = 10; ### allow_auto_random_explicit_insert New in v4.0.3 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - Determines whether to allow explicitly specifying the values of the column with the `AUTO_RANDOM` attribute in the `INSERT` statement. ### auto_increment_increment - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1` - Range: `[1, 65535]` - Controls the step size of `AUTO_INCREMENT` values to be allocated to a column. It is often used in combination with `auto_increment_offset`. @@ -60,6 +60,7 @@ SET GLOBAL tidb_distsql_scan_concurrency = 10; ### auto_increment_offset - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1` - Range: `[1, 65535]` - Controls the initial offset of `AUTO_INCREMENT` values to be allocated to a column. This setting is often used in combination with `auto_increment_increment`. For example: @@ -93,66 +94,77 @@ mysql> SELECT * FROM t1; ### autocommit - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - Controls whether statements should automatically commit when not in an explicit transaction. See [Transaction Overview](/transaction-overview.md#autocommit) for more information. ### block_encryption_mode - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `aes-128-ecb` - Defines the encryption mode for the `AES_ENCRYPT()` and `AES_DECRYPT()` functions. ### character_set_client - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4` - The character set for data sent from the client. See [Character Set and Collation](/character-set-and-collation.md) for details on the use of character sets and collations in TiDB. It is recommended to use [`SET NAMES`](/sql-statements/sql-statement-set-names.md) to change the character set when needed. ### character_set_connection - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4` - The character set for string literals that do not have a specified character set. ### character_set_database - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4` - This variable indicates the character set of the default database in use. **It is NOT recommended to set this variable**. When a new default database is selected, the server changes the variable value. ### character_set_results - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4` - The character set that is used when data is sent to the client. ### character_set_server - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4` - The default character set for the server. ### collation_connection - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4_bin` - This variable indicates the collation for string literals that do not have a specified collation. ### collation_database - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4_bin` - This variable indicates the collation of the default database in use. **It is NOT recommended to set this variable**. When a new default database is selected, the server changes the variable value. ### collation_server - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4_bin` - The default collation for the server. ### cte_max_recursion_depth - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1000` - Range: `[0, 4294967295]` - Controls the maximum recursion depth in Common Table Expressions. @@ -174,6 +186,7 @@ mysql> SELECT * FROM t1; ### default_authentication_plugin - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `mysql_native_password` - Possible values: `mysql_native_password`, `caching_sha2_password` - This variable sets the authentication method that the server advertises when the server-client connection is being established. Possible values for this variable are documented in [Authentication plugin status](/security-compatibility-with-mysql.md#authentication-plugin-status). @@ -182,6 +195,7 @@ mysql> SELECT * FROM t1; ### default_week_format - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 7]` - Sets the week format used by the `WEEK()` function. @@ -189,12 +203,14 @@ mysql> SELECT * FROM t1; ### foreign_key_checks - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - For compatibility, TiDB returns foreign key checks as `OFF`. ### group_concat_max_len - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1024` - Range: `[4, 18446744073709551615]` - The maximum buffer size for items in the `GROUP_CONCAT()` function. @@ -224,12 +240,14 @@ This variable is an alias for `last_insert_id`. ### init_connect - Scope: GLOBAL +- Persists to cluster: Yes - Default value: "" - The `init_connect` feature permits a SQL statement to be automatically executed when you first connect to a TiDB server. If you have the `CONNECTION_ADMIN` or `SUPER` privileges, this `init_connect` statement will not be executed. If the `init_connect` statement results in an error, your user connection will be terminated. ### innodb_lock_wait_timeout - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `50` - Range: `[1, 1073741824]` - Unit: Seconds @@ -238,6 +256,7 @@ This variable is an alias for `last_insert_id`. ### interactive_timeout - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `28800` - Range: `[1, 31536000]` - Unit: Seconds @@ -277,6 +296,7 @@ This variable is an alias for `last_insert_id`. ### max_allowed_packet - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `67108864` - Range: `[1024, 1073741824]` - Unit: Bytes @@ -285,6 +305,7 @@ This variable is an alias for `last_insert_id`. ### max_execution_time - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 2147483647]` - Unit: Milliseconds @@ -332,6 +353,7 @@ This variable is an alias for `last_insert_id`. ### skip_name_resolve New in v5.2.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls whether the `tidb-server` instance resolves hostnames as a part of the connection handshake. - When the DNS is unreliable, you can enable this option to improve network performance. @@ -355,6 +377,7 @@ This variable is an alias for `last_insert_id`. ### sql_log_bin - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - Indicates whether to write changes to [TiDB Binlog](/tidb-binlog/tidb-binlog-overview.md) or not. @@ -365,12 +388,14 @@ This variable is an alias for `last_insert_id`. ### sql_mode - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION` - This variable controls a number of MySQL compatibility behaviors. See [SQL Mode](/sql-mode.md) for more information. ### sql_select_limit New in v4.0.2 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `18446744073709551615` - Range: `[0, 18446744073709551615]` - Unit: Rows @@ -403,6 +428,7 @@ This variable is an alias for `last_insert_id`. ### tidb_allow_batch_cop New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1` - Range: `[0, 2]` - This variable is used to control how TiDB sends a coprocessor request to TiFlash. It has the following values: @@ -414,6 +440,7 @@ This variable is an alias for `last_insert_id`. ### tidb_allow_fallback_to_tikv New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: "" - This variable is used to specify a list of storage engines that might fall back to TiKV. If the execution of a SQL statement fails due to a failure of the specified storage engine in the list, TiDB retries executing this SQL statement with TiKV. This variable can be set to "" or "tiflash". When this variable is set to "tiflash", if TiFlash returns a timeout error (error code: ErrTiFlashServerTimeout), TiDB retries executing this SQL statement with TiKV. @@ -426,6 +453,7 @@ This variable is an alias for `last_insert_id`. ### tidb_allow_mpp New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - Controls whether to use the MPP mode of TiFlash to execute queries. The value options are as follows: - `0` or `OFF`, which means that the MPP mode will not be used. @@ -442,6 +470,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_analyze_version New in v5.1.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `2` - Range: `[1, 2]` - Controls how TiDB collects statistics. @@ -450,12 +479,14 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_auto_analyze_end_time - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `23:59 +0000` - This variable is used to restrict the time window that the automatic update of statistics is permitted. For example, to only allow automatic statistics updates between 1AM and 3AM, set `tidb_auto_analyze_start_time='01:00 +0000'` and `tidb_auto_analyze_end_time='03:00 +0000'`. ### tidb_auto_analyze_ratio - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `0.5` - This variable is used to set the threshold when TiDB automatically executes [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md) in a background thread to update table statistics. For example, a value of 0.5 means that auto-analyze is triggered when greater than 50% of the rows in a table have been modified. Auto-analyze can be restricted to only execute during certain hours of the day by specifying `tidb_auto_analyze_start_time` and `tidb_auto_analyze_end_time`. @@ -466,12 +497,14 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_auto_analyze_start_time - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `00:00 +0000` - This variable is used to restrict the time window that the automatic update of statistics is permitted. For example, to only allow automatic statistics updates between 1AM and 3AM, set `tidb_auto_analyze_start_time='01:00 +0000'` and `tidb_auto_analyze_end_time='03:00 +0000'`. ### tidb_backoff_lock_fast - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `10` - Range: `[1, 2147483647]` - This variable is used to set the `backoff` time when the read request meets a lock. @@ -479,6 +512,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_backoff_weight - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `2` - Range: `[1, 2147483647]` - This variable is used to increase the weight of the maximum time of TiDB `backoff`, that is, the maximum retry time for sending a retry request when an internal network or other component (TiKV, PD) failure is encountered. This variable can be used to adjust the maximum retry time and the minimum value is 1. @@ -490,6 +524,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_broadcast_join_threshold_count New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `10240` - Range: `[0, 9223372036854775807]` - Unit: Rows @@ -498,6 +533,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_broadcast_join_threshold_size New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `104857600` (100 MiB) - Range: `[0, 9223372036854775807]` - Unit: Bytes @@ -506,6 +542,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_build_stats_concurrency - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `4` - Unit: Threads - This variable is used to set the concurrency of executing the `ANALYZE` statement. @@ -514,6 +551,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_capture_plan_baselines New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - 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. @@ -542,6 +580,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_constraint_check_in_place - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This setting only applies to optimistic transactions. When this variable is set to `OFF`, checking for duplicate values in UNIQUE indexes is deferred until the transaction commits. This helps improve performance, but might be an unexpected behavior for some applications. See [Constraints](/constraints.md) for details. @@ -577,6 +616,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_ddl_error_count_limit - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `512` - Range: `[0, 9223372036854775807]` - This variable is used to set the number of retries when the DDL operation fails. When the number of retries exceeds the parameter value, the wrong DDL operation is canceled. @@ -584,6 +624,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_ddl_reorg_batch_size - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `256` - Range: `[32, 10240]` - Unit: Rows @@ -601,6 +642,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_ddl_reorg_worker_cnt - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `4` - Range: `[1, 256]` - Unit: Threads @@ -609,6 +651,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_disable_txn_auto_retry - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to set whether to disable the automatic retry of explicit optimistic transactions. The default value of `ON` means that transactions will not automatically retry in TiDB and `COMMIT` statements might return errors that need to be handled in the application layer. @@ -623,6 +666,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_distsql_scan_concurrency - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `15` - Range: `[1, 256]` - Unit: Threads @@ -634,6 +678,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_dml_batch_size - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 2147483647]` - Unit: Rows @@ -643,6 +688,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_1pc New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to specify whether to enable the one-phase commit feature for transactions that only affect one Region. Compared with the often-used two-phase commit, one-phase commit can greatly reduce the latency of transaction commit and increase the throughput. @@ -655,6 +701,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_amend_pessimistic_txn New in v4.0.7 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to control whether to enable the `AMEND TRANSACTION` feature. If you enable the `AMEND TRANSACTION` feature in a pessimistic transaction, when concurrent DDL operations and SCHEMA VERSION changes exist on tables associated with this transaction, TiDB attempts to amend the transaction. TiDB corrects the transaction commit to make the commit consistent with the latest valid SCHEMA VERSION so that the transaction can be successfully committed without getting the `Information schema is changed` error. This feature is effective on the following concurrent DDL operations: @@ -669,6 +716,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_async_commit New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls whether to enable the async commit feature for the second phase of the two-phase transaction commit to perform asynchronously in the background. Enabling this feature can reduce the latency of transaction commit. @@ -681,6 +729,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_auto_increment_in_generated - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to determine whether to include the `AUTO_INCREMENT` columns when creating a generated column or an expression index. @@ -691,6 +740,7 @@ Constraint checking is always performed in place for pessimistic transactions (d > Currently, cascades planner is an experimental feature. It is not recommended that you use it in production environments. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to control whether to enable the cascades planner. @@ -703,6 +753,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_clustered_index New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `INT_ONLY` - Possible values: `OFF`, `ON`, `INT_ONLY` - This variable is used to control whether to create the primary key as a [clustered index](/clustered-indexes.md) by default. "By default" here means that the statement does not explicitly specify the keyword `CLUSTERED`/`NONCLUSTERED`. Supported values are `OFF`, `ON`, and `INT_ONLY`: @@ -723,6 +774,7 @@ Constraint checking is always performed in place for pessimistic transactions (d > Currently, collecting statistics on `PREDICATE COLUMNS` is an experimental feature. It is not recommended that you use it in production environments. - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls whether to enable TiDB to collect `PREDICATE COLUMNS`. After enabling the collection, if you disable it, the information of previously collected `PREDICATE COLUMNS` is cleared. For details, see [Collect statistics on some columns](/statistics.md#collect-statistics-on-some-columns). @@ -744,6 +796,7 @@ Constraint checking is always performed in place for pessimistic transactions (d > Currently, `Fast Analyze` is an experimental feature. It is not recommended that you use it in production environments. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to set whether to enable the statistics `Fast Analyze` feature. - If the statistics `Fast Analyze` feature is enabled, TiDB randomly samples about 10,000 rows of data as statistics. When the data is distributed unevenly or the data size is small, the statistics accuracy is low. This might lead to a non-optimal execution plan, for example, selecting a wrong index. If the execution time of the regular `Analyze` statement is acceptable, it is recommended to disable the `Fast Analyze` feature. @@ -759,9 +812,18 @@ Constraint checking is always performed in place for pessimistic transactions (d > - Since v5.4.0, for a newly deployed TiDB cluster, this variable is enabled by default. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to control whether to enable the index merge feature. +### tidb_enable_legacy_instance_scope New in v6.0 + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Default value: `ON` +- This variable permits `INSTANCE` scoped variables to be set with `SET SESSION` as well as `SET GLOBAL` syntax. +- This option is enabled by default for compatibility with earlier versions of TiDB. + ### tidb_enable_list_partition New in v5.0 > **Warning:** @@ -769,12 +831,14 @@ Constraint checking is always performed in place for pessimistic transactions (d > Currently, List partition and List COLUMNS partition are experimental features. It is not recommended that you use it in production environments. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to set whether to enable the `LIST (COLUMNS) TABLE PARTITION` feature. ### tidb_enable_noop_functions New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - Possible values: `OFF`, `ON`, `WARN` - By default, TiDB returns an error when you attempt to use the syntax for functionality that is not yet implemented. When the variable value is set to `ON`, TiDB silently ignores such cases of unavailable functionality, which is helpful if you cannot make changes to the SQL code. @@ -792,6 +856,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_paging New in v5.4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls whether to use the method of paging to send coprocessor requests in `IndexLookUp` operator. - User scenarios: For read queries that use `IndexLookup` and `Limit` and that `Limit` cannot be pushed down to `IndexScan`, there might be high latency for the read queries and high CPU usage for TiKV's `unified read pool`. In such cases, because the `Limit` operator only requires a small set of data, if you set `tidb_enable_paging` to `ON`, TiDB processes less data, which reduces query latency and resource consumption. @@ -800,12 +865,14 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_parallel_apply New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls whether to enable concurrency for the `Apply` operator. The number of concurrencies is controlled by the `tidb_executor_concurrency` variable. The `Apply` operator processes correlated subqueries and has no concurrency by default, so the execution speed is slow. Setting this variable value to `1` can increase concurrency and speed up execution. Currently, concurrency for `Apply` is disabled by default. ### tidb_enable_pseudo_for_outdated_stats New in v5.3.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls the behavior of the optimizer on using statistics of a table when the statistics are outdated. - The optimizer determines whether the statistics of a table is outdated in this way: since the last time `ANALYZE` is executed on a table to get the statistics, if 80% of the table rows are modified (the modified row count divided by the total row count), the optimizer determines that the statistics of this table is outdated. You can change this ratio using the [`pseudo-estimate-ratio`](/tidb-configuration-file.md#pseudo-estimate-ratio) configuration. @@ -815,6 +882,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_rate_limit_action - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls whether to enable the dynamic memory control feature for the operator that reads data. By default, this operator enables the maximum number of threads that [`tidb_distsql_scan_concurrency`](/system-variables.md#tidb_distsql_scan_concurrency) allows to read data. When the memory usage of a single SQL statement exceeds [`tidb_mem_quota_query`](/system-variables.md#tidb_mem_quota_query) each time, the operator that reads data stops one thread. - When the operator that reads data has only one thread left and the memory usage of a single SQL statement continues to exceed [`tidb_mem_quota_query`](/system-variables.md#tidb_mem_quota_query), this SQL statement triggers other memory control behaviors, such as [spilling data to disk](/tidb-configuration-file.md#oom-use-tmp-storage). @@ -828,12 +896,14 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_stmt_summary New in v3.0.4 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `ON` - 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 `information_schema.STATEMENTS_SUMMARY` system table to identify and troubleshoot SQL performance issues. ### tidb_enable_strict_double_type_check New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to control if tables can be created with invalid definitions of type `DOUBLE`. This setting is intended to provide an upgrade path from earlier versions of TiDB, which were less strict in validating types. - The default value of `ON` is compatible with MySQL. @@ -858,6 +928,7 @@ Query OK, 0 rows affected (0.09 sec) ### tidb_enable_table_partition - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - Possible values: `OFF`, `ON`, `AUTO` - This variable is used to set whether to enable the `TABLE PARTITION` feature: @@ -868,6 +939,7 @@ Query OK, 0 rows affected (0.09 sec) ### tidb_enable_telemetry New in v4.0.2 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to dynamically control whether the telemetry collection in TiDB is enabled. By setting the value to `OFF`, 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. @@ -878,12 +950,14 @@ Query OK, 0 rows affected (0.09 sec) > Currently, Top SQL is an experimental feature. It is not recommended that you use it for production environments. - Scope: GLOBAL -- Default value: `OFF` +- Persists to cluster: Yes +- Default value: `ON` - This variable is used to control whether to enable the [Top SQL](/dashboard/top-sql.md) feature. ### tidb_enable_tso_follower_proxy New in v5.3.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to enable the TSO Follower Proxy feature. When the value is `OFF`, TiDB only gets TSO from the PD leader. After this feature is enabled, TiDB gets TSO by evenly sending requests to all PD nodes and forwarding TSO requests through PD followers. This helps reduce the CPU pressure of PD leader. - Scenarios for enabling TSO Follower Proxy: @@ -897,12 +971,14 @@ Query OK, 0 rows affected (0.09 sec) ### tidb_enable_vectorized_expression New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to control whether to enable vectorized execution. ### tidb_enable_window_function - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to control whether to enable the support for window functions. Note that window functions may use reserved keywords. This might cause SQL statements that could be executed normally cannot be parsed after upgrading TiDB. In this case, you can set `tidb_enable_window_function` to `OFF`. @@ -920,6 +996,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_evolve_plan_baselines New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - 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: @@ -929,12 +1006,14 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_evolve_plan_task_end_time New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `23:59 +0000` - This variable is used to set the end time of baseline evolution in a day. ### tidb_evolve_plan_task_max_time New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `600` - Range: `[-1, 9223372036854775807]` - Unit: Seconds @@ -943,12 +1022,14 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_evolve_plan_task_start_time New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `00:00 +0000` - This variable is used to set the start time of baseline evolution in a day. ### tidb_executor_concurrency New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `5` - Range: `[1, 256]` - Unit: Threads @@ -996,6 +1077,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_gc_concurrency New in v5.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1004,12 +1086,14 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_gc_enable New in v5.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `ON` - Enables garbage collection for TiKV. Disabling garbage collection will reduce system performance, as old versions of rows will no longer be purged. ### tidb_gc_life_time New in v5.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `10m0s` - Range: `[10m0s, 8760h0m0s]` - The time limit during which data is retained for each GC, in the format of Go Duration. When a GC happens, the current time minus this value is the safe point. @@ -1024,6 +1108,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_gc_run_interval New in v5.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `10m0s` - Range: `[10m0s, 8760h0m0s]` - Specifies the GC interval, in the format of Go Duration, for example, `"1h30m"`, and `"15m"` @@ -1035,6 +1120,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Currently, Green GC is an experimental feature. It is not recommended that you use it in production environments. - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `LEGACY` - Possible values: `PHYSICAL`, `LEGACY` - `LEGACY`: Uses the old way of scanning, that is, disable Green GC. @@ -1043,7 +1129,8 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_general_log -- Scope: INSTANCE +- Scope: GLOBAL +- Persists to cluster: No - Default value: `OFF` - This variable is used to set whether to record all SQL statements in the [log](/tidb-configuration-file.md#logfile). This feature is disabled by default. If maintenance personnel needs to trace all SQL statements when locating issues, they can enable this feature. - To see all records of this feature in the log, query the `"GENERAL_LOG"` string. The following information is recorded: @@ -1064,6 +1151,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1077,6 +1165,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1091,6 +1180,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1101,6 +1191,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_index_join_batch_size - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `25000` - Range: `[1, 2147483647]` - Unit: Rows @@ -1114,6 +1205,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1128,6 +1220,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1137,6 +1230,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_index_lookup_size - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `20000` - Range: `[1, 2147483647]` - Unit: Rows @@ -1146,6 +1240,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_index_serial_scan_concurrency - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1` - Range: `[1, 256]` - Unit: Threads @@ -1155,6 +1250,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_init_chunk_size - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `32` - Range: `[1, 32]` - Unit: Rows @@ -1183,6 +1279,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_max_chunk_size - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1024` - Range: `[32, 2147483647]` - Unit: Rows @@ -1191,6 +1288,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_max_delta_schema_count New in v2.1.18 and v3.0.5 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `1024` - Range: `[100, 16384]` - This variable is used to set the maximum number of schema versions (the table IDs modified for corresponding versions) allowed to be cached. The value range is 100 ~ 16384. @@ -1198,6 +1296,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_mem_quota_apply_cache New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `33554432` (32 MiB) - Range: `[0, 9223372036854775807]` - Unit: Bytes @@ -1239,6 +1338,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_multi_statement_mode New in v4.0.11 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - Possible values: `OFF`, `ON`, `WARN` - This variable controls whether to allow multiple queries to be executed in the same `COM_QUERY` call. @@ -1271,6 +1371,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_opt_correlation_exp_factor - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1` - Range: `[0, 2147483647]` - 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. @@ -1282,6 +1383,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_opt_correlation_threshold - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `0.9` - This variable is used to set the threshold value that determines whether to enable estimating the row count by using column order correlation. If the order correlation between the current column and the `handle` column exceeds the threshold value, this method is enabled. @@ -1323,12 +1425,14 @@ mysql> desc select count(distinct a) from test.t; ### tidb_opt_enable_correlation_adjustment - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to control whether the optimizer estimates the number of rows based on column order correlation ### tidb_opt_insubq_to_join_and_agg - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to set whether to enable the optimization rule that converts a subquery to join and aggregation. - For example, after you enable this optimization rule, the subquery is converted as follows: @@ -1352,6 +1456,7 @@ mysql> desc select count(distinct a) from test.t; ### tidb_opt_limit_push_down_threshold - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `100` - Range: `[0, 2147483647]` - This variable is used to set the threshold that determines whether to push the Limit or TopN operator down to TiKV. @@ -1360,6 +1465,7 @@ mysql> desc select count(distinct a) from test.t; ### tidb_opt_prefer_range_scan New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - After you set the value of this variable to `ON`, the optimizer always prefers range scans over full table scans. - In the following example, before you enable `tidb_opt_prefer_range_scan`, the TiDB optimizer performs a full table scan. After you enable `tidb_opt_prefer_range_scan`, the optimizer selects an index range scan. @@ -1401,12 +1507,14 @@ explain select * from t where age=5; > Currently, the dynamic pruning mode for partitioned tables is an experimental feature. It is not recommended that you use it in production environments. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `static` - Specifies whether to enable `dynamic` mode for partitioned tables. For details about the dynamic pruning mode, see [Dynamic Pruning Mode for Partitioned Tables](/partitioned-table.md#dynamic-pruning-mode). ### tidb_persist_analyze_options New in v5.4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls whether to enable the [ANALYZE configuration persistence](/statistics.md#persist-analyze-configurations) feature. @@ -1424,6 +1532,7 @@ explain select * from t where age=5; > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[-1, 256]` - Unit: Threads @@ -1459,6 +1568,7 @@ SET tidb_query_log_max_len = 20 ### tidb_redact_log - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls whether to hide user information in the SQL statement being recorded into the TiDB log and slow log. - When you set the variable to `1`, user information is hidden. For example, if the executed SQL statement is `insert into t values (1,2)`, the statement is recorded as `insert into t values (?,?)` in the log. @@ -1466,6 +1576,7 @@ SET tidb_query_log_max_len = 20 ### tidb_regard_null_as_point New in v5.4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls whether the optimizer can use a query condition including null equivalence as a prefix condition for index access. - This variable is enabled by default. When it is enabled, the optimizer can reduce the volume of index data to be accessed, which accelerates query execution. For example, if a query involves multiple-column indexes `index(a, b)` and the query condition contains `a<=>null and b=1`, the optimizer can use both `a<=>null` and `b=1` in the query condition for index access. If the variable is disabled, because `a<=>null and b=1` includes the null equivalence condition, the optimizer does not use `b=1` for index access. @@ -1473,6 +1584,7 @@ SET tidb_query_log_max_len = 20 ### tidb_replica_read New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `leader` - Possible values: `leader`, `follower`, `leader-and-follower`, `closest-replicas` - This variable is used to control where TiDB reads data. Here are three options: @@ -1484,6 +1596,7 @@ SET tidb_query_log_max_len = 20 ### tidb_retry_limit - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `10` - Range: `[-1, 9223372036854775807]` - This variable is used to set the maximum number of the retries for optimistic transactions. When a transaction encounters retryable errors (such as transaction conflicts, very slow transaction commit, or table schema changes), this transaction is re-executed according to this variable. Note that setting `tidb_retry_limit` to `0` disables the automatic retry. This variable only applies to optimistic transactions, not to pessimistic transactions. @@ -1491,6 +1604,7 @@ SET tidb_query_log_max_len = 20 ### tidb_row_format_version - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `2` - Range: `[1, 2]` - Controls the format version of the newly saved data in the table. In TiDB v4.0, the [new storage row format](https://github.com/pingcap/tidb/blob/master/docs/design/2018-07-19-row-format.md) version `2` is used by default to save new data. @@ -1500,6 +1614,7 @@ SET tidb_query_log_max_len = 20 ### tidb_scatter_region - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - By default, Regions are split for a new table when it is being created in TiDB. After this variable is enabled, the newly split Regions are scattered immediately during the execution of the `CREATE TABLE` statement. This applies to the scenario where data need to be written in batches right after the tables are created in batches, because the newly split Regions can be scattered in TiKV beforehand and do not have to wait to be scheduled by PD. To ensure the continuous stability of writing data in batches, the `CREATE TABLE` statement returns success only after the Regions are successfully scattered. This makes the statement's execution time multiple times longer than that when you disable this variable. - Note that if `SHARD_ROW_ID_BITS` and `PRE_SPLIT_REGIONS` have been set when a table is created, the specified number of Regions are evenly split after the table creation. @@ -1507,6 +1622,7 @@ SET tidb_query_log_max_len = 20 ### tidb_skip_ascii_check New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to set whether to skip ASCII validation. - Validating ASCII characters affects the performance. When you are sure that the input characters are valid ASCII characters, you can set the variable value to `ON`. @@ -1514,6 +1630,7 @@ SET tidb_query_log_max_len = 20 ### tidb_skip_isolation_level_check - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - After this switch is enabled, if an isolation level unsupported by TiDB is assigned to `tx_isolation`, no error is reported. This helps improve compatibility with applications that set (but do not depend on) a different isolation level. @@ -1530,6 +1647,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) ### tidb_skip_utf8_check - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to set whether to skip UTF-8 validation. - Validating UTF-8 characters affects the performance. When you are sure that the input characters are valid UTF-8 characters, you can set the variable value to `ON`. @@ -1567,6 +1685,7 @@ SET tidb_slow_log_threshold = 200; > Currently, synchronously loading statistics is an experimental feature. It is not recommended that you use it in production environments. - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls how TiDB behaves when the waiting time of SQL optimization reaches the timeout to synchronously load complete column statistics. The default value `OFF` means that SQL execution fails after the timeout. If you set this variable to `ON`, the SQL optimization gets back to using pseudo statistics after the timeout. @@ -1577,6 +1696,7 @@ SET tidb_slow_log_threshold = 200; > Currently, synchronously loading statistics is an experimental feature. It is not recommended that you use it in production environments. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 2147483647]` - Unit: Milliseconds @@ -1585,6 +1705,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_stmt_summary_history_size New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `24` - Range: `[0, 255]` - This variable is used to set the history capacity of [statement summary tables](/statement-summary-tables.md). @@ -1592,12 +1713,14 @@ SET tidb_slow_log_threshold = 200; ### tidb_stmt_summary_internal_query New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to control whether to include the SQL information of TiDB in [statement summary tables](/statement-summary-tables.md). ### tidb_stmt_summary_max_sql_length New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `4096` - Range: `[0, 2147483647]` - This variable is used to control the length of the SQL string in [statement summary tables](/statement-summary-tables.md). @@ -1605,6 +1728,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_stmt_summary_max_stmt_count New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `3000` - Range: `[1, 32767]` - This variable is used to set the maximum number of statements that [statement summary tables](/statement-summary-tables.md) store in memory. @@ -1612,6 +1736,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_stmt_summary_refresh_interval New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `1800` - Range: `[1, 2147483647]` - Unit: Seconds @@ -1620,6 +1745,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_store_limit New in v3.0.4 and v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 9223372036854775807]` - This variable is used to limit the maximum number of requests TiDB can send to TiKV at the same time. 0 means no limit. @@ -1627,6 +1753,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_tmp_table_max_size New in v5.3.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `67108864` - Range: `[1048576, 137438953472]` - Unit: Bytes @@ -1635,6 +1762,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_tso_client_batch_max_wait_time New in v5.3.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 10]` - Unit: Milliseconds @@ -1653,6 +1781,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_txn_mode - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `pessimistic` - Possible values: `pessimistic`, `optimistic` - This variable is used to set the transaction mode. TiDB 3.0 supports the pessimistic transactions. Since TiDB 3.0.8, the [pessimistic transaction mode](/pessimistic-transaction.md) is enabled by default. @@ -1662,6 +1791,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_use_plan_baselines New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - 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 `OFF` value. For the use of the execution plan binding, see [Execution Plan Binding](/sql-plan-management.md#create-a-binding). @@ -1689,6 +1819,7 @@ SET tidb_slow_log_threshold = 200; > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1698,6 +1829,7 @@ SET tidb_slow_log_threshold = 200; ### time_zone - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `SYSTEM` - This variable returns the current time zone. Values can be specified as either an offset such as '-8:00' or a named zone 'America/Los_Angeles'. - The value `SYSTEM` means that the time zone should be the same as the system host, which is available via the [`system_time_zone`](#system_time_zone) variable. @@ -1711,6 +1843,7 @@ SET tidb_slow_log_threshold = 200; ### transaction_isolation - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `REPEATABLE-READ` - Possible values: `READ-UNCOMMITTED`, `READ-COMMITTED`, `REPEATABLE-READ`, `SERIALIZABLE` - This variable sets the transaction isolation. TiDB advertises `REPEATABLE-READ` for compatibility with MySQL, but the actual isolation level is Snapshot Isolation. See [transaction isolation levels](/transaction-isolation-levels.md) for further details. @@ -1746,6 +1879,7 @@ This variable is an alias for `transaction_isolation`. ### wait_timeout - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `28800` - Range: `[0, 31536000]` - Unit: Seconds @@ -1760,5 +1894,6 @@ This variable is an alias for `transaction_isolation`. ### windowing_use_high_precision - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls whether to use the high precision mode when computing the window functions. From d504b121e3a499676ba8a5e415b072605d6db1ec Mon Sep 17 00:00:00 2001 From: Morgan Tocker Date: Wed, 13 Apr 2022 21:27:25 -0600 Subject: [PATCH 02/10] Add new changes --- system-variables.md | 109 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 103 insertions(+), 6 deletions(-) diff --git a/system-variables.md b/system-variables.md index babe8d39f40b7..2cbd4363b939d 100644 --- a/system-variables.md +++ b/system-variables.md @@ -249,7 +249,7 @@ This variable is an alias for `last_insert_id`. - Scope: SESSION | GLOBAL - Persists to cluster: Yes - Default value: `50` -- Range: `[1, 1073741824]` +- Range: `[1, 3600]` - Unit: Seconds - The lock wait timeout for pessimistic transactions (default). @@ -474,7 +474,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a - Default value: `2` - Range: `[1, 2]` - Controls how TiDB collects statistics. -- In versions before v5.1.0, the default value of this variable is `1`. In v5.1.0, the default value of this variable is `2`, which serves as an experimental feature. For detailed introduction, see [Introduction to Statistics](/statistics.md). +- In v5.3.0 and later versions, the default value of this variable is `2`, which serves as an experimental feature. If your cluster is upgraded from a version earlier than v5.3.0 to v5.3.0 or later, the default value of `tidb_analyze_version` does not change. For detailed introduction, see [Introduction to Statistics](/statistics.md). ### tidb_auto_analyze_end_time @@ -514,7 +514,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a - Scope: SESSION | GLOBAL - Persists to cluster: Yes - Default value: `2` -- Range: `[1, 2147483647]` +- Range: `[0, 2147483647]` - This variable is used to increase the weight of the maximum time of TiDB `backoff`, that is, the maximum retry time for sending a retry request when an internal network or other component (TiKV, PD) failure is encountered. This variable can be used to adjust the maximum retry time and the minimum value is 1. For example, the base timeout for TiDB to take TSO from PD is 15 seconds. When `tidb_backoff_weight = 2`, the maximum timeout for taking TSO is: *base time \* 2 = 30 seconds*. @@ -816,7 +816,7 @@ Constraint checking is always performed in place for pessimistic transactions (d - Default value: `ON` - This variable is used to control whether to enable the index merge feature. -### tidb_enable_legacy_instance_scope New in v6.0 +### tidb_enable_legacy_instance_scope New in v6.0.0 - Scope: SESSION | GLOBAL - Persists to cluster: Yes @@ -835,6 +835,13 @@ Constraint checking is always performed in place for pessimistic transactions (d - Default value: `OFF` - This variable is used to set whether to enable the `LIST (COLUMNS) TABLE PARTITION` feature. +### tidb_enable_mutation_checker New in v6.0.0 + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Default value: `OFF` +- This variable is used to control whether to enable TiDB mutation checker, which is a tool used to check consistency between data and indexes during the execution of DML statements. If the checker returns an error for a statement, TiDB rolls back the execution of the statement. Enabling this variable causes a slight increase in CPU usage. For more information, see [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md ). + ### tidb_enable_noop_functions New in v4.0 - Scope: SESSION | GLOBAL @@ -951,7 +958,7 @@ Query OK, 0 rows affected (0.09 sec) - Scope: GLOBAL - Persists to cluster: Yes -- Default value: `ON` +- Default value: `OFF` - This variable is used to control whether to enable the [Top SQL](/dashboard/top-sql.md) feature. ### tidb_enable_tso_follower_proxy New in v5.3.0 @@ -1188,6 +1195,14 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified - When the parameter of the aggregate function is not distinct, `HashAgg` is run concurrently and respectively in two phases - the `partial` phase and the `final` phase. - A value of `-1` means that the value of `tidb_executor_concurrency` will be used instead. +### tidb_ignore_prepared_cache_close_stmt New in v6.0.0 + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Default value: `OFF` +- This variable is used to set whether to ignore the commands for closing prepared statement cache. +- When this variable is set to `ON`, the `COM_STMT_CLOSE` command of the Binary protocol and the [`DEALLOCATE PREPARE`](/sql-statements/sql-statement-deallocate.md) statement of the text protocol are ignored. For details, see [Ignore the `COM_STMT_CLOSE` command and the `DEALLOCATE PREPARE` statement](/sql-prepare-plan-cache.md#ignore-the-com_stmt_close-command-and-the-deallocate-prepare-statement). + ### tidb_index_join_batch_size - Scope: SESSION | GLOBAL @@ -1303,6 +1318,16 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified - This variable is used to set the memory usage threshold of the local cache in the `Apply` operator. - The local cache in the `Apply` operator is used to speed up the computation of the `Apply` operator. You can set the variable to `0` to disable the `Apply` cache feature. +### tidb_mem_quota_binding_cache New in v6.0.0 + +- Scope: GLOBAL +- Persists to cluster: Yes +- Default value: `67108864` +- Range: `[0, 2147483647]` +- Unit: Bytes +- This variable is used to set the threshold of the memory used for caching bindings. +- If a system creates or captures excessive bindings, resulting in overuse of memory space, TiDB returns a warning in the log. In this case, the cache cannot hold all available bindings or determine which bindings to store. For this reason, some queries might miss their bindings. To address this problem, you can increase the value of this variable, which increases the memory used for caching bindings. After modifying this parameter, you need to run `admin reload bindings` to reload bindings and validate the modification. + ### tidb_mem_quota_query - Scope: SESSION @@ -1518,6 +1543,15 @@ explain select * from t where age=5; - Default value: `ON` - This variable controls whether to enable the [ANALYZE configuration persistence](/statistics.md#persist-analyze-configurations) feature. +### tidb_placement_mode New in v6.0.0 + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Default value: `STRICT` +- Possible values: `STRICT`, `IGNORE` +- This variable controls whether DDL statements ignore the [placement rules specified in SQL](/placement-rules-in-sql.md). When the variable value is `IGNORE`, all placement rule options are ignored. +- It is intended to be used by logical dump/restore tools to ensure that tables can always be created even if invalid placement rules are assigned. This is similar to how mysqldump writes `SET FOREIGN_KEY_CHECKS=0;` to the start of every dump file. + ### tidb_pprof_sql_cpu New in v4.0 - Scope: INSTANCE @@ -1553,10 +1587,24 @@ Usage example: SET tidb_query_log_max_len = 20 ``` +### tidb_rc_read_check_ts New in v6.0.0 + +> **Warning:** +> +> - This feature is incompatible with [`replica-read`](#tidb_replica_read-new-in-v40). Do not enable `tidb_rc_read_check_ts` and `replica-read` at the same time. +> - If your client uses a cursor, it is not recommended to enable `tidb_rc_read_check_ts` in case that the previous batch of returned data has already been used by the client and the statement eventually fails. + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Default value: `OFF` +- This variable is used to optimize the timestamp acquisition, which is suitable for scenarios with read-committed isolation level where read-write conflicts are rare. Enabling this variable can avoid the latency and cost of getting the global timestamp, and can optimize the transaction-level read latency. +- If read-write conflicts are severe, enabling this feature will increase the cost and latency of getting the global timestamp, and might cause performance regression. For details, see [Read Committed isolation level](/transaction-isolation-levels.md#read-committed-isolation-level). + ### tidb_read_staleness New in v5.4.0 - Scope: SESSION -- Default value: "" +- Default value: `0` +- Range: `[-2147483648, 0]` - This variable is used to set the time range of historical data that TiDB can read in the current session. After setting the value, TiDB selects a timestamp as new as possible from the range allowed by this variable, and all subsequent read operations are performed against this timestamp. For example, if the value of this variable is set to `-5`, on the condition that TiKV has the corresponding historical version's data, TiDB selects a timestamp as new as possible within a 5-second time range. ### tidb_record_plan_in_slow_log @@ -1750,6 +1798,22 @@ SET tidb_slow_log_threshold = 200; - Range: `[0, 9223372036854775807]` - 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_sysdate_is_now New in v6.0.0 + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Default value: `OFF` +- This variable is used to control whether the `SYSDATE` function can be replaced by the `NOW` function. This configuration item has the same effect as the MySQL option [`sysdate-is-now`](https://dev.mysql.com/doc/refman/8.0/en/server-options.html#option_mysqld_sysdate-is-now). + +### tidb_table_cache_lease New in v6.0.0 + +- Scope: GLOBAL +- Persists to cluster: Yes +- Default value: `3` +- Range: `[1, 10]` +- Unit: Seconds +- This variable is used to control the lease time of [cached tables](/cached-tables.md) with a default value of `3`. The value of this variable affects the modification to cached tables. After a modification is made to cached tables, the longest waiting time might be `tidb_table_cache_lease` seconds. If the table is read-only or can accept a high write latency, you can increase the value of this variable to increase the valid time for caching tables and to reduce the frequency of lease renewal. + ### tidb_tmp_table_max_size New in v5.3.0 - Scope: SESSION | GLOBAL @@ -1759,6 +1823,26 @@ SET tidb_slow_log_threshold = 200; - Unit: Bytes - This variable is used to set the maximum size of a single [temporary table](/temporary-tables.md). Any temporary table with a size larger than this variable value causes error. +### tidb_top_sql_max_meta_count + +- Scope: GLOBAL +- Persists to cluster: Yes +- Default value: `5000` +- Range: `[1, 10000]` +- This variable is used to control the maximum number of SQL statement types collected by [Top SQL](/dashboard/top-sql.md) per minute. + +### tidb_top_sql_max_time_series_count + +> **Note:** +> +> Currently, the Top SQL page in TiDB Dashboard only displays the top 5 types of SQL queries that contribute the most to the load, which is irrelevant with the configuration of `tidb_top_sql_max_time_series_count`. + +- Scope: GLOBAL +- Persists to cluster: Yes +- Default value: `100` +- Range: `[1, 5000]` +- This variable is used to control how many SQL statements that contribute the most to the load (that is, top N) can be recorded by [Top SQL](/dashboard/top-sql.md) per minute. + ### tidb_tso_client_batch_max_wait_time New in v5.3.0 - Scope: GLOBAL @@ -1778,6 +1862,19 @@ SET tidb_slow_log_threshold = 200; > > Suppose that the TSO RPC latency increases for reasons other than a CPU usage bottleneck of the PD leader (such as network issues). In this case, increasing the value of `tidb_tso_client_batch_max_wait_time` might increase the execution latency in TiDB and affect the QPS performance of the cluster. +### tidb_txn_assertion_level New in v6.0.0 + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Default value: `OFF` +- Possible values: `OFF`, `FAST`, `STRICT` +- This variable is used to control the assertion level. Assertion is a consistency check between data and indexes, which checks whether a key being written exists in the transaction commit process. For more information, see [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md ). + + - `OFF`: Disable this check. + - `FAST`: Enable most of the check items, with almost no impact on performance. + - `STRICT`: Enable all check items, with a minor impact on pessimistic transaction performance when the system workload is high. + + ### tidb_txn_mode - Scope: SESSION | GLOBAL From 1f74831ed23ab699587a3987338ce5ad07e804fb Mon Sep 17 00:00:00 2001 From: Morgan Tocker Date: Wed, 13 Apr 2022 21:29:39 -0600 Subject: [PATCH 03/10] Add new changes --- system-variables.md | 229 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 188 insertions(+), 41 deletions(-) diff --git a/system-variables.md b/system-variables.md index de03cb710f9f1..2cbd4363b939d 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6,13 +6,11 @@ aliases: ['/tidb/dev/tidb-specific-system-variables','/docs/dev/system-variables # System Variables -TiDB system variables behave similar to MySQL with some differences, in that settings might apply on a `SESSION`, `INSTANCE`, or `GLOBAL` scope, or on a scope that combines `SESSION`, `INSTANCE`, or `GLOBAL`. +TiDB system variables behave similar to MySQL, in that settings apply on a `SESSION` or `GLOBAL` scope: -- Changes to `GLOBAL` scoped variables **only apply to new connection sessions with TiDB**. Currently active connection sessions are not affected. These changes are persisted and valid after restarts. -- Changes to `INSTANCE` scoped variables apply to all active or new connection sessions with the current TiDB instance immediately after the changes are made. Other TiDB instances are not affected. These changes are not persisted and become invalid after TiDB restarts. -- Variables can also have `NONE` scope. These variables are read-only, and are typically used to convey static information that will not change after a TiDB server has started. - -Variables can be set with the [`SET` statement](/sql-statements/sql-statement-set-variable.md) on a per-session, instance or global basis: +- Changes on a `SESSION` scope will only affect the current session. +- Changes on a `GLOBAL` scope apply immediately, provided that the variable is not also `SESSION` scoped. In which case all sessions (including your session) will continue to use their current session value. +- Changes are made using the [`SET` statement](/sql-statements/sql-statement-set-variable.md): ```sql # These two identical statements change a session variable @@ -26,9 +24,9 @@ SET GLOBAL tidb_distsql_scan_concurrency = 10; > **Note:** > -> Executing `SET GLOBAL` applies immediately on the TiDB server where the statement was issued. A notification is then sent to all TiDB servers to refresh their system variable cache, which will start immediately as a background operation. Because there is a risk that some TiDB servers might miss the notification, the system variable cache is also refreshed automatically every 30 seconds. This helps ensure that all servers are operating with the same configuration. +> Several `GLOBAL` variables persist to the TiDB cluster. For variables that specify `Persists to cluster: Yes` a notification is sent to all TiDB servers to refresh their system variable cache when the global variable is changed. Adding additional TiDB servers (or restarting existing TiDB servers) will automatically use the persisted configuration value. For variables that specify `Persists to cluster: No` any changes only apply to the local TiDB instance that you are connected to. In order to retain any values set, you will need to specify them in your `tidb.toml` configuration file. > -> TiDB differs from MySQL in that `GLOBAL` scoped variables **persist** through TiDB server restarts. Additionally, TiDB presents several MySQL variables as both readable and settable. This is required for compatibility, because it is common for both applications and connectors to read MySQL variables. For example, JDBC connectors both read and set query cache settings, despite not relying on the behavior. +> Additionally, TiDB presents several MySQL variables as both readable and settable. This is required for compatibility, because it is common for both applications and connectors to read MySQL variables. For example, JDBC connectors both read and set query cache settings, despite not relying on the behavior. > **Note:** > @@ -47,12 +45,14 @@ SET GLOBAL tidb_distsql_scan_concurrency = 10; ### allow_auto_random_explicit_insert New in v4.0.3 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - Determines whether to allow explicitly specifying the values of the column with the `AUTO_RANDOM` attribute in the `INSERT` statement. ### auto_increment_increment - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1` - Range: `[1, 65535]` - Controls the step size of `AUTO_INCREMENT` values to be allocated to a column. It is often used in combination with `auto_increment_offset`. @@ -60,6 +60,7 @@ SET GLOBAL tidb_distsql_scan_concurrency = 10; ### auto_increment_offset - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1` - Range: `[1, 65535]` - Controls the initial offset of `AUTO_INCREMENT` values to be allocated to a column. This setting is often used in combination with `auto_increment_increment`. For example: @@ -93,66 +94,77 @@ mysql> SELECT * FROM t1; ### autocommit - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - Controls whether statements should automatically commit when not in an explicit transaction. See [Transaction Overview](/transaction-overview.md#autocommit) for more information. ### block_encryption_mode - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `aes-128-ecb` - Defines the encryption mode for the `AES_ENCRYPT()` and `AES_DECRYPT()` functions. ### character_set_client - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4` - The character set for data sent from the client. See [Character Set and Collation](/character-set-and-collation.md) for details on the use of character sets and collations in TiDB. It is recommended to use [`SET NAMES`](/sql-statements/sql-statement-set-names.md) to change the character set when needed. ### character_set_connection - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4` - The character set for string literals that do not have a specified character set. ### character_set_database - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4` - This variable indicates the character set of the default database in use. **It is NOT recommended to set this variable**. When a new default database is selected, the server changes the variable value. ### character_set_results - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4` - The character set that is used when data is sent to the client. ### character_set_server - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4` - The default character set for the server. ### collation_connection - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4_bin` - This variable indicates the collation for string literals that do not have a specified collation. ### collation_database - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4_bin` - This variable indicates the collation of the default database in use. **It is NOT recommended to set this variable**. When a new default database is selected, the server changes the variable value. ### collation_server - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `utf8mb4_bin` - The default collation for the server. ### cte_max_recursion_depth - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1000` - Range: `[0, 4294967295]` - Controls the maximum recursion depth in Common Table Expressions. @@ -174,6 +186,7 @@ mysql> SELECT * FROM t1; ### default_authentication_plugin - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `mysql_native_password` - Possible values: `mysql_native_password`, `caching_sha2_password` - This variable sets the authentication method that the server advertises when the server-client connection is being established. Possible values for this variable are documented in [Authentication plugin status](/security-compatibility-with-mysql.md#authentication-plugin-status). @@ -182,6 +195,7 @@ mysql> SELECT * FROM t1; ### default_week_format - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 7]` - Sets the week format used by the `WEEK()` function. @@ -189,12 +203,14 @@ mysql> SELECT * FROM t1; ### foreign_key_checks - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - For compatibility, TiDB returns foreign key checks as `OFF`. ### group_concat_max_len - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1024` - Range: `[4, 18446744073709551615]` - The maximum buffer size for items in the `GROUP_CONCAT()` function. @@ -224,20 +240,23 @@ This variable is an alias for `last_insert_id`. ### init_connect - Scope: GLOBAL +- Persists to cluster: Yes - Default value: "" - The `init_connect` feature permits a SQL statement to be automatically executed when you first connect to a TiDB server. If you have the `CONNECTION_ADMIN` or `SUPER` privileges, this `init_connect` statement will not be executed. If the `init_connect` statement results in an error, your user connection will be terminated. ### innodb_lock_wait_timeout - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `50` -- Range: `[1, 1073741824]` +- Range: `[1, 3600]` - Unit: Seconds - The lock wait timeout for pessimistic transactions (default). ### interactive_timeout - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `28800` - Range: `[1, 31536000]` - Unit: Seconds @@ -277,6 +296,7 @@ This variable is an alias for `last_insert_id`. ### max_allowed_packet - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `67108864` - Range: `[1024, 1073741824]` - Unit: Bytes @@ -285,6 +305,7 @@ This variable is an alias for `last_insert_id`. ### max_execution_time - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 2147483647]` - Unit: Milliseconds @@ -332,6 +353,7 @@ This variable is an alias for `last_insert_id`. ### skip_name_resolve New in v5.2.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls whether the `tidb-server` instance resolves hostnames as a part of the connection handshake. - When the DNS is unreliable, you can enable this option to improve network performance. @@ -355,6 +377,7 @@ This variable is an alias for `last_insert_id`. ### sql_log_bin - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - Indicates whether to write changes to [TiDB Binlog](/tidb-binlog/tidb-binlog-overview.md) or not. @@ -365,12 +388,14 @@ This variable is an alias for `last_insert_id`. ### sql_mode - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION` - This variable controls a number of MySQL compatibility behaviors. See [SQL Mode](/sql-mode.md) for more information. ### sql_select_limit New in v4.0.2 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `18446744073709551615` - Range: `[0, 18446744073709551615]` - Unit: Rows @@ -403,6 +428,7 @@ This variable is an alias for `last_insert_id`. ### tidb_allow_batch_cop New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1` - Range: `[0, 2]` - This variable is used to control how TiDB sends a coprocessor request to TiFlash. It has the following values: @@ -414,6 +440,7 @@ This variable is an alias for `last_insert_id`. ### tidb_allow_fallback_to_tikv New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: "" - This variable is used to specify a list of storage engines that might fall back to TiKV. If the execution of a SQL statement fails due to a failure of the specified storage engine in the list, TiDB retries executing this SQL statement with TiKV. This variable can be set to "" or "tiflash". When this variable is set to "tiflash", if TiFlash returns a timeout error (error code: ErrTiFlashServerTimeout), TiDB retries executing this SQL statement with TiKV. @@ -426,6 +453,7 @@ This variable is an alias for `last_insert_id`. ### tidb_allow_mpp New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - Controls whether to use the MPP mode of TiFlash to execute queries. The value options are as follows: - `0` or `OFF`, which means that the MPP mode will not be used. @@ -442,6 +470,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_analyze_version New in v5.1.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `2` - Range: `[1, 2]` - Controls how TiDB collects statistics. @@ -450,12 +479,14 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_auto_analyze_end_time - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `23:59 +0000` - This variable is used to restrict the time window that the automatic update of statistics is permitted. For example, to only allow automatic statistics updates between 1AM and 3AM, set `tidb_auto_analyze_start_time='01:00 +0000'` and `tidb_auto_analyze_end_time='03:00 +0000'`. ### tidb_auto_analyze_ratio - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `0.5` - This variable is used to set the threshold when TiDB automatically executes [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md) in a background thread to update table statistics. For example, a value of 0.5 means that auto-analyze is triggered when greater than 50% of the rows in a table have been modified. Auto-analyze can be restricted to only execute during certain hours of the day by specifying `tidb_auto_analyze_start_time` and `tidb_auto_analyze_end_time`. @@ -466,12 +497,14 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_auto_analyze_start_time - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `00:00 +0000` - This variable is used to restrict the time window that the automatic update of statistics is permitted. For example, to only allow automatic statistics updates between 1AM and 3AM, set `tidb_auto_analyze_start_time='01:00 +0000'` and `tidb_auto_analyze_end_time='03:00 +0000'`. ### tidb_backoff_lock_fast - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `10` - Range: `[1, 2147483647]` - This variable is used to set the `backoff` time when the read request meets a lock. @@ -479,8 +512,9 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_backoff_weight - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `2` -- Range: `[1, 2147483647]` +- Range: `[0, 2147483647]` - This variable is used to increase the weight of the maximum time of TiDB `backoff`, that is, the maximum retry time for sending a retry request when an internal network or other component (TiKV, PD) failure is encountered. This variable can be used to adjust the maximum retry time and the minimum value is 1. For example, the base timeout for TiDB to take TSO from PD is 15 seconds. When `tidb_backoff_weight = 2`, the maximum timeout for taking TSO is: *base time \* 2 = 30 seconds*. @@ -490,6 +524,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_broadcast_join_threshold_count New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `10240` - Range: `[0, 9223372036854775807]` - Unit: Rows @@ -498,6 +533,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_broadcast_join_threshold_size New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `104857600` (100 MiB) - Range: `[0, 9223372036854775807]` - Unit: Bytes @@ -506,6 +542,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_build_stats_concurrency - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `4` - Unit: Threads - This variable is used to set the concurrency of executing the `ANALYZE` statement. @@ -514,6 +551,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_capture_plan_baselines New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - 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. @@ -542,6 +580,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_constraint_check_in_place - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This setting only applies to optimistic transactions. When this variable is set to `OFF`, checking for duplicate values in UNIQUE indexes is deferred until the transaction commits. This helps improve performance, but might be an unexpected behavior for some applications. See [Constraints](/constraints.md) for details. @@ -577,6 +616,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_ddl_error_count_limit - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `512` - Range: `[0, 9223372036854775807]` - This variable is used to set the number of retries when the DDL operation fails. When the number of retries exceeds the parameter value, the wrong DDL operation is canceled. @@ -584,6 +624,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_ddl_reorg_batch_size - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `256` - Range: `[32, 10240]` - Unit: Rows @@ -601,6 +642,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_ddl_reorg_worker_cnt - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `4` - Range: `[1, 256]` - Unit: Threads @@ -609,6 +651,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_disable_txn_auto_retry - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to set whether to disable the automatic retry of explicit optimistic transactions. The default value of `ON` means that transactions will not automatically retry in TiDB and `COMMIT` statements might return errors that need to be handled in the application layer. @@ -623,6 +666,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_distsql_scan_concurrency - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `15` - Range: `[1, 256]` - Unit: Threads @@ -634,6 +678,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_dml_batch_size - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 2147483647]` - Unit: Rows @@ -643,6 +688,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_1pc New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to specify whether to enable the one-phase commit feature for transactions that only affect one Region. Compared with the often-used two-phase commit, one-phase commit can greatly reduce the latency of transaction commit and increase the throughput. @@ -655,6 +701,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_amend_pessimistic_txn New in v4.0.7 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to control whether to enable the `AMEND TRANSACTION` feature. If you enable the `AMEND TRANSACTION` feature in a pessimistic transaction, when concurrent DDL operations and SCHEMA VERSION changes exist on tables associated with this transaction, TiDB attempts to amend the transaction. TiDB corrects the transaction commit to make the commit consistent with the latest valid SCHEMA VERSION so that the transaction can be successfully committed without getting the `Information schema is changed` error. This feature is effective on the following concurrent DDL operations: @@ -669,6 +716,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_async_commit New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls whether to enable the async commit feature for the second phase of the two-phase transaction commit to perform asynchronously in the background. Enabling this feature can reduce the latency of transaction commit. @@ -681,6 +729,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_auto_increment_in_generated - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to determine whether to include the `AUTO_INCREMENT` columns when creating a generated column or an expression index. @@ -691,6 +740,7 @@ Constraint checking is always performed in place for pessimistic transactions (d > Currently, cascades planner is an experimental feature. It is not recommended that you use it in production environments. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to control whether to enable the cascades planner. @@ -703,6 +753,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_clustered_index New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `INT_ONLY` - Possible values: `OFF`, `ON`, `INT_ONLY` - This variable is used to control whether to create the primary key as a [clustered index](/clustered-indexes.md) by default. "By default" here means that the statement does not explicitly specify the keyword `CLUSTERED`/`NONCLUSTERED`. Supported values are `OFF`, `ON`, and `INT_ONLY`: @@ -723,6 +774,7 @@ Constraint checking is always performed in place for pessimistic transactions (d > Currently, collecting statistics on `PREDICATE COLUMNS` is an experimental feature. It is not recommended that you use it in production environments. - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls whether to enable TiDB to collect `PREDICATE COLUMNS`. After enabling the collection, if you disable it, the information of previously collected `PREDICATE COLUMNS` is cleared. For details, see [Collect statistics on some columns](/statistics.md#collect-statistics-on-some-columns). @@ -744,6 +796,7 @@ Constraint checking is always performed in place for pessimistic transactions (d > Currently, `Fast Analyze` is an experimental feature. It is not recommended that you use it in production environments. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to set whether to enable the statistics `Fast Analyze` feature. - If the statistics `Fast Analyze` feature is enabled, TiDB randomly samples about 10,000 rows of data as statistics. When the data is distributed unevenly or the data size is small, the statistics accuracy is low. This might lead to a non-optimal execution plan, for example, selecting a wrong index. If the execution time of the regular `Analyze` statement is acceptable, it is recommended to disable the `Fast Analyze` feature. @@ -759,9 +812,18 @@ Constraint checking is always performed in place for pessimistic transactions (d > - Since v5.4.0, for a newly deployed TiDB cluster, this variable is enabled by default. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to control whether to enable the index merge feature. +### tidb_enable_legacy_instance_scope New in v6.0.0 + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Default value: `ON` +- This variable permits `INSTANCE` scoped variables to be set with `SET SESSION` as well as `SET GLOBAL` syntax. +- This option is enabled by default for compatibility with earlier versions of TiDB. + ### tidb_enable_list_partition New in v5.0 > **Warning:** @@ -769,18 +831,21 @@ Constraint checking is always performed in place for pessimistic transactions (d > Currently, List partition and List COLUMNS partition are experimental features. It is not recommended that you use it in production environments. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to set whether to enable the `LIST (COLUMNS) TABLE PARTITION` feature. -### `tidb_enable_mutation_checker` (New in v6.0.0) +### tidb_enable_mutation_checker New in v6.0.0 - Scope: SESSION | GLOBAL -- Default value: `ON` +- Persists to cluster: Yes +- Default value: `OFF` - This variable is used to control whether to enable TiDB mutation checker, which is a tool used to check consistency between data and indexes during the execution of DML statements. If the checker returns an error for a statement, TiDB rolls back the execution of the statement. Enabling this variable causes a slight increase in CPU usage. For more information, see [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md ). ### tidb_enable_noop_functions New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - Possible values: `OFF`, `ON`, `WARN` - By default, TiDB returns an error when you attempt to use the syntax for functionality that is not yet implemented. When the variable value is set to `ON`, TiDB silently ignores such cases of unavailable functionality, which is helpful if you cannot make changes to the SQL code. @@ -798,6 +863,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_paging New in v5.4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls whether to use the method of paging to send coprocessor requests in `IndexLookUp` operator. - User scenarios: For read queries that use `IndexLookup` and `Limit` and that `Limit` cannot be pushed down to `IndexScan`, there might be high latency for the read queries and high CPU usage for TiKV's `unified read pool`. In such cases, because the `Limit` operator only requires a small set of data, if you set `tidb_enable_paging` to `ON`, TiDB processes less data, which reduces query latency and resource consumption. @@ -806,12 +872,14 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_parallel_apply New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls whether to enable concurrency for the `Apply` operator. The number of concurrencies is controlled by the `tidb_executor_concurrency` variable. The `Apply` operator processes correlated subqueries and has no concurrency by default, so the execution speed is slow. Setting this variable value to `1` can increase concurrency and speed up execution. Currently, concurrency for `Apply` is disabled by default. ### tidb_enable_pseudo_for_outdated_stats New in v5.3.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls the behavior of the optimizer on using statistics of a table when the statistics are outdated. - The optimizer determines whether the statistics of a table is outdated in this way: since the last time `ANALYZE` is executed on a table to get the statistics, if 80% of the table rows are modified (the modified row count divided by the total row count), the optimizer determines that the statistics of this table is outdated. You can change this ratio using the [`pseudo-estimate-ratio`](/tidb-configuration-file.md#pseudo-estimate-ratio) configuration. @@ -821,6 +889,7 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_rate_limit_action - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls whether to enable the dynamic memory control feature for the operator that reads data. By default, this operator enables the maximum number of threads that [`tidb_distsql_scan_concurrency`](/system-variables.md#tidb_distsql_scan_concurrency) allows to read data. When the memory usage of a single SQL statement exceeds [`tidb_mem_quota_query`](/system-variables.md#tidb_mem_quota_query) each time, the operator that reads data stops one thread. - When the operator that reads data has only one thread left and the memory usage of a single SQL statement continues to exceed [`tidb_mem_quota_query`](/system-variables.md#tidb_mem_quota_query), this SQL statement triggers other memory control behaviors, such as [spilling data to disk](/tidb-configuration-file.md#oom-use-tmp-storage). @@ -834,12 +903,14 @@ Constraint checking is always performed in place for pessimistic transactions (d ### tidb_enable_stmt_summary New in v3.0.4 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `ON` - 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 `information_schema.STATEMENTS_SUMMARY` system table to identify and troubleshoot SQL performance issues. ### tidb_enable_strict_double_type_check New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to control if tables can be created with invalid definitions of type `DOUBLE`. This setting is intended to provide an upgrade path from earlier versions of TiDB, which were less strict in validating types. - The default value of `ON` is compatible with MySQL. @@ -864,6 +935,7 @@ Query OK, 0 rows affected (0.09 sec) ### tidb_enable_table_partition - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - Possible values: `OFF`, `ON`, `AUTO` - This variable is used to set whether to enable the `TABLE PARTITION` feature: @@ -874,6 +946,7 @@ Query OK, 0 rows affected (0.09 sec) ### tidb_enable_telemetry New in v4.0.2 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to dynamically control whether the telemetry collection in TiDB is enabled. By setting the value to `OFF`, 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. @@ -884,30 +957,14 @@ Query OK, 0 rows affected (0.09 sec) > Currently, Top SQL is an experimental feature. It is not recommended that you use it for production environments. - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to control whether to enable the [Top SQL](/dashboard/top-sql.md) feature. -### tidb_top_sql_max_meta_count (New in v6.0.0) - -- Scope: GLOBAL -- Default value: `5000` -- Range: `[1, 10000]` -- This variable is used to control the maximum number of SQL statement types collected by [Top SQL](/dashboard/top-sql.md) per minute. - -### tidb_top_sql_max_time_series_count (New in v6.0.0) - -- Scope: GLOBAL -- Default value: `100` -- Range: `[1, 5000]` -- This variable is used to control how many SQL statements that contribute the most to the load (that is, top N) can be recorded by [Top SQL](/dashboard/top-sql.md) per minute. - -> **Note:** -> -> Currently, the Top SQL page in TiDB Dashboard only displays the top 5 types of SQL queries that contribute the most to the load, which is irrelevant with the configuration of `tidb_top_sql_max_time_series_count`. - ### tidb_enable_tso_follower_proxy New in v5.3.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to enable the TSO Follower Proxy feature. When the value is `OFF`, TiDB only gets TSO from the PD leader. After this feature is enabled, TiDB gets TSO by evenly sending requests to all PD nodes and forwarding TSO requests through PD followers. This helps reduce the CPU pressure of PD leader. - Scenarios for enabling TSO Follower Proxy: @@ -921,12 +978,14 @@ Query OK, 0 rows affected (0.09 sec) ### tidb_enable_vectorized_expression New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to control whether to enable vectorized execution. ### tidb_enable_window_function - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to control whether to enable the support for window functions. Note that window functions may use reserved keywords. This might cause SQL statements that could be executed normally cannot be parsed after upgrading TiDB. In this case, you can set `tidb_enable_window_function` to `OFF`. @@ -944,6 +1003,7 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_evolve_plan_baselines New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - 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: @@ -953,12 +1013,14 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_evolve_plan_task_end_time New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `23:59 +0000` - This variable is used to set the end time of baseline evolution in a day. ### tidb_evolve_plan_task_max_time New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `600` - Range: `[-1, 9223372036854775807]` - Unit: Seconds @@ -967,12 +1029,14 @@ MPP is a distributed computing framework provided by the TiFlash engine, which a ### tidb_evolve_plan_task_start_time New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `00:00 +0000` - This variable is used to set the start time of baseline evolution in a day. ### tidb_executor_concurrency New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `5` - Range: `[1, 256]` - Unit: Threads @@ -1020,6 +1084,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_gc_concurrency New in v5.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1028,12 +1093,14 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_gc_enable New in v5.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `ON` - Enables garbage collection for TiKV. Disabling garbage collection will reduce system performance, as old versions of rows will no longer be purged. ### tidb_gc_life_time New in v5.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `10m0s` - Range: `[10m0s, 8760h0m0s]` - The time limit during which data is retained for each GC, in the format of Go Duration. When a GC happens, the current time minus this value is the safe point. @@ -1048,6 +1115,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_gc_run_interval New in v5.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `10m0s` - Range: `[10m0s, 8760h0m0s]` - Specifies the GC interval, in the format of Go Duration, for example, `"1h30m"`, and `"15m"` @@ -1059,6 +1127,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Currently, Green GC is an experimental feature. It is not recommended that you use it in production environments. - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `LEGACY` - Possible values: `PHYSICAL`, `LEGACY` - `LEGACY`: Uses the old way of scanning, that is, disable Green GC. @@ -1067,7 +1136,8 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_general_log -- Scope: INSTANCE +- Scope: GLOBAL +- Persists to cluster: No - Default value: `OFF` - This variable is used to set whether to record all SQL statements in the [log](/tidb-configuration-file.md#logfile). This feature is disabled by default. If maintenance personnel needs to trace all SQL statements when locating issues, they can enable this feature. - To see all records of this feature in the log, query the `"GENERAL_LOG"` string. The following information is recorded: @@ -1088,6 +1158,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1101,6 +1172,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1115,6 +1187,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1122,9 +1195,10 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified - When the parameter of the aggregate function is not distinct, `HashAgg` is run concurrently and respectively in two phases - the `partial` phase and the `final` phase. - A value of `-1` means that the value of `tidb_executor_concurrency` will be used instead. -### tidb_ignore_prepared_cache_close_stmt (New in v6.0.0) +### tidb_ignore_prepared_cache_close_stmt New in v6.0.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to set whether to ignore the commands for closing prepared statement cache. - When this variable is set to `ON`, the `COM_STMT_CLOSE` command of the Binary protocol and the [`DEALLOCATE PREPARE`](/sql-statements/sql-statement-deallocate.md) statement of the text protocol are ignored. For details, see [Ignore the `COM_STMT_CLOSE` command and the `DEALLOCATE PREPARE` statement](/sql-prepare-plan-cache.md#ignore-the-com_stmt_close-command-and-the-deallocate-prepare-statement). @@ -1132,6 +1206,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_index_join_batch_size - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `25000` - Range: `[1, 2147483647]` - Unit: Rows @@ -1145,6 +1220,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1159,6 +1235,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1168,6 +1245,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_index_lookup_size - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `20000` - Range: `[1, 2147483647]` - Unit: Rows @@ -1177,6 +1255,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_index_serial_scan_concurrency - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1` - Range: `[1, 256]` - Unit: Threads @@ -1186,6 +1265,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_init_chunk_size - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `32` - Range: `[1, 32]` - Unit: Rows @@ -1214,6 +1294,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_max_chunk_size - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1024` - Range: `[32, 2147483647]` - Unit: Rows @@ -1222,6 +1303,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_max_delta_schema_count New in v2.1.18 and v3.0.5 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `1024` - Range: `[100, 16384]` - This variable is used to set the maximum number of schema versions (the table IDs modified for corresponding versions) allowed to be cached. The value range is 100 ~ 16384. @@ -1229,16 +1311,18 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_mem_quota_apply_cache New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `33554432` (32 MiB) - Range: `[0, 9223372036854775807]` - Unit: Bytes - This variable is used to set the memory usage threshold of the local cache in the `Apply` operator. - The local cache in the `Apply` operator is used to speed up the computation of the `Apply` operator. You can set the variable to `0` to disable the `Apply` cache feature. -### tidb_mem_quota_binding_cache (New in v6.0.0) +### tidb_mem_quota_binding_cache New in v6.0.0 - Scope: GLOBAL -- Default value: `67108864` (64 MiB) +- Persists to cluster: Yes +- Default value: `67108864` - Range: `[0, 2147483647]` - Unit: Bytes - This variable is used to set the threshold of the memory used for caching bindings. @@ -1279,6 +1363,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_multi_statement_mode New in v4.0.11 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - Possible values: `OFF`, `ON`, `WARN` - This variable controls whether to allow multiple queries to be executed in the same `COM_QUERY` call. @@ -1311,6 +1396,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_opt_correlation_exp_factor - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `1` - Range: `[0, 2147483647]` - 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. @@ -1322,6 +1408,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_opt_correlation_threshold - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `0.9` - This variable is used to set the threshold value that determines whether to enable estimating the row count by using column order correlation. If the order correlation between the current column and the `handle` column exceeds the threshold value, this method is enabled. @@ -1363,12 +1450,14 @@ mysql> desc select count(distinct a) from test.t; ### tidb_opt_enable_correlation_adjustment - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to control whether the optimizer estimates the number of rows based on column order correlation ### tidb_opt_insubq_to_join_and_agg - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable is used to set whether to enable the optimization rule that converts a subquery to join and aggregation. - For example, after you enable this optimization rule, the subquery is converted as follows: @@ -1392,6 +1481,7 @@ mysql> desc select count(distinct a) from test.t; ### tidb_opt_limit_push_down_threshold - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `100` - Range: `[0, 2147483647]` - This variable is used to set the threshold that determines whether to push the Limit or TopN operator down to TiKV. @@ -1400,6 +1490,7 @@ mysql> desc select count(distinct a) from test.t; ### tidb_opt_prefer_range_scan New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - After you set the value of this variable to `ON`, the optimizer always prefers range scans over full table scans. - In the following example, before you enable `tidb_opt_prefer_range_scan`, the TiDB optimizer performs a full table scan. After you enable `tidb_opt_prefer_range_scan`, the optimizer selects an index range scan. @@ -1441,18 +1532,21 @@ explain select * from t where age=5; > Currently, the dynamic pruning mode for partitioned tables is an experimental feature. It is not recommended that you use it in production environments. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `static` - Specifies whether to enable `dynamic` mode for partitioned tables. For details about the dynamic pruning mode, see [Dynamic Pruning Mode for Partitioned Tables](/partitioned-table.md#dynamic-pruning-mode). ### tidb_persist_analyze_options New in v5.4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls whether to enable the [ANALYZE configuration persistence](/statistics.md#persist-analyze-configurations) feature. -### tidb_placement_mode (New in v6.0.0) +### tidb_placement_mode New in v6.0.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `STRICT` - Possible values: `STRICT`, `IGNORE` - This variable controls whether DDL statements ignore the [placement rules specified in SQL](/placement-rules-in-sql.md). When the variable value is `IGNORE`, all placement rule options are ignored. @@ -1472,6 +1566,7 @@ explain select * from t where age=5; > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[-1, 256]` - Unit: Threads @@ -1492,7 +1587,7 @@ Usage example: SET tidb_query_log_max_len = 20 ``` -### tidb_rc_read_check_ts (New in v6.0.0) +### tidb_rc_read_check_ts New in v6.0.0 > **Warning:** > @@ -1500,6 +1595,7 @@ SET tidb_query_log_max_len = 20 > - If your client uses a cursor, it is not recommended to enable `tidb_rc_read_check_ts` in case that the previous batch of returned data has already been used by the client and the statement eventually fails. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to optimize the timestamp acquisition, which is suitable for scenarios with read-committed isolation level where read-write conflicts are rare. Enabling this variable can avoid the latency and cost of getting the global timestamp, and can optimize the transaction-level read latency. - If read-write conflicts are severe, enabling this feature will increase the cost and latency of getting the global timestamp, and might cause performance regression. For details, see [Read Committed isolation level](/transaction-isolation-levels.md#read-committed-isolation-level). @@ -1507,7 +1603,8 @@ SET tidb_query_log_max_len = 20 ### tidb_read_staleness New in v5.4.0 - Scope: SESSION -- Default value: "" +- Default value: `0` +- Range: `[-2147483648, 0]` - This variable is used to set the time range of historical data that TiDB can read in the current session. After setting the value, TiDB selects a timestamp as new as possible from the range allowed by this variable, and all subsequent read operations are performed against this timestamp. For example, if the value of this variable is set to `-5`, on the condition that TiKV has the corresponding historical version's data, TiDB selects a timestamp as new as possible within a 5-second time range. ### tidb_record_plan_in_slow_log @@ -1519,6 +1616,7 @@ SET tidb_query_log_max_len = 20 ### tidb_redact_log - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls whether to hide user information in the SQL statement being recorded into the TiDB log and slow log. - When you set the variable to `1`, user information is hidden. For example, if the executed SQL statement is `insert into t values (1,2)`, the statement is recorded as `insert into t values (?,?)` in the log. @@ -1526,6 +1624,7 @@ SET tidb_query_log_max_len = 20 ### tidb_regard_null_as_point New in v5.4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls whether the optimizer can use a query condition including null equivalence as a prefix condition for index access. - This variable is enabled by default. When it is enabled, the optimizer can reduce the volume of index data to be accessed, which accelerates query execution. For example, if a query involves multiple-column indexes `index(a, b)` and the query condition contains `a<=>null and b=1`, the optimizer can use both `a<=>null` and `b=1` in the query condition for index access. If the variable is disabled, because `a<=>null and b=1` includes the null equivalence condition, the optimizer does not use `b=1` for index access. @@ -1533,6 +1632,7 @@ SET tidb_query_log_max_len = 20 ### tidb_replica_read New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `leader` - Possible values: `leader`, `follower`, `leader-and-follower`, `closest-replicas` - This variable is used to control where TiDB reads data. Here are three options: @@ -1544,6 +1644,7 @@ SET tidb_query_log_max_len = 20 ### tidb_retry_limit - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `10` - Range: `[-1, 9223372036854775807]` - This variable is used to set the maximum number of the retries for optimistic transactions. When a transaction encounters retryable errors (such as transaction conflicts, very slow transaction commit, or table schema changes), this transaction is re-executed according to this variable. Note that setting `tidb_retry_limit` to `0` disables the automatic retry. This variable only applies to optimistic transactions, not to pessimistic transactions. @@ -1551,6 +1652,7 @@ SET tidb_query_log_max_len = 20 ### tidb_row_format_version - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `2` - Range: `[1, 2]` - Controls the format version of the newly saved data in the table. In TiDB v4.0, the [new storage row format](https://github.com/pingcap/tidb/blob/master/docs/design/2018-07-19-row-format.md) version `2` is used by default to save new data. @@ -1560,6 +1662,7 @@ SET tidb_query_log_max_len = 20 ### tidb_scatter_region - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - By default, Regions are split for a new table when it is being created in TiDB. After this variable is enabled, the newly split Regions are scattered immediately during the execution of the `CREATE TABLE` statement. This applies to the scenario where data need to be written in batches right after the tables are created in batches, because the newly split Regions can be scattered in TiKV beforehand and do not have to wait to be scheduled by PD. To ensure the continuous stability of writing data in batches, the `CREATE TABLE` statement returns success only after the Regions are successfully scattered. This makes the statement's execution time multiple times longer than that when you disable this variable. - Note that if `SHARD_ROW_ID_BITS` and `PRE_SPLIT_REGIONS` have been set when a table is created, the specified number of Regions are evenly split after the table creation. @@ -1567,6 +1670,7 @@ SET tidb_query_log_max_len = 20 ### tidb_skip_ascii_check New in v5.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to set whether to skip ASCII validation. - Validating ASCII characters affects the performance. When you are sure that the input characters are valid ASCII characters, you can set the variable value to `ON`. @@ -1574,6 +1678,7 @@ SET tidb_query_log_max_len = 20 ### tidb_skip_isolation_level_check - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - After this switch is enabled, if an isolation level unsupported by TiDB is assigned to `tx_isolation`, no error is reported. This helps improve compatibility with applications that set (but do not depend on) a different isolation level. @@ -1590,6 +1695,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) ### tidb_skip_utf8_check - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to set whether to skip UTF-8 validation. - Validating UTF-8 characters affects the performance. When you are sure that the input characters are valid UTF-8 characters, you can set the variable value to `ON`. @@ -1627,6 +1733,7 @@ SET tidb_slow_log_threshold = 200; > Currently, synchronously loading statistics is an experimental feature. It is not recommended that you use it in production environments. - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable controls how TiDB behaves when the waiting time of SQL optimization reaches the timeout to synchronously load complete column statistics. The default value `OFF` means that SQL execution fails after the timeout. If you set this variable to `ON`, the SQL optimization gets back to using pseudo statistics after the timeout. @@ -1637,6 +1744,7 @@ SET tidb_slow_log_threshold = 200; > Currently, synchronously loading statistics is an experimental feature. It is not recommended that you use it in production environments. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 2147483647]` - Unit: Milliseconds @@ -1645,6 +1753,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_stmt_summary_history_size New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `24` - Range: `[0, 255]` - This variable is used to set the history capacity of [statement summary tables](/statement-summary-tables.md). @@ -1652,12 +1761,14 @@ SET tidb_slow_log_threshold = 200; ### tidb_stmt_summary_internal_query New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to control whether to include the SQL information of TiDB in [statement summary tables](/statement-summary-tables.md). ### tidb_stmt_summary_max_sql_length New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `4096` - Range: `[0, 2147483647]` - This variable is used to control the length of the SQL string in [statement summary tables](/statement-summary-tables.md). @@ -1665,6 +1776,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_stmt_summary_max_stmt_count New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `3000` - Range: `[1, 32767]` - This variable is used to set the maximum number of statements that [statement summary tables](/statement-summary-tables.md) store in memory. @@ -1672,6 +1784,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_stmt_summary_refresh_interval New in v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `1800` - Range: `[1, 2147483647]` - Unit: Seconds @@ -1680,19 +1793,22 @@ SET tidb_slow_log_threshold = 200; ### tidb_store_limit New in v3.0.4 and v4.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 9223372036854775807]` - 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_sysdate_is_now （New in v6.0.0） +### tidb_sysdate_is_now New in v6.0.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `OFF` - This variable is used to control whether the `SYSDATE` function can be replaced by the `NOW` function. This configuration item has the same effect as the MySQL option [`sysdate-is-now`](https://dev.mysql.com/doc/refman/8.0/en/server-options.html#option_mysqld_sysdate-is-now). -### tidb_table_cache_lease (New in v6.0.0) +### tidb_table_cache_lease New in v6.0.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `3` - Range: `[1, 10]` - Unit: Seconds @@ -1701,14 +1817,36 @@ SET tidb_slow_log_threshold = 200; ### tidb_tmp_table_max_size New in v5.3.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `67108864` - Range: `[1048576, 137438953472]` - Unit: Bytes - This variable is used to set the maximum size of a single [temporary table](/temporary-tables.md). Any temporary table with a size larger than this variable value causes error. +### tidb_top_sql_max_meta_count + +- Scope: GLOBAL +- Persists to cluster: Yes +- Default value: `5000` +- Range: `[1, 10000]` +- This variable is used to control the maximum number of SQL statement types collected by [Top SQL](/dashboard/top-sql.md) per minute. + +### tidb_top_sql_max_time_series_count + +> **Note:** +> +> Currently, the Top SQL page in TiDB Dashboard only displays the top 5 types of SQL queries that contribute the most to the load, which is irrelevant with the configuration of `tidb_top_sql_max_time_series_count`. + +- Scope: GLOBAL +- Persists to cluster: Yes +- Default value: `100` +- Range: `[1, 5000]` +- This variable is used to control how many SQL statements that contribute the most to the load (that is, top N) can be recorded by [Top SQL](/dashboard/top-sql.md) per minute. + ### tidb_tso_client_batch_max_wait_time New in v5.3.0 - Scope: GLOBAL +- Persists to cluster: Yes - Default value: `0` - Range: `[0, 10]` - Unit: Milliseconds @@ -1724,10 +1862,11 @@ SET tidb_slow_log_threshold = 200; > > Suppose that the TSO RPC latency increases for reasons other than a CPU usage bottleneck of the PD leader (such as network issues). In this case, increasing the value of `tidb_tso_client_batch_max_wait_time` might increase the execution latency in TiDB and affect the QPS performance of the cluster. -### `tidb_txn_assertion_level` (New in v6.0.0) +### tidb_txn_assertion_level New in v6.0.0 - Scope: SESSION | GLOBAL -- Default value: `FAST` +- Persists to cluster: Yes +- Default value: `OFF` - Possible values: `OFF`, `FAST`, `STRICT` - This variable is used to control the assertion level. Assertion is a consistency check between data and indexes, which checks whether a key being written exists in the transaction commit process. For more information, see [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md ). @@ -1735,9 +1874,11 @@ SET tidb_slow_log_threshold = 200; - `FAST`: Enable most of the check items, with almost no impact on performance. - `STRICT`: Enable all check items, with a minor impact on pessimistic transaction performance when the system workload is high. + ### tidb_txn_mode - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `pessimistic` - Possible values: `pessimistic`, `optimistic` - This variable is used to set the transaction mode. TiDB 3.0 supports the pessimistic transactions. Since TiDB 3.0.8, the [pessimistic transaction mode](/pessimistic-transaction.md) is enabled by default. @@ -1747,6 +1888,7 @@ SET tidb_slow_log_threshold = 200; ### tidb_use_plan_baselines New in v4.0 - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - 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 `OFF` value. For the use of the execution plan binding, see [Execution Plan Binding](/sql-plan-management.md#create-a-binding). @@ -1774,6 +1916,7 @@ SET tidb_slow_log_threshold = 200; > Since v5.0, this variable is deprecated. Instead, use [`tidb_executor_concurrency`](#tidb_executor_concurrency-new-in-v50) for setting. - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `-1` - Range: `[1, 256]` - Unit: Threads @@ -1783,6 +1926,7 @@ SET tidb_slow_log_threshold = 200; ### time_zone - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `SYSTEM` - This variable returns the current time zone. Values can be specified as either an offset such as '-8:00' or a named zone 'America/Los_Angeles'. - The value `SYSTEM` means that the time zone should be the same as the system host, which is available via the [`system_time_zone`](#system_time_zone) variable. @@ -1796,6 +1940,7 @@ SET tidb_slow_log_threshold = 200; ### transaction_isolation - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `REPEATABLE-READ` - Possible values: `READ-UNCOMMITTED`, `READ-COMMITTED`, `REPEATABLE-READ`, `SERIALIZABLE` - This variable sets the transaction isolation. TiDB advertises `REPEATABLE-READ` for compatibility with MySQL, but the actual isolation level is Snapshot Isolation. See [transaction isolation levels](/transaction-isolation-levels.md) for further details. @@ -1831,6 +1976,7 @@ This variable is an alias for `transaction_isolation`. ### wait_timeout - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `28800` - Range: `[0, 31536000]` - Unit: Seconds @@ -1845,5 +1991,6 @@ This variable is an alias for `transaction_isolation`. ### windowing_use_high_precision - Scope: SESSION | GLOBAL +- Persists to cluster: Yes - Default value: `ON` - This variable controls whether to use the high precision mode when computing the window functions. From 89d61fd459e4e3ff89d419c69c60d37f338123bf Mon Sep 17 00:00:00 2001 From: Morgan Tocker Date: Wed, 13 Apr 2022 21:41:18 -0600 Subject: [PATCH 04/10] fix extra new line --- system-variables.md | 1 - 1 file changed, 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 2cbd4363b939d..40cbf3471839e 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1874,7 +1874,6 @@ SET tidb_slow_log_threshold = 200; - `FAST`: Enable most of the check items, with almost no impact on performance. - `STRICT`: Enable all check items, with a minor impact on pessimistic transaction performance when the system workload is high. - ### tidb_txn_mode - Scope: SESSION | GLOBAL From 85913bffb3b083d60247b1897dd45e8b71137f5d Mon Sep 17 00:00:00 2001 From: Morgan Tocker Date: Wed, 13 Apr 2022 21:52:06 -0600 Subject: [PATCH 05/10] update links based on anchor changing --- releases/release-6.0.0-dmr.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/releases/release-6.0.0-dmr.md b/releases/release-6.0.0-dmr.md index 619f7b18832b1..2d15289e73253 100644 --- a/releases/release-6.0.0-dmr.md +++ b/releases/release-6.0.0-dmr.md @@ -288,8 +288,8 @@ TiDB v6.0.0 is a DMR, and its version is 6.0.0-DMR. | [`tidb_rc_read_check_ts`](/system-variables.md#tidb_rc_read_check_ts-new-in-v600) | Newly added |
  • Optimizes read statement latency within a transaction. If read/write conflicts are more severe, turning this variable on will add additional overhead and latency, causing regressions in performance. The default value is `off`.
  • This variable is not yet compatible with [replica-read](/system-variables.md#tidb_replica_read-new-in-v40). If a read request has `tidb_rc_read_check_ts` on, it might not be able to use replica-read. Do not turn on both variables at the same time.
| | [`tidb_sysdate_is_now`](/system-variables.md#tidb_sysdate_is_now-new-in-v600) | Newly added | Controls whether the `SYSDATE` function can be replaced by the `NOW` function. This configuration item has the same effect as the MySQL option [`sysdate-is-now`](https://dev.mysql.com/doc/refman/8.0/en/server-options.html#option_mysqld_sysdate-is-now). The default value is `OFF`. | | [`tidb_table_cache_lease`](/system-variables.md#tidb_table_cache_lease-new-in-v600) | Newly added | Controls the lease time of [table cache](/cached-tables.md), in seconds. The default value is `3`. | -| [`tidb_top_sql_max_meta_count`](/system-variables.md#tidb_top_sql_max_meta_count-new-in-v600) | Newly added | Controls the maximum number of SQL statement types collected by [Top SQL](/dashboard/top-sql.md) per minute. The default value is `5000`. | -| [`tidb_top_sql_max_time_series_count`](/system-variables.md#tidb_top_sql_max_time_series_count-new-in-v600) | Newly added | Controls how many SQL statements that contribute the most to the load (that is, top N) can be recorded by [Top SQL](/dashboard/top-sql.md) per minute. The default value is `100`. | +| [`tidb_top_sql_max_meta_count`](/system-variables.md#tidb_top_sql_max_meta_count-span-classversion-marknew-in-v600) | Newly added | Controls the maximum number of SQL statement types collected by [Top SQL](/dashboard/top-sql.md) per minute. The default value is `5000`. | +| [`tidb_top_sql_max_time_series_count`](/system-variables.md#tidb_top_sql_max_time_series_count-span-classversion-marknew-in-v600) | Newly added | Controls how many SQL statements that contribute the most to the load (that is, top N) can be recorded by [Top SQL](/dashboard/top-sql.md) per minute. The default value is `100`. | | [`tidb_txn_assertion_level`](/system-variables.md#tidb_txn_assertion_level-new-in-v600) | Newly added | Controls the assertion level. The assertion is a consistency check between data and indexes, which checks whether a key being written exists in the transaction commit process. By default, the check enables most of the check items, with almost no impact on performance. | ### Configuration file parameters From 4b326774ec397b25c5d0e1b852e26434341d4e62 Mon Sep 17 00:00:00 2001 From: Morgan Tocker Date: Wed, 13 Apr 2022 22:01:07 -0600 Subject: [PATCH 06/10] fix anchors again --- releases/release-6.0.0-dmr.md | 4 ++-- system-variables.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/releases/release-6.0.0-dmr.md b/releases/release-6.0.0-dmr.md index 2d15289e73253..619f7b18832b1 100644 --- a/releases/release-6.0.0-dmr.md +++ b/releases/release-6.0.0-dmr.md @@ -288,8 +288,8 @@ TiDB v6.0.0 is a DMR, and its version is 6.0.0-DMR. | [`tidb_rc_read_check_ts`](/system-variables.md#tidb_rc_read_check_ts-new-in-v600) | Newly added |
  • Optimizes read statement latency within a transaction. If read/write conflicts are more severe, turning this variable on will add additional overhead and latency, causing regressions in performance. The default value is `off`.
  • This variable is not yet compatible with [replica-read](/system-variables.md#tidb_replica_read-new-in-v40). If a read request has `tidb_rc_read_check_ts` on, it might not be able to use replica-read. Do not turn on both variables at the same time.
| | [`tidb_sysdate_is_now`](/system-variables.md#tidb_sysdate_is_now-new-in-v600) | Newly added | Controls whether the `SYSDATE` function can be replaced by the `NOW` function. This configuration item has the same effect as the MySQL option [`sysdate-is-now`](https://dev.mysql.com/doc/refman/8.0/en/server-options.html#option_mysqld_sysdate-is-now). The default value is `OFF`. | | [`tidb_table_cache_lease`](/system-variables.md#tidb_table_cache_lease-new-in-v600) | Newly added | Controls the lease time of [table cache](/cached-tables.md), in seconds. The default value is `3`. | -| [`tidb_top_sql_max_meta_count`](/system-variables.md#tidb_top_sql_max_meta_count-span-classversion-marknew-in-v600) | Newly added | Controls the maximum number of SQL statement types collected by [Top SQL](/dashboard/top-sql.md) per minute. The default value is `5000`. | -| [`tidb_top_sql_max_time_series_count`](/system-variables.md#tidb_top_sql_max_time_series_count-span-classversion-marknew-in-v600) | Newly added | Controls how many SQL statements that contribute the most to the load (that is, top N) can be recorded by [Top SQL](/dashboard/top-sql.md) per minute. The default value is `100`. | +| [`tidb_top_sql_max_meta_count`](/system-variables.md#tidb_top_sql_max_meta_count-new-in-v600) | Newly added | Controls the maximum number of SQL statement types collected by [Top SQL](/dashboard/top-sql.md) per minute. The default value is `5000`. | +| [`tidb_top_sql_max_time_series_count`](/system-variables.md#tidb_top_sql_max_time_series_count-new-in-v600) | Newly added | Controls how many SQL statements that contribute the most to the load (that is, top N) can be recorded by [Top SQL](/dashboard/top-sql.md) per minute. The default value is `100`. | | [`tidb_txn_assertion_level`](/system-variables.md#tidb_txn_assertion_level-new-in-v600) | Newly added | Controls the assertion level. The assertion is a consistency check between data and indexes, which checks whether a key being written exists in the transaction commit process. By default, the check enables most of the check items, with almost no impact on performance. | ### Configuration file parameters diff --git a/system-variables.md b/system-variables.md index 40cbf3471839e..7c38ea7bd5c54 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1823,7 +1823,7 @@ SET tidb_slow_log_threshold = 200; - Unit: Bytes - This variable is used to set the maximum size of a single [temporary table](/temporary-tables.md). Any temporary table with a size larger than this variable value causes error. -### tidb_top_sql_max_meta_count +### tidb_top_sql_max_meta_count New in v6.0.0 - Scope: GLOBAL - Persists to cluster: Yes @@ -1831,7 +1831,7 @@ SET tidb_slow_log_threshold = 200; - Range: `[1, 10000]` - This variable is used to control the maximum number of SQL statement types collected by [Top SQL](/dashboard/top-sql.md) per minute. -### tidb_top_sql_max_time_series_count +### tidb_top_sql_max_time_series_count New in v6.0.0 > **Note:** > From 478f5cb963def09509f72ca0c1874208b3b33d9a Mon Sep 17 00:00:00 2001 From: Morgan Tocker Date: Mon, 25 Apr 2022 21:05:26 -0600 Subject: [PATCH 07/10] Update system-variables.md --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 7c38ea7bd5c54..8610654ea10f1 100644 --- a/system-variables.md +++ b/system-variables.md @@ -821,7 +821,7 @@ Constraint checking is always performed in place for pessimistic transactions (d - Scope: SESSION | GLOBAL - Persists to cluster: Yes - Default value: `ON` -- This variable permits `INSTANCE` scoped variables to be set with `SET SESSION` as well as `SET GLOBAL` syntax. +- This variable permits `INSTANCE` scoped variables to be set using the `SET SESSION` as well as `SET GLOBAL` syntax. - This option is enabled by default for compatibility with earlier versions of TiDB. ### tidb_enable_list_partition New in v5.0 From bb93f4afa7739334890ad87fa21181eeb595ac04 Mon Sep 17 00:00:00 2001 From: Morgan Tocker Date: Mon, 25 Apr 2022 21:05:52 -0600 Subject: [PATCH 08/10] Update system-variables.md Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 8610654ea10f1..9b7cfbe1e0b15 100644 --- a/system-variables.md +++ b/system-variables.md @@ -9,7 +9,7 @@ aliases: ['/tidb/dev/tidb-specific-system-variables','/docs/dev/system-variables TiDB system variables behave similar to MySQL, in that settings apply on a `SESSION` or `GLOBAL` scope: - Changes on a `SESSION` scope will only affect the current session. -- Changes on a `GLOBAL` scope apply immediately, provided that the variable is not also `SESSION` scoped. In which case all sessions (including your session) will continue to use their current session value. +- Changes on a `GLOBAL` scope apply immediately. If this variable is also`SESSION` scoped, all sessions (including your session) will continue to use their current session value. - Changes are made using the [`SET` statement](/sql-statements/sql-statement-set-variable.md): ```sql From 718605c595f1d1bfe3bed72e0d2b6defd08d6fa4 Mon Sep 17 00:00:00 2001 From: Morgan Tocker Date: Mon, 25 Apr 2022 21:06:11 -0600 Subject: [PATCH 09/10] Update system-variables.md Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- system-variables.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 9b7cfbe1e0b15..319a2dd444460 100644 --- a/system-variables.md +++ b/system-variables.md @@ -24,7 +24,9 @@ SET GLOBAL tidb_distsql_scan_concurrency = 10; > **Note:** > -> Several `GLOBAL` variables persist to the TiDB cluster. For variables that specify `Persists to cluster: Yes` a notification is sent to all TiDB servers to refresh their system variable cache when the global variable is changed. Adding additional TiDB servers (or restarting existing TiDB servers) will automatically use the persisted configuration value. For variables that specify `Persists to cluster: No` any changes only apply to the local TiDB instance that you are connected to. In order to retain any values set, you will need to specify them in your `tidb.toml` configuration file. +> Several `GLOBAL` variables persist to the TiDB cluster. Some variables in this document have a `Persists to cluster` setting, which can be configured to `Yes` or `No`. +> - For variables with the `Persists to cluster: Yes` setting, when a global variable is changed, a notification is sent to all TiDB servers to refresh their system variable cache. When you add additional TiDB servers or restart existing TiDB servers, the persisted configuration value is automatically used. +> - For variables with the `Persists to cluster: No` setting, changes only apply to the local TiDB instance that you are connected to. To retain any values set, you need to specify the variables in your `tidb.toml` configuration file. > > Additionally, TiDB presents several MySQL variables as both readable and settable. This is required for compatibility, because it is common for both applications and connectors to read MySQL variables. For example, JDBC connectors both read and set query cache settings, despite not relying on the behavior. From 010079ced9a013bf245661a91357e7b0f3d4f925 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Tue, 26 Apr 2022 11:22:48 +0800 Subject: [PATCH 10/10] fix ci --- system-variables.md | 1 + 1 file changed, 1 insertion(+) diff --git a/system-variables.md b/system-variables.md index 319a2dd444460..7053e1d16dc61 100644 --- a/system-variables.md +++ b/system-variables.md @@ -25,6 +25,7 @@ SET GLOBAL tidb_distsql_scan_concurrency = 10; > **Note:** > > Several `GLOBAL` variables persist to the TiDB cluster. Some variables in this document have a `Persists to cluster` setting, which can be configured to `Yes` or `No`. +> > - For variables with the `Persists to cluster: Yes` setting, when a global variable is changed, a notification is sent to all TiDB servers to refresh their system variable cache. When you add additional TiDB servers or restart existing TiDB servers, the persisted configuration value is automatically used. > - For variables with the `Persists to cluster: No` setting, changes only apply to the local TiDB instance that you are connected to. To retain any values set, you need to specify the variables in your `tidb.toml` configuration file. >