PostgreSQL¶

Connect Datahub to a PostgreSQL database — self-hosted or managed — and query it with insight cards, metrics and flows through one governed, read-only connection.

ServerSelf-hosted · managed · Azure Database

AuthRole + password

TransportTLS · SSL mode you choose

PowersInsights · Metrics · Flows

What it powers¶

Use the PostgreSQL integration when operational data lives in a PostgreSQL database and you want to read it from inside Datahub without copying it anywhere first.

Insight cards & dashboards

Build cards that query the database directly, alongside your Databricks, Fabric and catalog-backed cards.
Metrics

Point a metric definition at a table and let the metric builder browse schemas, tables and columns to find it.
Flows

Read query results inside a flow step, so a process can branch on what the database says.
Schema & table browsing

Walk database → schema → table → column from the builders, so a query points at a real column rather than a guessed one.

What this connection does not do

No writes, ever. Every statement is checked before it leaves Datahub and anything that is not read-only is refused. See Read-only, twice over.
No alerts yet. The alert evaluator does not support this connection type. It will not appear in the alert builder.
No AI agent tools yet. Agents cannot query this connection over MCP.
One database per connection. Register a second integration to reach another database on the same server.

How the connection works¶

Datahub connects to one database with one role, over TLS, and every query surface uses that single connection.

flowchart LR
    A[Insight cards] --> D[Datahub connection]
    B[Metrics] --> D
    C[Flows] --> D
    D -->|read-only role, TLS| E[(PostgreSQL database)]

Read-only, twice over¶

Two independent things keep this connection read-only, and you should set up both:

Datahub refuses the statement. Every query is parsed before it is sent, and anything that is not a read is rejected. This is not configurable.
The database refuses the role. Grant the role SELECT and nothing else. If the first guard ever fails, the second one still holds.

The second is the one you control, and it is the one worth doing properly.

Prerequisites¶

The host and port of the server (5432 unless it was changed).
The name of the database to query.
Permission to create a role on that database, or someone who can.
Network access from Datahub to the server. If the server is on a private network, see Private-network servers.

Setup¶

1. Create a read-only role¶

Connected to the database as an administrator:

CREATE ROLE datahub_ro LOGIN PASSWORD 'choose-a-strong-one';

GRANT CONNECT ON DATABASE your_database TO datahub_ro;
GRANT USAGE   ON SCHEMA   public        TO datahub_ro;
GRANT SELECT  ON ALL TABLES IN SCHEMA public TO datahub_ro;

Cover tables created later

GRANT SELECT ON ALL TABLES covers the tables that exist today. To extend it automatically:

ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT SELECT ON TABLES TO datahub_ro;

Repeat both grants for every schema you want Datahub to reach.

2. Allow the client to connect¶

On a self-hosted server, add a line to pg_hba.conf for the address Datahub connects from and reload:

hostssl  your_database  datahub_ro  <datahub-address>/32  scram-sha-256

On a managed service (Azure Database for PostgreSQL, RDS, Cloud SQL), add the address to the allowed-networks list instead.

3. Add the integration in Datahub¶

Go to Admin → Integrations, choose PostgreSQL, and fill in:

Field	What to enter
Name	Anything you will recognise later, for example `Production orders`
Host	The hostname or address of the server
Port	`5432` unless it was changed
Database	The database to query
SSL mode	See the table below
Username	`datahub_ro`
Password	The password you chose

4. Choose an SSL mode¶

Mode	What it does
Require	Encrypts the connection. The certificate is not verified.
Verify CA	Encrypts, and checks the certificate is signed by a trusted authority.
Verify full	Strongest. Also checks the certificate matches the hostname.
Disable	No encryption. The password and every result travel in the clear.

Start at Require. Move to Verify full once the server presents a certificate your platform trusts.

Disable sends your password in the clear

Reserve it for a database on the same private network, and prefer an encrypted mode even there.

5. Save, then test¶

Save the integration first. The connection test runs against the stored credentials, so it becomes available on the settings page once the integration exists.

A successful test names the role it authenticated as. That is the quickest way to catch a connection made as the wrong user.

Private-network servers¶

Most PostgreSQL databases are not on the public internet, and Datahub will not reach one unless you say so.

By default a connection is refused when the address resolves to a private, loopback or link-local network — on every path, not just the connection test. The refusal says so explicitly rather than reporting an unreachable host.

To allow it, open the integration and turn on Network access → Allow private-network hosts. It saves as soon as you switch it. Grant it only for a database you intend Datahub to reach there, and keep the address under your own control.

Supported features¶

Feature	Supported
Insight cards and dashboards
Metrics
Flows (read a query result)
Schema, table and column browsing
Alerts	not yet
AI agent tools (MCP)	not yet
Writing to the database	by design

Limitations¶

One database per connection. The database is part of the connection, not part of the query.
Read-only. Statements that are not reads are refused before they leave Datahub.
Results are capped. A query returns at most 10,000 rows, and the limit is applied in the database rather than after the fact, so a broad query does not pull a large table across the network.
Queries are stopped after 50 seconds. If one is cut off, narrow it with a filter or aggregate in the database.
Alerts and agents are not wired up yet. The connection will not appear in the alert builder or in agent tools.

Troubleshooting¶

What you see	What it usually means
Authentication failed (SQLSTATE 28P01)	The username or password is wrong. Update them and test again.
Authentication failed (SQLSTATE 28000)	The login was rejected, or `pg_hba.conf` does not allow this client. Check both.
The database does not exist (SQLSTATE 3D000)	The database name is wrong.
Connected, but this role lacks permission (SQLSTATE 42501)	The role connected but cannot read. Grant `USAGE` on the schema and `SELECT` on the tables.
This query ran longer than the 50-second limit and was stopped	The statement exceeded the platform limit. Narrow it with a filter, aggregate in the database, or reduce the range.
This connection points at a host on a private network	Datahub declined on purpose. See Private-network servers. Your firewall is not the issue.
Could not reach the database	The host, port or firewall. Nothing was rejected; nothing answered.