> ## 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.

# PostgreSQL

> Connect and back up PostgreSQL databases with Capsule.

## Required tools

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

<Tabs>
  <Tab title="Debian / Ubuntu">
    ```bash theme={null}
    sudo apt-get install postgresql-client
    ```
  </Tab>

  <Tab title="RHEL / CentOS / Amazon Linux">
    ```bash theme={null}
    sudo dnf install postgresql
    ```
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    brew install libpq && brew link --force libpq
    ```
  </Tab>
</Tabs>

Verify:

```bash theme={null}
capsule doctor
```

***

## Connection details

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

| Field         | Example                   |
| ------------- | ------------------------- |
| Host          | `localhost` or `10.0.0.5` |
| Port          | `5432`                    |
| Database name | `myapp_production`        |
| Username      | `myapp_user`              |
| Password      | your database password    |

***

## 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.

```
Container name: postgres_container
```

See [Docker containers](/databases/docker) for full details.

***

## Connection string format

Capsule accepts individual fields (host, port, etc.) — not a connection string URL. If you have a URL like:

```
postgresql://myapp_user:password@localhost:5432/myapp_production
```

break it into the individual fields when prompted, matching each piece to its position in the URL:

| URL piece          | Goes in field |
| ------------------ | ------------- |
| `myapp_user`       | Username      |
| `password`         | Password      |
| `localhost`        | Host          |
| `5432`             | Port          |
| `myapp_production` | Database name |

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.