PostgreSQL Integration

Connect your PostgreSQL databases to let the AI agent query application data, surface anomalies, and trace issues directly from your database during investigations.

note

Read-only access: This integration only executes SELECT queries. INSERT, UPDATE, DELETE, DROP, and all other data-modifying commands are blocked at the query level before they reach your database.

Capabilities

Once connected, the AI agent can:

Capability	Description
SQL Queries	Execute read-only SELECT queries against your databases
Schema Exploration	List databases, tables, columns, and indexes
Data Verification	Check data state and surface anomalies during incidents
Log & Event Tables	Query event logs, audit trails, and time-series data stored in PostgreSQL

Authentication Modes

Autoheal supports three ways to connect to PostgreSQL depending on where your database is hosted:

Mode	Best For	Password Stored?
Direct Connection	Self-hosted, Docker, on-prem, or any reachable PostgreSQL	Yes (encrypted)
AWS RDS (IAM Auth)	Amazon RDS or Aurora PostgreSQL	No — uses your AWS integration
GCP Cloud SQL	Google Cloud SQL for PostgreSQL	Yes (encrypted)

---

Direct Connection

Use this for self-hosted PostgreSQL, Docker containers, on-premise databases, or any instance reachable over the network.

Prerequisites

• A PostgreSQL instance (version 12 or later)
• Network connectivity from Autoheal to your database on port 5432 (or your custom port)
• A PostgreSQL user with read permissions

Step 1 — Create a Read-Only User

Connect to your PostgreSQL instance and create a dedicated user for Autoheal:

CREATE ROLE autoheal_reader WITH LOGIN PASSWORD 'your_secure_password';
GRANT CONNECT ON DATABASE your_database TO autoheal_reader;
GRANT USAGE ON SCHEMA public TO autoheal_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO autoheal_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO autoheal_reader;

tip

Run ALTER DEFAULT PRIVILEGES so that new tables created in the future are automatically readable — you won't need to re-grant permissions after schema changes.

Step 2 — Add Integration in Autoheal

1. Go to Integrations → PostgreSQL
2. Enter a name (e.g., "Production PostgreSQL")
3. Select Direct Connection as the auth type
4. Fill in:
   • Host: PostgreSQL hostname or IP address (e.g., postgres.example.com)
   • Port: PostgreSQL port (default: 5432)
   • Database: The database name to connect to
   • SSL Mode: See SSL Modes below
   • Username: The PostgreSQL username you created
   • Password: The PostgreSQL password
5. Click Test Connection, then Save

---

AWS RDS (IAM Auth)

Use this for Amazon RDS or Aurora PostgreSQL. Autoheal uses your existing AWS integration to generate short-lived IAM authentication tokens — no database password is stored.

How It Works

1. Autoheal uses your AWS integration (OIDC federation) to get temporary STS credentials
2. Those credentials are used to generate a short-lived RDS auth token (valid 15 minutes)
3. The token is used as the database password — a fresh one is generated for each query
4. Your database verifies the token against IAM — no long-lived credentials involved

Prerequisites

• An active AWS integration configured in Autoheal (see AWS Integration)
• IAM authentication enabled on the RDS instance
• The IAM role used by your AWS integration must have rds-db:connect permission
• A PostgreSQL user in RDS with the rds_iam role granted

Step 1 — Enable IAM Auth on RDS

If creating a new instance, enable IAM authentication at creation time:

aws rds create-db-instance \
  --enable-iam-database-authentication \
  ... other flags

For an existing instance:

aws rds modify-db-instance \
  --db-instance-identifier your-instance \
  --enable-iam-database-authentication \
  --apply-immediately

Step 2 — Create an IAM Database User

Connect to your RDS instance with the master user and run:

CREATE USER iam_db_user WITH LOGIN;
GRANT rds_iam TO iam_db_user;

-- Grant access to your database and schema
GRANT CONNECT ON DATABASE your_database TO iam_db_user;
GRANT USAGE ON SCHEMA public TO iam_db_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO iam_db_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO iam_db_user;

Step 3 — Add rds-db:connect Permission to Your IAM Role

Add the following inline policy to the IAM role used by your Autoheal AWS integration. Replace ACCOUNT_ID with your 12-digit AWS account ID:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "rds-db:connect",
    "Resource": "arn:aws:rds-db:us-east-1:ACCOUNT_ID:dbuser:*/iam_db_user"
  }]
}

tip

Scope the Resource ARN to a specific DB instance resource ID (e.g., db-ABCDEFGHIJK) instead of * for tighter control. Find the resource ID in the RDS console under Configuration.

Step 4 — Add Integration in Autoheal

1. Go to Integrations → PostgreSQL
2. Enter a name (e.g., "Production RDS")
3. Select AWS RDS (IAM Auth) as the auth type
4. Fill in:
   • AWS Integration: Select your configured AWS integration
   • RDS Endpoint: The RDS instance endpoint from the AWS Console (e.g., my-instance.xxxx.us-east-1.rds.amazonaws.com)
   • Database: The database name to connect to
   • Database Username: The IAM DB user created in Step 2 (e.g., iam_db_user)
5. Click Test Connection, then Save

info

The RDS endpoint is the hostname only — find it in the AWS Console under RDS → Databases → your instance → Connectivity & security → Endpoint.

---

GCP Cloud SQL

