Branching is a core PlanetScale feature that makes non-blocking schema changes possible. In PlanetScale, a database branch is a separate database that is deployed with a copy of the
main database's schema. All database schema changes must occur on a development database branch before being deployed to production.
To match a developer's workflow, PlanetScale uses a branching model similar to Git. Creating a database branch allows developers to create an exact copy of their production database schema. Developers can use that branch to test the implemented schema changes. Once developers have tested their changes, they can safely apply the schema changes to their production database.
Branching enables schema changes to happen online, asynchronously. (Online means it won't block production or inserts and selects on your database.) Database branching speeds up development by allowing developers to iterate quickly without worrying about impacting their production environment.
PlanetScale provides two types of branches, Production (
main) and Development branches. Production branches are intended for use in production, cannot be deleted, and can only be updated using deploy requests. Development branches are a separate database with a copy of the
main branch's schema. Developers can make schema changes in Development branches, test locally, and open a deploy request for deploying their changes to the production database.
main branch is your production database. To safely make a change to
main, simply create a new branch and name it by running the following command:
pscale branch create <database> <branch>
To see a list of all the branches for a given database, run the following command:
pscale branch list <database>
After making schema changes to a stable branch, the deployment phase begins. A deployment takes the changes made to a branch and applies them to the
Create a deploy request by running this command:
pscale deploy-request create <database> <branch>
To deploy the deploy request, run the following command:
pscale deploy-request deploy <database> <deploy-request-number>
If you no longer need to make schema changes or are done testing against your branch, you can safely delete it.
pscale branch delete <database> <branch>
Schema conflicts occur when your Deployment branch has conflicting changes with the Production branch. Perhaps a teammate has made different changes to the same column or the same table as you. Or perhaps someone deleted a table you were working on!
Solve schema conflicts by creating a new branch from
main and reapplying the schema changes.
Run the following command to view the schema differences between the local Development branch and the Production branch (
pscale branch diff <database> <branch>
Run the following command to show the schema of a branch:
pscale branch schema <database> <branch>