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
CONNECTon the database andUSAGE+SELECTon the schemas/tables you want to analyze. Make it aLOGINrole 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
| Field | Where to get it |
|---|---|
| Host | Your cloud console — AWS RDS: instance endpoint; GCP Cloud SQL: public or private IP; Azure Database for PostgreSQL: server hostname (*.postgres.database.azure.com) |
| Port | Default 5432; visible under the connection info panel in your cloud console |
| Database | The database name — list with \l in psql |
| Username | The role you created above |
| Password | The password you set in CREATE USER |
What to enter
Host: your-host.example.comPort: 5432Database: your_dbUsername: datarelix_readerPassword: ••••••••SSL mode: requireAllowed schema: publicConnection 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=requireConnection 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:
| Mode | Meaning |
|---|---|
disable | No TLS. Don’t use over public networks. |
allow / prefer | allow tries plaintext first; prefer tries TLS first. Both permit fallback. |
require | TLS required; server cert not verified. Default. Protects against passive eavesdropping but not active MITM. |
verify-ca | TLS + verify the server cert chains to a trusted CA. |
verify-full | TLS + 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
LIMITget one added automatically.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Connection refused | Firewall or wrong port | Verify psql -h host -p 5432 -U user db works from the same network. |
password authentication failed | Bad credentials or wrong pg_hba.conf method | Test 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 exist | Connecting through a transaction-mode pooler | Use a session-mode pooler or direct connection (Supabase: port 5432, not 6543). |
SSL connection required | Server enforces TLS, mode is disable/prefer | Set SSL mode to require or stronger. |
relation does not exist | Wrong schema | Set Allowed schema to the schema that owns the table; \dn in psql lists schemas. |
permission denied for table X | Role lacks SELECT on the table | GRANT 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. |