Add docs for placement rules in SQL

[morgo]

What is changed, added or deleted? (Required)

This provides docs for placement rules, a 5.3 experimental feature. It is still a work in progress, I'm publishing so I can get feedback from others.

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)
• v5.2 (TiDB 5.2 versions)
• v5.1 (TiDB 5.1 versions)
• v5.0 (TiDB 5.0 versions)
• v4.0 (TiDB 4.0 versions)
• v3.1 (TiDB 3.1 versions)
• v3.0 (TiDB 3.0 versions)
• v2.1 (TiDB 2.1 versions)

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

Docs for pingcap/tidb#18030

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]

[REVIEW NOTIFICATION]

This pull request has been approved by:

• TomShawn

To complete the pull request process, please ask the reviewers in the list to review by filling /cc @reviewer in the comment.
After your PR has acquired the required number of LGTMs, you can assign this pull request to the committer in the list by filling /assign @committer in the comment to help you merge this pull request.

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

Details

Reviewer can indicate their review by submitting an approval review.
Reviewer can cancel approval by submitting a request changes review.

[mjonss]

LGTM

[ti-chi-bot]

@mjonss: Thanks for your review. The bot only counts approvals from reviewers and higher roles in list, but you're still welcome to leave your comments.

Details

In response to this:

LGTM

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.

[xhebox]

While commenting in the lark, I noticed that some problems are highly confusing. I think the user guide may need a FAQ section.

1. region/zone/rack/host. What label could be used? Are these 4 special? How isolation applies to these labels(region is special)? Region is special that when one region in one rule is failed, other regions will be seen as unavailable. And when PD schedules, it will pick region with higher isolation score first(region has the highest isolation score, host the lowest).
2. TiFlash banned.
3. What if there is some unexpected cases and one of the rules can not be met? It is ignored if it can not be met after posted to PD. PD tries to meet all consontraints in one rule as much as possible.
4. If we want to keep the latency low, we must keep the majority in the primary region. That means when we add a new replica somewhere else, we may need another new region in the primary.
5. Direct syntax will be converted to a bundle of rules with different role. Sugar will be a bundle of two rules: one for the primary, one for others. And the schedule of PD happens rule by rule, which means the schedule is relatively independent between each role for the direct syntax, but more "smart" for the sugar syntax.
6. SCHDULE defaults to 'EVEN'
7. You can not add 2 replicas on the same tikv/store, for one region. For direct syntax, it means it is impossible to archive 2 replicas with only rule FOLLOWERS=2, neither possible with {+xx=m:1, +yy=n:1}, if there is only one tikv/store; for sugar syntax, it means you must provide as many tikv/store as the replicas you specify.

[morgo]

While commenting in the lark, I noticed that some problems are highly confusing. I think the user guide may need a FAQ section.

1. region/zone/rack/host. What label could be used? Are these 4 special? How isolation applies to these labels(region is special)? Region is special that when one region in one rule is failed, other regions will be seen as unavailable. And when PD schedules, it will pick region with higher isolation score first(region has the highest isolation score, host the lowest).
2. TiFlash banned.
3. What if there is some unexpected cases and one of the rules can not be met? It is ignored if it can not be met after posted to PD. PD tries to meet all consontraints in one rule as much as possible.
4. If we want to keep the latency low, we must keep the majority in the primary region. That means when we add a new replica somewhere else, we may need another new region in the primary.
5. Direct syntax will be converted to a bundle of rules with different role. Sugar will be a bundle of two rules: one for the primary, one for others. And the schedule of PD happens rule by rule, which means the schedule is relatively independent between each role for the direct syntax, but more "smart" for the sugar syntax.
6. SCHDULE defaults to 'EVEN'
7. You can not add 2 replicas on the same tikv/store, for one region. For direct syntax, it means it is impossible to archive 2 replicas with only rule FOLLOWERS=2, neither possible with {+xx=m:1, +yy=n:1}, if there is only one tikv/store; for sugar syntax, it means you must provide as many tikv/store as the replicas you specify.

I've tried to incorporate some of this feedback, but some we'll have to work on in development (for example: with item 1 - we've not added the zone/rack/host labels yet, but they should have the same place as region does in the current docs).We don't clarify the edge-cases in the docs, but we should in future.

[djshow832]

Rest LGTM

[nolouch]

rest LGTM:)

[nolouch]

Can we add a note like:

We recommend using this feature with the help of the official tidb team to help solve specific scenarios. Over-configuration of the placement plan will increase the difficulty of maintenance and troubleshooting, so reasonable planning is very necessary. Usually, the points that need to be considered, including disaster recovery issues, high availability issues, performance issues and so on.

[morgo]

Hi @nolouch. Some comments in line:

We recommend using this feature with the help of the official tidb team to help solve specific scenarios. Over-configuration of the placement plan will increase the difficulty of maintenance and troubleshooting, so reasonable planning is very necessary.

To a large degree we removed over configuration as a possibility between the original proposal and the newer proposal. You can no longer specify multiple constraints; and syntactic sugar constraints are mutually exclusive with regular constraints. The only complex scenarios that remain are both FOLLOWER_CONSTRAINTS and CONSTRAINTS can apply, and a user could set a complex constraint in dictionary format.

Usually, the points that need to be considered, including disaster recovery issues, high availability issues, performance issues and so on.

We don't document this well in the current experimental version. Because it is experimental, users are not encouraged to use it in production, so high availability/DR did not seem relevant (yet).

I have an alternative suggestion:

We value your feedback when evaluating experimental features. Please feel free to create a GitHub issue or reach out to us on TiDB Slack. We are interested to both the problems you encounter and your intended use-cases.

[TomShawn]

LGTM

[TomShawn]

/remove-status LGT1
/status LGT2

[TomShawn]

/merge

[ti-chi-bot]

@nolouch: Thanks for your review. The bot only counts approvals from reviewers and higher roles in list, but you're still welcome to leave your comments.

Details

In response to this:

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.

[ti-chi-bot]

This pull request has been accepted and is ready to merge.

Details

Commit hash: 5422310

[TomShawn]

Some newly added documents are missing in the TOC. They are added in #6766.