Getting Started

Query Doctor costs your queries against a real PostgreSQL planner. It reads your database through a Collector, a container the instance starts beside your database. The Collector sends back the schema, the table statistics and the query text, and analyzes none of it: that happens on the instance.

Before you start

• A PostgreSQL database with pg_stat_statements enabled (see below)
• A connection string for that database, reachable from the host the instance runs on
• If you self-host: a public address for the instance that is not localhost, since the Collector reports to it from its own container

Connect your database

In your project, go to Setup → Connected databases and click Add connection. Paste the connection string and press Connect.

The instance stores the string, opens one connection to check the database answers, and starts a Collector against it. There is no docker run command and nothing to install on your side.

The dialog stays open, because the answer takes longer than the click. A status line reports the launch. It reads “Starting a Collector” while the image is pulled, which on a first launch takes a few minutes, then “Collector started. Its first report is due within a minute.” Once the first check-in lands it reads “This database is connected”.

A launch that fails says what went wrong and what to do next: nothing answered at that address, credentials refused, no such database, or no container runtime on the instance’s host. Fixing it means disconnecting the database and connecting it again.

Below the status line, Preparing to Analyze lists what the platform did with that first check-in: the Postgres version it read, the planner image it matched, and any extensions your schema declares that it had to compile. A compile takes minutes; every database on that major reuses the image afterwards.

What the Collector sends

Every check-in, once a minute:

• Queries — what pg_stat_statements has tracked, minus the ones your test suite issued.
• The schema — read from the catalog, at most once every five minutes, and sent only when it differs from the last one the platform took.
• Table statistics — the pg_statistic dump, when a cheap pg_class read says the database has grown or changed shape since the last one.

Each read stands on its own: a database without pg_stat_statements still sends its schema and statistics.

What happens next

1. Queries arrive on their own, appearing on the Queries page with their call counts and mean execution time. Pull there queues a fresh schema read for the Collector’s next check-in.
2. The platform prepares a planner matching your database’s Postgres major, so there is something to cost against when a query needs a plan.
3. Plans come from CI. Index recommendations, cost comparisons and Findings are produced when a run analyzes the queries your tests exercised, so set that up next in CI integration.

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 SCHEMA IF NOT EXISTS ext;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements SCHEMA ext;

Skip the SCHEMA clause and the extension lands in public, where its views break any migration tool that reconciles that schema. Why, and how to move an existing one.

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 SCHEMA IF NOT EXISTS ext; CREATE EXTENSION IF NOT EXISTS pg_stat_statements SCHEMA ext;

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 SCHEMA IF NOT EXISTS ext;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements SCHEMA ext;

Verifying it works

After enabling, run:

SELECT count(*) FROM ext.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.