Skip to content

Branching

Create a development or staging environment for your database through branches

Overview

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 DiagramPlanetScale 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.

Note
Data from the main database is not copied to development branches.

Production branches are highly available databases intended for production traffic. They are protected from direct schema changes by default and include automated daily backups.

Tip
You'll see a ERROR 1105 (HY000): direct DDL is disabled message if you attempt schema changes in a production branch. Create a development branch and start your changes there.

Branch promotion

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 main.

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.

Copied
pscale 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 pscale.

Copied
pscale 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.

Copied
pscale 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.

Note
Administrators can require approval for deploy requests in the database's Settings tab.

Create a deploy request from the branch overview page app.planetscale.com/<organization>/<database>/<branch> or run the command below using the CLI.

Copied
pscale 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.

Copied
pscale 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.

Copied
pscale 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.

Deploy queueDeploy queue

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.

Copied
pscale 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.

Note
Only organization administrators have permission to delete production branches.

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:

  1. Go into the Settings for your database
  2. Enable "Automatically copy migration data"
  3. 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.

Need help?

Get help from PlanetScale's support team, or join our GitHub discussion board to see how others are using PlanetScale.

Was this page useful?
Last updated on November 18, 2021
Help us improve this page
PrivacyTerms© 2021 PlanetScale Inc.