Neon CLI command: branches

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 ...

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 otherwise asks you to pass --project-id.

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.

Bash

neon branches list [options]

Option	Description	Type	Default	Required
`--project-id`	Project ID	string	—	No

List branches with the default table output format:

Bash

neon branches list --project-id solitary-leaf-288182

title="Output"

┌────────────────────────┬──────────────────────────┬──────────────────────┬──────────────────────┐
│ 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, [anon] marks an anonymized 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:

Bash

neon branches list --project-id solitary-leaf-288182 --output json

Show output

JSON

[
  {
    "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.

Bash

neon branches create [options]

Option	Description	Type	Default	Required
`--compute`	Create a branch with or without a compute. By default branch is created with a read-write compute. To create a branch without compute use --no-compute	boolean	`true`	No
`--cu`	The number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").	string	project default	No
`--expires-at`	Set an expiration date for the branch. Accepts a date string (e.g., 2024-12-31T23:59:59Z).	string	never expires	No
`--name`	The branch name	string	branch id	No
`--parent`	Parent branch name or id or timestamp or LSN. Defaults to the default branch	string	—	No
`--protected`	Whether the branch is protected. Protected branches (and their computes) cannot be deleted, archived, or reset, and block deletion of the project. Can be gated by `protected_branches_only` in the IP allowlist. Paid plans only.	boolean	—	No
`--psql`	Connect to a new branch via psql	boolean	`false`	No
`--schema-only`	Create a schema-only branch. Requires exactly one read-write compute.	boolean	`false`	No
`--secrets`	Include connection credentials in command output. Use --no-secrets to omit them	boolean	`true`	No
`--suspend-timeout`	Duration of inactivity in seconds after which the compute endpoint is automatically suspended. The value `0` means use the global default. The value `-1` means never suspend. The default value is `300` seconds (5 minutes). The maximum value is `604800` seconds (1 week).	number	`0`	No
`--type`	Type of compute to add	string	`read_write`	No
`--project-id`	Project ID	string	—	No

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.

Bash

neon branches create

title="Output"

┌─────────────────────────┬─────────────────────────┬─────────┬──────────────────────┬──────────────────────┐
│ 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]                                  │
└──────────────────────────────────────────────────────────────────────────────────────────┘

Omit the connection string from the output, keeping it out of terminal scrollback and CI logs:

Bash

neon branches create --no-secrets

Needs Neon CLI 4.9.0+; older versions ignore --no-secrets and still print the connection string.

Create a branch with --output json, which returns the full branch response data:

Bash

neon branches create --output json

Show output

JSON

{
  "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:

Bash

neon branches create --name feature/user-auth

Set the compute size when creating a branch:

Bash

neon branches create --name mybranch --cu 2

Set the compute's autoscaling range when creating a branch:

Bash

neon branches create --name mybranch --cu 0.5-3

Create a branch with a read replica compute:

Bash

neon branches create --name my_read_replica_branch --type read_only

Create a branch from a parent branch other than your main branch:

Bash

neon branches create --name feature/payment-api --parent development

Create an instant restore branch by specifying the --parent option with a timestamp:

Bash

neon branches create --name data_recovery --parent 2023-07-11T10:00:00Z

The 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:

Bash

neon branches create --psql
neon branches create --psql -- -f dump.sql
neon branches create --psql -- -c "SELECT version()"

Create a schema-only branch:

Bash

neon branches create --schema-only

Create a protected branch:

Bash

neon branches create --name production --protected

neon 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.

Bash

neon branches reset <id|name> [options]

Option	Description	Type	Default	Required
`--parent`	Reset to a parent branch	boolean	`false`	No
`--preserve-under-name`	Name under which to preserve the old branch		—	No
`--project-id`	Project ID	string	—	No

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.

Bash

neon branches reset development --parent

title="Output"

┌──────────────────────┬─────────────┬─────────┬──────────────────────┬──────────────────────┐
│ 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 @timestamp or @lsn to 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 @timestamp or @lsn to restore to an earlier point in the source branch's history.

Bash

neon branches restore <target-id|name> <source>[@(timestamp|lsn)]

Option	Description	Type	Default	Required
`--preserve-under-name`	Name under which to preserve the old branch		—	No
`--project-id`	Project ID	string	—	No

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:

Bash

neon branches restore main ^self@2024-05-06T10:00:00.000Z --preserve-under-name main_restore_backup_2024-05-06

title="Output"

INFO: 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:

Bash

neon branches restore feature/user-auth main

title="Output"

INFO: 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:

Bash

neon branches restore feature/user-auth ^parent@2024-02-21T10:30:00.000Z

title="Output"

INFO: 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.

Bash

neon branches rename <id|name> <new-name> [options]

Option	Description	Type	Default	Required
`--project-id`	Project ID	string	—	No

The new name follows the same rules as --name on branches create; see Branch naming requirements.

Bash

neon branches rename mybranch teambranch

title="Output"

┌───────────────────────┬────────────┬──────────────────────┬──────────────────────┐
│ 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 @timestamp or @lsn to 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 @timestamp or @lsn to compare to an earlier point in the specified branch's history.

Bash

neon branches schema-diff [base-branch] [compare-source[@(timestamp|lsn)]] [options]

Option	Description	Type	Default	Required
`--database`, `--db`	Name of the database for which the schema comparison is performed	string	—	No
`--project-id`	Project ID	string	—	No

Compare the schema of the production branch to the head of the development branch:

Bash

neon branches schema-diff production development

The 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.

title="Output"

--- 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:

Bash

neon branches schema-diff feature/user-auth ^self@0/123456

Compare the schema of feature/user-auth to the head of its parent branch:

Bash

neon branches schema-diff feature/user-auth ^parent

Compare the schema of the production branch to the state of feature/payment-api at timestamp 2024-06-01T00:00:00.000Z:

Bash

neon branches schema-diff production feature/payment-api@2024-06-01T00:00:00.000Z

neon branches set-default

Sets a branch as the default branch in your Neon project.

Bash

neon branches set-default <id|name> [options]

Option	Description	Type	Default	Required
`--project-id`	Project ID	string	—	No

Bash

neon branches set-default mybranch

title="Output"

┌────────────────────┬──────────┬─────────┬──────────────────────┬──────────────────────┐
│ 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.

Bash

neon branches set-expiration <id|name> [options]

Option	Description	Type	Default	Required
`--expires-at`	Set a expiration date for the branch. If omitted, expiration will be removed. Format [RFC3339]: 2024-12-31T23:59:59Z	string	—	No
`--project-id`	Project ID	string	—	No

Set an expiration date for a branch:

Bash

neon branches set-expiration mybranch --expires-at 2025-08-15T18:00:00Z

Remove expiration from a branch (omit the parameter):

Bash

neon branches set-expiration mybranch

neon branches add-compute

Adds a compute to an existing branch in your Neon project.

Bash

neon branches add-compute <id|name> [options]

Option	Description	Type	Default	Required
`--cu`	The number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").	string	—	No
`--name`	Optional name of the compute	string	—	No
`--type`	Type of compute to add	string	`read_only`	No
`--project-id`	Project ID	string	—	No

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:

Bash

neon branches add-compute mybranch --type read_only

title="Output"

┌─────────────────────┬──────────────────────────────────────────────────┐
│ 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:

Bash

neon branches add-compute main --cu 2

Set the compute's autoscaling range when adding a compute to a branch:

Bash

neon branches add-compute main --cu 0.5-3

neon branches delete

Deletes a branch in a Neon project.

Bash

neon branches delete <id|name> [options]

Option	Description	Type	Default	Required
`--project-id`	Project ID	string	—	No

Bash

neon branches delete br-rough-sky-158193

title="Output"

┌─────────────────────┬─────────────────┬──────────────────────┬──────────────────────┐
│ 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.

Bash

neon branches get <id|name> [options]

Option	Description	Type	Default	Required
`--project-id`	Project ID	string	—	No

Get a branch with the default table output format:

Bash

neon branches get production

title="Output"

┌────────────────────────┬────────────┬──────────────────────┬──────────────────────┐
│ 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:

Bash

neon branches get production --output json

Show output

JSON

{
  "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"
}