From c1701372ad120c999e29556c6b454d7d7a270575 Mon Sep 17 00:00:00 2001 From: you06 Date: Thu, 12 Feb 2026 19:40:13 +0900 Subject: [PATCH 1/3] add doc for Signed-off-by: you06 --- foreign-key.md | 6 ++++-- system-variables.md | 9 +++++++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/foreign-key.md b/foreign-key.md index aea4246cc9cc8..49378fd7d5b8f 100644 --- a/foreign-key.md +++ b/foreign-key.md @@ -177,9 +177,11 @@ When the foreign key constraint check is disabled, the foreign key constraint ch ## Locking -When `INSERT` or `UPDATE` a child table, the foreign key constraint checks whether the corresponding foreign key value exists in the parent table, and locks the row in the parent table to avoid the foreign key value being deleted by other operations violating the foreign key constraint. The locking behavior is equivalent to performing a `SELECT FOR UPDATE` operation on the row where the foreign key value is located in the parent table. +When `INSERT` or `UPDATE` a child table, the foreign key constraint checks whether the corresponding foreign key value exists in the parent table, and locks the row in the parent table to avoid the foreign key value being deleted by other operations violating the foreign key constraint. -Because TiDB currently does not support `LOCK IN SHARE MODE`, if a child table accepts a large number of concurrent writes and most of the referenced foreign key values are the same, there might be serious locking conflicts. It is recommended to disable [`foreign_key_checks`](/system-variables.md#foreign_key_checks) when writing a large number of child table data. +By default, the locking behavior of foreign key checks is equivalent to performing a `SELECT FOR UPDATE` operation (exclusive lock) on the row where the foreign key value is located in the parent table. In concurrent write scenarios for a child table, if most of the referenced foreign key values are the same, there might be serious locking conflicts. + +You can enable the system variable [`tidb_foreign_key_check_in_shared_lock`](/system-variables.md#tidb_foreign_key_check_in_shared_lock) to let foreign key checks use shared locks. Shared locks allow multiple transactions to hold locks on the same row simultaneously, reducing lock conflicts and improving the performance of concurrent writes to child tables. ## Definition and metadata of foreign keys diff --git a/system-variables.md b/system-variables.md index ad0ca26e92d7a..863ba293b1c28 100644 --- a/system-variables.md +++ b/system-variables.md @@ -3147,6 +3147,15 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > > Starting from v6.6.0, TiDB supports [Resource Control](/tidb-resource-control-ru-groups.md). You can use this feature to execute SQL statements with different priorities in different resource groups. By configuring proper quotas and priorities for these resource groups, you can gain better scheduling control for SQL statements with different priorities. When resource control is enabled, statement priority will no longer take effect. It is recommended that you use [Resource Control](/tidb-resource-control-ru-groups.md) to manage resource usage for different SQL statements. +### tidb_foreign_key_check_in_shared_lock New in v8.5.6 + +- 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 foreign key constraint checks use shared locks instead of exclusive locks in pessimistic transactions. When enabled, foreign key checks acquire shared locks on parent table rows, allowing multiple concurrent transactions to check the same parent table row without blocking each other, thereby improving the performance of concurrent writes to child tables. + ### tidb_gc_concurrency New in v5.0 > **Note:** From a3abfa318db95f6891bf80fe8512c743edb21126 Mon Sep 17 00:00:00 2001 From: you06 Date: Thu, 12 Feb 2026 21:42:12 +0900 Subject: [PATCH 2/3] fix dead anchor Signed-off-by: you06 --- foreign-key.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/foreign-key.md b/foreign-key.md index 49378fd7d5b8f..f54edeb6a1f0d 100644 --- a/foreign-key.md +++ b/foreign-key.md @@ -181,7 +181,7 @@ When `INSERT` or `UPDATE` a child table, the foreign key constraint checks wheth By default, the locking behavior of foreign key checks is equivalent to performing a `SELECT FOR UPDATE` operation (exclusive lock) on the row where the foreign key value is located in the parent table. In concurrent write scenarios for a child table, if most of the referenced foreign key values are the same, there might be serious locking conflicts. -You can enable the system variable [`tidb_foreign_key_check_in_shared_lock`](/system-variables.md#tidb_foreign_key_check_in_shared_lock) to let foreign key checks use shared locks. Shared locks allow multiple transactions to hold locks on the same row simultaneously, reducing lock conflicts and improving the performance of concurrent writes to child tables. +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 hold locks on the same row simultaneously, reducing lock conflicts and improving the performance of concurrent writes to child tables. ## Definition and metadata of foreign keys From 51441811d59c3437f0b6a289145e7f900e08b27a Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Fri, 13 Feb 2026 12:36:01 +0800 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- foreign-key.md | 4 ++-- system-variables.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/foreign-key.md b/foreign-key.md index f54edeb6a1f0d..e52b2aa422add 100644 --- a/foreign-key.md +++ b/foreign-key.md @@ -177,11 +177,11 @@ When the foreign key constraint check is disabled, the foreign key constraint ch ## Locking -When `INSERT` or `UPDATE` a child table, the foreign key constraint checks whether the corresponding foreign key value exists in the parent table, and locks the row in the parent table to avoid the foreign key value being deleted by other operations violating the foreign key constraint. +When you `INSERT` into or `UPDATE` a child table, the foreign key constraint checks whether the corresponding foreign key value exists in the parent table and locks the row in the parent table to prevent other operations from deleting the foreign key value and violating the foreign key constraint. By default, the locking behavior of foreign key checks is equivalent to performing a `SELECT FOR UPDATE` operation (exclusive lock) on the row where the foreign key value is located in the parent table. In concurrent write scenarios for a child table, if most of the referenced foreign key values are the same, there might be serious locking conflicts. -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 hold locks on the same row simultaneously, reducing lock conflicts and improving the performance of concurrent writes to child tables. +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-and-v900) to let foreign key checks use shared locks. Shared locks allow multiple transactions to hold locks on the same row simultaneously, reducing lock conflicts and improving the performance of concurrent writes to child tables. ## Definition and metadata of foreign keys diff --git a/system-variables.md b/system-variables.md index 863ba293b1c28..aa99d556140d4 100644 --- a/system-variables.md +++ b/system-variables.md @@ -3147,14 +3147,14 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified > > Starting from v6.6.0, TiDB supports [Resource Control](/tidb-resource-control-ru-groups.md). You can use this feature to execute SQL statements with different priorities in different resource groups. By configuring proper quotas and priorities for these resource groups, you can gain better scheduling control for SQL statements with different priorities. When resource control is enabled, statement priority will no longer take effect. It is recommended that you use [Resource Control](/tidb-resource-control-ru-groups.md) to manage resource usage for different SQL statements. -### tidb_foreign_key_check_in_shared_lock New in v8.5.6 +### tidb_foreign_key_check_in_shared_lock New in v8.5.6 and v9.0.0 - 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 foreign key constraint checks use shared locks instead of exclusive locks in pessimistic transactions. When enabled, foreign key checks acquire shared locks on parent table rows, allowing multiple concurrent transactions to check the same parent table row without blocking each other, thereby improving the performance of concurrent writes to child tables. +- This variable controls whether foreign key checks in pessimistic transactions use shared locks instead of exclusive locks. When enabled, foreign key checks acquire shared locks on rows in the parent table, allowing multiple concurrent transactions to validate the same parent row without blocking each other. This behavior improves the performance of concurrent writes to child tables. ### tidb_gc_concurrency New in v5.0