Deploy Requests are how PlanetScale lets you change your database schema without taking your application offline.
Here’s a PlanetScale schema change in action. Imagine we have a simple users table:
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100) NOT NULL,
email VARCHAR(100) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
Now, let’s say we want to add a bio column to store user biographies. We’ll also make it nullable since not everyone will have one immediately.
First, we navigate to our PlanetScale database and click "New Schema Migration." We’re presented with a schema editor. We add the new column definition:
ALTER TABLE users
ADD COLUMN bio TEXT NULL;
When we click "Create Migration," PlanetScale doesn’t immediately apply this to our production branch. Instead, it creates a new branch off our production branch. This new branch contains only the proposed schema change.
Our production branch remains untouched, serving live traffic. The new branch is a safe, isolated environment where we can test and review the change. PlanetScale automatically provisions a new, temporary database schema based on this new branch. This temporary schema is a complete copy of our production schema, but with the bio column added.
This temporary schema is crucial. It means we can run queries against it, including potentially complex ones, without affecting our live database. We can even point a staging or testing environment to this temporary schema to see how our application behaves with the new column.
Once we’re happy, we go back to PlanetScale and click "Deploy" on our migration. PlanetScale now initiates a controlled rollout. It doesn’t just flip a switch. Instead, it performs a "dual-write" operation behind the scenes. For every write to the users table, PlanetScale now writes to both the old schema (without bio) and the new schema (with bio).
This dual-write phase is critical for zero-downtime. Your application can continue reading from the old schema, and new writes are being safely duplicated to the new schema. PlanetScale monitors this process for errors. If anything goes wrong, it can immediately roll back.
After a successful dual-write period, PlanetScale performs the final cutover. It switches all reads to the new schema. The old schema, now redundant, is dropped. The entire process is managed by PlanetScale, ensuring that at no point is your application unable to write to or read from the database.
The one thing most people don’t realize is that during the dual-write phase, PlanetScale is actually running two separate schema definitions simultaneously. Your application interacts with a single "logical" database, but under the hood, PlanetScale is orchestrating writes to both the old and new table structures. This allows for a seamless transition where the application is unaware of the underlying schema modification until the final cutover, which is also managed to be invisible.
The next step is understanding how to handle data migrations, like populating the new bio column for existing users.