postgresai

AI-native PostgreSQL observability

Monitoring, health checks, and root cause analysis — built for humans and AI agents

Live Demo · Documentation · Get started

Battle-tested in PostgresAI team's work with companies like GitLab, Miro, Chewy, Suno, Supabase, Gadget, and more — now packaged for easy use by humans and AI agents.

Why postgresai?

Traditional monitoring tools give you dashboards. postgresai gives AI agents the context they need to actually fix problems.

• Structured for AI — Reports and metrics designed for LLM consumption
• Issues workflow — Track problems from detection to resolution
• 45+ health checks — Bloat, indexes, queries, settings, security
• Active Session History — Postgres's answer to Oracle ASH
• Expert dashboards — Four Golden Signals methodology

Part of Self-Driving Postgres — PostgresAI's open-source initiative to make Postgres autonomous.

Get started

1. Sign up

Create a free account at postgres.ai

2. Authenticate

npx postgresai auth

This opens your browser to log in and saves your API key locally.

3. Run health checks

PGPASSWORD=secret npx postgresai checkup postgresql://user@host:5432/dbname

4. View results

Open console.postgres.ai to see:

• Detailed reports with suggested fixes
• Issues workflow to track remediation
• Historical data across all your projects

Offline mode: Add --no-upload to run locally without an account or sending report data to the PostgresAI API.

Express Checkup

Run specific checks or work offline:

# Run a specific check
npx postgresai checkup --check-id H002 postgresql://...

# Local JSON output only (no upload)
npx postgresai checkup --no-upload --check-id H002 postgresql://...

Markdown conversion is performed by the PostgresAI API and transmits the full report JSON. Therefore, --markdown cannot be combined with --no-upload. For local-only output, use --json or --output instead.

Tips: npx pgai checkup also works. bunx postgresai if you prefer Bun.

Full monitoring stack

For continuous monitoring with dashboards, install the full stack on a Linux machine with Docker:

# Quick demo with sample data
npx postgresai mon local-install --demo
# → Open http://localhost:3000

# Production setup (Linux + Docker required)
npx postgresai prepare-db postgresql://admin@host:5432/dbname  # Create monitoring role with minimal permissions
npx postgresai mon local-install --api-key=YOUR_TOKEN --db-url="postgresql://..."

Get your API key at console.postgres.ai — or use the fully managed version there.

Production-safe

All diagnostic queries are carefully designed to avoid the observer effect — they use timeouts, row limits, and non-blocking approaches. Battle-tested on production databases with dozens of TiB of data, hundreds of kTPS, and millions of DB objects.

Preview the setup SQL before running:

npx postgresai prepare-db --print-sql postgresql://...   # Review what will be created

The prepare-db step creates a read-only postgres_ai_mon user with minimal permissions, enables pg_stat_statements, and creates postgres_ai schema with a few helper views.

What's inside

For AI developers

postgresai is designed to feed AI agents with structured PostgreSQL diagnostics.

Claude Code plugin

Install from the marketplace:

claude plugin marketplace add postgres-ai/postgresai
claude plugin install pgai@postgresai

Then ask Claude to check your database. The postgresai skill (SKILL.md) deploys PostgresAI monitoring and reports the problems with exact fixes. Other agents install the skill with npx skills add postgres-ai/postgresai --skill postgresai.

Work with Issues from console.postgres.ai:

/pgai:issues

MCP server (Claude Code, Cursor, Windsurf)

# Install MCP server for your AI coding tool
npx postgresai mcp install

This enables AI agents to work with Issues and Action Items from console.postgres.ai directly within your IDE.

CLI + LLM

# Pipe checkup output to any LLM
npx postgresai checkup --json postgresql://... | llm -s "analyze this Postgres health report"

# Or use with Claude directly
npx postgresai checkup --json postgresql://... | claude -p "find issues and suggest fixes"

Sample AI workflow

1. AI agent detects slow query from application logs
2. Runs postgresai checkup --check-id H002 → finds unused indexes
3. Gets structured JSON with analysis
4. Suggests DROP INDEX or creates PR

Requirements

For checkup (express mode):

• Node.js 18+ (includes npm/npx)
• Network access to PostgreSQL 14-18

For full monitoring stack:

• Linux machine with Docker
• pg_stat_statements extension enabled

Tips

• Short alias: npx pgai checkup works too
• Can I use it without registration on console.postgres.ai? Yes, both express checkup and full-fledged monitoring are open-source and can be used without any connection to console.postgres.ai. In instructions above, just skip npx postgresai auth and:
  • Express checkup: use --no-upload
  • Full monitoring: omit --api-key
• Managed version: Express checkup finds problems. The managed version at console.postgres.ai also explains how to fix them and provides an Issues workflow to track fixes

Links

PostgresAI — Self-Driving Postgres

🎯 Use cases

For developers:

postgresai mon local-install --demo

Get a complete monitoring setup with demo data in under 2 minutes.

For production:

postgresai mon local-install --api-key=your_key
# Then add your databases
postgresai mon targets add "postgresql://user:pass@host:port/DB"

🔧 Management commands

# Instance management
postgresai mon targets add "postgresql://user:pass@host:port/DB"
postgresai mon targets list
postgresai mon targets test my-DB

# Service management
postgresai mon status
postgresai mon logs
postgresai mon restart

# Health check
postgresai mon health

🔄 Upgrading

⚠️ Breaking change in 0.15.0 — bundled PostgreSQL 15 → 17 requires a data migration.

0.15.0 upgrades the stack's bundled PostgreSQL from 15 to 17 (sink-postgres, and on the demo target-db / target-standby). PostgreSQL's on-disk format is not compatible across major versions, so the new images refuse to start on a PostgreSQL 15 data directory — an in-place upgrade will not come up until you migrate the data. Nothing is deleted automatically, and your externally-monitored databases are unaffected, but you must act on the bundled databases before bringing the stack up.

sink-postgres stores your historical monitoring measurements, so choose one:

• Preserve history — while still on the old images, dump it, then restore after the upgrade:

  # before `mon stop`/upgrade, with sink-postgres (PG15) running:
  docker compose exec