Branching

Branches on PlanetScale for Postgres are isolated database deployments that provide you with separate environments for development and testing, as well as restoring from backups.

When your PostgreSQL database is first initialized, a single production branch is created called main which acts as the default branch.

Currently branches are created by restoring backups. See Backups for information on how to create a new branch from a backup. All branches restored from a backup will have the full schema and data from the desired point in time.

Note

New branches incur additional charges. The cost depends on the selected resources for the branch. The monthly price for the new branch will be shown during branch creation. See pricing for more information.

Branches are completely isolated databases. Changes made in one branch, whether to the schema or the data, do not affect any other branches for a given database. There is no data replication between branches, so writing data into one will not replicate to another.

Development and production branches

PlanetScale for Postgres provides two types of database branches:

• Development branches - Development branches run on ‘PS-DEV’ instances that have limited performance capabilities. Great for experimentation, testing new schemas, and limited exploration of your data. Development branches do not include any replicas.

• Production branches — Production branches are highly available databases intended for production traffic. They are automatically provided with 2 replicas to resist outages, enabling zero-downtime failovers.

Create a branch

Note

We are still in the process of building out our branching functionality for Postgres. You can currently create a new empty branch which is an isolated database with no schema/data or create a branch from a backup, which includes schema and data.

There are 2 ways to create a new Postgres branch: from the Branches page (no schema or data included) or by restoring from a backup (schema and data included).

From the Branches page

This method does not include schema or data.

1. Click “Branches”

2. Click “New branch”

3. Give the branch a name

4. Choose the base branch. This currently does not copy the schema, but this functionality will be in place soon.

5. Select a region

6. Click “Create branch”

From a backup

This method includes both the schema and the data for the selected backup. We do not recommend using production data for development environments.

1. From the PlanetScale organization dashboard, select the desired database

2. Navigate to the Backups page from the menu on the left

3. Select the backup you wish to restore from

4. Click Restore to new branch

5. Configure the restored branch:

   • Branch name: Name for the new branch
   • Cluster size: Choose the desired size of the new cluster
6. Click Restore backup

A new branch will be created based on this backup and will become visible under the Branches page.

View all branches

To view all branches for your PostgreSQL database:

1. From the PlanetScale organization dashboard, select the desired database

2. Click on the Branches drop down

3. You’ll see a list of all branches with their type (development/production)

4. You can select a branch by its name to see its Dashboard

Similarly you can navigate directly to the Branches page to see all branches:

1. From the PlanetScale organization dashboard, select the desired database

2. Navigate to the Branches page from the menu on the left

Connect to a branch

Each branch has its own connection details. To connect to a specific branch:

1. Navigate to the desired branch following either of the paths shown above

2. Click the Connect button

3. If you haven’t already, follow the instructions to Create the default role

4. Choose your preferred connection method (direct or PgBouncer)

5. Copy the connection string or credentials

6. You should create new roles for specific use-cases and tailor their permissions appropriately for them

7. In your application, use the specific role(s) and the preferred connection method.

For detailed connection instructions, see the PostgreSQL connection documentation.

Rename a branch

To rename a branch:

1. From the PlanetScale organization dashboard, select the desired database

2. Navigate to the Branches page from the menu on the left

3. Click on the three dots (”…”) next to the branch you want to rename

4. Select Rename branch

5. Enter the new branch name

6. Click Save changes

Renaming a branch does not affect that branch’s credentials. You do not need to regenerate credentials if you rename a branch.

Set as default branch

The default branch serves as the source branch when creating new development branches. To change the default branch:

From the Branches page:

1. From the PlanetScale organization dashboard, select the desired database

2. Go to the Branches tab in your database dashboard

3. Click on the three dots (”…”) next to the branch you want to set as default

4. Click Set as default branch

From the Settings page:

1. From the PlanetScale organization dashboard, select the desired database

2. Navigate to the Settings page from the menu on the left

3. Select the branch from the Default branch dropdown you want to be the default branch

4. Scroll down and click Save database settings

If you change the default branch and intend for it to power your production application, you may need to update your application credentials to reference the new default branch.

Delete a branch

You can delete a branch that you no longer need:

1. From the PlanetScale organization dashboard, select the desired database

2. Go to the Branches tab in your database dashboard

3. Click on the three dots (”…”) next to the branch you want to delete

4. Select Delete

5. Confirm the deletion

Important notes:

• You cannot delete a branch that’s configured as the default branch. You must first set another branch as default.
• Only Organization Administrators and Database Administrators have permission to delete production branches. Database Members can delete non-production branches.
• Development branches are billed only for the time they are used, so it’s beneficial to delete them when no longer needed.

Promote a branch to production

Any development branch can be promoted to production to make it highly available with additional replicas:

1. Navigate to the development branch you want to promote

2. Click the Promote to production button

3. Confirm the promotion

Schema changes

Since PlanetScale for Postgres branches don’t use deploy requests, you make schema changes directly on each branch:

1. Connect to your development branch

2. Make your schema changes using standard PostgreSQL DDL commands

3. Test your changes in the development environment

4. When ready, manually apply the same changes to your production branch

There’s currently no automatic way to merge schema changes between PlanetScale for Postgres branches. You must manually copy your changes from development to production branches.

Need help?

Get help from the PlanetScale Support team, or join our GitHub discussion board to see how others are using PlanetScale.