Document missing system variables

[ghost]

Change Request

This repository is ONLY used to solve issues related to DOCS.
For other issues (related to TiDB, PD, etc), please move to other repositories.

Please answer the following questions before submitting your issue. Thanks!

1. Describe what you find is inappropriate or missing in the existing docs.

In #3152 I compared the current output of SHOW GLOBAL VARIABLES to what is in the documentation. The following system variables are not documented:

• allow_auto_random_explicit_insert improve system-variables documentation #4598
• tidb_batch_commit add the variables of batch-dml #10872
• tidb_batch_delete add the variables of batch-dml #10872
• tidb_dml_batch_size stmt-reference, sysvars: Document dml-batch-size #3838
• tidb_enable_clustered_index add system variable 'tidb_enable_clustered_index' for v5.0 #3907
• tidb_enable_collect_execution_info improve system-variables documentation #4598
• tidb_enable_radix_join
• tidb_executor_concurrency improve system-variables documentation #4598
• tidb_opt_concurrency_factor planner: add docs for some variables #9943
• tidb_opt_copcpu_factor planner: add docs for some variables #9943, sysvar: fix wrong variables names #10782
• tidb_opt_cpu_factor planner: add docs for some variables #9943
• tidb_opt_desc_factor planner: add docs for some variables #9943
• tidb_opt_disk_factor planner: add docs for some variables #9943
• tidb_opt_join_reorder_threshold sysvar: add 1 var #10799
• tidb_opt_memory_factor planner: add docs for some variables #9943
• tidb_opt_network_factor planner: add docs for some variables #9943
• tidb_opt_scan_factor planner: add docs for some variables #9943
• tidb_opt_seek_factor planner: add docs for some variables #9943
• tidb_optimizer_selectivity_level statistics: add some doc for the exp feature #9891
• tidb_shard_allocate_step sysvar: add 2 sysvars #10662
• tidb_skip_ascii_check system-variables: ensure alphabetical order #5711
• tidb_slow_log_masking

2. Describe your suggestion or addition.

Please explain what they do :-)

3. Provide some reference materials (documents, websites, etc) if you could.

[yikeke]

This PR in docs-cn might cover some of the variables of your list. I'm translating this PR and the English version is expected to be merged by the end of this week.

[ghost]

Yes, it does look like there are a lot in that PR! Let me know if there is anything I can do to help merge the two sets of changes better.

[yikeke]

Yes, it does look like there are a lot in that PR! Let me know if there is anything I can do to help merge the two sets of changes better.

Sure, I'll see what I can do to reduce the conflicts between the two sets of changes.

[yikeke]

Yes, it does look like there are a lot in that PR! Let me know if there is anything I can do to help merge the two sets of changes better.

The English version of that PR is opened: #3215. Please take a look and let's figure out a way to merge the two sets of changes better. @nullnotnil

[ghost]

The English version of that PR is opened: #3215. Please take a look and let's figure out a way to merge the two sets of changes better. @nullnotnil

I will let #3215 merge first and then rebase my changes. I think this makes the most sense.

[ghost]

I have updated this issue to remove what was documented in #3215

[ghost]

It looks like documenting tidb_dml_batch_size is important because of a behavior change in master. Previously I used LOAD DATA to import the example database in the docs. Because of pingcap/tidb#18807 the example now breaks by default due to a transaction too large error.

I can increase the transaction size, or set tidb_dml_batch_size to a non-zero value, but the error message is not entirely clear. I think the new behavior is better, so I suggest updating https://docs.pingcap.com/tidb/dev/sql-statement-load-data (which is now out of date for master as well) to say that there was a behavior change.

I will send a PR shortly.

cc @tina77fritz @jackysp @cfzjywxk

[github-actions]

This issue is stale because it has been open for 60 days with no activity. If no comment has been made and the lifecycle/stale label is not removed, this issue will be closed in 15 days.

[github-actions]

This issue is stale because it has been open for 60 days with no activity. If no comment has been made and the lifecycle/stale label is not removed, this issue will be closed in 15 days.

[morgo]

/unlabel lifecycle/stale

[morgo]

The options for character set and collation need documentation:

| character_set_client                                   | utf8mb4                                                                                                                                                                                                                                                                                                                                          |
| character_set_connection                               | utf8mb4                                                                                                                                                                                                                                                                                                                                          |
| character_set_database                                 | utf8mb4                                                                                                                                                                                                                                                                                                                                          |
| character_set_filesystem                               | binary                                                                                                                                                                                                                                                                                                                                           |
| character_set_results                                  | utf8mb4                                                                                                                                                                                                                                                                                                                                          |
| character_set_server                                   | utf8mb4                                                                                                                                                                                                                                                                                                                                          |
| character_set_system                                   | utf8                                                                                                                                                                                                                                                                                                                                             |
| collation_connection                                   | utf8mb4_bin                                                                                                                                                                                                                                                                                                                                      |
| collation_database                                     | utf8mb4_bin                                                                                                                                                                                                                                                                                                                                      |
| collation_server                                       | utf8mb4_bin                                                                                                                                                                                                                

