capsule connection

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.

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

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
`--force`	Skip the check for an existing same-label connection under a different host

Postgres / MySQL example

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

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)

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.

Server migration safety check

The dashboard identifies a connection by its host, port, and database — not its label. So if you migrate a database to a new server and re-add it there with the same label you used before, add won’t know to update the old entry; it’ll otherwise create a second, orphaned-looking connection with a duplicate label pointing at the old, now-decommissioned server. To catch this, add checks the dashboard for an existing connection with the same label under a different host/port/database before proceeding:

Error: a connection named "prod-postgres" already exists on the dashboard pointing at
old-server.example.com:5432/myapp — this one points at new-server.example.com:5432/myapp.
Adding it would create a second entry with the same label instead of updating the existing one.

If this is intentional (e.g. migrating this connection to a new server), re-run with --force.
Otherwise, remove the stale entry first: capsule connection remove --connection prod-postgres

If you’re intentionally migrating, pass --force to proceed anyway. If not, the safer fix is usually to remove the stale connection (from the old server if it’s still reachable, or via the dashboard if it’s already gone) before adding the new one — see Migrating to a new server below.

capsule connection list

capsule connection list [--page <n>] [--limit <n>]

Lists all configured connections along with your plan’s connection usage, 10 per page by default.

2 / 3 connections

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

Flags

Flag	Description
`--page`	Page number (default `1`)
`--limit`	Connections per page (default `10`)

Once you’re past the first page, the command prints the exact command to run for the next one. Requesting a page beyond the last one is an error, not an empty list — so a script checking the exit code can reliably tell “no more pages” from “something’s wrong.”

capsule connection update

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

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:

CAPSULE_CONN_PASSWORD="$NEW_PASSWORD" capsule connection update --connection prod-postgres

Changing a host

capsule connection update --connection prod-postgres --host db-replica.example.com

capsule connection remove

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 for details on how that works.

This only removes the connection from Capsule — your actual database is never touched.

Migrating to a new server

Moving a database to a new server involves two independent pieces of state: the dashboard’s connection record (identified by host/port/database, not label) and each server’s local config (connections.json, schedules) — neither carries over automatically. Recommended order:

# On the OLD server, before decommissioning it (if still reachable):
capsule connection remove --connection prod-postgres   # also removes its schedule

# On the NEW server:
capsule auth
capsule connection add --label prod-postgres --type postgres --host <new-host> --port 5432 --database myapp --user admin
capsule schedule add --connection prod-postgres --cron "0 2 * * *"

Removing the old connection first means the new add never has anything to collide with, and you skip the safety-check error entirely. If the old server is already gone before you could run remove there, the orphaned entry needs to be deleted manually from the dashboard’s Connections page instead — then add the new one as above.

If the host/port/database stay identical across the move (e.g. a floating IP or DNS name that gets repointed to the new server), re-adding it there updates the existing dashboard entry in place instead of creating a new one — no --force or cleanup needed. Schedules still need to be re-created locally either way, since they’re per-machine state.

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 = 6
Hobbyist and Solo plans are restricted to local databases — a host of localhost, 127.0.0.1, ::1, 0.0.0.0, or a Unix socket path. Pointing --host at anything else (e.g. a separate database server, a managed RDS instance) on those plans fails with remote connections require the Pro plan or higher. This matters most for the common “app server and database on separate machines” setup — that needs Pro or Team, even if you’re otherwise within your connection-count limit.

Getting Started

CLI Reference

Database Guides

Dashboard

Releases

Subcommands

capsule connection add

Flags

Postgres / MySQL example

MongoDB example

Server migration safety check

capsule connection list

Flags

capsule connection update

Flags

Rotating a password

Changing a host

capsule connection remove

Migrating to a new server

Notes

See also

​Subcommands

​capsule connection add

​Flags

​Postgres / MySQL example

​MongoDB example

​Server migration safety check

​capsule connection list

​Flags

​capsule connection update

​Flags

​Rotating a password

​Changing a host

​capsule connection remove

​Migrating to a new server

​Notes

​See also

Subcommands

capsule connection add

Flags

Postgres / MySQL example

MongoDB example

Server migration safety check

capsule connection list

Flags

capsule connection update

Flags

Rotating a password

Changing a host

capsule connection remove

Migrating to a new server

Notes

See also