> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quadrillion.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Postgres Integration

> Connect Qualia to a PostgreSQL database with a connection URL, on desktop or in Qualia Cloud.

Connect Qualia to a PostgreSQL database so notebooks can query it. You paste one connection URL in settings; the agent then queries the database from the notebook kernel through a small client, `qualia_postgres`, without ever seeing the URL in chat.

Both the desktop app and Qualia Cloud connect the same way, from the same settings page. The one difference — where the connection comes from, and so what your database has to allow — is called out below.

<Note>
  Connections are **read-only by default**. The client sets the session to reject writes, so a stray `UPDATE` fails instead of running. That is a guard rail, not a boundary: the agent can open a read-write connection when you ask for a write, and a statement can switch a transaction back. Use a database role that can only read if you want writes to be impossible rather than merely unasked for.
</Note>

## Prerequisites

* **A PostgreSQL database** reachable from where the kernel runs (see [Network access](#network-access)).
* **A database role** for Qualia to connect as. A role with `SELECT` on the tables you want to explore and nothing more is the recommended posture.
* **Its connection URL**, in libpq form: `postgresql://user:password@host:5432/database`. Add `?sslmode=require` if your server requires TLS.

## Connecting

1. Open **Settings → Integrations → Postgres**.
2. Paste the connection URL into **Connection URL**. It saves as you type, and shows afterwards with the credentials masked: `postgresql://••••@host:5432/database`. On desktop the URL is held in the operating system's keychain — or, on a machine without one, in a file only your user account can read — and only the masked form is written to Qualia's settings file.
3. Ask the agent to query the database. It loads the `postgres` skill and connects through `qualia_postgres`.

To disconnect, clear the field with the trash icon. The URL is deleted; nothing else is stored.

Where the URL lives depends on the deployment. On desktop it is in this machine's keychain (or the restricted fallback file above). In Qualia Cloud it is in your own encrypted credential store — each member saves their own URL, and one member's connection is never visible to another.

## Network access

The connection is opened by the **notebook kernel**, not by the Qualia app or the Qualia Cloud API.

* **Desktop**: the kernel runs on your machine, so anything you can reach from a terminal, Qualia can reach.
* **Qualia Cloud**: the kernel runs in a cloud sandbox whose IP address is neither fixed nor ours. A database behind an IP allowlist, or inside a private network with no public endpoint, is unreachable from there. Open the database to public connections over TLS with a read-only role, or connect from the desktop app instead. Deployments that restrict sandbox egress to an allowlist block outbound database connections entirely; ask your Qualia administrator whether yours does.

<Warning>
  There is no "Test connection" button, deliberately. The first query from a notebook is the test. If it fails, the error the agent reports — connection refused, timed out, password authentication failed, permission denied — is the database's own, and says which of the above to fix.
</Warning>

## What the agent can do

With a connection saved, the agent can:

* **Explore the schema** — tables, columns, foreign keys, approximate row counts — through the PostgreSQL catalog.
* **Run queries** into pandas DataFrames, with values bound as parameters rather than pasted into SQL.
* **Stream large results** in batches instead of loading a whole table.
* **Write**, only when you ask, over a connection it opens read-write for that purpose.

It is instructed never to print, store, or pass on the connection URL, and never to assemble its own connection from pieces you give it in chat — if the integration is not connected, it points you to settings instead.

## The connector catalog

Postgres also appears in the **MCP connector catalog** as a managed connector. Nothing is installed from there: the catalog entry shows whether a connection is saved and opens this settings page. See [MCP Integrations](/mcp-integrations) for how managed connectors differ from MCP servers you configure by hand.