📣

TiDB Cloud Essential is now in public preview. Try it out →

Project Migration FAQ for TiDB X Instances

TiDB X instances are service-oriented TiDB Cloud offerings built on the TiDB X architecture, including TiDB Cloud Starter and TiDB Cloud Essential instances.

This FAQ explains why the TiDB Cloud console prompts you to move your TiDB Cloud 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 me to move my TiDB Cloud 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 TiDB Cloud Dedicated clusters and TiDB X instances. However, mixing different resource types in one project increased management complexity because:

TiDB dedicated projects were originally designed for TiDB Cloud Dedicated clusters.
TiDB X instances and TiDB Cloud Dedicated clusters have different behaviors and management models.

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 dedicated project: for TiDB Cloud 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 TiDB Cloud 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 TiDB Cloud 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?

TiDB Cloud provides three project types for different resource types and use cases.

TiDB dedicated project: this project type is used only for TiDB Cloud Dedicated clusters.
- It helps you manage settings for TiDB Cloud Dedicated clusters separately by project, such as RBAC, networks, maintenance, alert subscriptions, and encryption access.
- Each TiDB Cloud Dedicated cluster must belong to a dedicated project.
- TiDB Cloud 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 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	TiDB Cloud Dedicated clusters only	TiDB X instances only	TiDB X instances only
Project is optional	❌ (Each TiDB Cloud 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 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 move my TiDB Cloud Starter and Essential instances?

It depends on how your current project is structured:

If your project contains only TiDB Cloud 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 TiDB Cloud Dedicated clusters and TiDB Cloud Starter or Essential instances, the TiDB Cloud console prompts you to move the TiDB Cloud Starter and Essential instances to a new TiDB X project by clicking Move & Unlock in the top banner.

Who can perform the migration?

Only users with the Organization Owner role can start and complete the migration.

What happens if my project contains only TiDB Cloud Starter and Essential instances?

Projects that contain only TiDB Cloud Starter and Essential instances are converted to a TiDB X project automatically on April 15, 2026.

What changes after the migration:

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.

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 TiDB Cloud Dedicated clusters and TiDB Cloud 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 TiDB Cloud Dedicated clusters and TiDB Cloud Starter or Essential instances, TiDB Cloud prompts you in the top banner to move the TiDB Cloud Starter and Essential instances in the project to a new TiDB X project.

Note

TiDB Cloud Dedicated clusters remain in the original project after the migration. Therefore, the migration does not affect TiDB Cloud 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 TiDB Cloud 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 TiDB Cloud 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.
TiDB Cloud Dedicated clusters remain in their current projects and are not moved.

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 TiDB Cloud Dedicated clusters through dedicated projects.

What actions are required after migration?

If your TiDB Cloud 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 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 TiDB Cloud Starter and Essential 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 before you start the migration.