From 5111bc892351fd6d2beb26cd29dfb09e4903554a Mon Sep 17 00:00:00 2001 From: awxxxxxx Date: Tue, 31 Mar 2026 10:22:54 +0800 Subject: [PATCH 01/25] docs: add FAQ on TiDB X and Dedicated Projects, detailing changes and instance migration requirements --- tidb-cloud/tidbx-instance-move-faq.md | 68 +++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 tidb-cloud/tidbx-instance-move-faq.md diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md new file mode 100644 index 0000000000000..76f0e66039829 --- /dev/null +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -0,0 +1,68 @@ +# TiDB X Project and Dedicated Project: What Changed and Why Instances Need to Move + +## What Changed + +TiDB Cloud now introduces **typed projects** to provide a clearer separation between different product tiers. Projects are classified into two distinct types: + +- **TiDB X Project** — designed for TiDB Cloud X instances (Starter, Essential, Premium) +- **Dedicated Project** — designed for TiDB Cloud Dedicated clusters + +Each project type can **only host its own resource type**: + +- A TiDB X Project can only contain TiDB X instances. +- A Dedicated Project can only contain Dedicated clusters. + +This typed project model maintains a consistent **Organization → Project → Resource** hierarchy across all tiers, while allowing each product line to evolve with its own project behavior and capabilities. + +## Why Two Project Types + +TiDB X Projects and Dedicated Projects serve different use cases and have different characteristics: + +| Capability | TiDB X Project | Dedicated Project | +|---|---|---| +| Project Settings | ❌ | ✅ | +| Project-level RBAC | ✅ | ✅ | +| Billing Aggregation | ✅ | ✅ | +| Move instances between projects | ✅ | ❌ | +| Project is optional | ✅ (instances can exist at org level) | ❌ (clusters must belong to a project) | +| Resource type | TiDB X instances only | Dedicated clusters only | + +### TiDB X Project + +- **Lightweight and optional**. TiDB X users can create instances without assigning them to a project. Projects become useful when users want to organize and group resources, but are not required. +- **Instance mobility**. TiDB X instances can be moved between TiDB X Projects or back to the organization level, giving users flexibility in how they organize their resources. + +### Dedicated Project + +- **Mandatory project membership**. Every Dedicated cluster must belong to a Dedicated Project. +- **No instance mobility across projects**. Dedicated clusters cannot be moved between projects due to their infrastructure bindings. + +## Why Instances Need to Move + +Before this change, a single project could contain both Dedicated clusters and TiDB X instances (Starter, Essential). With the introduction of typed projects, this mixed state is no longer supported. + +**If a Dedicated Project currently contains TiDB X instances (Starter or Essential), those instances need to be moved out.** + +This is because: + +1. **Each project type now exclusively hosts its own resource type.** A Dedicated Project can only contain Dedicated clusters, and a TiDB X Project can only contain TiDB X instances. +2. **TiDB X instances and Dedicated clusters have different project behaviors.** TiDB X instances benefit from lightweight, optional project membership and instance mobility — capabilities that do not apply within a Dedicated Project. +3. **Keeping them separated ensures a consistent experience.** Users interacting with a Dedicated Project expect Dedicated-specific settings and behaviors. Mixing resource types would create confusion around which capabilities apply. + +## What Happens When Instances Are Moved + +When TiDB X instances are moved out of a Dedicated Project: + +- The instances are moved to a **TiDB X Project**. +- **No data or service disruption** is expected. This is a resource re-organization action, not an infrastructure change. +- After the move, users manage their TiDB X instances through TiDB X Projects (or at the org level), and their Dedicated clusters continue to be managed through Dedicated Projects. + +## Summary + +| Before | After | +|---|---| +| A single project could contain both Dedicated clusters and TiDB X instances | Each project type exclusively hosts its own resource type | +| TiDB X instances in Dedicated Projects inherited Dedicated project behaviors | TiDB X instances are managed in TiDB X Projects with their own lightweight model | +| No distinction between project types | Clear separation: TiDB X Project vs Dedicated Project | + +This change gives each product tier a project model that fits its own needs, while keeping the overall organization structure consistent and predictable. \ No newline at end of file From 22b58998b5aaee35c01c568e197d68518381ba6c Mon Sep 17 00:00:00 2001 From: awxxxxxx Date: Tue, 31 Mar 2026 11:01:02 +0800 Subject: [PATCH 02/25] docs: address review comments for TiDB X project FAQ --- tidb-cloud/tidbx-instance-move-faq.md | 32 +++++++++++++-------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index 76f0e66039829..17639eed50d9d 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -1,8 +1,8 @@ -# TiDB X Project and Dedicated Project: What Changed and Why Instances Need to Move +# TiDB X Project and Dedicated Project: what changed and why instances need to move -## What Changed +## What changed -TiDB Cloud now introduces **typed projects** to provide a clearer separation between different product tiers. Projects are classified into two distinct types: +TiDB Cloud introduces **typed projects** to provide a clearer separation between different product tiers. Projects are classified into two distinct types: - **TiDB X Project** — designed for TiDB Cloud X instances (Starter, Essential, Premium) - **Dedicated Project** — designed for TiDB Cloud Dedicated clusters @@ -14,7 +14,7 @@ Each project type can **only host its own resource type**: This typed project model maintains a consistent **Organization → Project → Resource** hierarchy across all tiers, while allowing each product line to evolve with its own project behavior and capabilities. -## Why Two Project Types +## Why two project types TiDB X Projects and Dedicated Projects serve different use cases and have different characteristics: @@ -24,38 +24,38 @@ TiDB X Projects and Dedicated Projects serve different use cases and have differ | Project-level RBAC | ✅ | ✅ | | Billing Aggregation | ✅ | ✅ | | Move instances between projects | ✅ | ❌ | -| Project is optional | ✅ (instances can exist at org level) | ❌ (clusters must belong to a project) | +| Project is optional | ✅ (instances can exist at the organization level) | ❌ (clusters must belong to a project) | | Resource type | TiDB X instances only | Dedicated clusters only | ### TiDB X Project -- **Lightweight and optional**. TiDB X users can create instances without assigning them to a project. Projects become useful when users want to organize and group resources, but are not required. -- **Instance mobility**. TiDB X instances can be moved between TiDB X Projects or back to the organization level, giving users flexibility in how they organize their resources. +- **Lightweight and optional**. You can create TiDB X instances without assigning them to a project. Projects are useful when you want to organize and group resources, but they are not required. +- **Instance mobility**. You can move TiDB X instances between TiDB X Projects or back to the organization level, giving you flexibility in how you organize your resources. ### Dedicated Project - **Mandatory project membership**. Every Dedicated cluster must belong to a Dedicated Project. - **No instance mobility across projects**. Dedicated clusters cannot be moved between projects due to their infrastructure bindings. -## Why Instances Need to Move +## Why instances need to move Before this change, a single project could contain both Dedicated clusters and TiDB X instances (Starter, Essential). With the introduction of typed projects, this mixed state is no longer supported. -**If a Dedicated Project currently contains TiDB X instances (Starter or Essential), those instances need to be moved out.** +**If your Dedicated Project currently contains TiDB X instances (Starter or Essential), you need to move those instances out.** This is because: 1. **Each project type now exclusively hosts its own resource type.** A Dedicated Project can only contain Dedicated clusters, and a TiDB X Project can only contain TiDB X instances. 2. **TiDB X instances and Dedicated clusters have different project behaviors.** TiDB X instances benefit from lightweight, optional project membership and instance mobility — capabilities that do not apply within a Dedicated Project. -3. **Keeping them separated ensures a consistent experience.** Users interacting with a Dedicated Project expect Dedicated-specific settings and behaviors. Mixing resource types would create confusion around which capabilities apply. +3. **Keeping them separated ensures a consistent experience.** When you interact with a Dedicated Project, you expect Dedicated-specific settings and behaviors. Mixing resource types would create confusion around which capabilities apply. -## What Happens When Instances Are Moved +## What happens when you move instances -When TiDB X instances are moved out of a Dedicated Project: +When you move TiDB X instances out of a Dedicated Project: -- The instances are moved to a **TiDB X Project**. -- **No data or service disruption** is expected. This is a resource re-organization action, not an infrastructure change. -- After the move, users manage their TiDB X instances through TiDB X Projects (or at the org level), and their Dedicated clusters continue to be managed through Dedicated Projects. +- TiDB Cloud moves the instances to a **TiDB X Project**. +- No data or service disruption occurs. This is a resource re-organization action, not an infrastructure change. +- After the move, you manage your TiDB X instances through TiDB X Projects (or at the organization level), and you continue to manage your Dedicated clusters through Dedicated Projects. ## Summary @@ -65,4 +65,4 @@ When TiDB X instances are moved out of a Dedicated Project: | TiDB X instances in Dedicated Projects inherited Dedicated project behaviors | TiDB X instances are managed in TiDB X Projects with their own lightweight model | | No distinction between project types | Clear separation: TiDB X Project vs Dedicated Project | -This change gives each product tier a project model that fits its own needs, while keeping the overall organization structure consistent and predictable. \ No newline at end of file +This change gives each product tier a project model that fits its own needs, while keeping the overall organization structure consistent and predictable. From e3ecb85ab9116747ef409aaa8da74bcdfb5a23ae Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 7 Apr 2026 11:36:25 +0800 Subject: [PATCH 03/25] Update tidbx-instance-move-faq.md --- tidb-cloud/tidbx-instance-move-faq.md | 152 ++++++++++++++++++-------- 1 file changed, 108 insertions(+), 44 deletions(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index 17639eed50d9d..cfbaf10574960 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -1,68 +1,132 @@ -# TiDB X Project and Dedicated Project: what changed and why instances need to move +--- +title: Project Migration FAQ for TiDB X Instances +summary: Learn why TiDB Cloud prompts you to move or convert your {{{ .starter }}} and Essential resources, what changes during project migration, and what follow-up actions might be required. +--- -## What changed +# Project Migration FAQ for TiDB X Instances -TiDB Cloud introduces **typed projects** to provide a clearer separation between different product tiers. Projects are classified into two distinct types: +TiDB X instances are service-oriented TiDB Cloud offerings built on the [TiDB X architecture](/tidb-cloud/tidb-x-architecture.md), including {{{ .starter }}}, {{{ .essential }}}, and {{{ .premium }}} instances. -- **TiDB X Project** — designed for TiDB Cloud X instances (Starter, Essential, Premium) -- **Dedicated Project** — designed for TiDB Cloud Dedicated clusters +This FAQ explains why you see the project migration banner in the [TiDB Cloud console](https://tidbcloud.com/), what changes during project migration, and what follow-up actions might be required after the migration. -Each project type can **only host its own resource type**: +## Why do I see the migration banner? -- A TiDB X Project can only contain TiDB X instances. -- A Dedicated Project can only contain Dedicated clusters. +Before April 15, 2026, TiDB Cloud had only one project type: **TiDB dedicated project**. In a dedicated project, you could manage different types of TiDB Cloud resources, such as {{{ .dedicated }}} clusters, {{{ .starter }}} instances, and {{{ .essential }}} instances. As a result, some projects contain both Dedicated clusters and {{{ .starter }}} or Essential instances, while others contain only {{{ .starter }}} and Essential instances. This mixed resource model is difficult to manage because these resource types have different management models and capabilities. -This typed project model maintains a consistent **Organization → Project → Resource** hierarchy across all tiers, while allowing each product line to evolve with its own project behavior and capabilities. +Starting from April 15, 2026, TiDB Cloud introduces separate project types to provide a clearer separation between different TiDB Cloud resources. Each project type can host only its own resource type: -## Why two project types +- **TiDB X project** for TiDB X instances +- **TiDB dedicated project** for {{{ .dedicated }}} clusters +- **TiDB X virtual project** for TiDB X instances that are kept at the organization level -TiDB X Projects and Dedicated Projects serve different use cases and have different characteristics: +This change is needed because TiDB X instances and {{{ .dedicated }}} clusters have different project behaviors and management models. TiDB X projects are lightweight and optional, while Dedicated project settings such as maintenance and alert subscriptions are mandatory for {{{ .dedicated }}} clusters. Keeping them separated provides a more consistent experience and avoids confusion about which project capabilities apply. -| Capability | TiDB X Project | Dedicated Project | -|---|---|---| -| Project Settings | ❌ | ✅ | -| Project-level RBAC | ✅ | ✅ | -| Billing Aggregation | ✅ | ✅ | -| Move instances between projects | ✅ | ❌ | -| Project is optional | ✅ (instances can exist at the organization level) | ❌ (clusters must belong to a project) | -| Resource type | TiDB X instances only | Dedicated clusters only | +With the introduction of project types, each project type can now host only its own resource type. As a result, Dedicated projects can no longer contain TiDB X instances. If your organization contains existing {{{ .starter }}} or Essential resources in dedicated projects, TiDB Cloud prompts you to migrate them to TiDB X projects so that project types and resource types are aligned under the new model. -### TiDB X Project +## What project types are available in TiDB Cloud? -- **Lightweight and optional**. You can create TiDB X instances without assigning them to a project. Projects are useful when you want to organize and group resources, but they are not required. -- **Instance mobility**. You can move TiDB X instances between TiDB X Projects or back to the organization level, giving you flexibility in how you organize your resources. +There are now three project types in TiDB Cloud: -### Dedicated Project +- **TiDB dedicated project**: This project type is used only for {{{ .dedicated }}} clusters. It helps you manage settings for {{{ .dedicated }}} clusters separately by project, such as RBAC, networks, maintenance, alert subscriptions, and encryption access. Each {{{ .dedicated }}} cluster must belong to a Dedicated project. +- **TiDB X project**: This project type is used only for TiDB X instances. It helps you manage RBAC for TiDB X instances by project. TiDB X projects are lightweight and optional, so you can either group TiDB X instances in a TiDB X project or keep them at the organization level. +- **TiDB X virtual project**: This project is virtual and does not provide any management capabilities. It acts as a virtual container for TiDB X instances that do not belong to any project, so these instances can be accessed through the TiDB Cloud API by using a project ID. Each organization has a unique virtual project ID. You can get this ID from the project view on the **[My TiDB](https://tidbcloud.com/tidbs)** page. -- **Mandatory project membership**. Every Dedicated cluster must belong to a Dedicated Project. -- **No instance mobility across projects**. Dedicated clusters cannot be moved between projects due to their infrastructure bindings. +The following table lists the differences between these project types: -## Why instances need to move +| Feature | TiDB Dedicated project | TiDB X project | TiDB X virtual project | +|---|---|---|---| +| Project icon in the TiDB Cloud console | |
| N/A | +| Resource type in the project | {{{ .dedicated}}} clusters only | TiDB X instances only | TiDB X instances only | +| Project is optional | ❌
(Each {{{ .dedicated }}} cluster must belong to a Dedicated project) | ✅
(You can either group a TiDB X instance in a TiDB X project or keep it at the organization level) | N/A
(TiDB X instances not grouped in any TiDB X project are automatically grouped in the TiDB X virtual project) | +| Project settings | ✅ | ❌ | ❌ | +| Infrastructure binding | ✅
(Strong binding) | ❌ | ❌ | +| RBAC model | Organization -> Project | Organization -> Project -> Instance | Organization -> Project -> Instance | +| Project-level RBAC | ✅ | ✅ | ❌ | +| Project-level billing | ✅ | ✅ | ❌ | +| Instance movement between TiDB X projects or the global scope | ❌ | ✅ | ✅
(You can move a TiDB X instance out of any TiDB X project or to a specific TiDB X project) | -Before this change, a single project could contain both Dedicated clusters and TiDB X instances (Starter, Essential). With the introduction of typed projects, this mixed state is no longer supported. +## Do I need to migrate my {{{ .starter }}} and Essential instances? -**If your Dedicated Project currently contains TiDB X instances (Starter or Essential), you need to move those instances out.** +It depends on how your current project is structured: -This is because: +- If your project contains only {{{ .starter }}} and Essential instances, TiDB Cloud converts the project to a TiDB X project automatically on April 15, 2026, so no further action is required. +- If your project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances, the TiDB Cloud console prompts you to move the {{{ .starter }}} and Essential instances to a new TiDB X project by clicking **Move & Unlock** in the top banner. -1. **Each project type now exclusively hosts its own resource type.** A Dedicated Project can only contain Dedicated clusters, and a TiDB X Project can only contain TiDB X instances. -2. **TiDB X instances and Dedicated clusters have different project behaviors.** TiDB X instances benefit from lightweight, optional project membership and instance mobility — capabilities that do not apply within a Dedicated Project. -3. **Keeping them separated ensures a consistent experience.** When you interact with a Dedicated Project, you expect Dedicated-specific settings and behaviors. Mixing resource types would create confusion around which capabilities apply. +## Who can perform the migration? -## What happens when you move instances +Only users with the `Organization Owner` role can start and complete the migration. -When you move TiDB X instances out of a Dedicated Project: +## What happens if my project contains only {{{ .starter }}} and Essential instances? -- TiDB Cloud moves the instances to a **TiDB X Project**. -- No data or service disruption occurs. This is a resource re-organization action, not an infrastructure change. -- After the move, you manage your TiDB X instances through TiDB X Projects (or at the organization level), and you continue to manage your Dedicated clusters through Dedicated Projects. +Projects that contain only {{{ .starter }}} and Essential instances are converted to a TiDB X project automatically on April 15, 2026. -## Summary +What changes after the migration: -| Before | After | -|---|---| -| A single project could contain both Dedicated clusters and TiDB X instances | Each project type exclusively hosts its own resource type | -| TiDB X instances in Dedicated Projects inherited Dedicated project behaviors | TiDB X instances are managed in TiDB X Projects with their own lightweight model | -| No distinction between project types | Clear separation: TiDB X Project vs Dedicated Project | +- The project becomes a TiDB X project. +- The new TiDB X project does not include dedicated project settings, such as network settings, CMEK settings, and maintenance configurations. -This change gives each product tier a project model that fits its own needs, while keeping the overall organization structure consistent and predictable. +What does not change after the migration: + +- Your existing instances and their data, availability, and performance. +- Your billing and usage. +- The project name and project ID. + +## What happens if my project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances? + +With the introduction of separate project types for different TiDB Cloud resources, a Dedicated project can no longer host TiDB X instances. + +If a project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances, TiDB Cloud prompts you in the top banner to move the {{{ .starter }}} and Essential instances in the project to a new **TiDB X project**. + +> **Note:** +> +> {{{ .dedicated }}} clusters remain in the original project after the migration. Therefore, the migration does not affect {{{ .dedicated }}} clusters. + +If you are the `Organization Owner`, you can click **Move & Unlock** in the top banner and follow the migration wizard to complete the migration. + +The migration wizard displays a list of {{{ .starter }}} and Essential instances to be moved and lets you specify a new name for the new TiDB X project. + +What changes after the migration: + +- The {{{ .starter }}} and Essential instances are moved to a newly created TiDB X project. +- The moved instances belong to a new project ID after the migration. +- Project-level RBAC permissions are copied to the new project. + +What does not change after the migration: + +- Your instance data. +- Your instance availability. +- Your instance performance. +- Your billing and usage. +- The underlying infrastructure of your instances. +- {{{ .dedicated }}} clusters remain in their current projects and are not moved. + +There is no additional cost for this migration. + +## What actions are required after migration? + +If your {{{ .starter }}} or Essential instances are moved to a new TiDB X project, review anything that depends on the original project ID or original project-level setup, such as the following: + +- automation or scripts +- integrations +- project-based operational workflows +- user access and RBAC assignments +- Data Service setup +- Data Apps +- Data Service API keys + +Project-level RBAC permissions are copied to the new project, but you should still review access after migration to make sure users and workflows still work as expected. + +## Do I need to undeploy my Data Service endpoints before migration? + +For projects deployed with [TiDB Cloud Data Service](/tidb-cloud/data-service-overview.md) endpoints, whether you need to undeploy Data Service endpoints before migration depends on how your current project is structured: + +- If your project contains only {{{ .starter }}} and Essential instances, because the project ID does not change after the migration, the Data Service endpoints still work after the migration, so no further action is required. +- If your project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances, because these {{{ .starter }}} or Essential instances are moved to new TiDB X projects after the migration, note the following: + + - Those {{{ .starter }}} and Essential instances cannot be moved until the endpoints are undeployed. + - After the migration is complete, you need to redeploy the required endpoints in the new TiDB X project and update your application configuration accordingly. + - If you use Data Apps or Data Service API keys, review and reconfigure them in the new project as needed. For more information, see [Manage Data Service endpoints](/tidb-cloud/data-service-manage-endpoint.md) and [API Keys in Data Service](/tidb-cloud/data-service-api-key.md). + +## Where can I get help? + +If you are unsure whether your automation, integrations, or Data Service setup depends on the original project ID, contact TiDB Cloud support at [support@pingcap.com](mailto:support@pingcap.com) before you start the migration. \ No newline at end of file From d7ea2e2671e169bd9a366b3529f73094d7c70a1f Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 7 Apr 2026 16:10:51 +0800 Subject: [PATCH 04/25] Update tidbx-instance-move-faq.md --- tidb-cloud/tidbx-instance-move-faq.md | 45 ++++++++++++++------------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index cfbaf10574960..13dd6466b8230 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -7,37 +7,40 @@ summary: Learn why TiDB Cloud prompts you to move or convert your {{{ .starter } TiDB X instances are service-oriented TiDB Cloud offerings built on the [TiDB X architecture](/tidb-cloud/tidb-x-architecture.md), including {{{ .starter }}}, {{{ .essential }}}, and {{{ .premium }}} instances. -This FAQ explains why you see the project migration banner in the [TiDB Cloud console](https://tidbcloud.com/), what changes during project migration, and what follow-up actions might be required after the migration. +This FAQ explains why the [TiDB Cloud console](https://tidbcloud.com/) prompts you to migrate your {{{ .starter }}} and Essential instances in the top banner, what changes occur during the migration process, and what follow-up actions you need to take. -## Why do I see the migration banner? +## Why does the TiDB Cloud console prompt you to migrate your {{{ .starter }}} and Essential instances? -Before April 15, 2026, TiDB Cloud had only one project type: **TiDB dedicated project**. In a dedicated project, you could manage different types of TiDB Cloud resources, such as {{{ .dedicated }}} clusters, {{{ .starter }}} instances, and {{{ .essential }}} instances. As a result, some projects contain both Dedicated clusters and {{{ .starter }}} or Essential instances, while others contain only {{{ .starter }}} and Essential instances. This mixed resource model is difficult to manage because these resource types have different management models and capabilities. +Before April 15, 2026, TiDB Cloud used a single **TiDB dedicated project** type to manage all TiDB Cloud resources. Such a project could contain a mix of {{{ .dedicated }}} clusters and TiDB X instances. However, mixing different resource types in one project increased management complexity because: -Starting from April 15, 2026, TiDB Cloud introduces separate project types to provide a clearer separation between different TiDB Cloud resources. Each project type can host only its own resource type: +- TiDB dedicated projects were originally designed for {{{ .dedicated }}} clusters. +- TiDB X instances and {{{ .dedicated }}} clusters have different behaviors and management models. -- **TiDB X project** for TiDB X instances -- **TiDB dedicated project** for {{{ .dedicated }}} clusters -- **TiDB X virtual project** for TiDB X instances that are kept at the organization level +Starting from April 15, 2026, TiDB Cloud introduces separate project types to provide clear separation between different resource types. Each project type now exclusively hosts its own resource type: -This change is needed because TiDB X instances and {{{ .dedicated }}} clusters have different project behaviors and management models. TiDB X projects are lightweight and optional, while Dedicated project settings such as maintenance and alert subscriptions are mandatory for {{{ .dedicated }}} clusters. Keeping them separated provides a more consistent experience and avoids confusion about which project capabilities apply. +- **TiDB X project**: for TiDB X instances +- **TiDB dedicated project**: for {{{ .dedicated }}} clusters +- **TiDB X virtual project**: for TiDB X instances not grouped in any TiDB X project -With the introduction of project types, each project type can now host only its own resource type. As a result, Dedicated projects can no longer contain TiDB X instances. If your organization contains existing {{{ .starter }}} or Essential resources in dedicated projects, TiDB Cloud prompts you to migrate them to TiDB X projects so that project types and resource types are aligned under the new model. +TiDB X projects are lightweight and optional for TiDB X instances, while dedicated projects are mandatory for {{{ .dedicated }}} clusters. Separating these resources ensures a more consistent user experience and eliminates confusion over which project capabilities apply. + +As a result of this separation, dedicated projects can no longer contain TiDB X instances. If your organization has existing {{{ .starter }}} or Essential resources in dedicated projects, TiDB Cloud prompts you to migrate them to TiDB X projects to align with the new resource model. ## What project types are available in TiDB Cloud? There are now three project types in TiDB Cloud: -- **TiDB dedicated project**: This project type is used only for {{{ .dedicated }}} clusters. It helps you manage settings for {{{ .dedicated }}} clusters separately by project, such as RBAC, networks, maintenance, alert subscriptions, and encryption access. Each {{{ .dedicated }}} cluster must belong to a Dedicated project. -- **TiDB X project**: This project type is used only for TiDB X instances. It helps you manage RBAC for TiDB X instances by project. TiDB X projects are lightweight and optional, so you can either group TiDB X instances in a TiDB X project or keep them at the organization level. -- **TiDB X virtual project**: This project is virtual and does not provide any management capabilities. It acts as a virtual container for TiDB X instances that do not belong to any project, so these instances can be accessed through the TiDB Cloud API by using a project ID. Each organization has a unique virtual project ID. You can get this ID from the project view on the **[My TiDB](https://tidbcloud.com/tidbs)** page. +- **TiDB dedicated project**: this project type is used only for {{{ .dedicated }}} clusters. It helps you manage settings for {{{ .dedicated }}} clusters separately by project, such as RBAC, networks, maintenance, alert subscriptions, and encryption access. Each {{{ .dedicated }}} cluster must belong to a dedicated project. +- **TiDB X project**: this project type is used only for TiDB X instances. It helps you manage RBAC for TiDB X instances by project. TiDB X projects are lightweight and optional, so you can either group TiDB X instances in a TiDB X project or keep them at the organization level. +- **TiDB X virtual project**: this project is virtual and does not provide any management capabilities. It acts as a logical container for TiDB X instances that do not belong to any project, so these instances can be accessed through the TiDB Cloud API by using a project ID. Each organization has a unique virtual project ID. You can get this ID from the project view on the **[My TiDB](https://tidbcloud.com/tidbs)** page. The following table lists the differences between these project types: -| Feature | TiDB Dedicated project | TiDB X project | TiDB X virtual project | +| Feature | TiDB dedicated project | TiDB X project | TiDB X virtual project | |---|---|---|---| | Project icon in the TiDB Cloud console | |
| N/A | | Resource type in the project | {{{ .dedicated}}} clusters only | TiDB X instances only | TiDB X instances only | -| Project is optional | ❌
(Each {{{ .dedicated }}} cluster must belong to a Dedicated project) | ✅
(You can either group a TiDB X instance in a TiDB X project or keep it at the organization level) | N/A
(TiDB X instances not grouped in any TiDB X project are automatically grouped in the TiDB X virtual project) | +| Project is optional | ❌
(Each {{{ .dedicated }}} cluster must belong to a dedicated project) | ✅
(You can either group a TiDB X instance in a TiDB X project or keep it at the organization level) | N/A
(TiDB X instances not grouped in any TiDB X project are automatically grouped in the TiDB X virtual project) | | Project settings | ✅ | ❌ | ❌ | | Infrastructure binding | ✅
(Strong binding) | ❌ | ❌ | | RBAC model | Organization -> Project | Organization -> Project -> Instance | Organization -> Project -> Instance | @@ -49,7 +52,7 @@ The following table lists the differences between these project types: It depends on how your current project is structured: -- If your project contains only {{{ .starter }}} and Essential instances, TiDB Cloud converts the project to a TiDB X project automatically on April 15, 2026, so no further action is required. +- If your project contains only {{{ .starter }}} and Essential instances, TiDB Cloud converts the project to a TiDB X project automatically on April 15, 2026. No further action is required. - If your project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances, the TiDB Cloud console prompts you to move the {{{ .starter }}} and Essential instances to a new TiDB X project by clicking **Move & Unlock** in the top banner. ## Who can perform the migration? @@ -73,7 +76,7 @@ What does not change after the migration: ## What happens if my project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances? -With the introduction of separate project types for different TiDB Cloud resources, a Dedicated project can no longer host TiDB X instances. +With the introduction of separate project types for different TiDB Cloud resources, a dedicated project can no longer host TiDB X instances. If a project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances, TiDB Cloud prompts you in the top banner to move the {{{ .starter }}} and Essential instances in the project to a new **TiDB X project**. @@ -106,10 +109,10 @@ There is no additional cost for this migration. If your {{{ .starter }}} or Essential instances are moved to a new TiDB X project, review anything that depends on the original project ID or original project-level setup, such as the following: -- automation or scripts -- integrations -- project-based operational workflows -- user access and RBAC assignments +- Automation or scripts +- Integrations +- Project-based operational workflows +- User access and RBAC assignments - Data Service setup - Data Apps - Data Service API keys @@ -123,7 +126,7 @@ For projects deployed with [TiDB Cloud Data Service](/tidb-cloud/data-service-ov - If your project contains only {{{ .starter }}} and Essential instances, because the project ID does not change after the migration, the Data Service endpoints still work after the migration, so no further action is required. - If your project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances, because these {{{ .starter }}} or Essential instances are moved to new TiDB X projects after the migration, note the following: - - Those {{{ .starter }}} and Essential instances cannot be moved until the endpoints are undeployed. + - Those {{{ .starter }}} and Essential instances cannot be moved until their associated endpoints are undeployed. - After the migration is complete, you need to redeploy the required endpoints in the new TiDB X project and update your application configuration accordingly. - If you use Data Apps or Data Service API keys, review and reconfigure them in the new project as needed. For more information, see [Manage Data Service endpoints](/tidb-cloud/data-service-manage-endpoint.md) and [API Keys in Data Service](/tidb-cloud/data-service-api-key.md). From 825ff3a83b9355ebb99ea6a5b9dab1bd9b36d85f Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 7 Apr 2026 16:40:45 +0800 Subject: [PATCH 05/25] Update tidbx-instance-move-faq.md --- tidb-cloud/tidbx-instance-move-faq.md | 31 +++++++++++++++++++++------ 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index 13dd6466b8230..33ae8757b1744 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -9,7 +9,7 @@ TiDB X instances are service-oriented TiDB Cloud offerings built on the [TiDB X This FAQ explains why the [TiDB Cloud console](https://tidbcloud.com/) prompts you to migrate your {{{ .starter }}} and Essential instances in the top banner, what changes occur during the migration process, and what follow-up actions you need to take. -## Why does the TiDB Cloud console prompt you to migrate your {{{ .starter }}} and Essential instances? +## Why does the TiDB Cloud console prompt you to move your {{{ .starter }}} and Essential instances? Before April 15, 2026, TiDB Cloud used a single **TiDB dedicated project** type to manage all TiDB Cloud resources. Such a project could contain a mix of {{{ .dedicated }}} clusters and TiDB X instances. However, mixing different resource types in one project increased management complexity because: @@ -28,25 +28,40 @@ As a result of this separation, dedicated projects can no longer contain TiDB X ## What project types are available in TiDB Cloud? -There are now three project types in TiDB Cloud: +TiDB Cloud provides three project types for different resource types and use cases. -- **TiDB dedicated project**: this project type is used only for {{{ .dedicated }}} clusters. It helps you manage settings for {{{ .dedicated }}} clusters separately by project, such as RBAC, networks, maintenance, alert subscriptions, and encryption access. Each {{{ .dedicated }}} cluster must belong to a dedicated project. -- **TiDB X project**: this project type is used only for TiDB X instances. It helps you manage RBAC for TiDB X instances by project. TiDB X projects are lightweight and optional, so you can either group TiDB X instances in a TiDB X project or keep them at the organization level. -- **TiDB X virtual project**: this project is virtual and does not provide any management capabilities. It acts as a logical container for TiDB X instances that do not belong to any project, so these instances can be accessed through the TiDB Cloud API by using a project ID. Each organization has a unique virtual project ID. You can get this ID from the project view on the **[My TiDB](https://tidbcloud.com/tidbs)** page. +- **TiDB dedicated project**: this project type is used only for {{{ .dedicated }}} clusters. + + - It helps you manage settings for {{{ .dedicated }}} clusters separately by project, such as RBAC, networks, maintenance, alert subscriptions, and encryption access. + - Each {{{ .dedicated }}} cluster must belong to a dedicated project. + - {{{ .dedicated }}} clusters cannot be moved between projects because of their infrastructure bindings. + +- **TiDB X project**: this project type is used only for TiDB X instances. + + - It helps you manage RBAC for TiDB X instances by project. + - TiDB X projects are lightweight and optional, so you can create TiDB X instances without assigning them to a project. + - Projects are useful when you want to organize and group TiDB X instances, but they are not required. + - You can move TiDB X instances between TiDB X projects or back to the organization level. + +- **TiDB X virtual project**: this project is virtual and does not provide any management capabilities. + + - It acts as a logical container for TiDB X instances that do not belong to any project, so these instances can be accessed through the TiDB Cloud API by using a project ID. + - Each organization has a unique virtual project ID. + - You can get this ID from the project view on the **[My TiDB](https://tidbcloud.com/tidbs)** page. The following table lists the differences between these project types: | Feature | TiDB dedicated project | TiDB X project | TiDB X virtual project | |---|---|---|---| | Project icon in the TiDB Cloud console | |
| N/A | -| Resource type in the project | {{{ .dedicated}}} clusters only | TiDB X instances only | TiDB X instances only | +| Resource type | {{{ .dedicated}}} clusters only | TiDB X instances only | TiDB X instances only | | Project is optional | ❌
(Each {{{ .dedicated }}} cluster must belong to a dedicated project) | ✅
(You can either group a TiDB X instance in a TiDB X project or keep it at the organization level) | N/A
(TiDB X instances not grouped in any TiDB X project are automatically grouped in the TiDB X virtual project) | | Project settings | ✅ | ❌ | ❌ | | Infrastructure binding | ✅
(Strong binding) | ❌ | ❌ | | RBAC model | Organization -> Project | Organization -> Project -> Instance | Organization -> Project -> Instance | | Project-level RBAC | ✅ | ✅ | ❌ | | Project-level billing | ✅ | ✅ | ❌ | -| Instance movement between TiDB X projects or the global scope | ❌ | ✅ | ✅
(You can move a TiDB X instance out of any TiDB X project or to a specific TiDB X project) | +| Instance movement between projects | ❌ | ✅
(You can move a TiDB X instance to a specific TiDB X project or out of any project) | ✅
(You can move a TiDB X instance out of any TiDB X project to a specific TiDB X project) | ## Do I need to migrate my {{{ .starter }}} and Essential instances? @@ -105,6 +120,8 @@ What does not change after the migration: There is no additional cost for this migration. +After the migration, you can manage your TiDB X instances through TiDB X projects (or at the organization level), and continue to manage your {{{ .dedicated }}} clusters through dedicated projects. + ## What actions are required after migration? If your {{{ .starter }}} or Essential instances are moved to a new TiDB X project, review anything that depends on the original project ID or original project-level setup, such as the following: From 04ec81773a56cea0807a7ec2ca85f8549e4d9e26 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 8 Apr 2026 10:03:50 +0800 Subject: [PATCH 06/25] migrate -> move --- tidb-cloud/tidbx-instance-move-faq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index 33ae8757b1744..dfc2ba0bbe5a2 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -7,7 +7,7 @@ summary: Learn why TiDB Cloud prompts you to move or convert your {{{ .starter } TiDB X instances are service-oriented TiDB Cloud offerings built on the [TiDB X architecture](/tidb-cloud/tidb-x-architecture.md), including {{{ .starter }}}, {{{ .essential }}}, and {{{ .premium }}} instances. -This FAQ explains why the [TiDB Cloud console](https://tidbcloud.com/) prompts you to migrate your {{{ .starter }}} and Essential instances in the top banner, what changes occur during the migration process, and what follow-up actions you need to take. +This FAQ explains why the [TiDB Cloud console](https://tidbcloud.com/) prompts you to move your {{{ .starter }}} and Essential instances to TiDB X projects, and what changes occur during the migration process, and what follow-up actions you need to take. ## Why does the TiDB Cloud console prompt you to move your {{{ .starter }}} and Essential instances? @@ -24,7 +24,7 @@ Starting from April 15, 2026, TiDB Cloud introduces separate project types to pr TiDB X projects are lightweight and optional for TiDB X instances, while dedicated projects are mandatory for {{{ .dedicated }}} clusters. Separating these resources ensures a more consistent user experience and eliminates confusion over which project capabilities apply. -As a result of this separation, dedicated projects can no longer contain TiDB X instances. If your organization has existing {{{ .starter }}} or Essential resources in dedicated projects, TiDB Cloud prompts you to migrate them to TiDB X projects to align with the new resource model. +As a result of this separation, dedicated projects can no longer contain TiDB X instances. If your organization has existing {{{ .starter }}} or Essential resources in dedicated projects, TiDB Cloud prompts you to move them to TiDB X projects to align with the new resource model. ## What project types are available in TiDB Cloud? @@ -63,7 +63,7 @@ The following table lists the differences between these project types: | Project-level billing | ✅ | ✅ | ❌ | | Instance movement between projects | ❌ | ✅
(You can move a TiDB X instance to a specific TiDB X project or out of any project) | ✅
(You can move a TiDB X instance out of any TiDB X project to a specific TiDB X project) | -## Do I need to migrate my {{{ .starter }}} and Essential instances? +## Do I need to move my {{{ .starter }}} and Essential instances? It depends on how your current project is structured: From 1047fe1f126e1d61f868afce75a5698711757837 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 8 Apr 2026 17:08:37 +0800 Subject: [PATCH 07/25] remove the faq about data service --- tidb-cloud/tidbx-instance-move-faq.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index dfc2ba0bbe5a2..ad4cb48a6e59c 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -136,17 +136,6 @@ If your {{{ .starter }}} or Essential instances are moved to a new TiDB X projec Project-level RBAC permissions are copied to the new project, but you should still review access after migration to make sure users and workflows still work as expected. -## Do I need to undeploy my Data Service endpoints before migration? - -For projects deployed with [TiDB Cloud Data Service](/tidb-cloud/data-service-overview.md) endpoints, whether you need to undeploy Data Service endpoints before migration depends on how your current project is structured: - -- If your project contains only {{{ .starter }}} and Essential instances, because the project ID does not change after the migration, the Data Service endpoints still work after the migration, so no further action is required. -- If your project contains both {{{ .dedicated }}} clusters and {{{ .starter }}} or Essential instances, because these {{{ .starter }}} or Essential instances are moved to new TiDB X projects after the migration, note the following: - - - Those {{{ .starter }}} and Essential instances cannot be moved until their associated endpoints are undeployed. - - After the migration is complete, you need to redeploy the required endpoints in the new TiDB X project and update your application configuration accordingly. - - If you use Data Apps or Data Service API keys, review and reconfigure them in the new project as needed. For more information, see [Manage Data Service endpoints](/tidb-cloud/data-service-manage-endpoint.md) and [API Keys in Data Service](/tidb-cloud/data-service-api-key.md). - ## Where can I get help? If you are unsure whether your automation, integrations, or Data Service setup depends on the original project ID, contact TiDB Cloud support at [support@pingcap.com](mailto:support@pingcap.com) before you start the migration. \ No newline at end of file From eae9b6c452975831fbd15e3445ab1bd0642c2e1c Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 8 Apr 2026 17:14:09 +0800 Subject: [PATCH 08/25] =?UTF-8?q?remove=20an=20extra=20=E2=80=9Cand"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- tidb-cloud/tidbx-instance-move-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index ad4cb48a6e59c..059ee72eb3216 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -7,7 +7,7 @@ summary: Learn why TiDB Cloud prompts you to move or convert your {{{ .starter } TiDB X instances are service-oriented TiDB Cloud offerings built on the [TiDB X architecture](/tidb-cloud/tidb-x-architecture.md), including {{{ .starter }}}, {{{ .essential }}}, and {{{ .premium }}} instances. -This FAQ explains why the [TiDB Cloud console](https://tidbcloud.com/) prompts you to move your {{{ .starter }}} and Essential instances to TiDB X projects, and what changes occur during the migration process, and what follow-up actions you need to take. +This FAQ explains why the [TiDB Cloud console](https://tidbcloud.com/) prompts you to move your {{{ .starter }}} and Essential instances to TiDB X projects, what changes occur during the migration process, and what follow-up actions you need to take. ## Why does the TiDB Cloud console prompt you to move your {{{ .starter }}} and Essential instances? From c9fc987701f93299fcff2ae3880f47715c97f27a Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 10 Apr 2026 14:16:11 +0800 Subject: [PATCH 09/25] add the new added file to TOC --- TOC-tidb-cloud-essential.md | 1 + TOC-tidb-cloud-starter.md | 1 + 2 files changed, 2 insertions(+) diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index 8cf01a75cfebf..bbeaacfed8e8a 100644 --- a/TOC-tidb-cloud-essential.md +++ b/TOC-tidb-cloud-essential.md @@ -572,4 +572,5 @@ - [Get Support](/tidb-cloud/tidb-cloud-support.md) - FAQs - [TiDB Cloud FAQs](/tidb-cloud/tidb-cloud-faq.md) + - [Project Migration FAQ for TiDB X Instances](/tidb-cloud/tidbx-instance-move-faq.md) - [Glossary](/tidb-cloud/tidb-cloud-glossary.md) diff --git a/TOC-tidb-cloud-starter.md b/TOC-tidb-cloud-starter.md index 67172ccf892f3..c85ae4645e2a0 100644 --- a/TOC-tidb-cloud-starter.md +++ b/TOC-tidb-cloud-starter.md @@ -559,4 +559,5 @@ - FAQs - [TiDB Cloud FAQs](/tidb-cloud/tidb-cloud-faq.md) - [{{{ .starter }}} FAQs](/tidb-cloud/serverless-faqs.md) + - [Project Migration FAQ for TiDB X Instances](/tidb-cloud/tidbx-instance-move-faq.md) - [Glossary](/tidb-cloud/tidb-cloud-glossary.md) From 134db86d4a07b34c033a0e764b313a79af66814a Mon Sep 17 00:00:00 2001 From: awxxxxxx Date: Mon, 13 Apr 2026 10:54:31 +0800 Subject: [PATCH 10/25] Enhance TiDB Cloud documentation with OpenAPI Migration Guide for Starter and Essential instances, and update instance move FAQ to reference the new guide for API management. --- tidb-cloud/tidbx-instance-move-faq.md | 2 + ...arter-essential-openapi-migration-guide.md | 83 +++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index 059ee72eb3216..35e6cd6b54c5a 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -136,6 +136,8 @@ If your {{{ .starter }}} or Essential instances are moved to a new TiDB X projec Project-level RBAC permissions are copied to the new project, but you should still review access after migration to make sure users and workflows still work as expected. +If you use the TiDB Cloud API to manage your instances, see [OpenAPI Migration Guide for Starter and Essential](/tidbx-starter-essential-openapi-migration-guide.md) to update your API calls. + ## Where can I get help? If you are unsure whether your automation, integrations, or Data Service setup depends on the original project ID, contact TiDB Cloud support at [support@pingcap.com](mailto:support@pingcap.com) before you start the migration. \ No newline at end of file diff --git a/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md b/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md new file mode 100644 index 0000000000000..afed3d151d96a --- /dev/null +++ b/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md @@ -0,0 +1,83 @@ +--- +title: OpenAPI Lightweight Migration Guide for Starter and Essential +summary: Learn the minimum changes required to keep your existing v1beta API calls working after TiDB Cloud introduces separate project types for TiDB X instances. +--- + +# OpenAPI Migration Guide for Starter and Essential + +This guide is for API callers that want to keep most existing `v1beta` calls working and only patch project lookup and cluster creation for Starter and Essential instances. + +There are two changes to be aware of: + +- `project_id` values for Starter and Essential instances **can change** because these instances can be moved between projects. Do not hardcode `project_id` values. +- Project responses now include a `type` field. See [Project type values](#project-type-values) for the possible values. + +## Project API changes + +### GET /api/v1beta/projects + +`GET /api/v1beta/projects` now returns a `type` field for each project. + +#### Project type values + +| Value | Description | +|---|---| +| `dedicated` | A project that contains only TiDB Dedicated clusters. | +| `tidbx` | A project that contains only TiDB X instances (Starter, Essential, and Premium). | +| `tidbx_virtual` | The organization-level default project for TiDB X instances not assigned to any project. There is only one per organization. | + +> **Note:** +> +> Starter and Essential instances both use the `tidbx` project type. + +**If you only read `id` and `name` from project responses**, you likely do not need to make any changes. + +**If you need to distinguish between project types** (for example, to filter for dedicated projects, TiDB X projects, or the default project), start reading the `type` field. + +### POST /api/v1beta/projects + +If you create projects using `POST /api/v1beta/projects`, note the following: + +- Only `dedicated` and `tidbx` are valid values for `type` at creation time. +- If `type` is omitted, the API creates a `dedicated` project by default. + +## How to get a project ID for an existing instance + +If you already have a Starter or Essential instance and only need the current `project_id`, use the following approach instead of hardcoding a value. + +**Step 1.** Call the cluster detail endpoint: + +```http +GET https://serverless.tidbapi.com/v1beta1/clusters/{clusterId} +``` + +**Step 2.** Read `labels["tidb.cloud/project"]` from the response: + +```json +{ + "clusterId": "1048576", + "labels": { + "tidb.cloud/project": "2293484" + } +} +``` + +**Step 3.** Use the retrieved `project_id` with existing `v1beta` endpoints. For example: + +- `GET /api/v1beta/projects/{project_id}/clusters/{cluster_id}` +- `DELETE /api/v1beta/projects/{project_id}/clusters/{cluster_id}` +- `GET /api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports` +- `POST /api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports` + +> **Note:** +> +> This approach does not cover cluster creation using `POST /api/v1beta/projects/{project_id}/clusters`. Note that `v1beta` only supports creating Starter instances and Dedicated clusters. If you need to create an Essential instance, use the `v1beta1` API instead. For more information, see [TiDB Cloud API documentation](https://docs.pingcap.com/api/). For creating new Starter or Essential instances, see your cluster creation workflow to ensure you are targeting a `tidbx` project. + +## Summary of required changes + +| Scenario | Action required | +|---|---| +| You read `id` and `name` from project responses only | No changes needed. | +| You hardcode `project_id` for Starter or Essential instances | Replace hardcoded values with dynamic lookup via `labels["tidb.cloud/project"]`. | +| You create projects and need to target TiDB X instances | Pass `"type": "tidbx"` in the request body of `POST /api/v1beta/projects`. | +| You filter projects by type | Start reading the `type` field from `GET /api/v1beta/projects` responses. | From 4a0e0b9a73431383a0691eac048d760005a3ed27 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 13 Apr 2026 15:02:02 +0800 Subject: [PATCH 11/25] Apply suggestions from code review Co-authored-by: xixirangrang --- tidb-cloud/tidbx-instance-move-faq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index 35e6cd6b54c5a..63081ae4d24fa 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -9,7 +9,7 @@ TiDB X instances are service-oriented TiDB Cloud offerings built on the [TiDB X This FAQ explains why the [TiDB Cloud console](https://tidbcloud.com/) prompts you to move your {{{ .starter }}} and Essential instances to TiDB X projects, what changes occur during the migration process, and what follow-up actions you need to take. -## Why does the TiDB Cloud console prompt you to move your {{{ .starter }}} and Essential instances? +## Why does the TiDB Cloud console prompt me to move my {{{ .starter }}} and Essential instances? Before April 15, 2026, TiDB Cloud used a single **TiDB dedicated project** type to manage all TiDB Cloud resources. Such a project could contain a mix of {{{ .dedicated }}} clusters and TiDB X instances. However, mixing different resource types in one project increased management complexity because: @@ -18,8 +18,8 @@ Before April 15, 2026, TiDB Cloud used a single **TiDB dedicated project** type Starting from April 15, 2026, TiDB Cloud introduces separate project types to provide clear separation between different resource types. Each project type now exclusively hosts its own resource type: -- **TiDB X project**: for TiDB X instances - **TiDB dedicated project**: for {{{ .dedicated }}} clusters +- **TiDB X project**: for TiDB X instances - **TiDB X virtual project**: for TiDB X instances not grouped in any TiDB X project TiDB X projects are lightweight and optional for TiDB X instances, while dedicated projects are mandatory for {{{ .dedicated }}} clusters. Separating these resources ensures a more consistent user experience and eliminates confusion over which project capabilities apply. @@ -134,7 +134,7 @@ If your {{{ .starter }}} or Essential instances are moved to a new TiDB X projec - Data Apps - Data Service API keys -Project-level RBAC permissions are copied to the new project, but you should still review access after migration to make sure users and workflows still work as expected. +Project-level RBAC permissions are copied to the new project, but you must still review access after migration to make sure users and workflows still work as expected. If you use the TiDB Cloud API to manage your instances, see [OpenAPI Migration Guide for Starter and Essential](/tidbx-starter-essential-openapi-migration-guide.md) to update your API calls. From 0a1b73b809f8a7120516e71ec5ec23ae4f42a2eb Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 13 Apr 2026 17:01:19 +0800 Subject: [PATCH 12/25] add api change doc to toc and add some background info --- TOC-api.md | 1 + ...arter-essential-openapi-migration-guide.md | 72 ++++++++++--------- 2 files changed, 38 insertions(+), 35 deletions(-) diff --git a/TOC-api.md b/TOC-api.md index b31833afb27c3..3649d5c4fe694 100644 --- a/TOC-api.md +++ b/TOC-api.md @@ -8,6 +8,7 @@ - [API Overview](/api/tidb-cloud-api-overview.md) - [API v1beta1](/api/tidb-cloud-api-v1beta1.md) - [API v1beta](/api/tidb-cloud-api-v1beta.md) +- [TiDB Cloud API Migration Guide for Starter and Essential](/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md) ## TIDB SELF-MANAGED diff --git a/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md b/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md index afed3d151d96a..898e1dce38492 100644 --- a/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md +++ b/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md @@ -1,16 +1,18 @@ --- -title: OpenAPI Lightweight Migration Guide for Starter and Essential -summary: Learn the minimum changes required to keep your existing v1beta API calls working after TiDB Cloud introduces separate project types for TiDB X instances. +title: TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential +summary: Learn the minimum changes needed to keep your existing v1beta API calls working after TiDB Cloud introduces separate project types for TiDB X instances. --- -# OpenAPI Migration Guide for Starter and Essential +# TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential -This guide is for API callers that want to keep most existing `v1beta` calls working and only patch project lookup and cluster creation for Starter and Essential instances. +Starting from April 15, 2026, TiDB Cloud introduces separate project types for different resource types. For {{{ .starter }}} and Essential instances, you can now manage them either in TiDB X projects or at the organization level. For more information, see [Project Migration FAQ for TiDB X Instances](/tidb-cloud/tidbx-instance-move-faq.md). -There are two changes to be aware of: +This guide is intended for API callers who want to keep most existing `v1beta` calls working and make only the minimum changes to project lookup and cluster creation for {{{ .starter }}} and Essential instances. -- `project_id` values for Starter and Essential instances **can change** because these instances can be moved between projects. Do not hardcode `project_id` values. -- Project responses now include a `type` field. See [Project type values](#project-type-values) for the possible values. +Because of these project model changes, note the following API changes: + +- `project_id` values for {{{ .starter }}} and Essential instances **can change** because these instances can be moved between projects. Do not hardcode `project_id` values. +- Project responses now include a `type` field. For possible values, see [Project type values](#project-type-values). ## Project API changes @@ -23,61 +25,61 @@ There are two changes to be aware of: | Value | Description | |---|---| | `dedicated` | A project that contains only TiDB Dedicated clusters. | -| `tidbx` | A project that contains only TiDB X instances (Starter, Essential, and Premium). | -| `tidbx_virtual` | The organization-level default project for TiDB X instances not assigned to any project. There is only one per organization. | +| `tidbx` | A project that contains only TiDB X instances (such as {{{ .starter }}} and Essential). | +| `tidbx_virtual` | The default organization-level project for TiDB X instances that are not assigned to any project. For each organization, there is only a single `tidbx_virtual` project. | > **Note:** > -> Starter and Essential instances both use the `tidbx` project type. +> {{{ .starter }}} and Essential instances both use the `tidbx` project type. **If you only read `id` and `name` from project responses**, you likely do not need to make any changes. -**If you need to distinguish between project types** (for example, to filter for dedicated projects, TiDB X projects, or the default project), start reading the `type` field. +**If you need to distinguish between project types** (for example, to filter dedicated projects, TiDB X projects, or the TiDB X virtual project), start reading the `type` field. ### POST /api/v1beta/projects If you create projects using `POST /api/v1beta/projects`, note the following: -- Only `dedicated` and `tidbx` are valid values for `type` at creation time. +- Only `dedicated` and `tidbx` are valid `type` values when creating a project. - If `type` is omitted, the API creates a `dedicated` project by default. ## How to get a project ID for an existing instance -If you already have a Starter or Essential instance and only need the current `project_id`, use the following approach instead of hardcoding a value. +If you already have a {{{ .starter }}} or Essential instance and only need its current `project_id`, use the following approach instead of hardcoding the value. -**Step 1.** Call the cluster detail endpoint: +1. Call the cluster details endpoint: -```http -GET https://serverless.tidbapi.com/v1beta1/clusters/{clusterId} -``` + ```http + GET https://serverless.tidbapi.com/v1beta1/clusters/{clusterId} + ``` -**Step 2.** Read `labels["tidb.cloud/project"]` from the response: +2. Read `labels["tidb.cloud/project"]` from the response: -```json -{ - "clusterId": "1048576", - "labels": { - "tidb.cloud/project": "2293484" - } -} -``` + ```json + { + "clusterId": "1048576", + "labels": { + "tidb.cloud/project": "2293484" + } + } + ``` -**Step 3.** Use the retrieved `project_id` with existing `v1beta` endpoints. For example: +3. Use the retrieved `project_id` with your existing `v1beta` endpoints. For example: -- `GET /api/v1beta/projects/{project_id}/clusters/{cluster_id}` -- `DELETE /api/v1beta/projects/{project_id}/clusters/{cluster_id}` -- `GET /api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports` -- `POST /api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports` + - `GET /api/v1beta/projects/{project_id}/clusters/{cluster_id}` + - `DELETE /api/v1beta/projects/{project_id}/clusters/{cluster_id}` + - `GET /api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports` + - `POST /api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports` > **Note:** > -> This approach does not cover cluster creation using `POST /api/v1beta/projects/{project_id}/clusters`. Note that `v1beta` only supports creating Starter instances and Dedicated clusters. If you need to create an Essential instance, use the `v1beta1` API instead. For more information, see [TiDB Cloud API documentation](https://docs.pingcap.com/api/). For creating new Starter or Essential instances, see your cluster creation workflow to ensure you are targeting a `tidbx` project. +> This approach does not apply to cluster creation using `POST /api/v1beta/projects/{project_id}/clusters`. Note that `v1beta` supports creating only {{{ .starter }}} instances and Dedicated clusters. To create a {{{ .essential }}} instance, use the `v1beta1` API instead. For more information, see [TiDB Cloud API documentation](https://docs.pingcap.com/api/). When creating new {{{ .starter }}} or Essential instances, check your cluster creation workflow to ensure that it targets a `tidbx` project. ## Summary of required changes | Scenario | Action required | |---|---| -| You read `id` and `name` from project responses only | No changes needed. | -| You hardcode `project_id` for Starter or Essential instances | Replace hardcoded values with dynamic lookup via `labels["tidb.cloud/project"]`. | +| You read only `id` and `name` from project responses | No changes needed. | +| You hardcode `project_id` for {{{ .starter }}} or Essential instances | Replace hardcoded values with a dynamic lookup using `labels["tidb.cloud/project"]`. | | You create projects and need to target TiDB X instances | Pass `"type": "tidbx"` in the request body of `POST /api/v1beta/projects`. | -| You filter projects by type | Start reading the `type` field from `GET /api/v1beta/projects` responses. | +| You filter projects by type | Start reading the `type` field from `GET /api/v1beta/projects` responses. | \ No newline at end of file From d4b7e496f65bf7ae77c953cdbcdc0f74f10c94d9 Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 13 Apr 2026 17:01:19 +0800 Subject: [PATCH 13/25] rename tidbx-starter-essential-openapi-migration-guide.md to tidbx-starter-essential-api-migration-guide.md --- tidb-cloud/tidbx-instance-move-faq.md | 2 +- ...-guide.md => tidbx-starter-essential-api-migration-guide.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename tidb-cloud/{tidbx-starter-essential-openapi-migration-guide.md => tidbx-starter-essential-api-migration-guide.md} (100%) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index 63081ae4d24fa..e5543d6ba7383 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -136,7 +136,7 @@ If your {{{ .starter }}} or Essential instances are moved to a new TiDB X projec Project-level RBAC permissions are copied to the new project, but you must still review access after migration to make sure users and workflows still work as expected. -If you use the TiDB Cloud API to manage your instances, see [OpenAPI Migration Guide for Starter and Essential](/tidbx-starter-essential-openapi-migration-guide.md) to update your API calls. +If you use the TiDB Cloud API to manage your instances, see [OpenAPI Migration Guide for Starter and Essential](/tidbx-starter-essential-api-migration-guide.md) to update your API calls. ## Where can I get help? diff --git a/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md b/tidb-cloud/tidbx-starter-essential-api-migration-guide.md similarity index 100% rename from tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md rename to tidb-cloud/tidbx-starter-essential-api-migration-guide.md From c9e5d2d6ef43e989b44f4ffccc60d52f49504533 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 13 Apr 2026 22:04:18 +0800 Subject: [PATCH 14/25] Apply suggestions from code review Co-authored-by: xixirangrang --- tidb-cloud/tidbx-starter-essential-api-migration-guide.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tidb-cloud/tidbx-starter-essential-api-migration-guide.md b/tidb-cloud/tidbx-starter-essential-api-migration-guide.md index 898e1dce38492..c88d4201333a1 100644 --- a/tidb-cloud/tidbx-starter-essential-api-migration-guide.md +++ b/tidb-cloud/tidbx-starter-essential-api-migration-guide.md @@ -24,7 +24,7 @@ Because of these project model changes, note the following API changes: | Value | Description | |---|---| -| `dedicated` | A project that contains only TiDB Dedicated clusters. | +| `dedicated` | A project that contains only TiDB Cloud Dedicated clusters. | | `tidbx` | A project that contains only TiDB X instances (such as {{{ .starter }}} and Essential). | | `tidbx_virtual` | The default organization-level project for TiDB X instances that are not assigned to any project. For each organization, there is only a single `tidbx_virtual` project. | @@ -73,7 +73,9 @@ If you already have a {{{ .starter }}} or Essential instance and only need its c > **Note:** > -> This approach does not apply to cluster creation using `POST /api/v1beta/projects/{project_id}/clusters`. Note that `v1beta` supports creating only {{{ .starter }}} instances and Dedicated clusters. To create a {{{ .essential }}} instance, use the `v1beta1` API instead. For more information, see [TiDB Cloud API documentation](https://docs.pingcap.com/api/). When creating new {{{ .starter }}} or Essential instances, check your cluster creation workflow to ensure that it targets a `tidbx` project. +> - This approach does not apply to cluster creation using `POST /api/v1beta/projects/{project_id}/clusters`. +> - `v1beta` supports creating only {{{ .starter }}} instances and TiDB Cloud Dedicated clusters. To create a {{{ .essential }}} instance, use the `v1beta1` API instead. For more information, see [TiDB Cloud API documentation](https://docs.pingcap.com/api/). +> - When creating new {{{ .starter }}} or Essential instances, check your cluster creation workflow to ensure that it targets a `tidbx` project. ## Summary of required changes From f74c8267bc4a4919121b0db9c120e4b4abd1a972 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 14 Apr 2026 15:59:03 +0800 Subject: [PATCH 15/25] Update tidb-cloud/tidbx-instance-move-faq.md --- tidb-cloud/tidbx-instance-move-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index e5543d6ba7383..31e7a34834bea 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -136,7 +136,7 @@ If your {{{ .starter }}} or Essential instances are moved to a new TiDB X projec Project-level RBAC permissions are copied to the new project, but you must still review access after migration to make sure users and workflows still work as expected. -If you use the TiDB Cloud API to manage your instances, see [OpenAPI Migration Guide for Starter and Essential](/tidbx-starter-essential-api-migration-guide.md) to update your API calls. +If you use the TiDB Cloud API to manage your instances, see [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidbx-starter-essential-api-migration-guide.md) to update your API calls. ## Where can I get help? From 680013a82a2d32ff02189489224f459d0661af14 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 14 Apr 2026 16:18:44 +0800 Subject: [PATCH 16/25] Update TOC-api.md --- TOC-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TOC-api.md b/TOC-api.md index 3649d5c4fe694..1f55ba2a454ab 100644 --- a/TOC-api.md +++ b/TOC-api.md @@ -8,7 +8,7 @@ - [API Overview](/api/tidb-cloud-api-overview.md) - [API v1beta1](/api/tidb-cloud-api-v1beta1.md) - [API v1beta](/api/tidb-cloud-api-v1beta.md) -- [TiDB Cloud API Migration Guide for Starter and Essential](/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md) +- [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md) ## TIDB SELF-MANAGED From a32135b737bc86dcb995439b892d51a2fd36dcd7 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 14 Apr 2026 16:24:02 +0800 Subject: [PATCH 17/25] fix a broken link --- tidb-cloud/tidbx-instance-move-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index 31e7a34834bea..f9657e6a62cfd 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -136,7 +136,7 @@ If your {{{ .starter }}} or Essential instances are moved to a new TiDB X projec Project-level RBAC permissions are copied to the new project, but you must still review access after migration to make sure users and workflows still work as expected. -If you use the TiDB Cloud API to manage your instances, see [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidbx-starter-essential-api-migration-guide.md) to update your API calls. +If you use the TiDB Cloud API to manage your instances, see [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) to update your API calls. ## Where can I get help? From ab2811d057d6b37a6578668cb791b67c0399c509 Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 14 Apr 2026 16:37:32 +0800 Subject: [PATCH 18/25] move the API Migration Guide to starter/essential TOC --- TOC-api.md | 1 - TOC-tidb-cloud-essential.md | 1 + TOC-tidb-cloud-starter.md | 1 + 3 files changed, 2 insertions(+), 1 deletion(-) diff --git a/TOC-api.md b/TOC-api.md index 1f55ba2a454ab..b31833afb27c3 100644 --- a/TOC-api.md +++ b/TOC-api.md @@ -8,7 +8,6 @@ - [API Overview](/api/tidb-cloud-api-overview.md) - [API v1beta1](/api/tidb-cloud-api-v1beta1.md) - [API v1beta](/api/tidb-cloud-api-v1beta.md) -- [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md) ## TIDB SELF-MANAGED diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index bbeaacfed8e8a..c46254f6c1987 100644 --- a/TOC-tidb-cloud-essential.md +++ b/TOC-tidb-cloud-essential.md @@ -553,6 +553,7 @@ - [URI Formats of External Storage Services](/external-storage-uri.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) + - [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md) - Support Plan - [Connected Care Overview](/tidb-cloud/connected-care-overview.md) - [Connected Care Details](/tidb-cloud/connected-care-detail.md) diff --git a/TOC-tidb-cloud-starter.md b/TOC-tidb-cloud-starter.md index c85ae4645e2a0..24ecd39bd4d3c 100644 --- a/TOC-tidb-cloud-starter.md +++ b/TOC-tidb-cloud-starter.md @@ -544,6 +544,7 @@ - [URI Formats of External Storage Services](/external-storage-uri.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) + - [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md) - Support Plan - [Connected Care Overview](/tidb-cloud/connected-care-overview.md) - [Connected Care Details](/tidb-cloud/connected-care-detail.md) From 24d13e40fd455ed583d093899fc6c96bbb7dd8da Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 14 Apr 2026 16:44:28 +0800 Subject: [PATCH 19/25] fix broken links --- TOC-tidb-cloud-essential.md | 2 +- TOC-tidb-cloud-starter.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index c46254f6c1987..b6bbfae192951 100644 --- a/TOC-tidb-cloud-essential.md +++ b/TOC-tidb-cloud-essential.md @@ -553,7 +553,7 @@ - [URI Formats of External Storage Services](/external-storage-uri.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) - - [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md) + - [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) - Support Plan - [Connected Care Overview](/tidb-cloud/connected-care-overview.md) - [Connected Care Details](/tidb-cloud/connected-care-detail.md) diff --git a/TOC-tidb-cloud-starter.md b/TOC-tidb-cloud-starter.md index 24ecd39bd4d3c..86f36a97e09b4 100644 --- a/TOC-tidb-cloud-starter.md +++ b/TOC-tidb-cloud-starter.md @@ -544,7 +544,7 @@ - [URI Formats of External Storage Services](/external-storage-uri.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) - - [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-openapi-migration-guide.md) + - [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) - Support Plan - [Connected Care Overview](/tidb-cloud/connected-care-overview.md) - [Connected Care Details](/tidb-cloud/connected-care-detail.md) From 85f75fa7d2b74728d767682c8160965a09eab632 Mon Sep 17 00:00:00 2001 From: awxxxxxx Date: Tue, 14 Apr 2026 17:06:43 +0800 Subject: [PATCH 20/25] Update title and headings in API Migration Guide to reflect project terminology --- tidb-cloud/tidbx-starter-essential-api-migration-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tidb-cloud/tidbx-starter-essential-api-migration-guide.md b/tidb-cloud/tidbx-starter-essential-api-migration-guide.md index c88d4201333a1..d00be15e62bf9 100644 --- a/tidb-cloud/tidbx-starter-essential-api-migration-guide.md +++ b/tidb-cloud/tidbx-starter-essential-api-migration-guide.md @@ -1,9 +1,9 @@ --- -title: TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential +title: Project API Migration Guide for {{{ .starter }}} and Essential summary: Learn the minimum changes needed to keep your existing v1beta API calls working after TiDB Cloud introduces separate project types for TiDB X instances. --- -# TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential +# Project API Migration Guide for {{{ .starter }}} and Essential Starting from April 15, 2026, TiDB Cloud introduces separate project types for different resource types. For {{{ .starter }}} and Essential instances, you can now manage them either in TiDB X projects or at the organization level. For more information, see [Project Migration FAQ for TiDB X Instances](/tidb-cloud/tidbx-instance-move-faq.md). From 73933d588aa6db4f0e3d4ec854fed2980d451299 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 14 Apr 2026 17:09:29 +0800 Subject: [PATCH 21/25] rename the API Migration Guide --- TOC-tidb-cloud-essential.md | 2 +- TOC-tidb-cloud-starter.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index b6bbfae192951..0f712300cde33 100644 --- a/TOC-tidb-cloud-essential.md +++ b/TOC-tidb-cloud-essential.md @@ -553,7 +553,7 @@ - [URI Formats of External Storage Services](/external-storage-uri.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) - - [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) + - [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) - Support Plan - [Connected Care Overview](/tidb-cloud/connected-care-overview.md) - [Connected Care Details](/tidb-cloud/connected-care-detail.md) diff --git a/TOC-tidb-cloud-starter.md b/TOC-tidb-cloud-starter.md index 86f36a97e09b4..d9f3749fb4730 100644 --- a/TOC-tidb-cloud-starter.md +++ b/TOC-tidb-cloud-starter.md @@ -544,7 +544,7 @@ - [URI Formats of External Storage Services](/external-storage-uri.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) - - [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) + - [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) - Support Plan - [Connected Care Overview](/tidb-cloud/connected-care-overview.md) - [Connected Care Details](/tidb-cloud/connected-care-detail.md) From ea41589560f0c0251d8664f3d909a138aba86072 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 14 Apr 2026 17:09:57 +0800 Subject: [PATCH 22/25] rename API Migration Guide --- tidb-cloud/tidbx-instance-move-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index f9657e6a62cfd..0e4a4ce023725 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -136,7 +136,7 @@ If your {{{ .starter }}} or Essential instances are moved to a new TiDB X projec Project-level RBAC permissions are copied to the new project, but you must still review access after migration to make sure users and workflows still work as expected. -If you use the TiDB Cloud API to manage your instances, see [TiDB Cloud API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) to update your API calls. +If you use the TiDB Cloud API to manage your instances, see [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) to update your API calls. ## Where can I get help? From 401889e67c9a97e12597be57cd7701077e876722 Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 14 Apr 2026 17:18:25 +0800 Subject: [PATCH 23/25] rename the tidbx-starter-essential-api-migration-guide.md to tidbx-starter-essential-project-api-migration-guide.md --- TOC-tidb-cloud-essential.md | 2 +- TOC-tidb-cloud-starter.md | 2 +- tidb-cloud/tidbx-instance-move-faq.md | 2 +- ...d => tidbx-starter-essential-project-api-migration-guide.md} | 0 4 files changed, 3 insertions(+), 3 deletions(-) rename tidb-cloud/{tidbx-starter-essential-api-migration-guide.md => tidbx-starter-essential-project-api-migration-guide.md} (100%) diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index 0f712300cde33..33d663eddd180 100644 --- a/TOC-tidb-cloud-essential.md +++ b/TOC-tidb-cloud-essential.md @@ -553,7 +553,7 @@ - [URI Formats of External Storage Services](/external-storage-uri.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) - - [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) + - [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md) - Support Plan - [Connected Care Overview](/tidb-cloud/connected-care-overview.md) - [Connected Care Details](/tidb-cloud/connected-care-detail.md) diff --git a/TOC-tidb-cloud-starter.md b/TOC-tidb-cloud-starter.md index d9f3749fb4730..997ca6188baeb 100644 --- a/TOC-tidb-cloud-starter.md +++ b/TOC-tidb-cloud-starter.md @@ -544,7 +544,7 @@ - [URI Formats of External Storage Services](/external-storage-uri.md) - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md) - [Notifications](/tidb-cloud/notifications.md) - - [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) + - [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md) - Support Plan - [Connected Care Overview](/tidb-cloud/connected-care-overview.md) - [Connected Care Details](/tidb-cloud/connected-care-detail.md) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index 0e4a4ce023725..d600f96e4c234 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -136,7 +136,7 @@ If your {{{ .starter }}} or Essential instances are moved to a new TiDB X projec Project-level RBAC permissions are copied to the new project, but you must still review access after migration to make sure users and workflows still work as expected. -If you use the TiDB Cloud API to manage your instances, see [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-api-migration-guide.md) to update your API calls. +If you use the TiDB Cloud API to manage your instances, see [Project API Migration Guide for {{{ .starter }}} and Essential](/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md) to update your API calls. ## Where can I get help? diff --git a/tidb-cloud/tidbx-starter-essential-api-migration-guide.md b/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md similarity index 100% rename from tidb-cloud/tidbx-starter-essential-api-migration-guide.md rename to tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md From ea165dca5632fe34fa103779ebe333790436acec Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 14 Apr 2026 17:20:27 +0800 Subject: [PATCH 24/25] Update tidb-cloud/tidbx-instance-move-faq.md --- tidb-cloud/tidbx-instance-move-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/tidbx-instance-move-faq.md b/tidb-cloud/tidbx-instance-move-faq.md index d600f96e4c234..413db21552ead 100644 --- a/tidb-cloud/tidbx-instance-move-faq.md +++ b/tidb-cloud/tidbx-instance-move-faq.md @@ -5,7 +5,7 @@ summary: Learn why TiDB Cloud prompts you to move or convert your {{{ .starter } # Project Migration FAQ for TiDB X Instances -TiDB X instances are service-oriented TiDB Cloud offerings built on the [TiDB X architecture](/tidb-cloud/tidb-x-architecture.md), including {{{ .starter }}}, {{{ .essential }}}, and {{{ .premium }}} instances. +TiDB X instances are service-oriented TiDB Cloud offerings built on the [TiDB X architecture](/tidb-cloud/tidb-x-architecture.md), including {{{ .starter }}} and {{{ .essential }}} instances. This FAQ explains why the [TiDB Cloud console](https://tidbcloud.com/) prompts you to move your {{{ .starter }}} and Essential instances to TiDB X projects, what changes occur during the migration process, and what follow-up actions you need to take. From 466a7495acaf4f82193ab86710c7cb20b5ae275f Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 14 Apr 2026 17:23:10 +0800 Subject: [PATCH 25/25] Update tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md --- .../tidbx-starter-essential-project-api-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md b/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md index d00be15e62bf9..149ea61c4ce8e 100644 --- a/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md +++ b/tidb-cloud/tidbx-starter-essential-project-api-migration-guide.md @@ -11,7 +11,7 @@ This guide is intended for API callers who want to keep most existing `v1beta` c Because of these project model changes, note the following API changes: -- `project_id` values for {{{ .starter }}} and Essential instances **can change** because these instances can be moved between projects. Do not hardcode `project_id` values. +- `project_id` values for {{{ .starter }}} and Essential instances **can change** because these instances can be moved between projects in the TiDB Cloud console. Do not hardcode `project_id` values. - Project responses now include a `type` field. For possible values, see [Project type values](#project-type-values). ## Project API changes