> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryardent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Branches

> Create isolated database branches and use their connection URLs

Branches are isolated Postgres databases created from a connected source. They are built for work that should feel production-like without touching the source database: migrations, test runs, data investigations, demos, and agent workflows.

## ardent branch create

Create a branch from the current connector. The new branch becomes your current branch.

```bash theme={null}
ardent branch create my-feature
```

<Accordion defaultOpen={false} title="Example output">
  ```text theme={null}
  ✓ Branch 'my-feature' created and checked out in 4.2s

  postgresql://user:***@my-feature-postgres.routing.tryardent.com:5432/db?sslmode=require&channel_binding=disable
  ```
</Accordion>

### Options

| Option                 | Description                                                                                                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-s, --service <type>` | Branch service type. The CLI default is `postgres`; this is separate from the connector type `postgresql`. Omit it unless Ardent support tells you to use another service type |
| `--print-url`          | Print only the branch connection URL. Best for scripts and CI                                                                                                                  |
| `--format json`        | Print a stable JSON object for automation                                                                                                                                      |

`--print-url` and `--format` are mutually exclusive.

### Use in scripts

```bash theme={null}
DATABASE_URL="$(ardent branch create pr-123 --print-url)"
export DATABASE_URL
```

If `--print-url` prints nothing, stop the script. A missing database URL is a failed setup, not a value to fall back from.

If branch creation times out, it may still be running server-side. For the same connector, service type, and branch name, re-running the same command continues checking the original request or returns its completed result; it does not start a second branch create. Changing the branch name or service type starts a different create request. You can also run `ardent branch list`; if the branch already appears there, use that branch instead of creating another name. The timeout error includes an operation ID for support:

<Accordion defaultOpen={false} title="Create timeout output">
  ```text theme={null}
  ✗ Branch creation did not complete within 10 minutes. It may still be running server-side — do NOT assume it failed. Re-run the same command to resume, or check `ardent branch list`. If you contact Ardent support, reference operation id <operation-id>.
  ```
</Accordion>

### JSON output

```bash theme={null}
ardent branch create pr-123 --format json
```

```json theme={null}
{
  "schema_version": 1,
  "id": "br_123",
  "name": "pr-123",
  "connector_id": "conn_123",
  "service_type": "postgres",
  "status": "active",
  "branch_url": "postgresql://user:***@pr-123-postgres.routing.tryardent.com:5432/db?sslmode=require&channel_binding=disable",
  "created_at": "2026-06-01T12:00:00Z",
  "last_branch_activity": null,
  "current": true,
  "warning": null
}
```

Clients should read the fields they need and ignore additional fields.

`service_type` is the Ardent branch service value (`postgres`). The connection URL still uses the standard PostgreSQL URI scheme, `postgresql://`.

## Connecting to a branch

Use the branch connection URL exactly as Ardent returns it, including `?sslmode=require&channel_binding=disable`.

```bash theme={null}
psql "$(ardent branch info --print-url)"
```

Branch connections go through Ardent's connection routing layer. Set your SQL client or IDE to SSL mode `require`, and do not load a custom root certificate or CA bundle. With no custom root certificate configured, `sslmode=require` encrypts the connection but does not validate a CA chain. If your client has fields named root certificate, CA bundle, SSL certificate authority, or `sslrootcert`, leave them blank and clear any source database certificate you previously configured.

Some PostgreSQL clients treat `sslmode=require` plus a configured root certificate as certificate verification. A source database CA bundle cannot verify an Ardent branch URL and can cause TLS errors such as a secure channel mismatch. Clearing the custom certificate keeps the connection in TLS-required mode.

Keep `channel_binding=disable` in the URL. Ardent terminates TLS at the routing layer, so clients that force channel binding can reject an otherwise valid branch connection. If your IDE has a channel binding setting, set it to `disable` or `off`.

## ardent branch list

List branches for the current connector:

```bash theme={null}
ardent branch list
```

In the terminal, the current branch is highlighted and prefixed with `*`. `●` means active; `○` means not active. Offline cache output is clearly labeled with `⚠ Offline - showing cached data from ...`.

<Accordion defaultOpen={false} title="Example output">
  <div className="font-mono text-[13px] leading-normal rounded-md border border-zinc-200 bg-zinc-50 p-4 dark:border-zinc-800 dark:bg-zinc-950">
    <div className="text-zinc-800 dark:text-zinc-200">Branches:</div>

    <div className="text-green-600 dark:text-green-400">
      <div>\* ● my-feature</div>

      <div>
        {"      "}postgresql://user:\*\*\*@my-feature-postgres.routing.tryardent.com:5432/db?sslmode=require\&channel\_binding=disable
      </div>
    </div>

    <div className="h-3" aria-hidden />

    <div>
      <div className="text-zinc-800 dark:text-zinc-200">{"  "}○ staging</div>

      <div className="text-zinc-500 dark:text-zinc-500">
        {"      "}postgresql://user:\*\*\*@staging-postgres.routing.tryardent.com:5432/db?sslmode=require\&channel\_binding=disable
      </div>
    </div>
  </div>
</Accordion>

## ardent branch info

Show details and the connection URL for a branch. If you omit the name, Ardent shows the current branch.

```bash theme={null}
ardent branch info my-feature
```

<Accordion defaultOpen={false} title="Example output">
  ```text theme={null}
  Branch: my-feature
  Type:   postgres
  Status: active
  Created: 2 minutes ago
  URL:    postgresql://user:***@my-feature-postgres.routing.tryardent.com:5432/db?sslmode=require&channel_binding=disable
  ```
</Accordion>

Use the same automation flags as `branch create`:

```bash theme={null}
ardent branch info --print-url
ardent branch info my-feature --format json
```

## ardent branch switch

Switch the current branch for future CLI commands:

```bash theme={null}
ardent branch switch staging
```

<Accordion defaultOpen={false} title="Example output">
  ```text theme={null}
  Switched from 'my-feature' to 'staging'
  postgresql://user:***@staging-postgres.routing.tryardent.com:5432/db?sslmode=require&channel_binding=disable
  ```
</Accordion>

Switching branches does not change your source database and does not modify application configuration by itself. Copy the new URL into your app or test environment when you want to use it.

## ardent branch delete

Delete a branch when you are done. The CLI queues the delete, polls the operation until it completes, then removes the branch from the local cache:

```bash theme={null}
ardent branch delete my-feature
```

<Accordion defaultOpen={false} title="Example output">
  ```text theme={null}
  ✓ Branch deleted
  ```
</Accordion>

If polling times out, the delete may still be running server-side. Do not recreate cleanup logic by scraping cache state. The timeout error includes the operation ID to give Ardent support:

<Accordion defaultOpen={false} title="Timeout output">
  ```text theme={null}
  ✗ Branch delete did not complete within 10 minutes. It may still be running server-side. If you contact Ardent support, reference operation id <operation-id>.
  ```
</Accordion>

The CLI removes the branch from the local cache only after the server confirms deletion. After a timeout, cached output may still show the branch even if the server-side delete later completes. Re-running `ardent branch delete <name>` for the same branch is safe: Ardent reuses the active delete operation, and a re-delete after the branch row is already gone polls the prior delete operation instead of starting a second teardown. You can also re-run `ardent branch list` online to refresh and check the final state.

Branches auto-suspend after a short idle period, so cleanup is not urgent for local development. CI workflows should still delete branches with `if: always()` or your CI provider's equivalent so every run cleans up after itself.