PlanetScale Zero-Downtime Rename: Safely Rename Tables (2026)

Renaming a table in PlanetScale without downtime isn’t about a magic "rename" button; it’s a carefully orchestrated dance between your application and the database.

Let’s see this in action. Imagine you have a users table and want to rename it to customers.

-- Original table
CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL
);

-- You want to rename this to 'customers'

In a traditional database, you’d run ALTER TABLE users RENAME TO customers; and hope your app handles the brief moment of unavailability. PlanetScale’s approach is different. It leverages schema branches and deploy requests to make this a safe, multi-step process.

Here’s how the system works internally to achieve this:

1. Schema Branching: Every PlanetScale database has a main production schema. You create a branch from this schema. This branch is an isolated copy where you can make changes without affecting production. Think of it as a staging environment for your schema.

2. Schema Changes on the Branch: On your new branch, you perform the rename operation. PlanetScale doesn’t immediately lock the table. Instead, it records this as a pending schema change.

3. Deploy Request: Once the schema change is ready on the branch, you create a deploy request. This request proposes merging the changes from your branch into the production schema.

4. Controlled Rollout: This is where the magic happens. PlanetScale doesn’t just flip a switch. It uses a sophisticated strategy. When you approve the deploy request, PlanetScale performs the rename in stages:

   • It creates the new table (customers) with the desired structure.
   • It then synchronizes data from the old table (users) to the new one.
   • Crucially, it uses triggers or internal mechanisms to ensure that any writes happening to the old table are mirrored to the new table during this synchronization phase. This is the "dual-write" phase.
   • Your application continues to write to the users table. PlanetScale ensures these writes are also applied to customers.
   • Once the data is fully synchronized and the dual-write mechanism is active, PlanetScale switches the application’s view. Reads and writes are now directed to the customers table.
   • Finally, the old users table is dropped.

The primary problem this solves is eliminating the downtime associated with schema migrations. Traditional ALTER TABLE RENAME can lock tables for extended periods, especially on large tables, making them unsuitable for production environments that demand high availability. PlanetScale’s branching and controlled deployment process allows you to make schema changes that are effectively applied with zero perceived downtime by your users.

The exact levers you control are primarily within the PlanetScale UI or CLI when managing branches and deploy requests. You decide when to create a branch, when to apply the schema change (the RENAME TABLE command) to that branch, and most importantly, when to deploy that request to production. The system handles the complex, behind-the-scenes orchestration of data synchronization and cutover.

Here’s a typical workflow in the PlanetScale UI:

1. Navigate to your database.
2. Click "New branch."
3. Name your branch (e.g., rename-users-to-customers).
4. Select your production branch as the base.
5. Once the branch is created, connect to it (e.g., using pscale connect <database-name> <branch-name>).
6. Execute your schema change: ALTER TABLE users RENAME TO customers;
7. Go back to the PlanetScale UI, and you’ll see your branch has a pending schema change.
8. Create a deploy request from this branch to your production branch.
9. Review the deploy request and click "Deploy."

The system handles the rest, including data replication and the final switchover, ensuring your application remains available throughout the process.

What most people don’t realize is that PlanetScale doesn’t just magically make the ALTER TABLE RENAME command atomic and zero-downtime. It actually creates a new table, copies data over, and uses a sophisticated internal mechanism to ensure writes to the old table are immediately propagated to the new one before it switches over. This dual-write capability, combined with the ability to drop the old table after a safe period, is what enables the zero-downtime guarantee.

The next challenge you’ll likely encounter is managing foreign key constraints that reference the table you just renamed.