> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vegalake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PostgreSQL connector

> Configure and validate an enabled VegaFlow PostgreSQL connection using password or SSH-tunnel authentication.

# PostgreSQL connector

The PostgreSQL connector is enabled in VegaFlow and operationally supported for saved connections.

| Property         | Value      |
| ---------------- | ---------- |
| `connector_id`   | `postgres` |
| `connector_type` | `postgres` |
| Category         | Databases  |
| Availability     | Enabled    |

## Required database settings

| Field      | Requirement                                                                |
| ---------- | -------------------------------------------------------------------------- |
| `host`     | Non-empty PostgreSQL hostname or reachable address                         |
| `port`     | Integer from 1 to 65535; defaults to `5432`                                |
| `database` | Non-empty database name                                                    |
| `username` | Non-empty database username                                                |
| `ssl_mode` | `disable`, `require`, `verify-ca`, or `verify-full`; defaults to `disable` |

Choose exactly one authentication branch: `password_auth` or `ssh_tunnel_auth`.

## Password authentication

Store the database password in a [Secret Vault](/platform/secret-vaults), then select its secret reference.

```json theme={null}
{
  "host": "db.example.internal",
  "port": 5432,
  "database": "analytics",
  "username": "data_reader",
  "ssl_mode": "verify-full",
  "password_auth": {
    "password_ref": {
      "namespace": "production-data",
      "key": "postgres-password"
    }
  }
}
```

The example contains a reference name, not a secret value.

## SSH-tunnel authentication

Use an SSH tunnel when the database is reachable only through a bastion. This branch requires:

* `password_ref` for the PostgreSQL password
* `ssh_host`, `ssh_user`, and `ssh_host_fingerprint`
* `ssh_port`, which defaults to `22` and must be from 1 to 65535
* Exactly one of `ssh_password_ref` or `ssh_private_key_ref`
* Optional `ssh_private_key_passphrase_ref` when the selected key is encrypted

```json theme={null}
{
  "host": "db.private.internal",
  "port": 5432,
  "database": "analytics",
  "username": "data_reader",
  "ssl_mode": "require",
  "ssh_tunnel_auth": {
    "password_ref": {
      "namespace": "production-data",
      "key": "postgres-password"
    },
    "ssh_host": "bastion.example.internal",
    "ssh_port": 22,
    "ssh_user": "connector",
    "ssh_host_fingerprint": "SHA256:replace-with-verified-fingerprint",
    "ssh_private_key_ref": {
      "namespace": "production-data",
      "key": "ssh-private-key"
    }
  }
}
```

Verify the host fingerprint through a trusted channel before saving it. Do not obtain it from an unauthenticated failed connection.

## SSL modes

* `disable` does not require TLS. Use only for an explicitly trusted network and database configuration.
* `require` encrypts the connection without full certificate identity verification.
* `verify-ca` requires a certificate chain trusted by the runtime.
* `verify-full` additionally verifies that the server identity matches the requested host.

Prefer the strongest mode supported by the database deployment.

## Create and validate

1. Create every required database and SSH secret first.
2. Open **VegaFlow → Connections → PostgreSQL**.
3. Enter database settings and select one authentication method.
4. Select secret references; never paste values into names or descriptions.
5. Validate the connection.
6. Save it and assign only the permissions needed by QuickFlow operators.

## Troubleshooting

* A schema error usually indicates a missing required field, invalid port, unsupported SSL mode, both/neither authentication branches, or both/neither SSH credential types.
* A network failure can indicate DNS, routing, firewall, database listener, or bastion reachability.
* An authentication failure can indicate username, database password, SSH identity, or permission problems.
* A certificate failure can indicate CA trust, hostname mismatch, or an incorrect SSL mode.
* A fingerprint failure must be investigated, not bypassed.