Skip to main content

Getting started with Postgres copilot

This guide walks you through setting up Postgres copilot to monitor your Postgres databases and receive AI-powered optimization recommendations.

Prerequisites​

  • A running Postgres database (versions 14-17 supported)
  • A Linux machine with Docker for running postgres_ai monitoring (separate from your database server)
  • Network access from the monitoring machine to your Postgres database

Step 1: Install postgres_ai monitoring​

postgres_ai monitoring is the open-source foundation of Postgres copilot. It runs in your infrastructure and collects the metrics needed for health analysis.

Quick install​

# Download the CLI tool
curl -o postgres_ai https://gitlab.com/postgres-ai/postgres_ai/-/raw/main/postgres_ai
chmod +x postgres_ai

# Run the quickstart (demo mode for testing)
./postgres_ai quickstart --demo

This creates a complete demo environment with sample data. Access the dashboards at http://localhost:3000.

Production install​

For monitoring real databases:

./postgres_ai quickstart --api-key=your_access_token

See the full installation guide for detailed steps including:

  • Database preparation (creating monitoring user, enabling pg_stat_statements)
  • Security configuration
  • Adding multiple databases

Step 2: Get your access token​

  1. Sign up at https://console.postgres.ai
  2. Create a new organization
  3. Navigate to Your Organization → Support → Checkup reports
  4. Complete the payment process
  5. Click Generate new report → Generate token

The access token enables:

  • Automatic upload of monitoring data for analysis
  • Health check report generation
  • Issue creation and tracking

Step 3: Verify data collection​

After installation, verify that metrics are being collected:

# Check service status
./postgres_ai status

# Test database connection
./postgres_ai test-instance my-database-name

Within 5-10 minutes, you should see:

  • Metrics appearing in Grafana dashboards
  • Query statistics being collected

Step 4: Access your first health check​

Once data collection is working:

  1. Go to https://console.postgres.ai
  2. Navigate to your organization
  3. View the generated health check report

The health check analyzes dozens of areas including:

  • Query performance and missing indexes
  • Configuration issues
  • Bloat and maintenance status
  • Security considerations

Step 5: Work with Issues​

When Postgres copilot detects problems, it creates Issues with specific recommendations. Each Issue contains:

  • Problem description
  • Severity rating
  • Recommended fix (e.g., CREATE INDEX ...)
  • Supporting evidence

See Working with Issues to learn how to:

  • Review and prioritize Issues
  • Use AI tools to generate pull requests
  • Track resolution status

What happens next​

With Postgres copilot running:

  1. Continuous monitoring — postgres_ai collects metrics 24/7
  2. Automated analysis — Issues are created when problems are detected
  3. Expert review — Our team validates recommendations
  4. Monthly deep-dives — Comprehensive health check reports

Getting help​

Next steps​