Skip to content

tidbx-instance-move-faq.md

Latest commit

 

History

History
143 lines (93 loc) · 14.9 KB

tidbx-instance-move-faq.md

File metadata and controls

143 lines (93 loc) · 14.9 KB
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.

Project Migration FAQ for TiDB X Instances

TiDB X instances are service-oriented TiDB Cloud offerings built on the TiDB X architecture, including {{{ .starter }}} and {{{ .essential }}} instances.

This FAQ explains why the TiDB Cloud console 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 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:

  • TiDB dedicated projects were originally designed for {{{ .dedicated }}} clusters.
  • TiDB X instances and {{{ .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 {{{ .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.

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?

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.
    • {{{ .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 {{{ .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 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 {{{ .starter }}} and Essential instances?

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. 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?

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

What happens if my project contains only {{{ .starter }}} and Essential instances?

Projects that contain only {{{ .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 {{{ .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.

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:

  • 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 {{{ .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.