Development environments
Create isolated environments for developers or feature work without copying the entire database.
Neon · Const
Database branching
Neon database branching creates isolated copy-on-write clones of a database for development, testing, CI/CD, or recovery. A branch can start from the current or a retained historical state and then diverges independently.
How it works
A Neon branch is an isolated copy-on-write clone of a database. It starts from a current or historical state of a parent branch, shares the parent’s underlying data initially, and records later writes independently as changes.
Syntax
neon branches create --name <branch-name> --parent <parent-branch>Parameters
| Name | Type | Description |
|---|---|---|
--name | string | Name of the new branch; the CLI can generate a default name if omitted. |
--parent | string | Existing branch from which schema and data are inherited. |
past state | timestamp | Optional historical point from which to create the branch, when supported by the selected interface. |
Returns
A new isolated Neon database branch with the selected parent state and its own connection string.
Key points
- Branches use copy-on-write storage rather than eagerly duplicating the database.
- Branch creation can use either the latest parent state or a retained historical point.
- The new branch can be modified independently of the branch it came from.
- After creation, branch-specific writes are stored as differences from shared data.
- Branch creation remains fast even for large databases.
Common mistakes
- Branch creation does not load or alter the parent, but the new branch still has its own compute and lifecycle to manage.
Example: Create a database branch
neon branches create --name feature-x --parent mainCreates an isolated branch named feature-x from the main branch using the Neon CLI.
When to use it
Safe query testing
Run destructive DELETE, UPDATE, or DDL queries against production-like data safely.
CI/CD workflows
Create parallel, disposable database environments for automated pipelines.
Historical recovery
Reconstruct data from a retained historical point for investigation or recovery.
Interview questions
QWhat is a Neon database branch?
A branch is a copy-on-write clone of a Neon database. It inherits the parent’s schema and data at a selected point, then stores subsequent changes separately.
Follow-up: Why is creation fast? The branch initially references shared underlying data and writes only deltas instead of copying the whole database.
QHow does branching protect the parent database?
Branches are isolated: changes made in one do not affect its parent or other branches. Each branch can therefore serve as an independent development, testing, or CI environment.
Follow-up: How can production data be tested safely? Create a branch from the production state, run destructive or schema-changing queries there, and remove the branch afterward.
QCan a branch represent historical database state?
A branch can be created from the parent’s current state or from a past state within the available history. The selected parent supplies the schema and data baseline for the new branch.
Follow-up: What happens if the requested historical point is unavailable? The parent must retain that history, so creation from that point cannot proceed when it has expired.
Related
BranchParent branchRoot branchCopy-on-writeSnapshotsRestore windowneon branches create