cloud: document the TiDB X foreign key shared lock gate

[wfxr]

First-time contributors' checklist

• I've signed the Contributor License Agreement, which is required for the repository owners to accept my contribution.

What is changed, added or deleted? (Required)

Document the experimental [experimental].allow-enable-foreign-key-check-in-shared-lock configuration for TiDB X and clarify its interaction with tidb_foreign_key_check_in_shared_lock.

NOTE

This change applies only to TiDB X deployments used by TiDB Cloud Premium and Essential v2. It does not apply to TiDB Self-Managed (OP) or other classic TiDB deployments. The feature is experimental and has not reached general availability (GA).

• Explain that TiDB X requires the configuration to be enabled before SQL users can set the system variable to ON.
• Document that disabling the configuration prevents new SQL-level activation but does not override an ON value that has already been persisted or restored.

The related TiDB change was merged into TiDB master, but it only changes the behavior of TiDB X. This documentation PR targets release-8.5, which is the source branch for the current TiDB Cloud documentation. The documentation team can decide whether to apply the change to docs master during review.

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions.

• master (the latest development version)
• v8.5 (TiDB 8.5 versions)
• v8.4 (TiDB 8.4 versions)
• v8.3 (TiDB 8.3 versions)
• v8.2 (TiDB 8.2 versions)
• v8.1 (TiDB 8.1 versions)
• v7.5 (TiDB 7.5 versions)
• v7.1 (TiDB 7.1 versions)
• v6.5 (TiDB 6.5 versions)

What is the related PR or file link(s)?

• This PR is translated from:
• Other reference link(s):
  • sessionctx, config: gate FK shared-lock sysvar on next-gen tidb#70328
  • sessionctx, config: gate FK shared-lock sysvar on next-gen tidb#69167
  • cloud: add tidb-x-cloud.202603.1.md #23458

AI agent involvement

• The changes in this PR were primarily made by an AI agent on behalf of the PR author.

Do your changes match any of the following descriptions?

• Delete files
• Change aliases
• Need modification after applied to another branch
• Might cause conflicts after applied to another branch

Summary by CodeRabbit

• Documentation
  • Added warnings that foreign-key checks in shared locks are experimental on TiDB X and not recommended for production.
  • Documented the configuration prerequisite for enabling this feature.
  • Added the allow-enable-foreign-key-check-in-shared-lock setting, including its default behavior and effect on existing enabled values.

[ti-chi-bot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign kissmydb for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 108afc47-1752-49ab-ab40-8dd600ee09ef

📥 Commits

Reviewing files that changed from the base of the PR and between 8c98b83 and e9b2967.

📒 Files selected for processing (3)

• foreign-key.md
• system-variables.md
• tidb-configuration-file.md

---

📝 Walkthrough

Walkthrough

The documentation adds the TiDB X experimental configuration for shared-lock foreign key checks. It documents the prerequisite, default behavior, persisted-value behavior, and production-use warning.

Changes

Foreign key shared-lock documentation

Layer / File(s)	Summary
Configuration and variable contract tidb-configuration-file.md, system-variables.md	Documents the experimental allow-enable-foreign-key-check-in-shared-lock configuration, its false default, the prerequisite for setting tidb_foreign_key_check_in_shared_lock to ON, and the behavior of persisted or restored values.
Foreign key locking warning foreign-key.md	Marks shared-lock foreign key checks as experimental, not recommended for production, subject to change or removal, and dependent on the TiDB X configuration.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: qiancai, ti-chi-bot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the documented TiDB X foreign key shared lock gate.
Description check	✅ Passed	The description covers the changes, affected version, deployment scope, references, AI involvement, and version-specific handling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/tidb-x-fk-shared-lock-gate

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[wfxr]

/label version-specific-changes-required

[ti-chi-bot]

@wfxr: The label(s) version-specific-changes-required cannot be applied. These labels are supported: 2024-tidb-docs-dash, contribution, first-time-contributor, for-future-release, good first issue, hacktoberfest-accepted, Hacktoberfest, help wanted, needs-cherry-pick-master, needs-cherry-pick-release-7.5, needs-cherry-pick-release-8.1, needs-cherry-pick-release-8.5, needs-cherry-pick-release-9.0-beta.2, needs-cherry-pick-release-cloud, needs-cherry-pick-release-8.2, needs-cherry-pick-release-8.3, needs-cherry-pick-release-8.4, question, requires-followup, requires-version-specific-changes, special-week, website.

Details

In response to this:

/label version-specific-changes-required

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the ti-community-infra/tichi repository.

[pingcap-cla-assistant]

All committers have signed the CLA.

[wfxr]

/label requires-version-specific-changes

[wfxr]

/hold