# 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](/guides/postgres-introduction-read-replicas) to a branch, restores a branch to an earlier point in time, and runs a [schema diff](/guides/resilience-architecture-guides-schema-diff) between branches. For information about branches in Neon, see [Manage branches](/guides/manage-operate-manage-branches). If `--project-id` is omitted, the CLI resolves it from your [context file](/guides/apis-sdks-cli-link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`. #### Switch the active branch To pin a branch in your local `.neon` context file so subsequent commands target it, use [`neon checkout`](/guides/apis-sdks-cli-checkout). Subcommands: [add-compute](#neon-branches-add-compute), [create](#neon-branches-create), [delete](#neon-branches-delete), [get](#neon-branches-get), [list](#neon-branches-list), [rename](#neon-branches-rename), [reset](#neon-branches-reset), [restore](#neon-branches-restore), [schema-diff](#neon-branches-schema-diff), [set-default](#neon-branches-set-default), [set-expiration](#neon-branches-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 ``` :::accordion{title="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](/guides/manage-operate-manage-branches#branch-naming-requirements). A `read_only` compute is a [read replica](/guides/postgres-introduction-read-replicas). #### 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](/guides/resilience-architecture-guides-protected-branches#new-passwords-generated-for-postgres-roles-on-child-branches). ```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] │ └──────────────────────────────────────────────────────────────────────────────────────────┘ ``` #### 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](/guides/apis-sdks-cli-connection-string). 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 ``` :::accordion{title="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](https://it-tools.tech/date-converter) can help). For more about instant restore, see [Instant restore](/guides/postgres-backup-restore-branch-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](/guides/resilience-architecture-guides-protected-branches): ```bash neon branches create --name production --protected ``` ## neon branches reset Resets a child branch to the latest data from its parent. The `` is the branch ID or branch name; either works. ```bash neon branches reset [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](#neon-branches-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 `` is the ID or name of the branch you want to restore, and `` 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 [@(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 [options] ``` | Option | Description | Type | Default | Required | | -------------- | ----------- | ------ | ------- | -------- | | `--project-id` | Project ID | string | — | No | The new name follows the same rules as `--name` on [branches create](#neon-branches-create); see [Branch naming requirements](/guides/manage-operate-manage-branches#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`](/guides/apis-sdks-cli-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 | #### note Use the `--no-color` or `--color false` [global option](/guides/apis-sdks-cli#global-options) to decolorize command output in CI/CD pipelines. 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 [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 [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 [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](/guides/postgres-introduction-read-replicas). 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 [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 [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 ``` :::accordion{title="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" } ``` ::: ## Related pages - [Neon CLI command: snapshots](./apis-sdks-cli-snapshots.md) - [Neon CLI command: diff](./apis-sdks-cli-diff.md) - [Neon CLI command: projects](./apis-sdks-cli-projects.md) - [Neon CLI command: databases](./apis-sdks-cli-databases.md) - [Neon CLI command: roles](./apis-sdks-cli-roles.md) - [Neon CLI command: operations](./apis-sdks-cli-operations.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.