Connect PostgreSQL for agent queries

If PostgreSQL appears in your connector list, connect a database for agent queries and figures. Choose direct access or an on-demand SSH tunnel through your own bastion. A database behind the bastion can stay private.

Who can do this

A workspace administrator creates or replaces the connection. Your database administrator supplies a dedicated login, database access, and trusted TLS certificates. Members use connections made available to their agent and conversation.

Prefer a replica or curated reporting data. Grant SELECT only on the tables or views needed for analysis. Remove privileged memberships and functions that can change data or contact external services. Read-only transactions alone do not make those functions safe.

For statistics monitoring, use a separate login with CONNECT and pg_read_all_stats membership. Do not grant pg_read_all_data, application-table access, or default table privileges. pg_monitor and pg_stat_scan_tables memberships are not supported. Statistics can expose query text and sensitive metadata. Restrict this connection to people permitted to see them.

Prepare network access

Method	Requirements
Direct	A database host reachable from d5s, with a trusted TLS certificate matching that hostname. Allow the d5s outbound addresses through the database firewall.
SSH tunnel	A reachable customer bastion, a dedicated SSH account and private key, an independently trusted SSH host public key, and database credentials. The database can use a private hostname reachable only from the bastion.

For SSH, get the current regional d5s outbound allowlist from your administrator. Hosted deployments with fixed egress require a public IPv4 address for the bastion. Allow only the supplied list to reach its SSH port. The bastion must resolve and reach the private database hostname and port. Permit only forwarding to that database; disable shells, PTYs, agent forwarding and X11 forwarding for the dedicated account.

Obtain the bastion's host public key through a trusted administrative channel. An unverified network key scan is not proof of identity. PostgreSQL TLS verifies the database hostname even inside the SSH tunnel. Include the database CA certificate when its issuer is not publicly trusted. See the administrator's PostgreSQL SSH setup instructions for forwarding restrictions.

Connect and test

1. Open Connectors and choose PostgreSQL. Choose Direct or SSH tunnel.
2. Enter a connection name, database host, port, database name, username, and password. For SSH, also enter the bastion host, SSH port, username, private key, and trusted host public key. Add a database CA certificate when needed.
3. Select Test and connect. d5s opens the connection, checks access and database-role safety, and saves only after verification succeeds. A failure leaves the form open without saving the secret.
4. Activate the connection for the agent. Review its Allow, Ask, or Deny tool permissions. Ask for a schema listing or SELECT 1 AS ok.

For a statistics-only login, ask the agent to query statistics views directly. List schema shows accessible application tables and views and can be empty.

Results and ongoing use

The agent can query data and create charts or files in the conversation. Queries return at most 10,000 rows and 2 MB. An individual row above 64 KB stops the result. Narrow or aggregate SQL when a result is partial. Queries also have time limits.

A requested check or query opens its own database connection and, for SSH, its own tunnel. Both close afterward. Saving or activating a connection starts no background connection checks or alerts. No customer runner is required.

Your administrator maintains the database permissions, bastion, certificates, and secrets. d5s stores connection credentials encrypted without giving them to the agent or its coding environment. Query results transfer to d5s and can remain in conversation history and files. Removing a connection prevents new queries; it does not erase previous artifacts.

Replacing a connection requires the full new credentials and another successful test. Existing credentials survive a failed replacement. A successful replacement invalidates earlier approvals and prevents an in-flight result from the old target being retained. Obtain fresh approval for the replacement database.

If it fails

• PostgreSQL is missing: Ask your workspace administrator whether this beta connection is enabled.
• Connection test failed: Check network reachability, the firewall allowlist, credentials, and database-role permissions.
• SSH connection failed: Check bastion ingress, forwarding restrictions, private DNS and the trusted host public key. Verify any replacement key independently.
• TLS failed: Check the database hostname and CA chain. Certificate verification cannot be disabled.
• Query failed or result is partial: Narrow the query, inspect permissions, and use the retained result for further analysis. Do not assume a timed-out query completed.