PlanetScale Migration: Import Existing MySQL Database (2026)

PlanetScale’s import tool can be a bit of a black box, but it’s actually a pretty straightforward process once you understand the underlying mechanics.

Let’s see it in action. Imagine you have a local MySQL database with a users table:

-- Local MySQL
CREATE TABLE users (
    id INT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(100) NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO users (username, email) VALUES
('alice', 'alice@example.com'),
('bob', 'bob@example.com');

You want to bring this into a new PlanetScale database.

First, you’ll need to create a new PlanetScale database. Let’s call it my-awesome-app. Then, navigate to your database in the PlanetScale UI. You’ll see an "Import" button. Click it.

The import tool will prompt you for a few things:

1. Database Type: Select "MySQL".
2. Connection Method: This is where you have options. For a local database, you’ll typically choose "Direct Connection".
3. Host: This will be 127.0.0.1 or localhost.
4. Port: Usually 3306 for MySQL.
5. User: A MySQL user with SELECT and SHOW VIEW privileges on the tables you want to import.
6. Password: The password for that MySQL user.
7. Database Name: The name of your local database (e.g., my_local_db).

Once you fill these in, PlanetScale will attempt to connect. If successful, it will show you a list of tables and views in your local database. You can select which ones to import. For our example, we’d select the users table.

The magic happens when you click "Import". PlanetScale doesn’t directly pull data row-by-row in real-time. Instead, it triggers a mysqldump operation on your source database. It then takes that mysqldump file and streams it into your PlanetScale database. This is why you need SHOW VIEW privileges – mysqldump uses that to understand your schema.

The key to PlanetScale’s import is that it’s designed to be transactional and schema-aware. It’s not just dumping data; it’s reconstructing your tables, indexes, and constraints in PlanetScale. This ensures data integrity and that your new database is a faithful replica of your old one.

The primary problem this solves is the pain of manual schema creation and data transfer. Instead of writing CREATE TABLE statements for every table and then figuring out how to pipe INSERT statements, you get a single, unified import process. It handles data types, indexes, and even foreign key constraints (though complex ones might require manual review).

PlanetScale’s import is actually a two-phase process under the hood. First, it performs a schema-only dump and applies it to your PlanetScale branch. This creates all your tables, indexes, and constraints. Then, it performs a data-only dump of your source database and streams that data into the newly created tables in PlanetScale. This two-phase approach allows for better error handling and ensures that the schema is perfectly replicated before data is loaded.

If you’re migrating a very large database, you might find that the direct connection times out or becomes unstable. In such cases, PlanetScale offers an alternative: uploading a mysqldump file directly. You’d run mysqldump yourself locally, then upload the resulting .sql file through the PlanetScale UI. This bypasses the direct network connection for the data transfer itself, making it more robust for massive datasets.

The next step in a migration is often setting up your application to connect to the new PlanetScale database.