Postgres
Connect a PostgreSQL database to query and modify its data from agents and workflows.
The Postgres integration connects Compass to a PostgreSQL database. Once connected, your agents and workflows can inspect its schema, read and query it, and modify rows — through a typed set of actions.
Connecting
Under Studio → Connections, click Postgres, then New connection, and provide:
| Field | Required | Notes |
|---|---|---|
| Host | Yes | The database server's hostname. |
| Database | Yes | The database to connect to. |
| Port | No | Under Advanced. Defaults to 5432. |
| Ssl | No | Under Advanced. Off by default, which turns TLS off — switch it on for managed databases that require encrypted connections. |
Postgres authenticates with Username & Password (User and Password). Credentials are encrypted and never shown again — see Config and credentials.
When you save, Compass connects and reads the database's schema — its tables, columns, and foreign keys. If the database can't be reached, the save fails. That snapshot powers the canvas: an Integration node offers your tables in a dropdown and suggests column names as you fill in filters and values.
The schema snapshot isn't refreshed on edit
The schema is read when the connection is created. If you add tables or columns
later, refresh the snapshot through the API
(POST /v1/connections/{id}/introspect) so the canvas suggestions catch up.
Agents aren't affected — they can always ask the database directly.
Actions
| Action | Kind | What it does |
|---|---|---|
| list_tables | Read | List the database's tables and views. |
| list_columns | Read | List the columns of a table (optionally qualified as schema.table). |
| describe_schema | Read | Describe the whole schema, including foreign keys. |
| read | Read | Read rows from a table, with equality filters (where) and a limit (default 100). |
| execute_sql | Read | Run a statement that starts with SELECT or WITH, with positional parameters. Only the first keyword is checked — see the note below. |
| insert | Write | Insert a row and return it. |
| update | Write | Update rows matching an equality filter; returns the rows affected. |
| delete | Write | Delete rows matching an equality filter; returns the rows affected. A filter is required. |
Each action has a typed input and output, so the canvas can check what you bind and downstream steps know the shape of what comes back. Statements time out after 30 seconds.
Give agents a read-only database user
An agent's reach is only as narrow as the credentials behind it. execute_sql
only checks that a statement starts with SELECT or WITH, so a crafted query
could still change data — for connections an agent uses to answer questions,
connect as a database user that can only read. Note too that update applies to
every row when its filter is empty — keep write actions off unless an agent truly
needs them, and consider requiring approval when it does.
Let an agent explore the schema
Granting an agent list_tables, list_columns, or describe_schema alongside
execute_sql lets it discover the database structure and then query it —
useful for answering ad-hoc questions over your data.