Preview and feature development
Create an isolated environment for a pull request or feature branch.
Neon · Command
neonctl branches create
Creates a Neon branch for isolated development or testing. It defaults to the project's default branch and a read-write compute, with options for naming, parenting, expiration, protection, and compute sizing.
How it works
Run this command to create a Neon branch for isolated development or testing. Supply the project ID, optionally choose a branch name and parent, and use compute-related options to control whether and how a compute endpoint is created.
Syntax
neon branches create [options]Parameters
| Name | Type | Description |
|---|---|---|
--compute | boolean | Whether to create a compute; defaults to true, and --no-compute disables it. |
--cu | string | Compute Units as a fixed value or range, such as 2 or 0.5-3. |
--expires-at | string | Expiration date for the branch. |
--name | string | Name assigned to the branch. |
--parent | string | Parent branch name, ID, timestamp, or LSN. |
--protected | boolean | Whether the branch is protected. |
--project-id | string | Project in which to create the branch. |
Returns
A newly created Neon branch; the documentation also states that branches create commands return a connection string.
Key points
- The command creates a new branch inside the project identified by
--project-id. - Use
--nameto assign a human-readable branch name; if omitted, the command defaults to the branch ID. --parentaccepts a branch name, branch ID, timestamp, or LSN as the branch source.- When
--parentis not supplied, the new branch is based on the project's default branch. --cuconfigures compute capacity using a fixed number or a hyphen-delimited range.--expires-atlets you assign an expiration timestamp to the branch instead of leaving it without an expiration.
Common mistakes
- The command creates a read-write compute by default; use --no-compute when the branch should initially have no compute.
- A protected branch has lifecycle restrictions: it cannot be deleted, archived, or reset, and protection is available only on paid plans.
Example: Create a pull-request branch
neon branches create --name pr-1234 --project-id <project-id>Creates a named branch in the specified project, using the project's default branch as the parent unless another parent is supplied.
When to use it
Safe experimentation
Make a disposable copy of a development or staging branch.
Deferred compute provisioning
Create a branch without an immediately provisioned compute.
Temporary test environments
Automatically retire temporary branches after a specified date.
Interview questions
QWhat does neon branches create do, and which identifier is required?
The command is neon branches create [options]. It creates a branch in a Neon project, and the project ID identifies where the branch is created. The branch name is optional; without one, the default is the branch ID.
Follow-up: How would you create a branch without a compute endpoint? Use --no-compute, which overrides the default read-write compute behavior.
QHow do you select the branch or database state from which the new branch is created?
Use --parent to choose the source branch. The option accepts a parent branch name, branch ID, timestamp, or LSN; if omitted, creation uses the project's default branch.
Follow-up: Why might a timestamp or LSN be useful? It allows the new branch to represent a point-in-time state rather than only the current parent state.
QHow can compute creation and sizing be controlled?
The command creates a read-write compute by default. --cu sets the Compute Units as either a fixed value such as 2 or a range such as 0.5-3, while --no-compute creates the branch without compute.
Follow-up: What other creation-time compute choice is exposed? --compute controls whether a compute is created, with true as its default.
Related
neon branches listneon branches deleteneon branches resetneon connection-string