Query Plan Baseline Tracking & Performance Regression Automation
Production-grade guides and runbooks for automating query plan tracking, detecting
performance regressions, and enforcing CI/CD gates.
🌐 Visit the live site → www.queryplan.org
QueryPlan.org is a free, open reference resource for engineers who treat database query performance as a first-class control plane. Query performance regressions are among the most insidious failure modes in data-intensive platforms: they rarely trip infrastructure alerts, yet they quietly degrade p95/p99 latency, inflate compute spend, and cascade into application-level circuit breakers.
This site treats query plan tracking as an automated, testable pipeline — capture execution plans,
anchor them to deterministic baselines, and gate risky changes before they ever reach production
traffic. Every page is a deep, self-contained runbook with exact numeric thresholds, runnable
asyncio Python (with asyncpg, structlog, and OpenTelemetry), JSON Schema contracts, alerting
rules, and hand-drawn architecture diagrams — no toy examples, no filler.
Database SREs, query-optimization engineers, Python DevOps builders, and platform teams running PostgreSQL, MySQL, and distributed SQL at scale.
The library is organized around a strict, automation-first pipeline — Capture → Baseline → Regression → CI Gate — across four in-depth areas:
| Area | What it covers |
|---|---|
| Automated EXPLAIN Capture & Storage | Async ingestion of EXPLAIN output at high throughput, cross-engine plan normalization, centralized log routing, and metadata schema validation. |
| Core Architecture & Baselining | Deterministic plan hashing, regression thresholds, cost-to-latency mapping across engines, and security boundaries for baseline storage. |
| Regression Detection & Rule Engines | Cost-delta tracking, join-type-shift detection, statistical-distance drift scoring, graph-diff plan comparison, baseline promotion/rollback, and index recommendation. |
| CI/CD Gate Integration | Wiring plan-regression gates into GitHub Actions, GitLab CI, and Argo CD, plus canary and progressive-delivery gate design. |
Start with the full content library → or browse the curated picks on the homepage.
- 50+ in-depth pages covering the entire capture-to-deploy pipeline.
- Runnable, production-grade code — every snippet targets real
asyncioservices with structured logging and tracing, not pseudocode. - Exact numbers everywhere — SLO bands, alert thresholds, and tuning knobs are concrete values.
- Original inline SVG diagrams — architecture, data-flow, and decision diagrams drawn to a single design system, theme-aware and accessible.
- Accessible & fast — WCAG 2 A/AA checked, mobile-performance budgeted, structured data on every page, and a fully offline-capable PWA.
A static site generated with Eleventy (11ty) and deployed on Cloudflare Workers.
- Content: Markdown under
content/, organized as topic areas → guides → runbooks. - Templates: Nunjucks in
_includes/; the page layout auto-derives navigation, breadcrumbs, related links, and JSON-LD structured data. - Styling: a single hand-written design system in
assets/css/style.css. - Math & code: KaTeX for inline math and Prism for syntax highlighting, both self-hosted (no external CDNs).
npm install # install dependencies
npm run serve # local dev server with live reload
npm run build # production build to _site/
npm run deploy # build and deploy to Cloudflarecontent/ Markdown source (four topic areas → guides → runbooks)
_includes/ Nunjucks layouts and partials (header, footer, page)
_data/ Global site data (site.js) and asset cache-busting
assets/ CSS, JS, icons, images, and self-hosted vendor libraries
eleventy.config.js Build config: markdown pipeline, filters, transforms
index.njk Homepage
content-index.njk Content library index
Spotted an error, a stale threshold, or a diagram that could be clearer? Issues and pull requests are welcome — corrections to the technical content are especially appreciated.
Built and maintained by @queryplan · www.queryplan.org