[TomShawn]

The options for character set and collation need documentation:

| character_set_client                                   | utf8mb4                                                                                                                                                                                                                                                                                                                                          |
| character_set_connection                               | utf8mb4                                                                                                                                                                                                                                                                                                                                          |
| character_set_database                                 | utf8mb4                                                                                                                                                                                                                                                                                                                                          |
| character_set_filesystem                               | binary                                                                                                                                                                                                                                                                                                                                           |
| character_set_results                                  | utf8mb4                                                                                                                                                                                                                                                                                                                                          |
| character_set_server                                   | utf8mb4                                                                                                                                                                                                                                                                                                                                          |
| character_set_system                                   | utf8                                                                                                                                                                                                                                                                                                                                             |
| collation_connection                                   | utf8mb4_bin                                                                                                                                                                                                                                                                                                                                      |
| collation_database                                     | utf8mb4_bin                                                                                                                                                                                                                                                                                                                                      |
| collation_server                                       | utf8mb4_bin                                                                                                                                                                                                                

@wjhuang2016 PTAL

[dveeden]

@morgo is this still an issue after your recent improvements?

[morgo]

Yes. It is worse than this :( This list was created by filtering on SHOW VARIABLES LIKE 'tidb_%'.

Here is a more accurate list of what is not documented but should be:

case variable.BlockEncryptionMode, variable.CharacterSetClient, variable.CharacterSetConnection, variable.CharsetDatabase,
		variable.CharacterSetFilesystem, variable.CharacterSetResults, variable.CharacterSetServer, variable.CollationConnection, variable.CollationDatabase,
		variable.CollationServer, variable.CTEMaxRecursionDepth, variable.DataDir, variable.DefaultWeekFormat, variable.ErrorCount, variable.GroupConcatMaxLen,
		"have_openssl", "have_ssl", variable.InitConnect, "last_insert_id", variable.LowerCaseTableNames, variable.MaxAllowedPacket, variable.MaxConnections,
		variable.MaxPreparedStmtCount, variable.PluginDir, variable.PluginLoad, variable.SQLLogBin, "ssl_ca", "ssl_cert", "ssl_key", variable.TiDBAnalyzeVersion,
		variable.TiDBBatchCommit, variable.TiDBBatchDelete, variable.TiDBBatchInsert, variable.TiDBEnableChangeColumnType, variable.TiDBEnableChangeMultiSchema,
		variable.TiDBEnableDynamicPrivileges, variable.TiDBEnableExchangePartition, variable.TiDBEnableExtendedStats, variable.TiDBEnablePointGetCache,
		variable.TiDBEnableStreaming, variable.TiDBGuaranteeLinearizability, variable.WarningCount, variable.TiDBTxnScope, variable.TiDBTxnReadTS,
		variable.TxnIsolationOneShot, variable.Timestamp, variable.TiDBLastQueryInfo, variable.TiDBLastTxnInfo,
		variable.TiDBMemQuotaHashJoin, variable.TiDBStreamAggConcurrency, variable.TiDBTrackAggregateMemoryUsage, variable.TiDBOptBCJ,
		variable.TiDBOptConcurrencyFactor, variable.TiDBOptCopCPUFactor, variable.TiDBEnableIndexMergeJoin,
		variable.TiDBMemQuotaIndexLookupJoin, variable.TiDBMemQuotaIndexLookupReader, variable.TiDBMemQuotaMergeJoin,
		variable.TiDBEnableAlterPlacement, variable.TiDBSlowLogMasking, variable.TiDBShardAllocateStep, variable.TiDBMemQuotaTopn,
		variable.TiDBMemQuotaSort, variable.TiDBMergeJoinConcurrency, variable.TiDBOptCPUFactor, variable.TiDBOptDescScanFactor,
		variable.TiDBOptDiskFactor, variable.TiDBOptJoinReorderThreshold, variable.TiDBOptMemoryFactor, variable.TiDBOptNetworkFactor,
		variable.TiDBOptScanFactor, variable.TiDBOptTiFlashConcurrencyFactor, variable.TiDBOptimizerSelectivityLevel, variable.TiDBPartitionPruneMode,
		variable.TiDBOptSeekFactor, variable.LogBin, "license", variable.TiDBEnableTopSQL, variable.TiDBTopSQLAgentAddress, variable.TiDBTopSQLPrecisionSeconds,
		variable.TiDBTopSQLMaxStatementCount, variable.TiDBEnableGlobalTemporaryTable, variable.TiDBEnablePipelinedWindowFunction, variable.TiDBOptCartesianBCJ:

[shichun-0415]

@till now, all the system variables mentioned above have been documented and the related PRs have been attached for reference. Two variables tidb_enable_radix_join and tidb_slow_log_masking are not found in https://github.com/pingcap/tidb/blob/master/sessionctx/variable/sysvar.go and might have been removed. Therefore, this issue can be closed.