Refresh a branch

When you create a branch in Neon, you create a copy-on-write clone that reflects the current state of the parent branch, but what do you do if your branch becomes stale? For example, changes are made to the data or schema on the parent branch that you would like reflected in your development branch, or your branch has aged out of the point-in-time restore window (the history shared with the parent branch) and is now taking up storage space. Ideally, you want to refresh your branch but keep the same compute endpoint, whose connection details may already be configured in your application or toolchain.

There isn't a single command that refreshes a branch, but you can do so using a combination of Neon API calls. The procedure described below refreshes a branch by performing the following steps:

1. Creating a new up-to-date branch without a compute endpoint
2. Moving the compute endpoint from your current branch to the new branch
3. Deleting the old branch
4. Renaming the new branch to the name of the old branch

Prerequisites

The following information is required to perform the procedure:

• A Neon API key. For information about obtaining an API key, see Create an API key.
• The project_id for your Neon project. You can obtain a project_id using the List projects method, or you can find it on your project's Settings page in the Neon Console.
• The branch_id of the current branch. You can obtain a branch_id using the List branches method, or you can find it on your project's Branches page in the Neon Console. A branch_id has a br- prefix.
• The endpoint_id of the compute endpoint associated with the current branch. You can obtain an endpoint_id using the List endpoints method, or you can find it on the Branches page in the Neon Console. An endpoint_id has an ep- prefix.

Create a new up-to-date branch without a compute endpoint

The Create branch request shown below creates a branch without a compute endpoint. The only required parameter is your Neon project_id. The project_id value used in the example below is dark-cell-12604300. You must also set the $NEON_API_KEY variable or replace $NEON_API_KEY with an actual API key.

The response body includes the id of your new branch. You will need this value (br-falling-flower-15986510) to move the compute endpoint in the next step.

Response body

Move the compute endpoint from your current branch to the new branch

The Update endpoint API request shown below moves the compute endpoint from your current branch to the new branch. The required parameters are the project_id and endpoint_id of your current branch, and the branch_id of your new branch. You must also set the $NEON_API_KEY variable or replace $NEON_API_KEY with an actual API key.

Response body

Delete the old branch

The Delete branch API request shown below deletes the old branch. The old branch will take up storage space, so it's recommended that you remove it. The required parameters are the project_id and branch_id. You must also set the $NEON_API_KEY variable or replace $NEON_API_KEY with an actual API key.

Response body

Rename the new branch to the name of the old branch

Optionally, you can rename the new branch to the name of the old branch. The Update branch API request shown below renames the new branch from dev_branch_2 to dev_branch_1.

Response body