PostgreSQL targets

View as Markdown

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

Image loading...

Click New target and select PostgreSQL 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 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.

Info

Fields like Host, Username, Password, and Database can use custom variables 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.

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

Using the PostgreSQL target in YAML pipelines

Reference the target by ID in a PostgreSQL CLI action:

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 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, or route through a proxy SSH 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.