Use this for Google Cloud SQL for PostgreSQL. Autoheal uses your existing GCP integration to authenticate with the Cloud SQL Admin API and automatically discover the instance IP address — you don't need to manage IP allowlists manually.

Prerequisites

• An active GCP integration configured in Autoheal (see GCP Integration)
• The service account used by your GCP integration must have the roles/cloudsql.client IAM role
• Your Cloud SQL instance must have a public IP assigned

Step 1 — Grant Cloud SQL Client Role to Your Service Account

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:your-sa@your-project.iam.gserviceaccount.com" \
  --role="roles/cloudsql.client"

Replace YOUR_PROJECT_ID and the service account email with the values from your GCP integration.

Step 2 — Create a Database User

gcloud sql users create autoheal_reader \
  --instance=your-instance \
  --password='your_secure_password'

Then connect to the instance and grant read permissions:

GRANT CONNECT ON DATABASE your_database TO autoheal_reader;
GRANT USAGE ON SCHEMA public TO autoheal_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO autoheal_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO autoheal_reader;

Step 3 — Add Integration in Autoheal

1. Go to Integrations → PostgreSQL
2. Enter a name (e.g., "Production Cloud SQL")
3. Select GCP Cloud SQL as the auth type
4. Fill in:
   • GCP Integration: Select your configured GCP integration
   • Instance Connection Name: In the format project-id:region:instance-name (find it in GCP Console → Cloud SQL → your instance → Overview)
   • Database: The database name to connect to
   • Database Username: The PostgreSQL user created in Step 2
   • Database Password: The password for that user
5. Click Test Connection, then Save

---

SSL Modes

Applies to Direct Connection only. AWS RDS and GCP Cloud SQL always use SSL.

Mode	Description
disable	No SSL. Only use for local development or private networks.
require	Encrypts the connection but does not verify the server certificate.
verify-ca	Requires SSL and verifies the server certificate against a trusted CA.
verify-full	Requires SSL, verifies the certificate CA, and checks the hostname. Recommended for production.

warning

Use verify-ca or verify-full for production databases. The require mode encrypts traffic but cannot detect a man-in-the-middle attack.

---

Network Requirements

Mode	Requirement
Direct Connection	Autoheal must be able to reach your PostgreSQL host on port 5432 (or your custom port) over the network
AWS RDS	The RDS instance must be reachable from Autoheal. For publicly accessible instances, ensure port 5432 is open to Autoheal's IP range. Private-only instances (no public endpoint) are not supported unless Autoheal is deployed in your VPC.
GCP Cloud SQL	The Cloud SQL instance must have a public IP assigned. Autoheal calls the Cloud SQL Admin API (HTTPS) to discover the IP, then connects directly on port 5432.

---

Example Queries

Once connected, you can ask the AI agent:

Show me the most recent errors from the application_events table

Query the orders table for failed transactions in the last 24 hours

What tables exist in the public schema?

How many open incidents are there and what are their severities?

Show me all users who logged in today

---

Troubleshooting

Connection Refused (Direct)

• Verify the host and port are correct
• Check that PostgreSQL is running: pg_isready -h your-host -p 5432
• Ensure pg_hba.conf allows connections from Autoheal's IP
• Verify firewall or security group rules allow inbound connections on port 5432

Authentication Failed (Direct)

• Verify the username and password are correct
• Check that the user has LOGIN privilege: SELECT usename, usesuper FROM pg_user WHERE usename = 'your_user';
• Ensure pg_hba.conf allows the authentication method (md5, scram-sha-256, etc.)

SSL Errors (Direct)

• Try a less strict SSL mode (e.g., require instead of verify-full) to isolate the issue
• Verify the server has SSL enabled: SHOW ssl;
• For verify-ca / verify-full, ensure the server certificate is signed by a trusted CA

Permission Denied

• Verify the user has SELECT on the target table: \dp table_name in psql
• Check USAGE is granted on the schema
• Re-run GRANT SELECT ON ALL TABLES — it only applies to tables that exist at the time it runs. Use ALTER DEFAULT PRIVILEGES for new tables.

AWS RDS — Authentication Failed

• Confirm the IAM role has rds-db:connect permission on the correct DB user ARN
• Verify the PostgreSQL user has rds_iam granted: SELECT * FROM pg_roles WHERE rolname = 'iam_db_user';
• Ensure IAM database authentication is enabled on the RDS instance (AWS Console → RDS → Configuration → IAM database authentication)
• Check the RDS instance is publicly accessible and port 5432 is open in its security group

AWS RDS — Connection Timeout

• The RDS instance may not be publicly accessible — check AWS Console → RDS → Connectivity & security → Publicly accessible
• Verify the security group allows inbound TCP on port 5432 from Autoheal's IP range

GCP Cloud SQL — Cannot Discover Instance IP

• Verify the service account has roles/cloudsql.client on the project
• Confirm the Instance Connection Name format is exactly project-id:region:instance-name
• Ensure the Cloud SQL Admin API is enabled: gcloud services enable sqladmin.googleapis.com
• Check the instance has a public IP assigned (GCP Console → Cloud SQL → your instance → Connections → Public IP)

GCP Cloud SQL — Authentication Failed

• Verify the database username and password are correct
• Confirm the user exists: gcloud sql users list --instance=your-instance
• Check the user has the necessary permissions in PostgreSQL