The branches command lists, creates, renames, deletes, and retrieves details about branches in your Neon project. It also sets the default branch, adds a compute or read replica to a branch, restores a branch to an earlier point in time, and runs a schema diff between branches. For information about branches in Neon, see Manage branches. If --project-id is omitted, the CLI resolves it from your context file, auto-selects when your account has only one project, and prompts otherwise.
Switch the active branch
To pin a branch in your local .neon context file so subsequent commands target it, use neon checkout.
Subcommands: add-compute, create, delete, get, list, rename, reset, restore, schema-diff, set-default, set-expiration
neon branches list
Lists branches in a Neon project.
neon branches list [options]List branches with the default table output format:
neon branches list --project-id solitary-leaf-288182┌────────────────────────┬──────────────────────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Created At │ Updated At │
├────────────────────────┼──────────────────────────┼──────────────────────┼──────────────────────┤
│ br-small-meadow-878874 │ production [default] │ 2023-07-06T13:15:12Z │ 2023-07-06T14:26:32Z │
├────────────────────────┼──────────────────────────┼──────────────────────┼──────────────────────┤
│ br-round-queen-335380 │ development [current] │ 2023-07-06T14:45:50Z │ 2023-07-06T14:45:50Z │
└────────────────────────┴──────────────────────────┴──────────────────────┴──────────────────────┘Branch names include text labels that indicate status: [default] marks the project's default branch, [protected] marks a protected branch, and [current] marks the branch pinned in your local .neon context file.
List branches with --output json, which returns more information than the table format:
neon branches list --project-id solitary-leaf-288182 --output jsonShow output
[
{
"id": "br-wild-boat-648259",
"project_id": "solitary-leaf-288182",
"name": "production",
"current_state": "ready",
"logical_size": 29515776,
"creation_source": "console",
"default": true,
"cpu_used_sec": 78,
"compute_time_seconds": 78,
"active_time_seconds": 312,
"written_data_bytes": 107816,
"data_transfer_bytes": 0,
"created_at": "2023-07-09T17:01:34Z",
"updated_at": "2023-07-09T17:15:13Z"
},
{
"id": "br-shy-cake-201321",
"project_id": "solitary-leaf-288182",
"parent_id": "br-wild-boat-648259",
"parent_lsn": "0/1E88838",
"name": "development",
"current_state": "ready",
"creation_source": "console",
"default": false,
"cpu_used_sec": 0,
"compute_time_seconds": 0,
"active_time_seconds": 0,
"written_data_bytes": 0,
"data_transfer_bytes": 0,
"created_at": "2023-07-09T17:37:10Z",
"updated_at": "2023-07-09T17:37:10Z"
}
]neon branches create
Creates a branch in a Neon project.
neon branches create [options]The --name value must be unique within the project and can be up to 256 characters; see Branch naming requirements. A read_only compute is a read replica.
note
When creating a branch from a protected parent branch, role passwords on the child branch are changed. For more information about this Protected Branches feature, see New passwords generated for Postgres roles on child branches.
neon branches create┌─────────────────────────┬─────────────────────────┬─────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Default │ Created At │ Updated At │
├─────────────────────────┼─────────────────────────┼─────────┼──────────────────────┼──────────────────────┤
│ br-mute-sunset-67218628 │ br-mute-sunset-67218628 │ false │ 2023-08-03T20:07:27Z │ 2023-08-03T20:07:27Z │
└─────────────────────────┴─────────────────────────┴─────────┴──────────────────────┴──────────────────────┘
endpoints
┌───────────────────────────┬──────────────────────┐
│ Id │ Created At │
├───────────────────────────┼──────────────────────┤
│ ep-floral-violet-94096438 │ 2023-08-03T20:07:27Z │
└───────────────────────────┴──────────────────────┘
connection_uris
┌──────────────────────────────────────────────────────────────────────────────────────────┐
│ Connection Uri │
├──────────────────────────────────────────────────────────────────────────────────────────┤
│ postgresql://[user]:[password]@[neon_hostname]/[dbname] │
└──────────────────────────────────────────────────────────────────────────────────────────┘note
If the parent branch has more than one role or database, the branches create command does not output a connection URI. As an alternative, you can use the connection-string command to retrieve the connection URI for a branch. This command includes options for specifying the role and database. See the connection-string command.
Create a branch with --output json, which returns the full branch response data:
neon branches create --output jsonShow output
{
"branch": {
"id": "br-frosty-art-30264288",
"project_id": "polished-shape-60485499",
"parent_id": "br-polished-fire-02083731",
"parent_lsn": "0/1E887C8",
"name": "br-frosty-art-30264288",
"current_state": "init",
"pending_state": "ready",
"creation_source": "neon",
"default": false,
"cpu_used_sec": 0,
"compute_time_seconds": 0,
"active_time_seconds": 0,
"written_data_bytes": 0,
"data_transfer_bytes": 0,
"created_at": "2023-08-03T20:12:24Z",
"updated_at": "2023-08-03T20:12:24Z"
},
"endpoints": [
{
"host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
"id": "ep-cool-darkness-123456",
"project_id": "polished-shape-60485499",
"branch_id": "br-frosty-art-30264288",
"autoscaling_limit_min_cu": 1,
"autoscaling_limit_max_cu": 1,
"region_id": "aws-us-east-2",
"type": "read_write",
"current_state": "init",
"pending_state": "active",
"settings": {},
"pooler_enabled": false,
"pooler_mode": "transaction",
"disabled": false,
"passwordless_access": true,
"creation_source": "neon",
"created_at": "2023-08-03T20:12:24Z",
"updated_at": "2023-08-03T20:12:24Z",
"proxy_host": "us-east-2.aws.neon.tech",
"suspend_timeout_seconds": 0,
"provisioner": "k8s-pod"
}
],
"connection_uris": [
{
"connection_uri": "postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require",
"connection_parameters": {
"database": "dbname",
"password": "AbC123dEf",
"role": "alex",
"host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
"pooler_host": "ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech"
}
}
]
}Create a branch with a user-defined name:
neon branches create --name feature/user-authSet the compute size when creating a branch:
neon branches create --name mybranch --cu 2Set the compute's autoscaling range when creating a branch:
neon branches create --name mybranch --cu 0.5-3Create a branch with a read replica compute:
neon branches create --name my_read_replica_branch --type read_onlyCreate a branch from a parent branch other than your main branch:
neon branches create --name feature/payment-api --parent developmentCreate an instant restore branch by specifying the --parent option with a timestamp:
neon branches create --name data_recovery --parent 2023-07-11T10:00:00ZThe timestamp must be in RFC 3339 format (this timestamp converter can help). For more about instant restore, see Instant restore.
Create a branch and connect to it with psql immediately. Arguments after -- are passed through to psql, so you can run an .sql file or a query on creation:
neon branches create --psql
neon branches create --psql -- -f dump.sql
neon branches create --psql -- -c "SELECT version()"Create a schema-only branch:
neon branches create --schema-onlyCreate a protected branch:
neon branches create --name production --protectedneon branches reset
Resets a child branch to the latest data from its parent. The <id|name> is the branch ID or branch name; either works.
neon branches reset <id|name> [options]The --parent option is required; resetting from the parent branch is currently the only supported reset operation. To rewind a branch to an earlier point in time, see restore.
neon branches reset development --parent┌──────────────────────┬─────────────┬─────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Default │ Created At │ Last Reset At │
├──────────────────────┼─────────────┼─────────┼──────────────────────┼──────────────────────┤
│ br-aged-sun-a5qowy01 │ development │ false │ 2024-05-07T09:31:59Z │ 2024-05-07T09:36:32Z │
└──────────────────────┴─────────────┴─────────┴──────────────────────┴──────────────────────┘neon branches restore
Restores a branch to a specified point in time in its own or another branch's history. The <target-id|name> is the ID or name of the branch you want to restore, and <source> is the source branch you want to restore from. Source options are:
^self: restores the selected branch to an earlier point in its own history. You must specify a timestamp or LSN (restoring to head is not supported).^parent: restores the target branch to its parent. By default the target is restored to the latest (head) of its parent. Append@timestampor@lsnto restore to an earlier point in the parent's history.- A source branch ID or name: restores the target branch to the selected source branch. It restores the latest (head) by default. Append
@timestampor@lsnto restore to an earlier point in the source branch's history.
neon branches restore <target-id|name> <source>[@(timestamp|lsn)]The --preserve-under-name option is required when restoring to ^self.
Restore main to an earlier point in its own history, saving the previous state to a backup branch named main_restore_backup_2024-05-06:
neon branches restore main ^self@2024-05-06T10:00:00.000Z --preserve-under-name main_restore_backup_2024-05-06INFO: Restoring branch br-purple-dust-a5hok5mk to the branch br-purple-dust-a5hok5mk timestamp 2024-05-06T10:00:00.000Z
Restored branch
┌─────────────────────────┬──────┬──────────────────────┐
│ Id │ Name │ Last Reset At │
├─────────────────────────┼──────┼──────────────────────┤
│ br-purple-dust-a5hok5mk │ main │ 2024-05-07T09:45:21Z │
└─────────────────────────┴──────┴──────────────────────┘
Backup branch
┌─────────────────────────┬────────────────────────────────┐
│ Id │ Name │
├─────────────────────────┼────────────────────────────────┤
│ br-flat-forest-a5z016gm │ main_restore_backup_2024-05-06 │
└─────────────────────────┴────────────────────────────────┘Restore the target branch feature/user-auth to the head of the source branch main:
neon branches restore feature/user-auth mainINFO: Restoring branch br-restless-frost-69810125 to the branch br-curly-bar-82389180 head
Restored branch
┌────────────────────────────┬───────────────────┬──────────────────────┐
│ Id │ Name │ Last Reset At │
├────────────────────────────┼───────────────────┼──────────────────────┤
│ br-restless-frost-69810125 │ feature/user-auth │ 2024-02-21T15:42:34Z │
└────────────────────────────┴───────────────────┴──────────────────────┘Restore feature/user-auth to an earlier point in time from its parent branch:
neon branches restore feature/user-auth ^parent@2024-02-21T10:30:00.000ZINFO: Restoring branch br-restless-frost-69810125 to the branch br-patient-union-a5s838zf timestamp 2024-02-21T10:30:00.000Z
Restored branch
┌────────────────────────────┬───────────────────┬──────────────────────┐
│ Id │ Name │ Last Reset At │
├────────────────────────────┼───────────────────┼──────────────────────┤
│ br-restless-frost-69810125 │ feature/user-auth │ 2024-02-21T15:55:04Z │
└────────────────────────────┴───────────────────┴──────────────────────┘neon branches rename
Renames a branch.
neon branches rename <id|name> <new-name> [options]The new name follows the same rules as --name on branches create; see Branch naming requirements.
neon branches rename mybranch teambranch┌───────────────────────┬────────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Created At │ Updated At │
├───────────────────────┼────────────┼──────────────────────┼──────────────────────┤
│ br-rough-sound-590393 │ teambranch │ 2023-07-09T20:46:58Z │ 2023-07-09T21:02:27Z │
└───────────────────────┴────────────┴──────────────────────┴──────────────────────┘neon branches schema-diff
Compares the latest schemas of any two branches, or compares against a specific point in a branch's own or another branch's history.
For a git-style shortcut that defaults to comparing a branch against its parent, see neon diff.
The [base-branch] is the branch to compare against. It's optional; if omitted, the command uses the branch from your set-context file, or the project's default branch if no context is configured.
The [compare-source] specifies the branch or state to compare against. Options are:
^self: compares the selected branch to an earlier point in its own history. You must specify a timestamp or LSN.^parent: compares the selected branch to the head of its parent branch. You can append@timestampor@lsnto compare to an earlier point in the parent's history.- A branch ID or name: compares the selected branch to the head of another specified branch. Append
@timestampor@lsnto compare to an earlier point in the specified branch's history.
neon branches schema-diff [base-branch] [compare-source[@(timestamp|lsn)]] [options]note
Use the --no-color or --color false global option to decolorize command output in CI/CD pipelines.
Compare the schema of the production branch to the head of the development branch:
neon branches schema-diff production developmentThe output indicates that in the table public.playing_with_neon, a new column description character varying(255) has been added in the development branch that is not present in the production branch.
--- Database: neondb (Branch: br-wandering-firefly-a50un462)
+++ Database: neondb (Branch: br-fancy-sky-a5cydw8p)
@@ -26,9 +26,10 @@
CREATE TABLE public.playing_with_neon (
id integer NOT NULL,
name text NOT NULL,
- value real
+ value real,
+ description character varying(255)
);Compare the schema of feature/user-auth to an earlier point in its own history at LSN 0/123456:
neon branches schema-diff feature/user-auth ^self@0/123456Compare the schema of feature/user-auth to the head of its parent branch:
neon branches schema-diff feature/user-auth ^parentCompare the schema of the production branch to the state of feature/payment-api at timestamp 2024-06-01T00:00:00.000Z:
neon branches schema-diff production feature/payment-api@2024-06-01T00:00:00.000Zneon branches set-default
Sets a branch as the default branch in your Neon project.
neon branches set-default <id|name> [options]neon branches set-default mybranch┌────────────────────┬──────────┬─────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Default │ Created At │ Updated At │
├────────────────────┼──────────┼─────────┼──────────────────────┼──────────────────────┤
│ br-odd-frog-703504 │ mybranch │ true │ 2023-07-11T12:22:12Z │ 2023-07-11T12:22:59Z │
└────────────────────┴──────────┴─────────┴──────────────────────┴──────────────────────┘neon branches set-expiration
Sets or updates the expiration date for a branch. When the expiration time is reached, the branch and its compute endpoints are permanently deleted.
neon branches set-expiration <id|name> [options]Set an expiration date for a branch:
neon branches set-expiration mybranch --expires-at 2025-08-15T18:00:00ZRemove expiration from a branch (omit the parameter):
neon branches set-expiration mybranchneon branches add-compute
Adds a compute to an existing branch in your Neon project.
neon branches add-compute <id|name> [options]A read_only compute is a read replica. A branch can have a single primary read-write compute and multiple read replica computes.
Add a read replica compute to a branch:
neon branches add-compute mybranch --type read_only┌─────────────────────┬──────────────────────────────────────────────────┐
│ Id │ Host │
├─────────────────────┼──────────────────────────────────────────────────┤
│ ep-rough-lab-865061 │ ep-rough-lab-865061.ap-southeast-1.aws.neon.tech │
└─────────────────────┴──────────────────────────────────────────────────┘Set the compute size when adding a compute to a branch:
neon branches add-compute main --cu 2Set the compute's autoscaling range when adding a compute to a branch:
neon branches add-compute main --cu 0.5-3neon branches delete
Deletes a branch in a Neon project.
neon branches delete <id|name> [options]neon branches delete br-rough-sky-158193┌─────────────────────┬─────────────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Created At │ Updated At │
├─────────────────────┼─────────────────┼──────────────────────┼──────────────────────┤
│ br-rough-sky-158193 │ my_child_branch │ 2023-07-09T20:57:39Z │ 2023-07-09T21:06:41Z │
└─────────────────────┴─────────────────┴──────────────────────┴──────────────────────┘neon branches get
Retrieves details about a branch.
neon branches get <id|name> [options]Get a branch with the default table output format:
neon branches get production┌────────────────────────┬────────────┬──────────────────────┬──────────────────────┐
│ Id │ Name │ Created At │ Updated At │
├────────────────────────┼────────────┼──────────────────────┼──────────────────────┤
│ br-small-meadow-878874 │ production │ 2023-07-06T13:15:12Z │ 2023-07-06T13:32:37Z │
└────────────────────────┴────────────┴──────────────────────┴──────────────────────┘Get a branch with the --output format option set to json:
neon branches get production --output jsonShow output
{
"id": "br-lingering-bread-896475",
"project_id": "noisy-rain-039137",
"name": "production",
"current_state": "ready",
"logical_size": 29769728,
"creation_source": "console",
"default": false,
"cpu_used_sec": 522,
"compute_time_seconds": 522,
"active_time_seconds": 2088,
"written_data_bytes": 174433,
"data_transfer_bytes": 20715,
"created_at": "2023-06-28T10:17:28Z",
"updated_at": "2023-07-11T12:22:59Z"
}