Getting Started

Query Doctor runs entirely in your browser. The analyzer — a local Docker container — bridges the gap between your database and the browser-based tooling. No query data is sent to Query Doctor’s servers.

There are two ways to get started: try an example dataset instantly, or connect your own database.

Quick start with an example

When you first open the app, the onboarding flow offers three pre-built datasets:

• Game Leaderboard — players, games, and scores with a ranking query
• Phonebook — contacts table with a name-lookup query
• Chat Room — users, channels, and messages with a recent-messages join

Select one and click Continue. The schema and sample data are loaded into an in-browser PostgreSQL instance (PGlite), and you’re taken straight to the Live Queries page with pre-loaded queries ready for analysis.

This is a good way to explore the interface without connecting a real database. No Docker or setup is needed.

Connect your own database

To analyze the queries running against your actual database, you’ll walk through a three-step setup wizard.

Prerequisites

• Docker installed and running
• A PostgreSQL database (version 12+) with pg_stat_statements enabled (see below)
• A connection string with read access to the database

Step 1: Start the analyzer

Run the analyzer container:

docker run --pull always -t -p 2345:2345 ghcr.io/query-doctor/analyzer

The onboarding wizard polls http://localhost:2345/health and shows a green checkmark once the analyzer is ready. This usually takes a few seconds.

Note

If your database is on localhost (e.g. a local development instance), you may need --network host so the analyzer container can reach it:

docker run --pull always -t --network host ghcr.io/query-doctor/analyzer

Step 2: Enter your connection string

Paste a PostgreSQL connection string in the standard format:

postgresql://user:password@host:5432/database

The app sends this to the local analyzer — not to Query Doctor’s servers. The analyzer connects to your database, reads the schema from information_schema, and pulls all tracked queries from pg_stat_statements. It also imports table and column statistics from pg_statistic so the optimization engine can produce accurate cost estimates.

If the connection succeeds, you’ll see a Connected indicator and the Continue button becomes available.

Step 3: Confirm sync results

The final step shows a summary of what the analyzer found:

• Number of tables and their column counts
• Number of indexes
• Number of queries from pg_stat_statements

Review the summary and click Continue. You’re taken to the Live Queries page, where the analyzer begins optimizing each query in the background.

What happens next

Once you’re on the Live Queries page:

1. Queries sync automatically — in live mode, the app polls the analyzer periodically to pick up new queries as they appear in pg_stat_statements.
2. Optimization runs in the background — each query is analyzed for possible index improvements using your database’s real statistics. Results stream in via a WebSocket connection.
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.