Skip to main content

Connect a Postgres datasource

Goal​

You'll add a Postgres database to PLACEHOLDER Cloud, confirm the connection is reachable, and discover its tables so you can start authoring rules.

Prereqs​

  • A running PLACEHOLDER Cloud (see Self-host).
  • A Postgres user with SELECT on the schema you want to validate. Read-only is correct — PLACEHOLDER Cloud never writes back.
  • The host, port, database, user, and password.

If your Postgres lives on a private network (10.0.0.0/8, 192.168.0.0/16), you must opt-in by adding the CIDR to DATASOURCE_NETWORK_ALLOWLIST — see Configuration. The SSRF guard rejects private targets by default.

Steps​

  1. Log in to the UI as a workspace editor or higher.

  2. Navigate to Datasources → New.

  3. Fill in the form:

    • Name — prod-postgres (or any readable label).
    • Type — postgres.
    • Host — your Postgres host.
    • Port — usually 5432.
    • Database — the DB name.
    • User / Password — your read-only credentials.
    • SSL mode — require is the default; only relax it if you understand the consequences.

  4. Click "Test connection". PLACEHOLDER Cloud opens a connection, runs SELECT 1, and reports either a green check with the round-trip latency or a red X with the error.

    • Common error: "connection refused" — host / port wrong, or the Postgres pg_hba.conf denies your worker's source IP.
    • Common error: "password authentication failed" — credentials wrong, or the user lacks LOGIN.
    • Common error: "Datasource address rejected by network allowlist" — the target host resolved to a private IP and isn't in DATASOURCE_NETWORK_ALLOWLIST. Add the CIDR and restart the API.

  5. Save the datasource.

  6. Click "Discover assets". PLACEHOLDER Cloud queries pg_class / pg_namespace, filters out system schemas (pg_catalog, information_schema, pg_toast), and lists every table and view. Tick the ones you want and click Add selected.

Verify​

  • The datasource shows up under Datasources with a green health badge.
  • Discovered assets appear under the datasource's detail page.
  • You can now author a rule suite against one of those assets — see Write a rule suite without code.

Caveats​

  • The PARITY-1 test endpoint times out after 5 seconds by default. If your warehouse takes longer to acknowledge a connection, bump DATASOURCE_TEST_TIMEOUT_SECONDS.
  • Discover results are cached in Redis for 15 minutes. If you create a new table and don't see it, that's why. Click Refresh in the modal (or wait).
  • Connection strings (host, port, database, user, password) are AES-256-GCM-encrypted at rest. The plaintext exists only inside the worker process during a job.