From f278fd0416a6b71fff6aa9bb7f3188a6790bb817 Mon Sep 17 00:00:00 2001 From: Wenxuan Zhang Date: Mon, 10 Aug 2026 12:08:14 +0800 Subject: [PATCH 1/3] 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 c738522eb18b2..5ce2fae7083be 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. From bc4ce17a20680b7d68fa5f7841c01c87926e4818 Mon Sep 17 00:00:00 2001 From: Wenxuan Zhang Date: Wed, 2 Sep 2026 09:33:17 +0800 Subject: [PATCH 2/3] docs: document TiDB X shared lock upgrade --- foreign-key.md | 6 +++++- system-variables.md | 18 ++++++++++++++++-- tidb-configuration-file.md | 2 +- 3 files changed, 22 insertions(+), 4 deletions(-) diff --git a/foreign-key.md b/foreign-key.md index e9bc31ab6c453..5e2afcc7686f3 100644 --- a/foreign-key.md +++ b/foreign-key.md @@ -183,9 +183,13 @@ 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. +If a pessimistic transaction needs to update or delete a parent table row after a foreign key check has acquired a shared lock on that row, enable [`tidb_enable_shared_lock_upgrade`](/system-variables.md#tidb_enable_shared_lock_upgrade) to let TiDB upgrade the shared lock to an exclusive lock. + +Transactions that hold shared locks do not support one-phase commit (1PC) or Async Commit. + > **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`. +> 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. 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 diff --git a/system-variables.md b/system-variables.md index 5ce2fae7083be..aeffdb0d324f9 100644 --- a/system-variables.md +++ b/system-variables.md @@ -2785,9 +2785,23 @@ Assume that you have a cluster with 4 TiDB nodes and multiple TiKV nodes. In thi - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: Boolean - Default value: `OFF` -- This variable controls whether to enable the feature of upgrading shared locks to exclusive locks. TiDB does not support `SELECT LOCK IN SHARE MODE` by default. When the variable value is `ON`, TiDB tries to upgrade the `SELECT LOCK IN SHARE MODE` statement to `SELECT FOR UPDATE` and add a pessimistic lock. The default value of this variable is `OFF`, which means that the feature of upgrading shared locks to exclusive locks is disabled. +- This variable controls whether `SELECT ... LOCK IN SHARE MODE` acquires an exclusive pessimistic lock. When the value is `ON`, TiDB executes `SELECT ... LOCK IN SHARE MODE` as `SELECT ... FOR UPDATE`. This behavior acquires an exclusive lock directly rather than upgrading an existing shared lock to an exclusive lock. - Enabling this variable takes effect on the `SELECT LOCK IN SHARE MODE` statement, regardless of whether [`tidb_enable_noop_functions`](/system-variables.md#tidb_enable_noop_functions-new-in-v40) is enabled or not. +### tidb_enable_shared_lock_upgrade + +> **Warning:** +> +> Shared lock upgrade is an experimental feature that can only be enabled on TiDB X. It is not recommended that you enable this feature in production environments. + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: Boolean +- Default value: `OFF` +- This variable controls whether a pessimistic transaction can upgrade a shared lock that it already holds to an exclusive lock. +- Shared lock upgrade is not supported in aggressive locking mode or fair locking mode. + ### tidb_enable_slow_log > **Note:** @@ -3180,7 +3194,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > **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. +> 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. 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 diff --git a/tidb-configuration-file.md b/tidb-configuration-file.md index c00624ad04216..9dc1545c2269a 100644 --- a/tidb-configuration-file.md +++ b/tidb-configuration-file.md @@ -1066,7 +1066,7 @@ The `experimental` section, introduced in v3.1.0, describes the configurations r > **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. +> 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. + 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` From 37be60aac4d6c5f98b426e8d11500310df729482 Mon Sep 17 00:00:00 2001 From: Wenxuan Zhang Date: Wed, 2 Sep 2026 09:45:04 +0800 Subject: [PATCH 3/3] docs: clarify shared lock limitations --- foreign-key.md | 2 +- system-variables.md | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/foreign-key.md b/foreign-key.md index 5e2afcc7686f3..a16b4e8b57331 100644 --- a/foreign-key.md +++ b/foreign-key.md @@ -185,7 +185,7 @@ You can enable the system variable [`tidb_foreign_key_check_in_shared_lock`](/sy If a pessimistic transaction needs to update or delete a parent table row after a foreign key check has acquired a shared lock on that row, enable [`tidb_enable_shared_lock_upgrade`](/system-variables.md#tidb_enable_shared_lock_upgrade) to let TiDB upgrade the shared lock to an exclusive lock. -Transactions that hold shared locks do not support one-phase commit (1PC) or Async Commit. +Shared locks are not supported in aggressive locking mode or fair locking mode. Transactions that hold shared locks do not support one-phase commit (1PC) or Async Commit. > **Warning:** > diff --git a/system-variables.md b/system-variables.md index aeffdb0d324f9..f09cf666a8811 100644 --- a/system-variables.md +++ b/system-variables.md @@ -2800,7 +2800,6 @@ Assume that you have a cluster with 4 TiDB nodes and multiple TiKV nodes. In thi - Type: Boolean - Default value: `OFF` - This variable controls whether a pessimistic transaction can upgrade a shared lock that it already holds to an exclusive lock. -- Shared lock upgrade is not supported in aggressive locking mode or fair locking mode. ### tidb_enable_slow_log