Learn how to refresh a Neon branch using the Neon API
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:
The branch refresh procedure does not preserve data or schema changes on your current branch. Do not perform this procedure if you need to maintain changes made to your branch. The procedure is best suited to branches used in a read-only capacity.
The following information is required to perform the procedure:
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 Project 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.
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.
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.
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.