Renaming a column in PlanetScale doesn’t actually touch your production data until you explicitly tell it to, which is wild.
Let’s see this in action. Imagine we have a users table:
CREATE TABLE users (
id INT PRIMARY KEY AUTO_INCREMENT,
email VARCHAR(255) NOT NULL UNIQUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
And we want to rename email to user_email. In PlanetScale, you’d open a schema editor or run a gh-schema command:
gh-schema schema diff --alter "ALTER TABLE users RENAME COLUMN email TO user_email"
PlanetScale presents you with a schema diff. You review it. It looks like this:
users
- email VARCHAR(255) NOT NULL UNIQUE
+ user_email VARCHAR(255) NOT NULL UNIQUE
You then create a new branch from this diff. PlanetScale creates a new branch, and applies this schema change to the schema definition of that branch. Your production database, however, is completely unaffected. It still has the email column.
Now, you can deploy this branch. When you deploy a branch in PlanetScale, it initiates a "vReplication" process. This is the magic. It doesn’t directly alter your production table. Instead, it creates a new, shadow table alongside your existing one, with the new schema (the user_email column).
Your application, meanwhile, is still pointing to the original users table. PlanetScale’s vReplication system then streams all changes (INSERTs, UPDATEs, DELETEs) from your original users table to this new shadow table, ensuring they stay in sync.
At this point, your application is still reading and writing to the email column on the original table. The shadow table has user_email, and all changes are being replicated to it.
The crucial step is the "Switchover." When you’re ready, you tell PlanetScale to switch over. PlanetScale performs a brief, atomic cutover. It briefly pauses writes to the original table, ensures the shadow table is fully synchronized, then atomically swaps the "pointer" so your application now interacts with the new table (which has user_email). The original table becomes the shadow.
This whole process happens without any downtime because your application never experiences a period where the database is unavailable or the schema is in an inconsistent state. It’s always interacting with a valid, live table.
The key mental model is that PlanetScale doesn’t alter your production table in place for schema changes like renames or adding columns. It orchestrates the creation of a new table with the desired schema, synchronizes data and writes, and then performs an atomic switch. You’re always working with a fully functional, albeit potentially older version of the schema, or a brand-new, fully synchronized one.
What most people don’t realize is that the "switchover" isn’t just a simple ALTER TABLE. It’s a carefully orchestrated ballet of replication and atomic pointer swaps managed by PlanetScale’s underlying vReplication engine. The old table isn’t dropped immediately; it becomes the shadow, ready to be reverted to if needed, and the data is maintained in sync until you’re confident.
After the switchover, you’ll want to understand how to manage the old, now-shadow table.