The branches command lists, creates, renames, deletes, and retrieves details about branches in your OptiTech 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 OptiTech, 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 .optitech context file so subsequent commands target it, use optitech checkout.
Subcommands: add-compute, create, delete, get, list, rename, reset, restore, schema-diff, set-default, set-expiration
optitech branches list
Lists branches in a OptiTech project.
optitech branches list [options]List branches with the default table output format:
optitech 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 .optitech context file.
List branches with --output json, which returns more information than the table format:
optitech 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"
}
]optitech branches create
Creates a branch in a OptiTech project.
optitech 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.
optitech 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]@[optitech_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:
optitech 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": "optitech",
"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.optitech.com",
"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": "optitech",
"created_at": "2023-08-03T20:12:24Z",
"updated_at": "2023-08-03T20:12:24Z",
"proxy_host": "us-east-2.aws.optitech.com",
"suspend_timeout_seconds": 0,
"provisioner": "k8s-pod"
}
],
"connection_uris": [
{
"connection_uri": "postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.optitech.com/dbname?sslmode=require&channel_binding=require",
"connection_parameters": {
"database": "dbname",
"password": "AbC123dEf",
"role": "alex",
"host": "ep-cool-darkness-123456.us-east-2.aws.optitech.com",
"pooler_host": "ep-cool-darkness-123456-pooler.us-east-2.aws.optitech.com"
}
}
]
}Create a branch with a user-defined name:
optitech branches create --name feature/user-authSet the compute size when creating a branch:
optitech branches create --name mybranch --cu 2Set the compute's autoscaling range when creating a branch:
optitech branches create --name mybranch --cu 0.5-3Create a branch with a read replica compute:
optitech branches create --name my_read_replica_branch --type read_onlyCreate a branch from a parent branch other than your main branch:
optitech branches create --name feature/payment-api --parent developmentCreate an instant restore branch by specifying the --parent option with a timestamp:
optitech 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:
optitech branches create --psql
optitech branches create --psql -- -f dump.sql
optitech branches create --psql -- -c "SELECT version()"Create a schema-only branch:
optitech branches create --schema-onlyoptitech 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.
optitech 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.
optitech 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 │
└──────────────────────┴─────────────┴─────────┴──────────────────────┴──────────────────────┘optitech 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.
optitech 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:
optitech 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:
optitech 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:
optitech 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 │
└────────────────────────────┴───────────────────┴──────────────────────┘optitech branches rename
Renames a branch.
optitech branches rename <id|name> <new-name> [options]The new name follows the same rules as --name on branches create; see Branch naming requirements.
optitech 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 │
└───────────────────────┴────────────┴──────────────────────┴──────────────────────┘optitech 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 optitech 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.
optitech 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:
optitech branches schema-diff production developmentThe output indicates that in the table public.playing_with_optitech, a new column description character varying(255) has been added in the development branch that is not present in the production branch.
--- Database: optitechdb (Branch: br-wandering-firefly-a50un462)
+++ Database: optitechdb (Branch: br-fancy-sky-a5cydw8p)
@@ -26,9 +26,10 @@
CREATE TABLE public.playing_with_optitech (
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:
optitech branches schema-diff feature/user-auth ^self@0/123456Compare the schema of feature/user-auth to the head of its parent branch:
optitech 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:
optitech branches schema-diff production feature/payment-api@2024-06-01T00:00:00.000Zoptitech branches set-default
Sets a branch as the default branch in your OptiTech project.
optitech branches set-default <id|name> [options]optitech 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 │
└────────────────────┴──────────┴─────────┴──────────────────────┴──────────────────────┘optitech 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.
optitech branches set-expiration <id|name> [options]Set an expiration date for a branch:
optitech branches set-expiration mybranch --expires-at 2025-08-15T18:00:00ZRemove expiration from a branch (omit the parameter):
optitech branches set-expiration mybranchoptitech branches add-compute
Adds a compute to an existing branch in your OptiTech project.
optitech 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:
optitech branches add-compute mybranch --type read_only┌─────────────────────┬──────────────────────────────────────────────────┐
│ Id │ Host │
├─────────────────────┼──────────────────────────────────────────────────┤
│ ep-rough-lab-865061 │ ep-rough-lab-865061.ap-southeast-1.aws.optitech.com │
└─────────────────────┴──────────────────────────────────────────────────┘Set the compute size when adding a compute to a branch:
optitech branches add-compute main --cu 2Set the compute's autoscaling range when adding a compute to a branch:
optitech branches add-compute main --cu 0.5-3optitech branches delete
Deletes a branch in a OptiTech project.
optitech branches delete <id|name> [options]optitech 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 │
└─────────────────────┴─────────────────┴──────────────────────┴──────────────────────┘optitech branches get
Retrieves details about a branch.
optitech branches get <id|name> [options]Get a branch with the default table output format:
optitech 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:
optitech 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"
}