PlanetScale’s data branching lets you experiment with schema changes or data migrations on a copy of your production database without impacting live traffic.
Let’s see it in action. Imagine you have a production PlanetScale database named my-app-prod. You want to add a new users table. Instead of doing this directly on my-app-prod, you’ll create a data branch.
First, navigate to your my-app-prod database in the PlanetScale UI. You’ll see a "Branch" button. Click it.
You’ll be prompted to name your new branch. Let’s call it feature-add-users.
PlanetScale then creates a read-only snapshot of your my-app-prod database at that exact moment. This is your feature-add-users branch. It’s a full, independent copy of the data, but it doesn’t consume additional storage or incur performance overhead until you make changes.
Now, you can connect to feature-add-users just like you would any other database.
pscale connect my-app-prod --branch feature-add-users
This command will give you a connection string or a direct psql prompt. You can now run CREATE TABLE users (...) on this branch.
CREATE TABLE users (
id SERIAL PRIMARY KEY,
username VARCHAR(50) UNIQUE NOT NULL,
email VARCHAR(100) UNIQUE NOT NULL,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
You can also insert test data, run queries, and perform any data manipulation you need. Because it’s a read-only snapshot initially, nothing you do here will affect my-app-prod.
Once you’re satisfied with your schema changes and have tested them thoroughly, you can create a schema migration. In the PlanetScale UI, navigate to your feature-add-users branch. You’ll see a "Deploy to…" option. Select my-app-prod.
PlanetScale will analyze the schema differences between feature-add-users and my-app-prod. It will generate a SQL migration plan. You can review this plan to ensure it’s exactly what you expect.
When you’re ready, you can deploy this migration. PlanetScale will then apply the CREATE TABLE users... statement to your my-app-prod database. This deployment happens atomically, meaning the table is either created fully or not at all, preventing partial states.
The core problem data branching solves is the risk associated with modifying production databases. Traditionally, applying schema changes meant downtime, potential data corruption, or complex rollback procedures. Data branching decouples schema development from production deployment. It provides an isolated environment that mirrors production data without the risk. You get the confidence of testing against real data without the fear of breaking your live application.
The surprising part is how PlanetScale manages this without actually duplicating all the data upfront. When you create a branch, it’s not a full copy in the traditional sense. It’s a pointer to a specific state of the production database’s underlying data, leveraging a technology similar to copy-on-write. When you modify the branch (e.g., CREATE TABLE, INSERT), only the new data or changes are stored separately. This makes branch creation nearly instantaneous and incredibly efficient, both in terms of time and resources. Your branches are essentially lightweight, and only grow in storage footprint as you diverge from the parent.
Once you’ve deployed your schema change from a branch, that branch typically becomes a historical artifact. You’ll often create a new branch for your next feature or fix. The system is designed around this workflow: branch, develop, test, deploy, repeat.
The next concept you’ll likely encounter is managing multiple branches and understanding their lineage, especially when dealing with complex feature development or parallel schema evolution.