Getting Started

Query Doctor costs your queries against a real PostgreSQL planner. The analyzer — a Docker container you run — connects to your database, collects your schema, table statistics and query text, and sends them to Query Doctor.

Before you start

• Docker installed and running
• A PostgreSQL database with pg_stat_statements enabled (see below)
• A connection string for that database, or let Query Doctor provision one for you

Connect your database

In your project, go to Settings → Connected databases and click Connect a database. The wizard hands you a docker run command with your project token and database URL already filled in:

docker run --pull always -t \
  -e TOKEN=<your-project-token> \
  -e SOURCE_DATABASE_URL=postgres://user:password@host:5432/db \
  ghcr.io/query-doctor/analyzer

Both variables are required, and the container exits at startup without them. Run it and the wizard reports Analyzer connected.

The analyzer then copies your schema with pg_dump, introspects pg_catalog, reads table statistics from pg_statistic, and pulls tracked queries from pg_stat_statements.

Note

If your database runs on localhost, add --network host so the container can reach it.

What happens next

Once you’re on the Queries page:

1. Queries arrive on their own — the analyzer polls pg_stat_statements and pushes new queries as it finds them. Pull fetches them on demand.
2. Optimization runs in the background — each query is costed for possible index improvements, and results stream in over a WebSocket.
3. Suggestions surface as nudges — queries with optimization opportunities show a cost reduction percentage and concrete CREATE INDEX recommendations. Queries with anti-patterns get nudges pointing to the specific issue.

Enabling pg_stat_statements

pg_stat_statements is a PostgreSQL extension that tracks execution statistics for all queries. Query Doctor reads from it to know what queries are running against your database.

Self-managed PostgreSQL

Add to postgresql.conf:

shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.track = all

Restart PostgreSQL, then create the extension:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Amazon RDS / Aurora

pg_stat_statements is available by default. Enable it in your parameter group:

1. In the RDS console, find your DB parameter group
2. Set shared_preload_libraries to pg_stat_statements
3. Reboot the instance
4. Connect and run CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Supabase

pg_stat_statements is pre-installed and enabled on all Supabase projects. No action needed.

Neon

pg_stat_statements is available as an extension. Enable it by running:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Verifying it works

After enabling, run:

SELECT count(*) FROM pg_stat_statements;

If this returns a number (even 0 for a fresh install), the extension is working. Queries will accumulate as your application runs.