Skip to main content
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.
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.

​
Prerequisites

  • A PostgreSQL database reachable from where the kernel runs (see 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.
  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. Each cloud member saves their own private connection URL. See API key storage for credential protection on desktop and Cloud.

​
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.
Run a query to check your connection. If it fails, the error identifies the problem, such as network access, credentials, or database permissions.

​
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.

​
The connector catalog

You can also open these settings from Customize agent > MCP Servers > Browse connectors > Postgres.