Skip to main content

​
Required tools

Capsule uses pg_dump to create backups and psql to restore them. Install the PostgreSQL client tools on your server:
Verify:

​
Connection details

When adding a PostgreSQL connection in the Capsule TUI, you’ll be prompted for:

​
Authentication

Capsule stores your password in an encrypted local file and passes it to pg_dump via a temporary .pgpass file that is deleted immediately after the backup completes — the password never appears in the process list and is not left on disk.

​
Docker

If your PostgreSQL instance runs in Docker, enter the container name in the Docker field when adding the connection. Capsule will run pg_dump inside the container via docker exec, so the host tools are not needed.
See Docker containers for full details.

​
Connection string format

Capsule accepts individual fields (host, port, etc.) — not a connection string URL. If you have a URL like:
break it into the individual fields when prompted, matching each piece to its position in the URL: The general shape is always postgresql://USERNAME:PASSWORD@HOST:PORT/DATABASE.

​
Troubleshooting

pg_dump: error: connection to server failed
  • Confirm the host and port are correct and reachable from the server
  • Check that pg_hba.conf allows the connection from localhost (or the server IP)
  • Verify the username and password are correct
pg_dump: command not found Install the PostgreSQL client tools and run capsule doctor to confirm.