From e9b29678722dda6410fd38637110a8b8c6189da2 Mon Sep 17 00:00:00 2001 From: Wenxuan Zhang Date: Mon, 10 Aug 2026 12:08:14 +0800 Subject: [PATCH] docs: document TiDB X foreign key shared lock gate Add the experimental TiDB X configuration and clarify the system variable prerequisite. Document how persisted or restored ON values behave across upgrades. --- foreign-key.md | 4 ++++ system-variables.md | 4 ++++ tidb-configuration-file.md | 9 +++++++++ 3 files changed, 17 insertions(+) diff --git a/foreign-key.md b/foreign-key.md index 003354246b154..e9bc31ab6c453 100644 --- a/foreign-key.md +++ b/foreign-key.md @@ -183,6 +183,10 @@ By default, in pessimistic transactions, the locking behavior of foreign key che You can enable the system variable [`tidb_foreign_key_check_in_shared_lock`](/system-variables.md#tidb_foreign_key_check_in_shared_lock-new-in-v856) to let foreign key checks use shared locks. Shared locks allow multiple transactions to perform foreign key checks on the same parent table row simultaneously, thereby reducing lock conflicts and improving the performance of concurrent writes to child tables. +> **Warning:** +> +> On TiDB X, using shared locks for foreign key checks is an experimental feature. It is not recommended that you use this feature in production environments. This feature might be changed or removed without prior notice. Before setting `tidb_foreign_key_check_in_shared_lock` to `ON`, you must set [`experimental.allow-enable-foreign-key-check-in-shared-lock`](/tidb-configuration-file.md#allow-enable-foreign-key-check-in-shared-lock) to `true`. + ## Definition and metadata of foreign keys To view the definition of a foreign key constraint, execute the [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) statement: diff --git a/system-variables.md b/system-variables.md index 04cd42552715c..6e8e4af55ce14 100644 --- a/system-variables.md +++ b/system-variables.md @@ -3178,6 +3178,10 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified ### tidb_foreign_key_check_in_shared_lock New in v8.5.6 +> **Warning:** +> +> On TiDB X, using shared locks for foreign key checks is an experimental feature. It is not recommended that you use this feature in production environments. This feature might be changed or removed without prior notice. Before setting this variable to `ON`, you must set [`experimental.allow-enable-foreign-key-check-in-shared-lock`](/tidb-configuration-file.md#allow-enable-foreign-key-check-in-shared-lock) to `true`. When this configuration item is `false`, TiDB rejects attempts to set this variable to `ON`, but an `ON` value that has already been persisted or restored continues to take effect. + - Scope: SESSION | GLOBAL - Persists to cluster: Yes - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No diff --git a/tidb-configuration-file.md b/tidb-configuration-file.md index f9392a612cd42..c00624ad04216 100644 --- a/tidb-configuration-file.md +++ b/tidb-configuration-file.md @@ -1062,6 +1062,15 @@ Configuration items related to the PROXY protocol. The `experimental` section, introduced in v3.1.0, describes the configurations related to the experimental features of TiDB. +### `allow-enable-foreign-key-check-in-shared-lock` + +> **Warning:** +> +> This configuration item applies only to TiDB X. Using shared locks for foreign key checks on TiDB X is an experimental feature. It is not recommended that you use this feature in production environments. This feature might be changed or removed without prior notice. + ++ Controls whether SQL users can set [`tidb_foreign_key_check_in_shared_lock`](/system-variables.md#tidb_foreign_key_check_in_shared_lock-new-in-v856) to `ON` in TiDB X. When this configuration item is `false`, TiDB rejects attempts to set the system variable to `ON`. This configuration item does not change an `ON` value that has already been persisted or restored, so the existing behavior is preserved after an upgrade. ++ Default value: `false` + ### `allow-expression-index` New in v4.0.0 + Controls whether an expression index can be created. Since TiDB v5.2.0, if the function in an expression is safe, you can create an expression index directly based on this function without enabling this configuration. If you want to create an expression index based on other functions, you can enable this configuration, but correctness issues might exist. By querying the `tidb_allow_function_for_expression_index` variable, you can get the functions that are safe to be directly used for creating an expression.