cloud: document TiDB X foreign key shared locks and lock upgrades

foreign-key.md

@@ -183,6 +183,14 @@ 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.
+
+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:**
+>
+> 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
 
 To view the definition of a foreign key constraint, execute the [`SHOW CREATE TABLE`](/sql-statements/sql-statement-show-create-table.md) statement:

system-variables.md

@@ -2785,9 +2785,22 @@ 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.
+
 ### tidb_enable_slow_log
 
 > **Note:**
@@ -3178,6 +3191,10 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified
 
 ### tidb_foreign_key_check_in_shared_lock <span class="version-mark">New in v8.5.6</span>
 
+> **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. 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

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.
+
++ 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` <span class="version-mark">New in v4.0.0</span>
 
 + 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.