Introduction

PostgreSQL has one of the most sophisticated query planners of any database. It evaluates dozens of execution strategies for every query, estimates their costs using table statistics, and picks the cheapest one — all in milliseconds. The problem is that this process is almost entirely invisible.

Explain EXPLAIN to me

Standard EXPLAIN output shows you the plan PostgreSQL chose, but not the plans it rejected. It shows a total cost number, but not what drives that cost. It tells you a sort happened, but not whether the sort was avoidable. And it says nothing about indexes that exist but couldn’t be used, or indexes that don’t exist but would help.

For most developers, this makes EXPLAIN output something you glance at but can’t act on. You know a query is slow. You can see the plan. But there’s no clear path from one to the other — no explanation of what to change, or whether a change would even help.

The usual alternative is to guess at indexes, or wait until queries are slow enough to become incidents and troubleshoot under pressure.

What Query Doctor does

Query Doctor opens up the black box. It connects to your PostgreSQL database, reads every query tracked by pg_stat_statements, and runs each one through an analysis pipeline that surfaces information PostgreSQL knows internally but doesn’t normally expose.

Augmented explain plans

Query Doctor extends standard EXPLAIN output with fields that help you understand why a plan looks the way it does:

• Cost breakdowns — what contributes to a node’s cost (I/O, CPU, filtering, startup)
• Alternative plans — execution strategies the planner considered and rejected, with the reason
• Ineligible indexes — indexes that exist on the table but couldn’t serve the query, and why not
• Order analysis — whether a sort node receives data in the order it needs, or has to re-sort

These fields are marked with an asterisk (*) in the UI and aren’t part of standard PostgreSQL EXPLAIN output. They’re computed by the analyzer, an open-source container that runs on your machine.

Production-grade optimization without production access

Beyond explaining what’s happening today, Query Doctor can tell you what would happen if you changed the schema. It imports your database’s statistics — row counts, value distributions, correlations — and uses PostgreSQL’s own cost model to evaluate hypothetical indexes. The improvement percentages you see aren’t estimates or heuristics — they’re the output of the same planner, with the same statistics, comparing two real plans.

Importantly, this works with any database you can connect to — it doesn’t need to be production. The analyzer reads schema metadata and planner statistics, not your actual data. If your staging or development database has representative statistics (i.e. ANALYZE has been run), Query Doctor’s recommendations will be just as accurate as if it were pointed at production. This means you can get production-quality optimization insights without ever exposing a production connection string.

When an improvement is found, Query Doctor provides the exact CREATE INDEX statement. When no improvement is possible, it tells you that too — which is just as valuable, because it means you can stop looking.

Query analysis

Not every performance issue requires an index change. Query Doctor parses your SQL and flags common anti-patterns — functions on indexed columns, leading wildcard searches, NULL comparisons with equality operators, unnecessary DISTINCT, missing join conditions, and more. Each nudge points to the exact location in the query and explains both the problem and the fix.

Source-to-query tracing

With SQLCommenter integration, Query Doctor can trace each query back to the file, route, or function that produced it — turning a parameterized SQL string into a clickable link to your source code.

CI integration

The analyzer also runs as a GitHub Action, so you can catch query regressions in pull requests before they reach production.

What it doesn’t do

Query Doctor is an analysis and recommendation tool. It does not:

• Require production access (any database with representative statistics works — staging, development, or a read replica)
• Execute queries on your database (it reads pg_stat_statements and pg_statistic, both read-only)
• Create or drop indexes automatically (you apply recommendations yourself, after review)
• Modify your database in any way (the analyzer is read-only)
• Send your data to external servers (the analyzer runs locally; query text and statistics stay on your machine)

You stay in control. Query Doctor gives you the information to make informed decisions — the decisions remain yours.