[metadata]
description: Data resides in a branch. Each Neon project is created with a root branch, which is also designated as your default branch. Projects created in the Neon Console have a root branch named production, wh...
og:description: Data resides in a branch. Each Neon project is created with a root branch, which is also designated as your default branch. Projects created in the Neon Console have a root branch named production, wh...
og:image: https://neon.com/docs/og?title=TWFuYWdlIGJyYW5jaGVz&category=TWFuYWdlICYgb3BlcmF0ZQ==
og:site_name: Neon
og:title: Manage branches - Neon Docs
og:type: article
og:url: https://neon.com/docs/manage/branches
twitter:card: summary_large_image
twitter:description: Data resides in a branch. Each Neon project is created with a root branch, which is also designated as your default branch. Projects created in the Neon Console have a root branch named production, wh...
twitter:image: https://neon.com/docs/og?title=TWFuYWdlIGJyYW5jaGVz&category=TWFuYWdlICYgb3BlcmF0ZQ==
twitter:site: @neondatabase
twitter:title: Manage branches - Neon Docs
viewport: width=device-width, initial-scale=1, viewport-fit=cover

[canonical-links]
https://neon.com/docs/manage/branches

[document-links]
/docs
AI Gateway: /docs/ai-gateway/overview
AI agents on Neon: /docs/ai/ai-agents-tools
API keys: /docs/manage/api-keys
APIs & SDKs: /docs/reference/api
About: /about-us
Account recovery: /docs/manage/account-recovery
Accounts: /docs/manage/accounts
Active queries: /docs/introduction/monitor-active-queries
Add members by domain: /docs/manage/orgs-add-members-by-domain
Apache Software Foundation: https://www.apache.org
Auth: /docs/auth/overview
Blog: /blog
Branch archiving: /docs/guides/branch-archiving
Branch expiration guide: /docs/guides/branch-expiration
Branches: /docs/manage/branches
Branching: /docs/introduction/branching
Building on Neon: /docs/guides/platform-integration-overview
CCPA Compliant: https://trust.neon.com/?itemUid=4064ac33-7b48-407b-aed7-ce02971d1ec1
CLI actions: /docs/manage/orgs-cli
California Privacy: https://www.databricks.com/legal/supplemental-privacy-notice-california-residents
Careers: https://www.databricks.com/company/careers/open-positions?department=engineering&location=all&itm_source=www&itm_category=company&itm_page=engineering-at-databricks&itm_location=body&itm_component=hero&itm_offer=open-positions
Changelog: /docs/changelog
Community Guides: /guides
Community: /docs/community/community-intro
Compliance Guide: /docs/security/hipaa
Computes: /docs/manage/computes
Contact Sales: /contact-sales
Create an API key: /docs/manage/api-keys#create-an-api-key
Data API: /docs/data-api/overview
Data anonymization: /docs/workflows/data-anonymization
Database access: /docs/manage/database-access
Databases: /docs/manage/databases
Datadog: /docs/guides/datadog
Discord Server: https://discord.gg/92vNTzKDGp
Discord: https://discord.gg/92vNTzKDGp
Docs: /docs
Edit on GitHub: https://github.com/neondatabase/website/tree/main/content/docs/manage/branches.md
Examples repo: https://github.com/neondatabase/examples
FAQs: /faqs
Frameworks: /docs/get-started/frameworks
GDPR Compliant: https://trust.neon.com/?itemUid=45220873-6e51-4dbb-b1b1-37d66ee9ef95
Get started: /docs/introduction
GitHub: https://github.com/neondatabase
Glossary: /docs/reference/glossary
Grafana Cloud: /docs/guides/grafana-cloud
HIPAA Compliant: /docs/security/hipaa
How to apply IP restrictions to protected branches: /docs/guides/protected-branches#how-to-apply-ip-restrictions-to-protected-branches
ISO 27001 Certified: https://trust.neon.com/?itemUid=1fed9faa-4a87-427c-9a95-96b4d6bf66b7
ISO 27701 Certified: https://trust.neon.com/?itemUid=dc79cbc7-c99d-4eb9-891e-f5dc44b943d7
Instant restore: /docs/guides/branch-restore
Integrations & tooling: /docs/guides/integrations
Integrations: /docs/manage/integrations
Languages: /docs/get-started/languages
Learn PostgreSQL: https://neon.com/postgresql/tutorial
Learn more: /docs/guides/protected-branches#new-passwords-generated-for-postgres-roles-on-child-branches
LinkedIn: https://www.linkedin.com/company/neondatabase/
Log in: https://console.neon.tech/login
Logs: /docs/introduction/monitor-logs
Manage & operate: /docs/manage/platform
Manage Organizations: /docs/manage/orgs-manage
Manage computes: /docs/manage/computes#view-a-compute
Manage databases: /docs/manage/databases
Manage organizations via API: /docs/manage/orgs-api
Manage roles: /docs/manage/roles
Metrics & logs: /docs/reference/metrics-logs
Modern Slavery Statement: https://www.databricks.com/legal/modern-slavery-policy-statement
Monitoring dashboard: /docs/introduction/monitoring-page
Multitenancy: /docs/guides/multitenancy
Neon API Reference: /docs/reference/api
Neon API: /docs/reference/api
Neon CLI commands — branches: /docs/cli/branches
Neon CLI: /docs/cli
Neon Functions: /docs/compute/functions/overview
Neon Platform Terms: /platform-terms
Neon SQL Editor: /docs/get-started/query-with-neon-sql-editor
Neon status loading...: https://neonstatus.com/
Neon-Managed Vercel integration: /docs/guides/neon-managed-vercel-integration
Neon: /
Neon’s Sub Contractors: /hipaa-contractors
Next Computes: /docs/manage/computes
Object Storage: /docs/storage/overview
Object hierarchy: /docs/manage/overview
OpenTelemetry: /docs/guides/opentelemetry
Organizations: /docs/manage/organizations
Overview: /docs/introduction/monitoring
Overview: /docs/manage/maintenance-updates-overview
Overview: /docs/manage/organizations
Permissions quickstart new: /docs/manage/project-permissions-get-started
PgHero: /docs/introduction/monitor-pghero
Plans & billing: /docs/introduction/about-billing
Platform maintenance: /docs/manage/platform-maintenance
PostgreSQL Tutorial: /postgresql/tutorial
Postgres: /docs/postgres/overview
Previous Multitenancy: /docs/guides/multitenancy
Privacy Notice: https://www.databricks.com/legal/privacynotice
Production checklist: /docs/get-started/production-checklist
Project collaboration: /docs/guides/project-collaboration-guide
Projects: /docs/manage/projects
Protected branches guide: /docs/guides/protected-branches
Query organization metrics via API: /docs/manage/orgs-api-consumption
Query performance: /docs/introduction/monitor-query-performance
RSS feeds: /docs/reference/feeds
Regions: /docs/introduction/regions
Reset from parent: /docs/guides/reset-from-parent
Resilience & architecture: /docs/introduction/architecture-overview
Roadmap: /docs/introduction/roadmap
Roles: /docs/manage/roles
SOC 2 Certified: https://trust.neon.com/?itemUid=7bfa66da-33ab-49de-8391-e329738a1ae9
Schema-only branches: /docs/guides/branching-schema-only
Security & compliance: /docs/security/security-overview
Security: /security
Sign up: https://console.neon.tech/signup
Startups: /startups
Status: /docs/introduction/status
Support: /docs/introduction/support
System operations: /docs/manage/operations
Tables: /docs/guides/tables
Terms of Use: https://www.databricks.com/legal/terms-of-use
Transfer projects: /docs/manage/orgs-project-transfer
Trust Center: https://trust.neon.com
Updates: /docs/manage/updates
User permissions: /docs/manage/user-permissions
We ran the same workload through 42 models via AI Gateway and compared costs: https://neon.com/blog/comparing-token-economics-across-42-ai-models
X.com: https://x.com/neondatabase
YouTube: https://www.youtube.com/channel/UCoMzQTJSIr7-RU1QbomQI2w
archived: /docs/guides/branch-archiving
branch protection: /docs/guides/protected-branches
create branch API call: /docs/reference/api/branches/create-project-branch
history window: /docs/introduction/history-window
https://discord.gg/92vNTzKDGp
https://github.com/neondatabase
https://neon.com/docs/llms.txt: https://neon.com/docs/llms.txt
instant restore: /docs/introduction/branch-restore
pgAdmin: /docs/introduction/monitor-pgadmin
plan allowances: /docs/introduction/plans
reset: /docs/manage/branches#reset-a-branch-from-parent

