PlanetScale’s branching model fundamentally changes how you think about database schema changes, allowing you to treat them like application code changes.
Let’s see it in action. Imagine you have a users table.
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL
);
Now, you need to add a bio column. Instead of a stressful ALTER TABLE on your production schema, you create a new branch in PlanetScale.
planetscale branch create my-app@main my-bio-branch --git-branch main
This command creates a new database branch named my-bio-branch that’s a direct copy of your main production branch. It also links this database branch to your application’s main Git branch.
On my-bio-branch, you run your migration:
ALTER TABLE users ADD COLUMN bio TEXT;
This change is isolated to my-bio-branch. Your main database branch remains untouched.
When you’re ready to merge this schema change, you open a pull request in PlanetScale. This PR will show you the exact SQL diff between my-bio-branch and main.
--- main
+++ my-bio-branch
@@ -1,6 +1,7 @@
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(255) NOT NULL,
- email VARCHAR(255) UNIQUE NOT NULL
+ email VARCHAR(255) UNIQUE NOT NULL,
+ bio TEXT
);
Once approved, merging the PlanetScale branch triggers a schema migration on your production main branch. Crucially, PlanetScale performs this migration safely, often without downtime, by leveraging its underlying technology to create new tables, copy data, and then swap them. This is the magic that prevents the typical "production outage during migration" horror story.
The real power comes from integrating this with your application’s CI/CD. When you merge a feature branch in your Git repository (e.g., feat/add-user-bio) into main, you can have a CI job that automatically creates a corresponding PlanetScale branch. This branch would be based on your production main PlanetScale branch. You’d then run your application tests against this new, isolated database branch. If tests pass, you can then open a PlanetScale branch merge request.
This workflow means that every schema change is reviewed, tested against a production-like environment, and deployed with minimal risk. You’re not just deploying code; you’re deploying database schema changes as first-class citizens. The system handles the complexities of safe schema evolution, allowing you to focus on application logic.
What most people don’t realize is that PlanetScale’s branching isn’t just about creating isolated copies of your schema; it’s about creating deployable units of schema change. When you merge a branch in PlanetScale, it doesn’t just apply the SQL. It orchestrates a series of internal operations, often involving shadow tables and atomic switches, to ensure that the transition from the old schema to the new one is as seamless as possible, even for complex, data-modifying operations like adding a nullable column or changing a data type.
The next step is exploring how to manage multiple concurrent schema changes and their dependencies across different application branches.