Create a development or staging environment for your database through branches
PlanetScale allows you to branch databases schemas the way you branch your code.
Development database branches are isolated copies of your database created with the current production schema. They can be used to develop features and test changes without impacting your production database. When you're ready, schema changes on a development branch can be safely applied to the production database using PlanetScale’s non-blocking schema change workflow. This workflow ensures that your changes are deployed without blocking the database, locking individual tables, or slowing down production during the migration.
PlanetScale Branching Flow Diagram
Development and production branches
PlanetScale provides two types of database branches, development branches and production branches.
Development branches provide isolated copies of your production database schema where you can make changes, experiment, or run CI.
Production branches are highly available databases intended for production traffic. They are protected from direct schema changes by default and include automated daily backups.
ERROR 1105 (HY000): direct DDL is disabledmessage if you attempt schema changes in a production branch. Create a development branch and start your changes there.
PlanetScale provides the ability to promote any development branch with a valid schema to production. Promoting a branch to production will require future schema changes to be made via a deploy request and will engage any custom backup schedules you have configured for production branches in addition to the automatic daily backups.
Promote the main database branch
Every PlanetScale database is created with a development branch named
This allows you to apply a schema directly to this branch, import data, and experiment with your database before promoting the branch to production.
Once you are satisfied with the changes you have made to your
main branch, you can promote the
main branch to production.
A branch can be promoted from the branch overview page in the PlanetScale app or you can use the command below to promote a branch using the PlanetScale CLI.
Copiedpscale branch promote <database> <branch>
Promote any development branch
Any PlanetScale development branch can be promoted to production. It's possible to run multiple production branches simultaneously, however it's important to note that PlanetScale does not provide data syncing between production branches.
You can promote any development branch from the given branch overview page, or from the command line with
Copiedpscale branch promote <database> <branch>
Create a development branch
You can create a development branch from any production branch. Create a branch from the production branch overview page
app.planetscale.com/<organization>/<database>/<branch> or use the command below.
Copiedpscale branch create <database> <branch>
Deploy a branch
Once you are satisfied with the schema changes you have made on a branch, you can deploy your changes to production.
Create a deploy request
The first step is to create a deploy request. If you are working in a team, the deploy request creates an opportunity for your teammates to review the changes you have made before they are deployed to production.
Create a deploy request from the branch overview page
app.planetscale.com/<organization>/<database>/<branch> or run the command below using the CLI.
Copiedpscale deploy-request create <database> <branch>
Review the schema diff
The deploy request includes a schema diff that allows you to review the schema changes introduced by the deploy request. View the schema diff in the Schema tab in the PlanetScale app.
You can also run the command below to see the schema diff in the CLI.
Copiedpscale deploy-request diff <database> <deploy-request-number>
Add changes to the deploy queue
Once a deploy request has been created (and approved, if required), you will need to add the changes to the deploy queue. Schema changes are deployed to a database in the order in which they are received. PlanetScale analyzes the schema changes in a deploy request when they are added to the deploy queue to ensure that the changes do not conflict with any of the queued schema changes.
To add a deploy request to the deploy queue click on the button “Add changes to the deploy queue” on the deploy request page.
Alternatively, you can run the following command.
Copiedpscale deploy-request deploy <database> <deploy-request-number>
PlanetScale provides insight on the deploy queue, listing all of the schema changes in the queue with their completion status.
Set a default branch
Each PlanetScale database with a production branch has a default branch that cannot be deleted.
The first database branch that gets promoted to production is automatically set as the default branch for your database.
However, this can be updated in the database Settings tab. Use the default branch dropdown menu to select the branch you would to set as default and click the Save database settings button to save your changes.
Delete a branch
You can delete your branch either from the branches overview page
app.planetscale.com/<organization>/<database>/branches or run the following command in the CLI.
Copiedpscale branch delete <database> <branch>
We recommend deleting your branch once you have used it to merge a schema change, or if you are no longer using the branch for testing. You can always create a new branch from your production database.
Resolve a schema conflict
Schema conflicts occur when your development branch has conflicting changes with the production branch.
To resolve a schema conflict, create a new branch, which will have the most up-to-date schema, and apply the necesary schema changes to the new branch before repeating the deploy process.
Automatically copy migration data
Many frameworks and migration tools keep track of data schema changes in a migration table. When turned on, PlanetScale will automatically copy migration table metadata from your
development branch to the
main branch as part of our deployment process.
To turn on for your database, go to the web app:
- Go into the Settings for your database
- Enable "Automatically copy migration data"
- Select one of the migration frameworks: Rails/Phoenix, Django, .NET, Prisma, Prisma, Sequelize, or Other, which allows you to specify a custom table name
You can see how this works in this Rails migration tutorial.