PlanetScale Large Table Migration: Zero-Downtime Changes (2026)

PlanetScale’s large table migration feature lets you alter schema without locking your tables, but the real magic is how it orchestrates these changes asynchronously to avoid blocking application writes.

Let’s see it in action. Imagine you have a users table with millions of rows and you need to add a new email_verified_at timestamp column.

ALTER TABLE users ADD COLUMN email_verified_at TIMESTAMP NULL DEFAULT NULL;

Normally, this ALTER TABLE command would acquire an exclusive lock on the users table. For the duration of the lock, no writes (INSERT, UPDATE, DELETE) would be permitted. On a large table, this could take minutes or even hours, leading to significant downtime.

PlanetScale’s approach is different. When you run that ALTER TABLE command on a PlanetScale database, it doesn’t immediately modify the live table. Instead, it kicks off a background process.

Here’s the internal process:

1. Schema Change Registration: PlanetScale registers the intended schema change.
2. New Table Creation: A new, temporary table is created with the desired schema (including the new email_verified_at column).
3. Data Copying (Background): Data from the original users table is copied, row by row, to this new table in the background. This is the most time-consuming part for large tables.
4. Write Forwarding: While data is being copied, PlanetScale intercepts all writes to the original users table and forwards them to both the original table and the new table. This ensures data consistency.
5. Cutover: Once the data copy is complete and the write forwarding has synchronized the tables, PlanetScale performs a near-instantaneous "cutover." It swaps the users table name with the new table’s name. This cutover is a metadata operation and takes milliseconds.
6. Original Table Dropped: The old table is then dropped asynchronously.

The key levers you control are standard SQL ALTER TABLE statements. PlanetScale handles the complex orchestration behind the scenes. You don’t need to choose a specific migration strategy or manage intermediate states. The system is designed to abstract away the locking and downtime concerns.

What most people don’t realize is that during the background data copy and write forwarding, the application is interacting with the original table. The new schema is only truly active for reads and writes after the cutover. This means any application logic that relies on the presence of the new column will fail until the cutover is complete, even though the ALTER TABLE command itself appears to have finished immediately. You need to ensure your application can gracefully handle the column being NULL or absent until the migration is fully propagated.

The next step is often to add indexes to the newly created or modified tables, which also leverages similar background processing.