Skip to content

Connect PostgreSQL

Datarelix connects to PostgreSQL through a read-only query service. All queries are validated and executed inside that service — the model never sees credentials or executes raw SQL against your database.

Prerequisites

  • A PostgreSQL server (an actively supported release; confirm compatibility with your provider).
  • A database role with CONNECT on the database and USAGE + SELECT on the schemas/tables you want to analyze. Make it a LOGIN role that is not a superuser and has no write privileges.
  • Network reachability from Datarelix’s egress IPs to your Postgres server.

Auth modes

Username & password

Standard SQL authentication using a database username and password. The password is stored encrypted; all other connection fields are stored as plain configuration.

Setup — create a read-only role

Run the following in your database (as a superuser or role with CREATEROLE):

CREATE USER datarelix_reader WITH PASSWORD 'choose-a-strong-password';
GRANT CONNECT ON DATABASE your_db TO datarelix_reader;
GRANT USAGE ON SCHEMA public TO datarelix_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO datarelix_reader;
ALTER DEFAULT PRIVILEGES FOR ROLE table_owner IN SCHEMA public
GRANT SELECT ON TABLES TO datarelix_reader;

Replace your_db and public with your actual database and schema names. See the PostgreSQL GRANT reference for the full privilege model.

table_owner must be the role that creates future tables. Default privileges apply to that creator, not every role in the schema. The administrator needs authority to create the reader and grant access to the objects. Review inherited roles and PUBLIC privileges, including function execution and temporary tables; these grants do not establish the identity’s complete effective permissions. Default privileges, privilege model.

Where to find your credentials

FieldWhere to get it
HostYour cloud console — AWS RDS: instance endpoint; GCP Cloud SQL: public or private IP; Azure Database for PostgreSQL: server hostname (*.postgres.database.azure.com)
PortDefault 5432; visible under the connection info panel in your cloud console
DatabaseThe database name — list with \l in psql
UsernameThe role you created above
PasswordThe password you set in CREATE USER

What to enter

Host: your-host.example.com
Port: 5432
Database: your_db
Username: datarelix_reader
Password: ••••••••
SSL mode: require
Allowed schema: public

Connection string

Paste a postgresql:// URL instead of filling individual fields. Useful when your cloud provider gives you a ready-made connection string.

Where to find your connection string

  • AWS RDS — RDS console → your DB instance → Connectivity & security → copy the endpoint hostname, then build: postgresql://datarelix_reader:password@endpoint:5432/dbname?sslmode=require
  • GCP Cloud SQL — Cloud SQL → your instance → Overview → copy the public IP; a local Cloud SQL Auth Proxy is not automatically reachable by the hosted Datarelix service
  • Azure Database for PostgreSQL — Azure portal → your server → Connect → copy the connection details and swap in your password
  • Supabase — Project settings → Database → Connection string → URI tab
  • Neon — Dashboard → your project → Connection Details → copy the connection string

What to enter

postgresql://datarelix_reader:your-password@your-host.example.com:5432/your_db?sslmode=require

Connection poolers (transaction vs session mode)

Use a direct endpoint or a session pooler for initial setup. Transaction pooling compatibility depends on the client, provider and configuration. Current PgBouncer can support protocol-level prepared statements with max_prepared_statements enabled; SQL PREPARE and session state have different restrictions. Confirm compatibility before using transaction mode. PgBouncer feature matrix

For Supabase, confirm the endpoint, network reachability and username in its connection guide.


SSL modes

The SSL mode field maps to libpq’s standard SSL modes:

ModeMeaning
disableNo TLS. Don’t use over public networks.
allow / preferallow tries plaintext first; prefer tries TLS first. Both permit fallback.
requireTLS required; server cert not verified. Default. Protects against passive eavesdropping but not active MITM.
verify-caTLS + verify the server cert chains to a trusted CA.
verify-fullTLS + verify the cert and the hostname matches. Strongest. Recommended for managed Postgres in production.

Scope semantics

The Allowed schema field selects the schemas available to discovery and queries. Default: public.

Select the approved schemas in the connection scope and confirm the role has access to each.

Discovery

Fully supported. Discovery reads information_schema and pg_catalog to list tables, columns, types, nullability, defaults, primary keys and foreign keys; the role only sees objects it has privileges on. Optional AI schema analysis adds descriptions and suggests undeclared relationships from naming conventions.

Limitations

  • No write or DDL queries — Datarelix rejects any statement that is not a read before it runs.
  • Only the allowed schemas are available to discovery and queries.
  • Results are capped at 5,000 rows — queries without a LIMIT get one added automatically.

Troubleshooting

SymptomLikely causeFix
Connection refusedFirewall or wrong portVerify psql -h host -p 5432 -U user db works from the same network.
password authentication failedBad credentials or wrong pg_hba.conf methodTest with psql first; check the role’s expected auth method. On Azure, use the plain username — Flexible Server does not need the user@servername suffix (that was only for the retired Single Server). On Supabase poolers the username is postgres.<project-ref>.
prepared statement ... already exists / does not existConnecting through a transaction-mode poolerUse a session-mode pooler or direct connection (Supabase: port 5432, not 6543).
SSL connection requiredServer enforces TLS, mode is disable/preferSet SSL mode to require or stronger.
relation does not existWrong schemaSet Allowed schema to the schema that owns the table; \dn in psql lists schemas.
permission denied for table XRole lacks SELECT on the tableGRANT SELECT ON ALL TABLES IN SCHEMA X TO role plus ALTER DEFAULT PRIVILEGES IN SCHEMA X GRANT SELECT ON TABLES TO role for future tables.