PostgreSQL Integration

Connect any PostgreSQL database — RDS, Aurora, or self-hosted — so your agent can query it and answer questions with real data.

Last updated: July 5, 2026

PostgreSQL gives Brief direct, read-only access to a database you host yourself — RDS, Aurora, or a self-hosted instance. Enter connection details once, choose which tables the agent can see, and start asking questions in chat instead of writing SQL by hand.

What can Brief do with PostgreSQL?

  • Query your data — Ask natural language questions, get SQL-backed answers
  • Explore schema — List tables and describe columns, grouped by schema
  • Run analytics — Aggregations, counts, trends, and ad-hoc analysis
  • Table-level access control — Admins choose exactly which tables the agent can query
Brief only runs read-only queries. Only SELECT, WITH (CTE), and EXPLAIN statements are allowed — nothing can insert, update, or delete data.

Which database should I connect?

We strongly recommend a read replica or analytics database, not your primary production instance — the same practice you'd use with any BI tool. It removes any risk to production and keeps agent queries from competing with application traffic.

Brief also needs a publicly reachable host. It connects over the Postgres wire protocol directly, so an address that only resolves inside your private network (a VPC-internal hostname, localhost, or an RFC1918 IP) will be refused. Use your database provider's public endpoint, or a bastion/proxy that exposes one.

Create a dedicated read-only database user for Brief. It keeps the credential scoped to exactly what the agent needs, independent of any application user.

How do I set up this integration?

Setup time: 3-5 minutes
Initial sync: Instant (no background sync needed)
Updates: Real-time queries on each use

Connecting PostgreSQL is admin-only — you need to be a workspace admin.

Steps

Part 1: Enter connection details

  1. Go to Settings → Integrations in Brief
  2. Find PostgreSQL and click Connect
  3. Fill in a connection name, host, port, database, username, and password
  4. Set SSL Mode to Verify Full — Brief requires verify-full and won't save a connection without it
  5. Click Test Connection & Continue

Part 2: Choose which tables to expose

  1. Brief introspects the schema and shows every table it found
  2. Uncheck any tables you don't want the agent to access
  3. Click Connect Database — done, Brief can now query the selected tables

If schema introspection returns nothing, Brief connects without restrictions rather than blocking you — you can still ask the agent to describe individual tables by name.

Security model

Brief applies several layers of protection to every query:

  1. Statement validation — only SELECT, WITH (CTE), and EXPLAIN are allowed; everything else is rejected before it reaches your database
  2. Read-only transactions — every query runs with default_transaction_read_only set, so even a write statement that slipped through validation would be rejected by Postgres itself
  3. Table allowlist — the agent can only see and query tables an admin explicitly selected during setup
  4. Function and keyword deny-list — file access, network-egress, and privilege functions (and statements like COPY, GRANT, VACUUM) are blocked, even inside a CTE
  5. Private-host blocking — connections to internal, loopback, or link-local addresses are refused
  6. Result limits — query results are capped and truncated so a large table can't flood the conversation

Credentials are encrypted at rest, and every query opens a short-lived connection that closes immediately after.

How does it work in chat?

Once connected, your agent can answer data questions directly:

You: How many orders came in last week? Agent: runs a read-only SELECT count(*) against your orders table You had 312 orders last week, up from 275 the week before.

The agent discovers your database through Brief's skill system — it won't see database tools until the conversation is relevant, keeping context focused. Brief also generates a starter skill describing how to use your connected database, which you can refine from Settings.

Managing connections

Changing table access

There's no in-place editor for an existing connection's table selection today. To expose different tables, disconnect and reconnect — you'll get a fresh table selector during setup.

Disconnecting

Go to Settings → Integrations, find the connection, and click Disconnect. Brief immediately stops querying the database.

Common Issues

"Connection test failed"

Cause: Brief couldn't reach the database with the credentials provided. Fix: Double-check host, port, database name, username, and password. Confirm the database accepts connections from outside your network.

"Refused to connect: host is in a private/internal range"

Cause: The host resolves to an internal, loopback, or link-local address. Fix: Point Brief at a publicly reachable endpoint — your provider's public host, not a VPC-internal one.

"PostgreSQL connection requires ssl_mode=verify-full"

Cause: The connection was saved without full SSL verification, or your database's SSL setup changed. Fix: Reconnect from Settings → Integrations and confirm your database supports verify-full SSL.

"Access denied: table is not in the allowed list"

Cause: The table you're asking about wasn't selected during setup. Fix: Disconnect and reconnect from Settings → Integrations, adding the table to your selection.

Queries are slow or get truncated

Cause: A complex query on a large table, or a result set past the row/size limit. Fix: Ask more specific questions — the agent narrows queries with WHERE and LIMIT — and prefer a read replica over production for anything heavy.

What's Next?

Now that PostgreSQL is connected: