Migrate from PlanetScale to TiDB Serverless in Minutes: A Developer’s Guide

If you’re here, you’re probably curious about moving a database from PlanetScale over to TiDB Serverless—or maybe you’re just exploring new database options. In any case, I’ll walk you through the why and how of this migration. We’ll talk about differences between PlanetScale and TiDB, then dive straight into the steps to get your data moved over with minimal fuss. If you’ve got questions or get stuck, drop a comment or join our community. Let’s get into it.

Why Migrate from PlanetScale to TiDB Serverless?

So, why even consider moving away from PlanetScale? Here are a few reasons I’ve heard from folks:

1. Cost – PlanetScale’s new billing tiers might not fit everyone’s budget. For example, if you’re using a PS-40 cluster for your main production branch ($99 per month) and two PS-20 clusters for additional branches ($59 each), your total cost would be $217 per month. In contrast, TiDB Serverless starts at $0 per month, offering 25 GB of row storage, 25 GB of column storage, and 250 million Request Units (RUs) free per month for each organization. Beyond that, it’s $0.20 per GB of storage and $0.10 per million RUs. This pay-as-you-go model allows you to scale costs directly with your usage, often resulting in significant savings.

2. MySQL Compatibility – TiDB Serverless is fully MySQL-compatible, ensuring your existing SQL queries and tools will work with minimal changes. A notable example is Foreign Keys, which are not natively supported in PlanetScale. While PlanetScale does offer a workaround for foreign key constraints, TiDB Serverless provides full native support, allowing you to enforce referential integrity seamlessly between tables.

3. Distributed & Scalable – TiDB Serverless handles read and write scaling behind the scenes—no single primary node to bottleneck. This can make life a lot easier when traffic surges.

4. Online DDL – If you hate scheduling maintenance windows for schema changes, TiDB lets you do that online.

5. Rich Dev Features – Vector search, branching (like Git for databases), and more. Perfect if you’re building AI or advanced analytics.

But enough about reasons—let’s actually do it. I’ll show you how to migrate step-by-step, using a small example database.

Migration Overview

Migrating from PlanetScale to TiDB Serverless basically boils down to two big steps:

1. Dump your PlanetScale data to your local machine.
2. Import that dump into TiDB Serverless. We’ll also do a little optional verification, like checking table counts, just to make sure everything came over. Let’s start with dumping your PlanetScale data.

Dumping Data from PlanetScale

1. Retrieve Connection Info
   • In your PlanetScale dashboard, at the top right corner click “Connect”.

• If needed, generate a new password.

• Copy the MySQL CLI connection string.

For example: mysql -h aws.connect.psdb.cloud -D mydb -u - --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/cert.pem

1. Verify Existing Data
   • Paste that string into your terminal.
   • Run SHOW TABLES; in your PlanetScale shell.

• Optionally, do a few SELECT COUNT(*) checks to confirm row counts in each table. This is good to compare later.

1. Next we need to install the pscale CLI
   • On macOS, you might do brew install planetscale/tap/pscale.

• For Windows or Linux, check PlanetScale’s docs for installation steps.

1. Log in via pscale
   • Run pscale auth login (or pscale login).

1. Dump Your Database
   • Use the command pscale database dump your-db-name --org your-org --branch main-branch (adjust org and branch names accordingly).

• This creates SQL files locally. You’ll see something like *-schema.sql and *.numbers.sql for data inserts. That’s all for the dump. Once you’ve got those SQL files on your machine, we’re ready to move on.

Creating a TiDB Serverless Cluster

1. Navigate to TiDB Serverless Console
   • Head to tidbcloud.com and sign in (or sign up if it’s your first time).

• Click “Create Cluster” and pick TiDB Serverless.

1. Choose a Region & Name
   • Select a region close to your users or your own location.
   • Name your cluster something memorable, like my-planet2tidb-cluster.
   • Wait a few seconds for the cluster to be created.
2. Generate Connection Credentials
   • Click “Connect,” then “Generate Password.”