[structured-data]
{"@context":"https://schema.org","@type":"Article","author":{"@type":"Organization","name":"Neon"},"headline":"Manage branches"}

[content]
Manage branches - Neon Docs
We ran the same workload through 42 models via AI Gateway and compared costs
Neon
Docs
Search
...
⌘K
Ask AI
Log in
Sign up
Get started
Products
Postgres
Auth
Data API
Neon Functions
Object Storage
AI Gateway
Platform
Manage & operate
Resilience & architecture
Security & compliance
Plans & billing
Building on Neon
AI agents on Neon
Reference
APIs & SDKs
Integrations & tooling
Glossary
Resources
Support & Community
Support
Community
Product updates
Status
Changelog
Roadmap
RSS feeds
Starter code
Examples repo
Learn PostgreSQL
Search
...
⌘K
Ask AI
Full Neon documentation index:
https://neon.com/docs/llms.txt
Manage & operate
Access & collaboration
Accounts
Permissions quickstart
new
User permissions
Organizations
Overview
Manage Organizations
Add members by domain
Transfer projects
Organizations API
Manage organizations via API
Query organization metrics via API
CLI
CLI actions
Project collaboration
Database access
API keys
Account recovery
Projects & resources
Object hierarchy
Projects
Multitenancy
Branches
Computes
Roles
Databases
Tables
Integrations
Monitoring & observability
Overview
Metrics & logs
Monitoring dashboard
System operations
Active queries
Query performance
Logs
Third-party monitoring
Datadog
Grafana Cloud
OpenTelemetry
pgAdmin
PgHero
Operations & maintenance
Production checklist
Updates
Overview
Platform maintenance
Updates
Regions
/
Manage & operate
/
Branches
Manage branches
Copy page
Data resides in a branch. Each Neon project is created with a
root branch
, which is also designated as your
default branch
. Projects created in the Neon Console have a root branch named
production
, while projects created via the API or CLI have a root branch named
main
. You can create child branches from your root branch or from previously created branches. A branch can contain multiple databases and roles. Neon's
plan allowances
define the number of branches you can create.
A child branch is a copy-on-write clone of the parent branch. You can modify the data in a branch without affecting the data in the parent branch. For more information about branches and how you can use them in your development workflows, see
Branching
.
You can create and manage branches using the Neon Console,
Neon CLI
, or
Neon API
.
important
When working with branches, it is important to remove old and unused branches. Branches hold a lock on the data they contain, which will add to your storage usage as they age out of your project's
history window
.
Branch naming requirements
Specifying a branch name is optional. If you don't provide one, the branch name defaults to the automatically generated branch ID with a
br-
prefix (for example,
br-curly-wave-af4i4oeu
).
If you do specify a custom branch name when creating or renaming a branch, it must meet the following requirements:
Maximum length
: 256 characters (API limit). Note that the Neon Console enforces a more restrictive limit of 128 characters.
Uniqueness
: Branch names must be unique within a project. You cannot have two branches with the same name in the same project.
Non-empty
: Branch names cannot be empty or consist only of whitespace characters.
Character flexibility
: Unlike some other Neon resources (such as databases or roles), branch names have no special character restrictions. You can use any characters as long as they meet the requirements above.
Create a branch
Console
CLI
API
To create a branch:
In the Neon Console, select a project.
Select
Branches
under
Project
.
Click
New branch
to open the branch creation dialog.
Select a
Parent branch
. This determines the origin of the schema and data for your new branch. By default, your project's default branch (named
main
if the project was created with the CLI or API, or
production
if created in the Console) is selected, but you can choose any existing branch in your project.
Specify a branch name, or leave it blank to use the default generated name.
Select what to include in the new branch:
Current data
: Creates a copy of the parent branch’s latest data and schema, resulting in an isolated database that reflects the parent at the time of creation.
Past data
: Creates a copy using data from a specific past date and time of the parent branch. The parent branch must have the relevant history.
note
You can only specify a date and time that falls within your
history window
.
Schema only
: Replicates only the database schema (tables, views, roles, etc.) from the parent branch, without copying any of the actual data. This is useful for testing migrations or building new test data without exposing sensitive real-world data. See
Schema-only branches
.
Anonymized data
: Creates a branch with masked sensitive data. You can configure data anonymization rules to protect personally identifiable information while preserving realistic data sets for development. See
Data anonymization
.
Configure auto-deletion: By default,
Automatically delete branch after
is checked with 1 day selected to help prevent unused branches from accumulating. You can choose 1 hour, 1 day, or 7 days, or uncheck to disable expiration entirely. This is useful for CI/CD pipelines and short-lived development environments. Note: This default only applies when creating branches through the Console; API and CLI branches have no expiration by default. Refer to our
Branch expiration guide
for details.
Click
Create
to create your branch.
You are presented with the connection details for your new branch and directed to the
Branch
overview page where you are shown the details for your new branch.
Postgres role passwords on branches
When creating a new branch, the branch will have the same Postgres roles and passwords as the parent branch. If you want your branch created with new role passwords, you can enable
branch protection
.
View branches
Console
CLI
API
To view the branches in a Neon project:
In the Neon Console, select a project.
Select
Branches
under
Project
to view all current branches in the project.
Branch details in this table view include:
Branch
: The branch name, which is a generated name if no name was specified when created.
Parent
: Indicates the parent from which this branch was created, helping you track your branch hierarchy.
Compute hours
: Number of hours the branch's compute was active so far in the current billing period.
Primary compute
: Shows the current compute size and status for the branch's compute.
Data size
: Indicates the logical data size of the branch, helping you monitor your plan's storage limit. Data size does not include history.
Created by
: The account or integration that created the branch.
Last active
: Shows when the branch's compute was last active.
Select a branch from the table to view details about the branch.
Branch details shown on the branch page may include:
Archive status
: This only appears if the branch was archived. For more, see
Branch archiving
.
ID
: The branch ID. Branch IDs have a
br-
prefix.
Created on
: The date and time the branch was created.
Compute hours
: The compute hours used by the default branch in the current billing period.
Data size
: The logical data size of the branch. Data size does not include history.
Parent branch
: The branch from which this branch was created (only applicable to child branches).
The branch details page also includes details about the
Computes
,
Roles
,
Databases
, and
Child branches
that belong to the branch. All of these objects are associated with a particular branch. For information about these objects, see:
Manage computes
.
Manage roles
Manage databases
View branches
Branch archiving
On the Free plan, Neon automatically archives inactive branches to cost-efficient archive storage after a defined threshold. For more, see
Branch archiving
.
note
For branches with predictable lifespans, you can set an expiration date when creating branches to automatically delete them at a specified time. This offers an alternative to archiving for temporary development and testing environments, ensuring cleanup happens exactly when needed.
Rename a branch
Neon permits renaming a branch, including your project's default branch.
Console
CLI
API
To rename a branch:
In the Neon Console, select a project.
Select
Branches
under
Project
to view the branches for the project.
Select a branch from the table.
On the branch overview page, click the
More
drop-down menu and select
Rename
.
Specify a new name for the branch and click
Save
.
Set a branch as default
Each Neon project is created with a default branch (named
main
if the project was created with the CLI or API, or
production
if created in the Console), but you can designate any branch as your project's default branch. When creating a new branch without specifying the parent, a new branch is created from your project's default branch. Default branch is automatically selected in the UI when creating the new branch, and it's used in the
create branch API call
. The
Neon-Managed Vercel integration
also creates preview deployment branches from your project's default branch.
For more information, see
Default branch
.
Console
CLI
API
To set a branch as the default branch:
In the Neon Console, select a project.
Select
Branches
under
Project
to view the branches for the project.
Select a branch from the table.
On the branch overview page, click the
More
drop-down menu and select
Set as default
.
In the
Set as default
confirmation dialog, click
Set as default
to confirm your selection.
Set a branch as protected
This feature is available on all Neon's paid plans, which supports up to five protected branches.
Console
CLI
API
To set a branch as protected:
In the Neon Console, select a project.
Select
Branches
under
Project
to view the branches for the project.
Select a branch from the table.
On the branch overview page, click the
More
drop-down menu and select
Set as protected
.
In the
Set as protected
confirmation dialog, click
Set as protected
to confirm your selection.
For details and configuration instructions, refer to our
Protected branches guide
.
Set a branch expiration
To set or update a branch's expiration (auto-deletion TTL):
Console
CLI
API
In the Neon Console, select a project.
Select
Branches
under
Project
to view the branches for the project.
Select a branch from the table.
On the branch overview page, click the
Actions
drop-down menu and select
Edit expiration
.
Set a new expiration date and time, or toggle off "Automatically delete branch after" to remove expiration.
Click
Save
.
For details and configuration instructions, refer to our
Branch expiration guide
.
Connect to a branch
You connect to a branch through a compute associated with it, using a Postgres connection string that carries your role, the compute hostname (it starts with
ep-
), and the database name. Get the string from the Console, CLI, or API, then connect with any Postgres client. To run queries without a client, use the
Neon SQL Editor
.
Console
CLI
API
On the
Project Dashboard
, click
Connect
, then select the branch, database, and role. Copy the connection string.
Then connect with any client, for example
psql
:
psql
postgresql://[user]:[password]@[neon_hostname]/[dbname]
For application connection examples, see
Frameworks
and
Languages
.
Reset a branch from parent
You can use Neon's
Reset from parent
feature to instantly update a branch with the latest schema and data from its parent. This feature can be an integral part of your CI/CD automation.
You can use the Neon Console, CLI, or API. For details, see
Reset from parent
.
Restore a branch to its own or another branch's history
There are several restore operations available using Neon's instant restore feature:
Restore a branch to its own history
Restore a branch to the head of another branch
Restore a branch to the history of another branch
You can use the Neon Console, CLI, or API. For more details, see
Instant restore
.
Delete a branch
Deleting a branch is a permanent action. Deleting a branch also deletes the databases and roles that belong to the branch as well as the compute associated with the branch. You cannot delete a branch that has child branches. The child branches must be deleted first.
Console
CLI
API
To delete a branch:
In the Neon Console, select a project.
Select
Branches
under
Project
.
Select a branch from the table.
On the branch overview page, click the
More
drop-down menu and select
Delete
.
On the confirmation dialog, click
Delete
.
tip
For temporary branches, consider setting an expiration date when creating them to automate cleanup and reduce manual deletion overhead.
Check the data size
You can check the logical data size for the databases on a branch by viewing the
Data size
value on the
Branches
page or page in the Neon Console. Alternatively, you can run the following query on your branch from the
Neon SQL Editor
or any SQL client connected to your database:
SELECT
pg_size_pretty(
sum
(pg_database_size(datname)))
FROM
pg_database;
The query value may differ slightly from the
Data size
reported in the Neon Console.
Data size is your logical data size.
Storage is unlimited on paid plans
Storage is unlimited on paid plans (Launch and Scale): there's no hard per-branch size limit, and your branch storage grows with your usage.
The Free plan is limited to 0.5 GB per project.
Branch types
Neon has different branch types with different characteristics.
Root branch
A root branch is a branch without a parent branch. Each Neon project starts with a root branch (named
production
in the Console,
main
via API/CLI), which cannot be deleted and is set as the
default branch
for the project.
Neon also supports two other types of root branches that have no parent but
can
be deleted:
Backup branches
, created by instant restore operations on other root branches.
Schema-only branches
.
The number of root branches allowed in a project depends on your Neon plan.
Plan
Root branch allowance per project
Free
3
Launch
5
Scale
25
Default branch
Each Neon project has a default branch. In the Neon Console, your default branch is identified by a
DEFAULT
tag. You can designate any branch as the default branch for your project.
When creating a new branch without specifying the parent, a new branch is created from your project's default branch. The
Neon-Managed Vercel integration
also creates preview deployment branches from your project's default branch.
Non-default branch
Any branch not designated as the default branch is considered a non-default branch. You can rename or delete non-default branches.
Protected branch
Neon's protected branches feature implements a series of protections:
Protected branches cannot be deleted.
Protected branches cannot be
reset
.
Projects with protected branches cannot be deleted.
Computes associated with a protected branch cannot be deleted.
New passwords are automatically generated for Postgres roles on branches created from protected branches.
Learn more
.
With additional configuration steps, you can apply IP Allow restrictions to protected branches only. See
How to apply IP restrictions to protected branches
.
Protected branches are not
archived
due to inactivity.
Typically, a protected status is given to a branch or branches that hold production data or sensitive data. The protected branch feature is only supported on Neon's paid plans. See
Set a branch as protected
.
Schema-only branch
A branch that replicates only the database schema from a source branch, without copying any of the actual data. This feature is particularly valuable when working with sensitive information. Rather than creating branches that include confidential data, you can duplicate just the database structure and then populate it with your own data.
Schema-only branches are
root branches
, meaning they have no parent. As a root branch, each schema-only branch starts an independent line of data in a Neon project.
See
Schema-only branches
.
Backup branch
A branch created by an
instant restore
operation. When you restore a branch from a particular point in time, the current branch is saved as a backup branch. Performing a restore operation on a root branch, creates a backup branch without a parent branch (a root branch). See
Instant restore
.
Branch with expiration
A branch with an expiration timestamp is automatically deleted when the expiration time is reached. Any branch can have an expiration timestamp added or removed at any time. Use it for temporary development and testing environments.
Branching with the Neon CLI
The Neon CLI supports creating and managing branches. See
Neon CLI commands — branches
.
Branching with the Neon API
Branch actions performed in the Neon Console can also be performed using the
Neon API
. Each operation above includes an example in its
API
tab; see the
Neon API Reference
for complete request and response schemas. A request requires an API key: see
Create an API key
, where
$NEON_API_KEY
stands in for your key.
Create a branch with the API
See
Create a branch
for the Console, CLI, and API options.
List branches with the API
See
View branches
for the Console, CLI, and API options.
Delete a branch with the API
See
Delete a branch
for the Console, CLI, and API options.
Need help?
Join our
Discord Server
to ask questions or see what others are doing with Neon. For paid plan support options, see
Support
.
Was this page helpful?
Yes
No
Thank you for your feedback!
Edit on GitHub
Previous
Multitenancy
Next
Computes
On this page
Branch naming requirements
Create a branch
View branches
Branch archiving
Rename a branch
Set a branch as default
Set a branch as protected
Set a branch expiration
Connect to a branch
Reset a branch from parent
Restore a branch to its own or another branch's history
Delete a branch
Check the data size
Branch types
Branching with the Neon CLI
Branching with the Neon API
Need help?
Set up Neon with AI
Copy neon init command
Neon Docs
Neon
Neon is part of the Databricks Platform
Neon status loading...
© Neon 2026. All rights reserved. Apache, Apache Spark, Spark, the Spark Logo, Apache Iceberg, Iceberg, and the Apache Iceberg logo are trademarks of the
Apache Software Foundation
.
Privacy Notice
Terms of Use
Neon Platform Terms
Modern Slavery Statement
California Privacy
Company
About
Blog
Careers
Contact Sales
Security
Resources
Docs
Changelog
Support
Community Guides
FAQs
PostgreSQL Tutorial
Startups
Community
Discord
GitHub
X.com
LinkedIn
YouTube
Compliance
CCPA
Compliant
GDPR
Compliant
ISO 27001
Certified
ISO 27701
Certified
SOC 2
Certified
HIPAA
Compliant
Compliance Guide
Neon’s Sub Contractors
Trust Center
