Skip to main content
The built-in Postgres integration gives agents read-only, SELECT-only SQL access to a curated allowlist of schemas and tables in one PostgreSQL database. An admin configures the connection once and it is shared tenant-wide. Writes are not supported.
This connector is designed for a dedicated analytics database or replica, not your application’s primary operational database. Point it at a read replica or a least-privilege reporting role.

​
What you’ll need

  • A PostgreSQL connection string for the database you want Aperium to read.
  • A database role scoped for analytics — ideally login-only with SELECT on just the tables in scope, and none of SUPERUSER, CREATEROLE, CREATEDB, REPLICATION, or BYPASSRLS.
  • The list of schemas (and, optionally, specific tables) you want to expose as query scopes.

​
How it connects

Aperium stores the connection string encrypted against the tenant. Setup does no network I/O — the connection is not dialed at save time (which would be an SSRF vector against the operator-submitted host). Connectivity is validated on the first tool call instead. At save time Aperium runs two classes of check:
The connection’s host, port, and database are compared against Aperium’s own registered databases, resolving hostnames to IPs so localhost, 127.0.0.1, and container DNS all collide. A collision, or a malformed connection string or scopes definition, is rejected outright.
Aperium warns (but still lets you save) if the role can’t log in or holds a disqualifying privilege (SUPERUSER, CREATEROLE, CREATEDB, REPLICATION, BYPASSRLS), if it has SELECT on Aperium’s own sentinel tables, or if the host is a private/loopback address. The warnings surface in the admin UI so you can confirm a save-anyway.

​
Setup

1

Open the Postgres setup form

In the admin onboarding flow or the Admin Console’s MCP Servers tab, open the Postgres connector’s setup form.
2

Enter the connection string

Paste the connection string into the Connection String field. It is marked secret and stored encrypted against your tenant.
3

Define query scopes

Provide the Query Scopes JSON — the allowlist of schemas (and optional per-schema table allowlists) agents may read. Every tool call resolves through this allowlist before any SQL runs.
4

Set the safety caps (optional)

Optionally override Max Result Rows, Query Timeout (seconds), and Max Response Bytes. Leave blank to use the server defaults. Click Enable.

​
What agents can do

Once configured, agents can call five tools:
  • List scopes. Return the database, host, configured scopes, and caps — no SQL runs.
  • Schema overview. Enumerate the schemas and tables inside the configured scopes, with estimated row counts.
  • Describe table. Inspect a table’s columns, types, and primary-key columns. Tables outside every scope are rejected before any SQL runs.
  • Run SQL. Execute a SELECT-only query against the allowlisted schemas.
  • Explain. Return the query plan for a SELECT statement.

​
Safety model

Every query is guarded before it reaches the database:
  • SELECT-only. The statement is parsed to an AST; INSERT, UPDATE, DELETE, MERGE, CREATE, DROP, ALTER, TRUNCATE, and SET are rejected at the tool layer.
  • Function deny-list. Dangerous functions (for example pg_read_server_files, dblink, pg_terminate_backend, lo_export, pg_ls_dir) are rejected.
  • Scope enforcement. Every referenced base table must be schema-qualified and inside a configured scope; unqualified names are rejected so search_path can’t resolve them to an out-of-scope schema.
  • Bounded execution. Queries run inside a READ ONLY transaction with statement and lock timeouts, a row-LIMIT cap, and a response-byte cap.
The connection string is encrypted at rest and never echoed in any tool response.