• Switch to “Connect With MySQL CLI” to get a MySQL connection string.

Importing Data into TiDB Serverless

Now it’s time to feed our PlanetScale dump into TiDB.
CD into the correct folder

1. Schema Creation
   • Your dump folder has *-schema.sql files.
   • You can loop over them in your terminal with a shell command. For example: for file in ./*-schema.sql; do mysql --host xxx.tidbcloud.com --port 4000 \ --user your-user --password='your-pass' < "$file" done
   • Replace xxx.tidbcloud.com, port, and credentials with your actual TiDB Serverless connection string.

During this process, you might encounter an error related to the unsupported utf8mb4_0900_ai_ci collation. See below:

Here’s why it happens and how to fix it before proceeding:

Why does this happen?

• PlanetScale uses MySQL 8.0, which supports the utf8mb4_0900_ai_ci collation.
• TiDB (as of now) does not support this collation. Instead, it supports other utf8mb4 collations such as utf8mb4_general_ci. ## The Solution
• You need to modify the *-schema.sql files to replace the unsupported utf8mb4_0900_ai_ci collation with a supported one, such as utf8mb4_general_ci. Step 1: Modify the Schema Files Run the following for loop in your terminal to automatically replace the collation in all *-schema.sql files:

This loops through all *-schema.sql files and replaces every occurrence of utf8mb4_0900_ai_ci with utf8mb4_general_ci.

If you encountered the error and applied the fix by modifying the files, you need to re-run the command to insert the data into TiDB. Use the following:

1. If the sed command you’re using is encountering compatibility issues with your system (likely macOS or a non-GNU version of sed). Here’s what you need to do next:

1. Fix the sed issue

   1. The sed error is due to using an incompatible version. On macOS, sed -i requires an argument for the backup extension. Here’s the corrected command:
      1. for file in ./*-schema.sql; do sed -i '' 's/utf8mb4_0900_ai_ci/utf8mb4_general_ci/g' "$file" Done
   2. If this still fails, install GNU sed using homebrew
      1. brew install gnu-sed
   3. Then replace sed with gsed in your script:
      1. for file in ./*-schema.sql; do gsed -i 's/utf8mb4_0900_ai_ci/utf8mb4_general_ci/g' "$file" done
   4. Insert the data and verify the schema import

2. Similar process for the data files named something like *.numbers.sql:

   1. for file in ./*.00001.sql; do mysql --comments -u '32Z4oGrkgk78qLp.root' -h gateway01.us-west-2.prod.aws.tidbcloud.com -P 4000 -D 'test' --ssl-mode=VERIFY_IDENTITY --ssl-ca=/etc/ssl/cert.pem -p'vVsi9OSNzFwWRfdy' < "$file" done

1. Verify Next we will want to verify the data and you can do that by running this string, but this time without the loop:

  - Connect to your TiDB cluster directly:
mysql --host xxx.tidbcloud.com --port 4000 \
--user your-user --password='your-pass'

• Run SHOW TABLES; and check row counts again to ensure all data matches what you saw on PlanetScale.

Wrap-up and Additional Tips

That’s literally it. Your PlanetScale data is now sitting happily in TiDB Serverless. A couple of pro tips before we go:

• Enjoy the cost savings: TiDB Serverless can scale down to zero, meaning if your traffic dies off, you’re not paying for idle capacity. This is a big deal for dev/test environments or smaller projects.
• Try out advanced TiDB features like vector search or online DDL. If you’re building AI-driven apps, vector columns let you store embeddings right next to your relational data. And if you like living on the edge, online schema changes are a life-saver if you need to update your tables mid-traffic.

Conclusion

And that’s a wrap. We successfully migrated data from PlanetScale to TiDB Serverless, step by step, without too much hassle. Whether you’re looking for free usage tiers, more flexible scalability, or advanced features like AI-ready queries, TiDB Serverless could be an excellent fit. If you run into any issues or have follow-up questions, drop them in the comments below or hit up our community forum. Thanks for watching, and happy building!