Manage branches

Data resides in a branch. Each Neon project is created with a primary branch called main. You can create child branches from main or from previously created branches. A branch can contain multiple databases and roles. Tier limits define the number of branches you can create in a project and the amount of data you can store in a branch.

A child branch is a copy-on-write clone of the parent branch. You can modify the data in a branch without affecting the data in the parent branch. For more information about branches and how you can use them in your development workflows, see Branching.

You can create and manage branches using the Neon Console or Neon API. This topic covers both methods.

Primary branch

Each Neon project has a primary branch. In the Neon Console, your primary branch is identified by a PRIMARY tag. You can designate any branch as the primary branch for your project. The advantage of the primary branch is that its compute endpoint remains accessible if you exceed your project's limits, ensuring uninterrupted access to data that resides on the primary branch, which is typically the branch used in production.

• For Free Tier users, the compute endpoint associated with the primary branch remains accessible if you exceed the Active time limit of 100 hours per month.
• For Pro plan users, the compute endpoint associated with the primary branch is exempt from the limit on simultaneously active computes, ensuring that it is always available. Neon has a default limit of 20 simultaneously active computes to protect your account from unintended usage.

Non-primary branch

Any branch not designated as the primary branch is considered a non-primary branch. You can rename or delete non-primary branches.

• For Free Tier users, compute endpoints associated with non-primary branches are suspended if you exceed the Free Tier compute active time limit of 100 hours per month.
• For Pro plan users, default limits prevent more than 20 simultaneously active compute endpoints. Beyond that limit, a compute endpoint associated with a non-primary branch remains suspended.

Create a branch

To create a branch:

1. In the Neon Console, select a project.
2. Select Branches.
3. Click New Branch to open the branch creation dialog.
4. Enter a name for the branch.
5. Select a parent branch. You can branch from your Neon project's primary branch or a non-primary branch.
6. Select one of the following branching options:
   • Head: Creates a branch with data up to the current point in time (the default).
   • Time: Creates a branch with data up to the specified date and time.
   • LSN: Creates a branch with data up to the specified Log Sequence Number (LSN).
7. Select whether or not to create a compute endpoint, which is required to connect to the branch. If you are unsure, you can add a compute endpoint later. Pro plan users can users click Change or Settings to override or modify the default compute settings, including the compute size, autoscaling, and auto-suspend settings.
8. Click Create Branch to create your branch.

You are directed to the Branches page where you are shown the details for your new branch.

View branches

To view the branches in a Neon project:

1. In the Neon Console, select a project.
2. Select Branches to view the branches for the project.
3. Select a branch from the table to view details about the branch.

Branch details shown on the branch page include:

• ID: The branch ID. Branch IDs have a br- prefix.
• Created: The date and time the branch was created.
• Current Data Size: The current data size of the branch.
• Active Time: The total amount of time that your branch compute has been active within the current billing period, measured in hours.
• Compute Time: The computing capacity used by the branch within the current billing period, measured in Compute Unit (CU) hours.
• Written Data: The total volume of data written from your branch compute to storage within the current billing period, measured in gibibytes (GiBs).
• Data Transfer: The total volume of data transferred out of Neon (known as "egress") within the current billing period, measured in (GiBs).
• Parent Branch: The branch from which this branch was created (only visible for child branches).
• Date: The date the parent branch was created (only displayed for branches created with the Time option).
• Time: The time the parent branch was created (only displayed for branches created with the Time option).

For more information about Active Time, Compute Time, Written Data, and Data Transfer usage metrics, refer to our Billing page.

The branch details page also includes details about the compute endpoint associated with the branch. For more information, see View a compute endpoint.

Rename a branch

Neon permits renaming a branch, including your project's primary branch. To rename a branch:

1. In the Neon Console, select a project.
2. Select Branches to view the branches for the project.
3. Select a branch from the table.
4. On the branch page, click the More drop-down menu and select Rename.
5. Specify a new name for the branch and click Save.

Set a branch as primary

Each Neon project is created with a primary branch called main, but you can designate any branch as your project's primary branch. The benefit of the primary branch is that the compute endpoint associated with the primary branch remains accessible if you exceed project limits, ensuring uninterrupted access to data on the primary branch. For more information, see Primary branch.

To set a branch as the primary branch:

