PostgreSQL Integration
Beta On-demand Connect a PostgreSQL database so Annie can query it read-only and correlate application data, slow queries, and database health with your infrastructure graph.Available on request — contact us to enable it for your workspace.
What Annie can do
- Discover the schema — list schemas, tables, views, sequences, and extensions, and read columns, constraints, and indexes
- Run SQL — execute read-only
SELECTqueries to answer questions about your application data - Explain queries — show execution plans with
EXPLAIN - Find slow queries — rank the slowest or most resource-hungry queries from
pg_stat_statements - Check database health — indexes, connections, vacuum, sequences, replication, buffer cache, and constraints
- Recommend indexes — for your overall workload or for specific queries (uses the
hypopgextension)
Quickstart
- Contact us so Anyshift enables the integration for your workspace.
- Choose an access scope and create a dedicated, narrowly scoped role for it.
- Allow Anyshift’s outbound IPs to reach your database.
- Go to the Anyshift integrations page.
- In the Analytics section, open PostgreSQL and click Add connection.
- Fill in the form:
- Name — a label for this connection, for example
Production PostgreSQL - Host — the public hostname or IP of your database, for example
db.example.com - Port — defaults to
5432 - Database — the database Annie should query
- Username and Password — the role you created
- Access scope — keep the default Health & stats, or choose Diagnostics schema or Full read (see Access scopes)
- SSL mode — keep the default
require(see SSL mode)
- Name — a label for this connection, for example
- Click Save PostgreSQL connection.
SELECT 1 (10-second timeout). The connection shows Active when it succeeds and Error when it fails. Only active connections are available to Annie.
Multiple connections
You can add as many connections as you need, for example one per database or environment. Annie sees each connection as a separate PostgreSQL server and reports which one it queried. Each connection has its own role and access scope, so you can pair a Health & stats or Diagnostics schema connection to production with a separate Full read connection to an analytics database.Security model
Annie’s PostgreSQL access is strictly read-only:- Queries run through Annie’s PostgreSQL MCP server in restricted mode: every statement runs in a read-only transaction with a statement timeout. Restricted mode is enforced server-side and cannot be turned off.
INSERT,UPDATE,DELETE, and DDL are refused.- Your password is encrypted at rest with AWS KMS and is never exposed to the AI agent.
- Only publicly reachable hosts are accepted. Hosts that resolve to private, loopback, link-local, or other non-public addresses are rejected.
Access scopes
Each connection has an access scope that decides what Annie can read. Access to this integration is enabled per workspace by Anyshift. Pick the narrowest scope that answers your questions.
The scope is enforced twice: by Anyshift, and by the privileges of the database role you create. The role is the real boundary, so grant it only what the chosen scope needs. Run the SQL below as an administrator: creating the role needs
CREATEROLE (or superuser), and grants must come from the owner of the objects or a role allowed to grant on them. Replace the password, database, and schema names with your own.
Health & stats (default)
pg_stat_statements for query statistics (see the note at the end of this section). Sequence-exhaustion checks need current sequence values, which pg_monitor does not expose; they only work if you also grant USAGE on the relevant sequences.
A smaller pg_read_all_stats grant alone (without pg_monitor) works for slow-query analysis but disables the buffer-cache health checks, which need pg_monitor.
Diagnostics schema
A DBA-style setup for production: a dedicatedannie role that can read only a handful of health views in a diagnostics schema: database size, transactions, deadlocks, cache hit ratio, connections versus limits, long-running queries without query text, lock waits, and vacuum stats. Use it instead of the Health & stats role: it creates annie itself and deliberately does not grant pg_monitor.
pg_stat_activity, pg_stat_statements, and pg_stat_replication filter rows by the calling role, so plain views would show annie empty values. The views therefore read them through SECURITY DEFINER functions owned by the administrator, which return sanitized columns only (no query text or client address). Views and functions run with their owner’s privileges, so annie sees only what they expose and has no access to application tables.
pg_stat_statements; the rest of the setup works without it. The extension must be in shared_preload_libraries. It is exposed as queryid and timings only, with no query text. Run as the same administrator:
diagnostics. To expose your own aggregate as well, create a view in the same schema and grant SELECT on it to annie, for example:
Full read
Create theannie role as in Health & stats (or reuse a role without pg_monitor), then grant read access:
Slow-query analysis and workload index recommendations need the
pg_stat_statements extension, and index recommendations need hypopg. Annie works without them and tells you when an extension is missing. On managed services, enable them through the provider’s parameter group or extension settings, then run CREATE EXTENSION in the database.Network access
Your database must be reachable from the internet on its PostgreSQL port. If it sits behind a firewall, security group, or IP allowlist, allow inbound traffic from Anyshift’s outbound IP addresses:
See Network Requirements for the downloadable list.
SSL mode
Example questions
- “Which tables in the
ordersdatabase grew the most, and do they have the indexes they need?” - “What are the slowest queries right now, and why is the top one slow?”
- “Run a health check on the production database: bloat, unused indexes, vacuum, and connections.”
- “How many orders failed per hour since yesterday’s deploy?”
- “Explain this query and suggest an index:
SELECT * FROM events WHERE account_id = $1 ORDER BY created_at DESC LIMIT 50”
Troubleshooting
”Invalid PostgreSQL host”
The connection is not saved. The message tells you why:- “host resolves to a non-public address” — the host resolves to a private, loopback, link-local, or other internal address. Annie only connects to publicly reachable databases. Use the database’s public endpoint.
- “could not resolve host” — the hostname does not exist in public DNS. Check the spelling, or use the public IP.
Status Error with a timeout
Anyshift could not reach the database within 10 seconds. Usually a firewall, security group, or network ACL blocks the connection:- Allow Anyshift’s outbound IPs on the PostgreSQL port
- Make sure the database is publicly accessible, for example Publicly accessible on Amazon RDS
- Check the host and port
Status Error with “password authentication failed”
- Check the username and password
- Make sure your
pg_hba.conf(or provider settings) allows password logins from Anyshift’s IPs - Make sure the role has
LOGINandCONNECTon the database
SSL errors
- “SSL is not enabled on the server” — the server does not accept TLS. Enable SSL on the server; switch to a weaker mode only if you accept unencrypted traffic.
- Certificate verification errors — with
verify-full, make sure Host is a DNS name listed in the server certificate (not an IP address or alias it doesn’t cover). If the certificate does not chain to a publicly trusted CA (for example Amazon RDS, self-signed or private CA), switch torequire(see SSL mode).
Annie says a table is missing or permission is denied
This is expected with a narrowly scoped role. If you want Annie to read that data, grantUSAGE on the schema and SELECT on its tables, as in Full read, or switch the connection to that access scope.
Annie doesn’t use PostgreSQL
- Verify the connection shows Active on the integrations page
- Make sure Annie’s access to this connection is not disabled in your integration settings
- After fixing a connection in Error, update it so Anyshift re-tests it