Isolated development
Create a production-like environment where developers can run migrations or experiment without changing production.
Neon · Const
Branching
Neon branching creates isolated copy-on-write database branches from current or historical states. Child changes are stored independently, enabling safe development, testing, CI/CD, and recovery workflows.
How it works
Neon branching creates an isolated copy-on-write clone from a branch's current or historical state. The new branch initially shares its parent's data, while subsequent writes are stored independently as deltas, so experimenting on the child does not affect the parent or add load to it.
Syntax
neon branches create --project-id <project-id> --name <branch-name>Key points
- A branch starts as a logical clone of the selected database state without requiring a full physical copy.
- Branch creation supports both the latest parent state and an earlier point in the database's history.
- After creation, writes made on the child remain separate from writes on its parent.
- Neon stores post-creation changes as differences, which makes branch creation fast and storage-efficient.
- A project's first branch uses the root branch as its source.
- Branch management can be automated through the CLI, API, or GitHub Actions.
Common mistakes
- Branch creation does not protect the child from its own changes: modifications are independent, but the branch still starts from the selected parent state.
- A branch can be based on another child branch, so verify the ancestry before creating it when the starting data matters.
Example: Create a preview branch
neon branches create --project-id "$NEON_PROJECT_ID" --name preview-123Creates an isolated database branch named preview-123 from the project's default branch.
When to use it
Preview and CI environments
Give each pull request or pipeline run its own database state for migrations and tests.
Point-in-time recovery
Start a branch from an earlier database state to investigate or recover from data loss.
Interview questions
QWhat is a Neon branch?
A Neon branch is a copy-on-write clone of database data. It can be created from the current state or a past state, and changes made afterward are isolated to that branch.
Follow-up: Why is creating one suitable for production-like testing? The branch shares existing data rather than copying it up front, while writes become deltas and do not affect the parent.
QHow are branch relationships formed?
The first branch is created from the project's root branch. Later branches may use either the root or an existing branch as their parent, allowing branch hierarchies.
Follow-up: What must be checked before branching from a child? Its inherited state and ancestry, because the resulting branch starts from that child's state rather than directly from the root.
QWhat workflows does branching support?
Branching is useful for isolated development, testing, and CI/CD. A branch can contain production-like data while developers or automated pipelines modify it without changing production.
Follow-up: How can branching help recover data? Neon allows a branch to be created from a previous point within the available history window, enabling rollback-oriented recovery.
Related
root branchparent branchNeon CLINeon APIGitHub Actions