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

# capsule connection

> Add, list, and remove database connections from the command line.

<Note>
  Connections can also be managed from the interactive TUI (just run `capsule` with no arguments). Use the `connection` subcommands when you want to script or automate setup — e.g. provisioning a new server with Ansible, cloud-init, or a Docker entrypoint.
</Note>

## Subcommands

| Command                     | Description                                                       |
| --------------------------- | ----------------------------------------------------------------- |
| `capsule connection add`    | Add a new database connection                                     |
| `capsule connection list`   | List all configured connections                                   |
| `capsule connection update` | Update fields on an existing connection (e.g. rotate credentials) |
| `capsule connection remove` | Remove a connection                                               |

***

## capsule connection add

```bash theme={null}
capsule connection add --label <name> --type <postgres|mysql|mongo> [flags]
```

Adds a new database connection. Fails immediately — before prompting for any secret — if your plan's connection limit has already been reached.

### Flags

| Flag               | Description                                                            |
| ------------------ | ---------------------------------------------------------------------- |
| `--label`, `-l`    | Connection label (required)                                            |
| `--type`, `-t`     | Database type: `postgres`, `mysql`, or `mongo` (required)              |
| `--host`           | Database host (required for `postgres`/`mysql`)                        |
| `--port`           | Database port (defaults to `5432` for postgres, `3306` for mysql)      |
| `--database`, `-d` | Database name (required for `postgres`/`mysql`)                        |
| `--user`, `-u`     | Database user (required for `postgres`/`mysql`)                        |
| `--uri`            | Full MongoDB connection URI (mongo only)                               |
| `--docker`         | Docker container name — omit for a native (non-containerized) database |

### Postgres / MySQL example

```bash theme={null}
capsule connection add -l prod-postgres -t postgres \
  --host db.example.com --port 5432 -d myapp -u admin
```

You'll be prompted for the password with input hidden:

```
Enter database password (input hidden):
Connection added: prod-postgres (postgres)
```

### MongoDB example

```bash theme={null}
capsule connection add -l prod-mongo -t mongo
```

If `--uri` isn't passed, you'll be prompted for the full connection string with input hidden (it contains embedded credentials):

```
Enter MongoDB connection URI (input hidden):
Connection added: prod-mongo (mongo)
```

<Tip>
  For fully non-interactive setups (provisioning scripts, CI), set `CAPSULE_CONN_PASSWORD` or `CAPSULE_CONN_URI` as environment variables instead of being prompted. Neither is ever written to shell history since they're read from the environment, not a flag.
</Tip>

***

## capsule connection list

```bash theme={null}
capsule connection list
```

Lists all configured connections along with your plan's connection usage.

```
2 / 3 connections

  prod-postgres  (postgres)  db.example.com:5432/myapp
  prod-mongo     (mongo)     mongodb+srv://cluster0.mongodb.net/myapp
```

***

## capsule connection update

```bash theme={null}
capsule connection update --connection <label> [flags]
```

Updates one or more fields on an existing connection **in place** — same connection ID, so any schedule attached to it is untouched. Use this instead of `remove` + `add` when credentials rotate or a host changes, since `remove` deletes the associated schedule too.

### Flags

| Flag                 | Description                                  |
| -------------------- | -------------------------------------------- |
| `--connection`, `-c` | Connection label to update (required)        |
| `--host`             | New database host                            |
| `--port`             | New database port                            |
| `--database`, `-d`   | New database name                            |
| `--user`, `-u`       | New database user                            |
| `--uri`              | New full MongoDB connection URI (mongo only) |
| `--docker`           | New Docker container name                    |
| `--rotate-password`  | Prompt for a new password (input hidden)     |

Only the flags you pass are changed — everything else is left as-is. At least one field (or a password/URI rotation) must be given, or the command errors out.

### Rotating a password

```bash theme={null}
capsule connection update --connection prod-postgres --rotate-password
```

```
Enter new database password (input hidden):
Connection updated: prod-postgres
```

For non-interactive use (Ansible, CI), set `CAPSULE_CONN_PASSWORD` (or `CAPSULE_CONN_URI` for mongo) instead of passing `--rotate-password` — if either is set, the update applies it without any prompt:

```bash theme={null}
CAPSULE_CONN_PASSWORD="$NEW_PASSWORD" capsule connection update --connection prod-postgres
```

### Changing a host

```bash theme={null}
capsule connection update --connection prod-postgres --host db-replica.example.com
```

***

## capsule connection remove

```bash theme={null}
capsule connection remove --connection <label>
```

Removes a connection and its associated schedule (if any). This also live-reloads the running daemon so the change takes effect immediately, without interrupting an in-flight backup — see [`capsule schedule`](/cli/schedule#live-reload) for details on how that works.

<Warning>
  This only removes the connection from Capsule — your actual database is never touched.
</Warning>

## Notes

* Connections are stored locally in `~/.local/share/capsule/connections.json`, encrypted at rest
* Every successful `add`, `update`, and `remove` syncs to your dashboard automatically; a sync failure (e.g. offline) is logged as a warning but doesn't block the local change
* Plan connection limits: Hobbyist = 1, Solo = 3, Pro = 5, Team = unlimited

## See also

* [`capsule schedule`](/cli/schedule) — schedule automatic backups for a connection you've added
* [`capsule doctor`](/cli/doctor) — verify the required database client tools are installed before adding a connection