Analyzer

The analyzer is an open-source Docker container that connects to your PostgreSQL database. It collects your schema, table statistics and query text, sends them to Query Doctor, and costs candidate indexes against a copy of your schema.

Source code: github.com/query-doctor/analyzer

What it reads

The analyzer collects:

Schema — tables, columns, indexes, constraints, functions, views, types, triggers, and extensions.
Query statistics — recent queries and their execution metrics from the pg_stat_statements extension. Note that pg_stat_statements can contain real query text, including literal parameter values depending on your PostgreSQL configuration.
Table statistics — row estimates and sample rows from your tables, used for query plan analysis. These are real values read from your database.

What leaves your database

All three go to Query Doctor’s API at https://api.querydoctor.com, which stores them against your project. The table statistics carry the most sensitive data: pg_statistic rows include the most common values and histogram bounds Postgres sampled from your columns, so they contain real values out of your tables.

The TOKEN you pass the container authenticates that upload. No setting keeps the data on your machine.

What it writes to your database

Two actions write to the database in your connection string. You trigger both from the app:

Installing pg_stat_statements runs CREATE EXTENSION pg_stat_statements, plus ALTER SYSTEM SET shared_preload_libraries if the extension isn’t already preloaded. The ALTER SYSTEM takes effect on the next server restart.
Resetting statistics runs pg_stat_statements_reset().

Testing index recommendations writes nothing here. The analyzer copies your schema into a scratch database of its own, creates the candidate indexes there inside a transaction, and rolls that transaction back.

Running the analyzer

Docker (recommended)

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

Build from source

git clone https://github.com/Query-Doctor/analyzer.git
cd analyzer
docker build -t analyzer .
docker run -p 2345:2345 analyzer

The analyzer listens on port 2345 by default.

Connecting from IndeX-Ray

Start the analyzer.
Open IndeX-Ray and begin the onboarding flow.
The default endpoint is http://localhost:2345. If you’re running the analyzer on a different host or port, expand Advanced settings in the first onboarding step to change it.
Enter your PostgreSQL connection string and sync.

IndeX-Ray checks the analyzer’s health endpoint (GET /health) every 10 seconds and shows a status indicator so you know the connection is live.

API

The analyzer exposes two endpoints:

`GET /health`

Returns { "status": "ok" } when the analyzer is running and ready.

`POST /postgres`

Syncs schema and query data from the source database.

Request body:

{
  "db": "postgresql://user:password@host:5432/database"
}

Response: a RemoteSyncResponse containing:

Field	Description
`meta`	Analyzer version and inferred statistics strategy
`schema`	Full database schema (tables, indexes, constraints, etc.)
`queries`	Recent queries from `pg_stat_statements` with metrics
`disabledIndexes`	Indexes that are currently disabled

Each field is wrapped in { type: "ok", value: ... } or { type: "error", error: "..." } so partial failures (e.g. pg_stat_statements not installed) don’t block the rest of the sync.

Prerequisites on the source database

pg_stat_statements extension — required for query statistics. Install it with:
```
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
```
The extension must also be added to shared_preload_libraries in your PostgreSQL config, which requires a server restart.
Database access — the user in your connection string needs read access to the schema and the statistics views. That is enough for everything except installing pg_stat_statements from the app, which needs a superuser: CREATE EXTENSION and ALTER SYSTEM both require one. Install the extension yourself and read access covers the rest.