PgQueryNarrative

PgQueryNarrative investigates PostgreSQL queries: it shows plan findings, proposes a rewrite or index from the query's own parse tree, compares the plans, verifies that the result rows match, and writes the evidence up as a report.

flowchart LR
  A[Expensive query] --> B[Plan findings]
  B --> C[Proposed rewrite<br/>or index]
  C --> D[Measured compare]
  D --> E[Result verification]
  E --> F[Engineering report]

It does not apply a rewrite, index, or DDL statement to the database it investigates; a person reviews and applies the change. User SQL runs through a dedicated read-only role. See Concepts for vocabulary, Architecture for the system map, and Trust model for the security boundaries.

Getting started

• Quick start
• Installation
• Connect your PostgreSQL
• pqn: run from a terminal, no server

Query investigation

• Investigate a slow query
• Understand plan findings
• Suggest and rank candidates
• Compare plans
• Verify result equivalence
• Regressions and applied fixes

Security and operations

• Database roles
• Query execution safety
• Deployment
• Production configuration

Integrations

• REST API
• MCP server
• PostgreSQL extensions
• LLM providers

Development

• Setup
• Repository architecture
• Testing

How to contribute, get help, and report a vulnerability: Contributing, Security policy.

Reference

Checked against the code by make docs-contract-check: configuration, API, API errors, status vocabulary, CLI, pqn, versions and limits.

Local preview

make docs   # http://127.0.0.1:8000