# PostgreSQL targets

Connect Buddy CI/CD to PostgreSQL with a reusable target. Run psql scripts, schema migrations, and maintenance queries from any pipeline.

PostgreSQL targets in Buddy let you store the connection to a Postgres instance once and reuse it across every pipeline that runs `psql` scripts, schema migrations, or maintenance queries. The target is consumed by the [PostgreSQL CLI action](/docs/yaml/yaml-actions/postgresql-cli.md) and can be referenced by name, by tag, or inline in YAML.

## How to add a PostgreSQL target in Buddy

Navigate to the **Targets** tab where all globally defined connections are listed.

![](/docs/targets/target-add.png 640x369)

Click **New target** and select <u>PostgreSQL</u> from the dropdown menu.

## PostgreSQL connection settings

Required fields:

- **Name** - human-readable target name; the unique ID is generated automatically and can be edited.
- **Scope** - defines which pipelines have [access](/docs/targets/target-scope.md) to the target.
- **Host** - hostname or IP of the PostgreSQL server (e.g. `pg.example.com`).
- **Port** - PostgreSQL server port. Default: `5432`.
- **Database** - default database name.
- **Username & Password** - PostgreSQL authentication credentials.

Optional fields:

- **Proxy** - an SSH target used to tunnel traffic to a private PostgreSQL server (useful for RDS, Cloud SQL, or any database behind a bastion).
- **Tags** - labels used to group and match targets.

<Hint type="info">

Fields like `Host`, `Username`, `Password`, and `Database` can use [custom variables](/docs/pipelines/variables.md) defined at the workspace, project, or pipeline level. This keeps secrets out of YAML and lets you switch between environments by overriding the variable set.

</Hint>

## Testing the PostgreSQL connection

Before saving, use **Test connection** to verify the credentials and network access. The test connects from a Buddy runner to the host and port you provided and authenticates with the supplied credentials against the target database. If the test fails, see [Troubleshooting](#troubleshooting-postgresql-connection-errors) below.

## Using the PostgreSQL target in YAML pipelines

Reference the target by ID in a [PostgreSQL CLI action](/docs/yaml/yaml-actions/postgresql-cli.md):

```yaml
- pipeline: "Apply Postgres migrations"
  trigger_mode: ON_EVERY_PUSH
  actions:
    - action: "Migrate schema"
      type: "POSTGRESQL_CLI"
      target: "pg-prod"
      execute_commands:
        - "SELECT version();"
      execute_files:
        - "migrations/2026_05_19_add_index.sql"
```

You can also define the target inline if you do not want to manage it in the UI:

```yaml
- action: "Smoke query"
  type: "POSTGRESQL_CLI"
  targets:
    - target: "pg-prod"
      type: "POSTGRESQL"
      host: "pg.example.com"
      port: 5432
      database: "$PG_DB"
      username: "$PG_USER"
      password: "$PG_PASSWORD"
  execute_commands:
    - "SELECT id, email FROM users ORDER BY created_at DESC LIMIT 10;"
```

See the [PostgreSQL CLI YAML reference](/docs/yaml/yaml-actions/postgresql-cli.md) for the full field list.

## Troubleshooting PostgreSQL connection errors

Most failures fall into one of the categories below.

- **password authentication failed for user** - the password is wrong or the user is configured with `peer` / `ident` auth in `pg_hba.conf`. Switch the matching `pg_hba.conf` line to `md5` or `scram-sha-256` and reload (`SELECT pg_reload_conf();`).
- **no pg_hba.conf entry for host** - Postgres rejects the runner's IP. Add a rule for the [Buddy IP range](/docs/troubleshooting/ip-whitelist.md), or route through a [proxy SSH target](/docs/targets/ssh.md#proxy-target).
- **connection timeout / host unreachable** - the database is not exposed to Buddy runners. Whitelist the Buddy IPs on the firewall (or AWS Security Group / GCP firewall rule).
- **database "..." does not exist** - the named database is missing. Create it first or fix the name. Note that `psql` defaults to a database named after the user when none is given.
- **FATAL: sorry, too many clients already** - the Postgres `max_connections` cap was hit. Lower pipeline concurrency, switch to a pooler (PgBouncer), or raise the cap.
- **SSL required** - the server requires SSL but the target is not configured for it. Re-test the connection after updating the server or routing through a proxy that terminates TLS.

## See also

- [PostgreSQL CLI action - YAML reference](/docs/yaml/yaml-actions/postgresql-cli.md)
- [Other database targets: MSSQL](/docs/targets/mssql.md), [MongoDB](/docs/targets/mongodb.md), [MySQL](/docs/targets/mysql.md)
- [Targets - REST API](/docs/api/targets.md)
- [Custom variables in pipelines](/docs/pipelines/variables.md)


---
Original source: https://buddy.works/docs/targets/postgresql