PlanetScale’s branching is fundamentally a way to give every developer a personal, isolated copy of your database schema for a given branch, without the usual overhead of provisioning and managing separate databases.
Let’s see it in action. Imagine you’re on the main branch of your PlanetScale database, which represents your production schema.
-- On PlanetScale database 'my-app', branch 'main'
CREATE TABLE users (
id INT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
Now, you want to add a new email column to the users table for a new feature. Instead of altering the main branch directly (which is risky!), you create a new branch from main.
pscale branch create my-app@main feature/add-email-column
This command doesn’t spin up a new PostgreSQL instance or provision a new MySQL server. It creates a logical separation within PlanetScale’s distributed system. Your feature/add-email-column branch is now an independent schema state that you can modify without affecting main.
-- On PlanetScale database 'my-app', branch 'feature/add-email-column'
ALTER TABLE users
ADD COLUMN email VARCHAR(255) UNIQUE;
You can then make commits to this branch, effectively saving schema changes.
pscale branch commit my-app@feature/add-email-column --message "Add email column to users table"
Once your feature is complete and tested, you can open a "deploy request" to merge your feature/add-email-email branch back into main. PlanetScale then shows you a diff of the schema changes, allows for reviews, and if approved, performs a safe, zero-downtime schema migration on your production database.
The core problem this solves is the friction and risk associated with database schema changes in team environments. Traditionally, developers share a single staging or development database, leading to "schema drift" where different features are tested against slightly different database structures. Alternatively, teams might provision ephemeral databases for each feature, incurring significant infrastructure costs and management complexity. PlanetScale’s branching abstracts away the underlying database infrastructure, presenting a Git-like workflow for your schema. Each branch is a pointer to a specific schema version, and changes are applied atomically.
Internally, PlanetScale’s branching leverages its distributed SQL architecture. When you create a branch, you’re not creating a new physical database. Instead, you’re creating a new logical schema state that shares underlying storage and infrastructure with the parent branch. Commits represent diffs against the parent schema. When you merge, PlanetScale orchestrates a controlled application of these schema diffs to the target branch’s underlying data. This is why branches are so cheap and fast to create – it’s a metadata operation, not an infrastructure provisioning one.
The exact levers you control are the branches themselves and the deploy requests. You can create branches from any existing branch, not just main. This allows for more complex workflows where you might branch off a release candidate branch to fix a bug, or branch off another feature branch to incorporate its changes. Deploy requests are the mechanism for integration, controlled by reviews and CI/CD pipelines.
What most people don’t realize is that the underlying storage for branches is shared. When you create a branch, it initially points to the same underlying data as its parent. Only when you start making schema changes and committing them does the storage diverge, and even then, PlanetScale employs clever techniques to deduplicate data where possible, minimizing storage costs and improving efficiency. This shared storage is key to the speed and low cost of branching.
The next logical step after mastering branching is understanding how to integrate this workflow with your CI/CD pipeline for automated testing and deployments.