Document MySQL-compatible dual password support

[takaidohigasi]

First-time contributors' checklist

• I've signed Contributor License Agreement that's required for repo owners to accept my contribution.

What is changed, added or deleted? (Required)

Documents the MySQL 8.0-compatible dual password feature being added in pingcap/tidb#68393 (ALTER USER ... RETAIN CURRENT PASSWORD / DISCARD OLD PASSWORD, SET PASSWORD ... RETAIN CURRENT PASSWORD, and the APPLICATION_PASSWORD_ADMIN dynamic privilege).

• password-management.md: new Dual password policy section — no-downtime rotation walkthrough, storage location (mysql.user.User_attributes), required privileges (self vs cross-account), restrictions (capable auth plugins; ER_CURRENT_PASSWORD_CANNOT_BE_RETAINED, ER_SECOND_PASSWORD_CANNOT_BE_EMPTY, ER_PASSWORD_CANNOT_BE_RETAINED_ON_PLUGIN_CHANGE), and a rolling-upgrade note.
• sql-statements/sql-statement-alter-user.md: DualPasswordOption in the synopsis + rotation example.
• sql-statements/sql-statement-set-password.md: RETAIN CURRENT PASSWORD in the synopsis + example + privilege note; also notes that the REPLACE clause is not supported.
• privilege-management.md: APPLICATION_PASSWORD_ADMIN added to the dynamic privileges list.
• security-compatibility-with-mysql.md: removed "Dual password policy" from the unsupported security features list.

Note to reviewers: pingcap/tidb#68393 (master) and pingcap/tidb#69735 (release-8.5 backport) are both merged; the feature ships in v8.5.7, and the version notes say Starting from v8.5.7. This PR therefore applies to master and the v8.5 docs branch.

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)
• v9.0 (TiDB 9.0 versions)
• v8.5 (TiDB 8.5 versions)
• v8.1 (TiDB 8.1 versions)
• v7.5 (TiDB 7.5 versions)

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

• This PR is translated from: N/A
• Other reference link(s): *: support MySQL dual passwords — behavior (executor / privilege / tests) tidb#68393, *: parser support for MySQL dual passwords (RETAIN CURRENT PASSWORD / DISCARD OLD PASSWORD) tidb#68028 (parser), MySQL dual passwords

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

[ti-chi-bot]

Hi @takaidohigasi. Thanks for your PR.

I'm waiting for a pingcap member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

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 kubernetes-sigs/prow repository.

[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 lilin90 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

[gemini-code-assist]

Code Review

This pull request documents the new dual password policy feature introduced in TiDB v9.0.0, which allows for zero-downtime password rotation by supporting primary and secondary passwords. The changes span password management, privilege management, and SQL statement documentation (ALTER USER and SET PASSWORD). The review feedback focuses on aligning the new text with the style guide, specifically by addressing the user in the second person ('you') and converting passive voice constructions to active voice.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[takaidohigasi]

Starting from v9.0.0
Need to consul

[takaidohigasi]

Starting from v9.0.0,

Need to consult

[takaidohigasi]

Starting from v9.0.0

also need to consul

[takaidohigasi]

MySQL-compatibility docs verification

Audited every compatibility-related page for dual-password impact. Result:

Doc	Dual-password relevance	Action
security-compatibility-with-mysql.md	Listed "Dual password policy" under Unsupported security features	✅ Fixed in this PR — entry removed
mysql-compatibility.md	General compatibility page: its Unsupported-features list covers SQL/engine features only and has never mentioned dual passwords (security topics are delegated to security-compatibility-with-mysql.md)	✅ Verified — no change needed
mysql-schema/mysql-schema-user.md	Described the User_attributes column without the secondary password	✅ Fixed in 27e2c7b — both TiDB and TiDB Cloud variants now note that $.additional_password stores the secondary password, linking to the dual password policy section
basic-features.md	Security feature matrix — version columns currently end at v8.5, so a "Dual passwords" row cannot be added yet	⏳ Follow-up for the docs team: when the matrix gains a v9.0 column, please add a Dual passwords row (Y for v9.0, N for earlier versions) linking to /password-management.md#dual-password-policy

Also verified the statement-level compatibility notes:

• sql-statement-set-password.md's "fully compatible with MySQL" claim is corrected in this PR: TiDB does not support the REPLACE 'current_auth_string' clause (current-password verification), which MySQL allows to combine with RETAIN CURRENT PASSWORD.
• The unsupported-features entry "Password verification policy, which requires you to verify the current password when you change it" in security-compatibility-with-mysql.md remains accurate and is intentionally kept.

[takaidohigasi]

I found this is planned to release at 8.5.x, so will fix some.
pingcap/tidb#69735

[takaidohigasi]

8.5.7 or 8.5.8 which is the proper version...?

[takaidohigasi]

pingcap/tidb#69735 (release-8.5 backport) has merged and the feature ships in the v8.5.7 train, so ee5a87f52 updates the three version notes from Starting from v9.0.0 to Starting from v8.5.7 (password-management.md intro + section, sql-statement-set-password.md). The PR description's affected-versions checklist now includes v8.5 for the cherry-pick.

[takaidohigasi]

One behavioral nuance for reviewers (and for anyone extending these pages later):

On release-8.5 (v8.5.7), APPLICATION_PASSWORD_ADMIN is deliberately hidden from SHOW PRIVILEGES output while remaining fully grantable and enforced. pingcap/tidb#69735 introduced a release-branch-only mechanism (dynamicPrivsHiddenFromShowPrivileges) so that the externally pinned mysql-test corpus, which treats SHOW PRIVILEGES output as stable, does not break on the release branch. On master (v9.0.0+), the privilege is listed by SHOW PRIVILEGES normally.

Impact on this PR: none — the current text never references SHOW PRIVILEGES, and GRANT / SHOW GRANTS / enforcement behave identically on both branches.

Please keep this in mind for future edits, though: if a "verify the privilege with SHOW PRIVILEGES" step is ever added to Privilege Management or the dual-password section, it would behave differently on v8.5.7 (row absent) vs v9.0.0+ (row present), so such an example would need a version-scoped note.