🇦🇺 Hello Australia! Sydney region is officially live on Neon.Sign Up

Branching with the Neon CLI

Learn how to create and delete branches with the Neon CLI

The examples in this guide demonstrate creating, viewing, and deleting branches using the Neon CLI. For other branch-related CLI commands, refer to Neon CLI commands — branches. This guide also describes how to use the --api-key option to authenticate CLI branching commands from the command line.

The examples show the default table output format. The Neon CLI also supports json and yaml output formats. For example, if you prefer output in json, add --output json to your Neon CLI command.

Prerequisites

Create a branch with the CLI

The following Neon CLI command creates a branch. If your Neon account has more than one project, you will be required to specify a project ID using the --project-id option. To view the CLI documentation for this command, refer to the Neon CLI reference. The command response includes the branch ID, the compute endpoint ID, and and the connection URI for connecting to the branch.

tip

You can use the --name option with a neonctl branches create command to specify your own branch name instead of using the name generated by Neon. For example: neonctl branches create --name mybranch. Also, for any Neon CLI command, you can specify --output json to change the command output from the default table format to JSON format.

neonctl branches create

branch
┌───────────────────────┬───────────────────────┬─────────┬──────────────────────┬──────────────────────┐
 Id                    │ Name                  │ Primary │ Created At           │ Updated At           │
├───────────────────────┼───────────────────────┼─────────┼──────────────────────┼──────────────────────┤
 br-lucky-mud-08878834 │ br-lucky-mud-08878834 │ false2023-07-24T20:22:42Z │ 2023-07-24T20:22:42Z │
└───────────────────────┴───────────────────────┴─────────┴──────────────────────┴──────────────────────┘
endpoints
┌────────────────────────┬──────────────────────┐
 Id                     │ Created At           │
├────────────────────────┼──────────────────────┤
 ep-mute-voice-52609794 │ 2023-07-24T20:22:42Z │
└────────────────────────┴──────────────────────┘
connection_uris
┌───────────────────────────────────────────────────────────────────────────────────────┐
 Connection Uri                                                                        │
├───────────────────────────────────────────────────────────────────────────────────────┤
 postgres://[user]:[password]@[neon_hostname]/[dbname]                                 │
└───────────────────────────────────────────────────────────────────────────────────────┘

tip

The Neon CLI provides a neonctl connection-string command you can use to extract a connection uri programmatically. See Neon CLI commands — connection-string.

List branches with the CLI

The following Neon CLI command lists branches in your Neon project. If your Neon account has more than one project, you will be required to specify a project ID using the --project-id option. To view the CLI documentation for this method, refer to the Neon CLI reference.

neonctl branches list
┌────────────────────────────┬───────────────────────┬─────────┬──────────────────────┬──────────────────────┐
 Id                         │ Name                  │ Primary │ Created At           │ Updated At           │
├────────────────────────────┼───────────────────────┼─────────┼──────────────────────┼──────────────────────┤
 br-lucky-mud-08878834      │ br-lucky-mud-08878834 │ false2023-07-24T20:22:42Z │ 2023-07-24T20:38:34Z │
├────────────────────────────┼───────────────────────┼─────────┼──────────────────────┼──────────────────────┤
 br-wandering-king-30669552 │ main                  │ true2023-07-24T15:31:03Z │ 2023-07-24T16:13:48Z │
└────────────────────────────┴───────────────────────┴─────────┴──────────────────────┴──────────────────────┘

Delete a branch with the CLI

The following Neon CLI command deletes the specified branch. If your Neon account has more than one project, you will be required to specify a project ID using the --project-id option. To view the CLI documentation for this command, refer to the Neon CLI reference. You can delete a branch by its ID or name.

neonctl branches delete br-rough-sky-158193
┌───────────────────────┬───────────────────────┬─────────┬──────────────────────┬──────────────────────┐
 Id                    │ Name                  │ Primary │ Created At           │ Updated At           │
├───────────────────────┼───────────────────────┼─────────┼──────────────────────┼──────────────────────┤
 br-lucky-mud-08878834 │ br-lucky-mud-08878834 │ false2023-07-24T20:22:42Z │ 2023-07-24T20:44:51Z │
└───────────────────────┴───────────────────────┴─────────┴──────────────────────┴──────────────────────┘

Branching automation with the Neon CLI

The Neon CLI enables easy automation of branching operations for integration into your workflows or toolchains. To facilitate authentication to Neon when running a CLI command, the Neon CLI allows you to use an API key. For information about obtaining an API key, see Create an API key.

To use an API key, you can store it in an environment variable on your system. This prevents the key from being hardcoded into your automation scripts or exposed in another way. For example, you can add the following line to your shell's profile file (.bashrc or .bash_profile for bash shell):

export NEON_API_KEY=<neon_api_key>

After exporting your key, source the profile file (source ~/.bashrc or source ~/.bash_profile), or start a new terminal session.

You do not need to specify the variable name explicitly when using a Neon CLI command. A Neon CLI command looks for a NEON_API_KEY variable setting by default.

This API key configuration ensures that the API key is kept secure while still providing a way to authenticate your CLI commands. Remember, you should handle your API key with the same level of security as your other credentials.

Need help?

Join our Discord Server to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more detail, see Getting Support.

Last updated on

Edit this page
Was this page helpful?