Skip to main content

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.
The PostgreSQL integration is currently in beta. Supported tools and database health checks may expand as we harden the connector.

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 SELECT queries 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 hypopg extension)

Quickstart

  1. Contact us so Anyshift enables the integration for your workspace.
  2. Choose an access scope and create a dedicated, narrowly scoped role for it.
  3. Allow Anyshift’s outbound IPs to reach your database.
  4. Go to the Anyshift integrations page.
  5. In the Analytics section, open PostgreSQL and click Add connection.
  6. 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)
  7. Click Save PostgreSQL connection.
On save, Anyshift connects to the database and runs 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.
Each connection is limited by its access scope. We recommend a dedicated, narrowly scoped role, so the database itself enforces the same limits.

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)

Enable 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.
pg_monitor inherits pg_read_all_stats, which lets the role see all sessions’ activity, including the text of queries in pg_stat_activity and pg_stat_statements, across every database on the cluster. If your application queries contain customer data or secrets as SQL literals, that text is visible to Annie even without SELECT on any table. Use the Diagnostics schema scope below to avoid exposing query text.
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 dedicated annie 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.
Optional: slow-query statistics. Skip this block if you don’t use 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:
In the connection form, select Diagnostics schema and keep the schema name 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

Granting SELECT on your application tables exposes customer and application data to Annie, and the queries it runs can add load to your database. Only do this if you need Annie to answer questions about your data, and point the connection at a read replica rather than your primary whenever possible.
Create the annie role as in Health & stats (or reuse a role without pg_monitor), then grant read access:
Repeat the schema grants for every schema Annie should read.
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

verify-ca and verify-full work when the server certificate chains to a publicly trusted CA. Amazon RDS and Aurora certificates use AWS’s own CAs, which the save-time check does not trust yet, so use require for them. Self-signed or private-CA certificates are not supported in these modes; use require.

Example questions

  • “Which tables in the orders database 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 LOGIN and CONNECT on 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 to require (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, grant USAGE 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