premium: add limitations on import and index creation #22026
Conversation
ti-chi-bot
bot
added
contribution
Summary of ChangesHello @Frank945946, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request delivers a substantial update to the TiDB documentation, focusing on clarity, accuracy, and the introduction of new features across both TiDB Cloud and Self-Managed offerings. Key changes include the addition of specific Table of Contents for different TiDB Cloud tiers, a major overhaul of the overall documentation structure, and detailed guides for new functionalities like advanced index management and batch processing. These updates aim to provide users with more precise and comprehensive resources for developing, deploying, and optimizing their TiDB applications. Highlights
Ignored Files
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a significant number of updates and refactoring across the documentation for the v8.5 release. Key changes include the introduction of new Table of Contents files, updates to existing ones, widespread use of new template variables for product naming, and the addition of several new guides and best practice documents. Many existing documents have been improved for clarity, accuracy, and consistency, with updated performance metrics, compatibility information, and configuration recommendations. I've found a few minor issues, such as typos and style guide inconsistencies, and one case of duplicated content that should be addressed. Overall, this is a very thorough and valuable update to the documentation.
|  | ||
|
|
||
| The **Total RU of user resource groups** represents the total amount of RU for all user resource groups, excluding the `default` resource group. If this value is less than the estimated capacity, the system triggers an alert. By default, the system allocates unlimited usage to the predefined `default` resource group. When all users belong to the `default` resource group, resources are allocated in the same way as when resource control is disabled. | ||
| The **Total RU of user resource groups** represents the total amount of RU for all user resource groups, excluding the `default` resource group. If this value is more than the estimated capacity, the system triggers an alert. By default, the system allocates unlimited usage to the predefined `default` resource group. When all users belong to the `default` resource group, resources are allocated in the same way as when resource control is disabled. |
There was a problem hiding this comment.
This is a good correction. The alert should trigger when the total RU is more than the capacity, not less.
| #### Obsolete MVCC versions and excessive keys | ||
|
|
||
| A TiKV instance has much outdated data, which needs to be cleaned up for data scan. This impacts the processing speed. | ||
| If too many obsolete MVCC versions exist on TiKV, or if the retention time of historical MVCC data for GC is long, excessive MVCC versions can accumulate. Handling these unnecessary MVCC versions can affect scan performance. |
There was a problem hiding this comment.
The new heading and description are more detailed and technically accurate, which is a great improvement.
| title: Best Practices for Tuning TiKV Performance with Massive Regions | ||
| summary: TiKV performance tuning involves reducing the number of Regions and messages, increasing Raftstore concurrency, enabling Hibernate Region and Region Merge, adjusting Raft base tick interval, increasing TiKV instances, and adjusting Region size. Other issues include slow PD leader switching and outdated PD routing information. | ||
| aliases: ['/docs/dev/best-practices/massive-regions-best-practices/','/docs/dev/reference/best-practices/massive-regions/'] | ||
| --- | ||
|
|
||
| # Best Practices for TiKV Performance Tuning with Massive Regions | ||
| # Best Practices for Tuning TiKV Performance with Massive Regions | ||
|
|
||
| In TiDB, data is split into Regions, each storing data for a specific key range. These Regions are distributed among multiple TiKV instances. As data is written into a cluster, millions of Regions might be created. Too many Regions on a single TiKV instance can bring a heavy burden to the cluster and affect its performance. |
There was a problem hiding this comment.
The title change to 'Best Practices for Tuning TiKV Performance with Massive Regions' is more concise and improves readability.
| - C# | ||
| - [C#](/develop/dev-guide-sample-application-cs.md) | ||
| - [WordPress](/tidb-cloud/dev-guide-wordpress.md) | ||
| - Serverless Driver  <!--TBD, ToDo: Not sure if we need to update the driver name--> |
There was a problem hiding this comment.
This file contains an internal <!--TBD, ToDo: ... --> comment. These should be removed before merging the documentation.
|
|
||
| # Table of Contents | ||
|
|
||
| ## GET STARTED |
There was a problem hiding this comment.
The style guide specifies using sentence case for headings (e.g., ## Configure the cluster). Headings like ## GET STARTED should be changed to ## Get started to align with the guide. This applies to other all-caps headings in this file as well.1
| ## GET STARTED | |
| ## Get started |
Style Guide References
Footnotes
-
Use sentence case for headings (e.g.,
## Configure the cluster). ↩
| title: Best Practices for Using UUIDs as Primary Keys | ||
| summary: UUIDs, when used as primary keys, offer benefits such as reduced network trips, support in most programming languages and databases, and protection against enumeration attacks. Storing UUIDs as binary in a `BINARY(16)` column is recommended. It's also advised to avoid setting the `swap_flag` with TiDB to prevent hotspots. MySQL compatibility is available for UUIDs. | ||
| --- | ||
|
|
||
| # UUID Best Practices | ||
| # Best Practices for Using UUIDs as Primary Keys | ||
|
|
||
| UUIDs (Universally Unique Identifiers) are a popular alternative to auto-incrementing integers for primary keys in distributed databases. This document outlines the benefits of using UUIDs in TiDB, and offers best practices for storing and indexing them efficiently. |
There was a problem hiding this comment.
The new title 'Best Practices for Using UUIDs as Primary Keys' is more specific and improves clarity. The expanded introduction is also helpful.
| ``` | ||
|
|
||
| ``` | ||
| ERROR 1115 (42000): Unsupported character introducer: 'gbk' | ||
| ``` |
There was a problem hiding this comment.
This formatting change improves readability by putting the error message in its own code block.
| - C# | ||
| - [C#](/develop/dev-guide-sample-application-cs.md) | ||
| - [WordPress](/tidb-cloud/dev-guide-wordpress.md) | ||
| - Serverless Driver  <!--TBD, ToDo: Not sure if we need to update the driver name--> |
There was a problem hiding this comment.
This file contains an internal <!--TBD, ToDo: ... --> comment. These should be removed before merging the documentation.
| title: Best Practices for DDL Execution in TiDB | ||
| summary: Learn about how DDL statements are implemented in TiDB, the online change process, and best practices. | ||
| --- | ||
|
|
||
| # Execution Principles and Best Practices of DDL Statements | ||
| # Best Practices for DDL Execution in TiDB | ||
|
|
||
| This document provides an overview of the execution principles and best practices related to DDL statements in TiDB. The principles include the DDL Owner module and the online DDL change process. |
There was a problem hiding this comment.
The new title and introduction are clearer and more direct.
| ``` | ||
|
|
||
| The example query above takes `1.03` seconds to execute, which is an ideal performance. | ||
| The example query above takes `1.03` seconds to execute, which is not ideal performance. |
There was a problem hiding this comment.
This is a good correction. The original text stated the performance was 'ideal', which was incorrect given the context of optimization. Changing it to 'not ideal' makes the document much clearer.
ti-chi-bot
bot
added
size/M
| > **Note:** | ||
| > | ||
| > This variable is read-only for [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#starter) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential). | ||
| > This variable is read-only for [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#starter) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential). For [{{{ .premium }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#premium), modifying this parameter has no effect on index creation. |
There was a problem hiding this comment.
not read-only, it's not working for add-index, for other reorg jobs it still work
Replaced explicit TiDB Cloud Premium links with template variable {{{ .premium }}} and clarified that certain options are auto-tuned and cannot be modified by users. Updated support contact phrasing for consistency and accuracy.
Updated the documentation for the tidb_ddl_disk_quota variable to clarify its behavior across TiDB Cloud cluster tiers. Added custom content blocks for different plans and improved notes for the premium tier, including support contact information and consistent terminology.
ti-chi-bot
bot
removed
the
missing-translation-status
lilin90
added
area/tidb-cloud
lilin90
changed the title
| | `CLOUD_STORAGE_URI` | All file formats | Specifies the target address where encoded KV data for [Global Sort](/tidb-global-sort.md) is stored. When `CLOUD_STORAGE_URI` is not specified, `IMPORT INTO` determines whether to use Global Sort based on the value of the system variable [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740). If this system variable specifies a target storage address, `IMPORT INTO` uses this address for Global Sort. When `CLOUD_STORAGE_URI` is specified with a non-empty value, `IMPORT INTO` uses that value as the target storage address. When `CLOUD_STORAGE_URI` is specified with an empty value, local sorting is enforced. Currently, the target storage address only supports S3. For details about the URI configuration, see [Amazon S3 URI format](/external-storage-uri.md#amazon-s3-uri-format). When this feature is used, all TiDB nodes must have read and write access for the target S3 bucket, including at least these permissions: `s3:ListBucket`, `s3:GetObject`, `s3:DeleteObject`, `s3:PutObject`, `s3: AbortMultipartUpload`. | | ||
| | `DISABLE_PRECHECK` | All file formats and query results of `SELECT` | Setting this option disables pre-checks of non-critical items, such as checking whether there are CDC or PITR tasks. | | ||
|
|
||
| <CustomContent plan="premium"> |
There was a problem hiding this comment.
| <CustomContent plan="premium"> | |
| <CustomContent platform="tidb-cloud" plan="premium"> |
| > | ||
| > This variable is read-only for [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#starter) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential). | ||
|
|
||
| </CustomContent> |
There was a problem hiding this comment.
| </CustomContent> | |
| </CustomContent> | |
| - When Global Sort is disabled, only one TiDB node writes to TiKV at a time. In this case, the maximum write bandwidth per TiKV node is `100MiB`. | ||
| - When Global Sort is enabled, all 4 TiDB nodes can write to TiKV simultaneously. In this case, the maximum write bandwidth per TiKV node is `4 * 100MiB = 400MiB`. | ||
| <CustomContent plan="premium"> |
There was a problem hiding this comment.
| <CustomContent plan="premium"> | |
| <CustomContent platform="tidb-cloud" plan="premium"> |
| - Starting from v8.3.0, this parameter is supported at the SESSION level. Modifying the parameter at the GLOBAL level will not impact currently running DDL statements. It will only apply to DDLs submitted in new sessions. | ||
| - Starting from v8.5.0, you can modify this parameter for a running DDL job by executing `ADMIN ALTER DDL JOBS <job_id> THREAD = <new_thread_count>;`. Note that this operation is not supported for `ADD INDEX` DDL when [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) is enabled. For details, see [`ADMIN ALTER DDL JOBS`](/sql-statements/sql-statement-admin-alter-ddl.md). | ||
| <CustomContent plan="premium"> |
There was a problem hiding this comment.
| <CustomContent plan="premium"> | |
| <CustomContent platform="tidb-cloud" plan="premium"> |
| SET GLOBAL tidb_cloud_storage_uri = 's3://my-bucket/test-data?role-arn=arn:aws:iam::888888888888:role/my-role' | ||
| ``` | ||
|
|
||
| <CustomContent plan="premium"> |
There was a problem hiding this comment.
| <CustomContent plan="premium"> | |
| <CustomContent platform="tidb-cloud" plan="premium"> |
|
|
||
| </CustomContent> |
There was a problem hiding this comment.
| </CustomContent> |
| > This variable is read-only for [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#starter) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential). | ||
|
|
||
| </CustomContent> | ||
| <CustomContent platform="tidb-cloud" plan="premium"> |
There was a problem hiding this comment.
| <CustomContent platform="tidb-cloud" plan="premium"> | |
| <CustomContent platform="tidb-cloud" plan="starter,essential,premium"> |
| </CustomContent> | ||
| ### tidb_ddl_reorg_worker_cnt | ||
There was a problem hiding this comment.
| <CustomContent platform="tidb-cloud" plan="starter,essential,premium"> | |
| > | ||
| > This variable is read-only for [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#starter) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential). | ||
| > This variable is read-only for [{{{ .starter }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#starter) and [{{{ .essential }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#essential). For [{{{ .premium }}}](https://docs.pingcap.com/tidbcloud/select-cluster-tier#premium), modifying this parameter has no effect on index creation. | ||
There was a problem hiding this comment.
| </CustomContent> | |
Co-authored-by: xixirangrang <hfxsd@hotmail.com>
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
4 participants
First-time contributors' checklist
What is changed, added or deleted? (Required)
Add limitations on import and index creation for TiDB X Premium
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.
What is the related PR or file link(s)?
Do your changes match any of the following descriptions?