Quick start guide for Supabase users

Set up PostgresAI monitoring for your Supabase databases using the built-in Supabase integration in PostgresAI Console.

Overview

The Supabase integration uses OAuth to automatically discover your Supabase projects and provision monitoring — no manual database credentials or network configuration required.

Choose Starter ($16/cluster/month) or Scale ($512/cluster/month). Both include Full monitoring, Checkup reports, agent workflows, issues and action plans, email/Slack alerts, and async support.

Starter covers the primary node with 14-day retention and no included expert requests. Scale covers one primary + up to 5 replicas in one cluster with 13-month retention, Grafana dashboards, Private RDS / PrivateLink, Trend analysis (Performance Cliffs and Walls), and two human expert requests per month on two topics. Scale responses are within 24 business hours, with a one-week issue conversation. Both plans offer two additional expert requests for $500 as a one-off pack; contact us for pack terms.

Included monthly expert requests expire at month end and do not roll over or accumulate. Purchased-pack terms are separate; contact us for details.

Partner-sponsored organizations use Scale with Billed to partner. A Supabase referral alone does not mean your organization is sponsored. Self-paying organizations choose and pay for their own plan.

Prerequisites

1. A Supabase account with at least one project.
2. A PostgresAI Console account. Sign up with Google, LinkedIn, GitHub, or GitLab.
3. An organization in PostgresAI Console. Create one if you don't have one yet.
4. A payment method on file (required for self-paying Starter and Scale plans). In your organization, open Billing, click Edit payment methods, and add a card in the Stripe portal.

Step 1. Start the Supabase setup

In PostgresAI Console, navigate to DB health — Getting started and click Connect Supabase.

Step 2. Choose your plan

Choose Starter or Scale on the monitoring plan page. Both use the same monitoring product; retention, node coverage, dashboards, and expert allowance differ. Enterprise customers can contact us.

See Pricing for the comparison. The selected plan is carried through setup. Partner-sponsored organizations see Scale billed to their partner instead of self-pay prices.

Step 3. Authorize Supabase access

During setup, you are redirected to Supabase to authorize PostgresAI.

Review the requested permissions and select the organization you want to monitor, then click Authorize PostgresAI.

The requested permissions include:

• Read and Write access to Postgres configurations, SQL snippets, SSL enforcement configurations, and TypeScript schema types.
• Read access to the organization and all its members.
• Read access to project metadata, upgrade status, network restrictions, and network bans.

Step 4. Select projects and deploy

After authorization, you are returned to PostgresAI Console.

1. In Billing & plan, confirm your selected plan and payment method (or partner sponsorship).
2. In Supabase project, select the Organization and check the Projects to provision.
3. Optionally, expand Advanced setup to choose the cloud provider or cloud region.
4. Click Deploy.

tip

PostgresAI automatically creates a dedicated monitoring user in your Supabase database and deploys the monitoring stack. No manual database setup is required.

Step 5. Wait for deployment

After clicking Deploy, the monitoring stack is provisioned and configured. Track progress on the installation page:

1. Waiting for SSH
2. Provisioning VM
3. Installing base packages
4. Starting monitoring services
5. Finishing setup

While waiting, you can set up the CLI tools:

# Install CLI
npm i -g postgresai

# Authenticate
postgresai auth

# Set up MCP for your AI coding tool (Cursor, Claude Code, etc.)
postgresai mcp install

Step 6. Save Grafana credentials (Scale only)

Starter users: skip to Step 8 to review issues in Console. Grafana dashboards are not included in Starter.

For Scale, once the deployment completes, the page shows Deployment completed successfully! with your Grafana access details:

• URL — your dedicated Grafana instance
• Username — monitor
• Password — auto-generated

caution

Save your Grafana credentials in a password manager — they are not stored in PostgresAI Console.

Step 7. Open Grafana dashboards (Scale only)

Open the Grafana URL from the deployment page. You can sign in using one of the following methods:

• Grafana credentials — use the username and password from the previous step.
• PostgresAI OAuth — click Sign in with PostgresAI for passwordless access.

Start with 01. Single node performance overview (high-level) for a high-level health check of your Supabase database. Key panels to check first:

1. Active session history (ASH) — wait events over time
2. Sessions — active, idle, and idle in transaction connections
3. TPS — transactions per second
4. QPS — queries per second

Step 8. Review first issues

After about 30 minutes, PostgresAI generates the first automated issue reports. Navigate to Issues in PostgresAI Console to see detected problems and recommended actions.

Common issues detected automatically include:

• Redundant indexes — duplicate indexes wasting storage
• Unused indexes — indexes that are never scanned
• Invalid indexes — indexes that failed to build
• Autovacuum tuning — recommended configuration changes
• Minor version updates — available PostgreSQL updates

See How to work with issues for details on managing issues, assigning team members, and integrating with AI coding tools.

Next steps

• Dashboard guide — complete dashboard reference
• PostgresAI CLI — CLI setup and commands
• MCP integration — set up MCP for Cursor, Claude Code, or other AI coding tools

FAQ

What database role is created and what permissions does it have?

The monitoring user is created automatically during Supabase setup with read-only access to metadata only. To review the exact SQL statements used to create the monitoring role:

npx postgresai@latest prepare-db --print-sql

This shows all grant statements and confirms the minimal, read-only nature of the permissions.

What data is collected from my database?

PostgresAI monitoring collects only database metadata — no actual data or query parameters. To review exactly what metrics are collected, examine the metric definitions:

• Prometheus sink metrics: metrics.yml (pgwatch-prometheus)
• PostgreSQL sink metrics (including normalized queries): metrics.yml (pgwatch-postgres)

See also: data privacy details.