Clean up temporary branches
Remove a temporary development or preview branch after its work is complete.
Neon · Command
neonctl branches delete
Permanently deletes a Neon project branch by ID or name. Specify --project-id unless a default project has been set with neon set-context.
How it works
The command permanently removes the selected branch using either its ID or name. Supply the project explicitly unless a default project has been configured with neon set-context; the operation also removes the branch’s associated databases, roles, and compute.
Syntax
neon branches delete <id|name> [options]Parameters
| Name | Type | Description |
|---|---|---|
id|name | string | Branch ID or name to delete. |
--project-id | string | Project ID containing the branch; optional when a default project context is configured. |
Returns
On success, the command displays the deleted branch's name, ID, current state, and creation time.
Key points
- The command removes one branch from a Neon project.
- The positional argument accepts either a branch ID or branch name.
--project-idis an optional string identifying the target project.
Example: Delete a branch
neon branches delete br-rough-sky-123456 --project-id my-project-idDeletes the named branch from the specified Neon project.
When to use it
Prune a branch hierarchy
Delete a parent branch after first removing all of its child branches.
Automate environment cleanup
Run controlled cleanup in automation with an explicit project and branch ID.
Interview questions
QWhat is the command syntax and how does it identify the branch?
The command is neon branches delete <id|name> [options]. It accepts either a branch identifier or branch name, and --project-id selects the target project when needed.
Follow-up: What prevents deleting a branch? A root or default branch, a branch with children, or the last remaining branch in a project cannot be deleted.
QWhat are the operational consequences of deletion?
Deleting a branch is permanent and also removes the databases, roles, and compute associated with that branch. Existing client connections can therefore be disrupted while compute endpoints enter an idle state.
Follow-up: What cleanup is required first? Delete child branches before their parent, because a branch with children is not eligible for deletion.
QHow should the command be used safely in scripts?
Use --project-id to identify the project unless neon set-context has configured a default project. The command can address the branch by either its name or ID.
Follow-up: How would you avoid an ambiguous target? Use the branch ID together with an explicit project ID, especially in automation.
Related
neon set-contextneon branches listneon branches createDelete branch