1. In the Neon Console, select a project.
2. Select Branches to view the branches for the project.
3. Select a branch from the table.
4. On the branch page, click the More drop-down menu and select Set as primary.
5. In the Set as primary confirmation dialog, click Set as Primary to confirm your selection.

Connect to a branch

Connecting to a database in a branch requires connecting via a compute endpoint associated with the branch. The following steps describe how to connect using psql and a connection string obtained from the Neon Console.

1. In the Neon Console, select a project.
2. On the project Dashboard, under Connection Details, select the branch, the database, and the role you want to connect with.
3. Copy the connection string. A connection string includes your role name, the compute endpoint hostname, and database name.
4. Connect with psql as shown below.

If you want to connect from an application, the Connection Details widget on the project Dashboard and the Guides section in the documentation provide connection examples for various languages and frameworks. For more information about connecting, see Connect from any application.

Delete a branch

Deleting a branch is a permanent action. Deleting a branch also deletes the databases and roles that belong to the branch as well as the compute endpoint associated with the branch. You cannot delete a branch that has child branches. The child branches must be deleted first.

To delete a branch:

1. In the Neon Console, select a project.
2. Select Branches.
3. Select a branch from the table.
4. On the branch page, click the More drop-down menu and select Delete.
5. On the confirmation dialog, click Delete.

Check the data size

Tier limits define the amount of data you can store in a branch. Neon's Free Tier permits 3 GB per branch. When creating a new branch, the child branch includes the data from the parent branch. For example, if you have a branch with 1 GB of data, the child branch is created with the same 1 GB of data.

You can check the data size for a branch by viewing the Database size value on the branch details page (see View branches). Alternatively, you can run the following query from the Neon SQL Editor:

Branching with the Neon CLI

The Neon CLI supports creating and managing branches. For instructions, see Neon CLI commands — branches. For a Neon CLI branching guide, see Branching with the Neon CLI.

Branching with the Neon API

Branch actions performed in the Neon Console can also be performed using the Neon API. The following examples demonstrate how to create, view, and delete branches using the Neon API. For other branch-related API methods, refer to the Neon API reference.

The jq option specified in each example is an optional third-party tool that formats the JSON response, making it easier to read. For information about this utility, see jq.

Prerequisites

A Neon API request requires an API key. For information about obtaining an API key, see Create an API key. In the examples shown below, $NEON_API_KEY is specified in place of an actual API key, which you must provide when making a Neon API request.

Create a branch with the API

The following Neon API method creates a branch. To view the API documentation for this method, refer to the Neon API reference.

The API method appears as follows when specified in a cURL command. The endpoints attribute creates a compute endpoint, which is required to connect to the branch. A branch can be created with or without a compute endpoint. The branch attribute specifies the parent branch.

• The project_id for a Neon project is found on the Settings page in the Neon Console, or you can find it by listing the projects for your Neon account using the Neon API.
• The parent_id can be obtained by listing the branches for your project. See List branches. The <parent_id> is the id of the branch you are branching from. A branch id has a br- prefix. You can branch from your Neon project's primary branch or a previously created branch.

The response body includes information about the branch, the branch's compute endpoint, and the create_branch and start_compute operations that were initiated.

Response body

List branches with the API

The following Neon API method lists branches for the specified project. To view the API documentation for this method, refer to the Neon API reference.

The API method appears as follows when specified in a cURL command:

The project_id for a Neon project is found on the Settings page in the Neon Console, or you can find it by listing the projects for your Neon account using the Neon API.

The response body lists the project's primary branch and any child branches. The name of the primary branch in this example is main.

Response body

Delete a branch with the API

The following Neon API method deletes the specified branch. To view the API documentation for this method, refer to the Neon API reference.

The API method appears as follows when specified in a cURL command:

• The project_id for a Neon project is found on the Settings page in the Neon Console, or you can find it by listing the projects for your Neon account using the Neon API.
• The branch_id can be found by listing the branches for your project. The <branch_id> is the id of a branch. A branch id has a br- prefix. See List branches.

The response body shows information about the branch being deleted and the suspend_compute and delete_timeline operations that were initiated.

Response body

You can verify that a branch is deleted by listing the branches for your project. See List branches. The deleted branch should no longer be listed.

Need help?

Send a request to support@neon.tech, or join the Neon community forum.