QueryLens

QueryLens is a Postgres query plan analyzer. You paste your SQL, it runs EXPLAIN ANALYZE on your database and shows you exactly what Postgres is doing — which nodes are slow, where the cost is going, and a health score so you know at a glance how good or bad the query is.

It is useful when you have a slow query and want to understand why, without having to read raw EXPLAIN output by hand.

Demo: Watch on Loom

---

What it does

• Connect to any Postgres database — add a connection string from the UI, works with local or remote DBs
• Analyze queries — runs EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) on your DB and parses the result
• Plan Tree — shows the execution plan as a tree with timing and cost at each node
• Flame Graph — shows where time is being spent across all nodes visually
• Stats view — lists every node with self time, row estimates, and warnings
• Health score — a 0–100 score based on seq scans, row estimate mismatches, nested loops, and hotspots
• Save queries — save a query to a collection, tag it, star it
• Run history — every time you analyze a saved query, it records the run; you can see the health score improve over time in the Runs tab

For details on how the health score and warnings work, see docs/heuristics.md.

---

Tech stack

Layer	What
Backend	Go, chi, sqlx, pgx
Frontend	React 19, Vite, RTK Query, Tailwind v4
Database	Postgres 16 (via Docker)
Migrate	golang-migrate

---

Prerequisites

Make sure these are installed:

• Docker
• Go 1.25+
• Node.js 20+
• golang-migrate CLI

Install golang-migrate on Mac:

brew install golang-migrate

---

Running locally

1. Start Postgres

make up

Starts a Postgres container on port 5433. Username and password are both querylens.

2. Run migrations

make migrate-up

Creates all the tables.

3. Start the backend

make run

API runs on http://localhost:8080.

4. Start the frontend

cd web
npm install
npm run dev

Frontend runs on http://localhost:5173. Open that in your browser.

---

First time setup in the UI

1. Open http://localhost:5173
2. Go to Connections and add a Postgres connection string — point it at any database you want to analyze (your local app DB, staging, anything)
3. Select that connection from the dropdown in the header
4. Go to Query, paste your SQL, and click Analyze (or press ⌘⇧E)
5. Switch between Plan Tree, Flame Graph, and Stats tabs to explore the plan
6. Click Save to save a query to your library — future runs against it will show up in the Runs tab so you can track improvements over time

---

Useful commands

Command	What it does
make up	Start Postgres via Docker Compose
make down	Stop Postgres
make run	Start the Go API server
make migrate-up	Apply all pending DB migrations
make migrate-down	Roll back the last migration
make psql	Open a psql shell into the local DB
make test	Run unit tests
make test-integration	Run integration tests against the DB

---

Project structure

.
├── api/          — HTTP handlers and routing (chi)
├── analyzer/     — Plan analysis, health scoring, warnings
├── parser/       — Parses raw EXPLAIN JSON from Postgres
├── store/        — Database layer (sqlx) + migrations
├── cmd/server/   — Main entry point
├── docs/         — Additional documentation
└── web/          — React frontend (Vite + RTK Query)

---

Docs

• docs/heuristics.md — how the health score is calculated and what each warning means