losefor/pg-explain

pg-explain, distributed as the npm package pgexplain, takes the technical output PostgreSQL databases produce when you ask them to explain how they will run a query, and turns it into a human readable report. Database query plans are usually dense and full of jargon, so most tools that display them simply show you the raw tree of steps without telling you whether anything is actually wrong. This tool goes further by running an advisor over the plan that looks for known problem patterns, and for each one it finds it explains what happened, why it matters, and exactly how to fix it, often including a ready to copy SQL command such as the specific index to create. The tool can detect eighteen different kinds of query plan problems, including scans that read far more of a table than needed, sorts and other operations that spill to disk because they ran out of memory, tables whose statistics are outdated and are causing the database to misjudge how much data a step will touch, and risky database changes that could lock a table for longer than expected. It can also show a live snapshot of which database operations are currently blocked and waiting on each other. It works as a command line tool that can read a saved plan from a file, accept one piped in from the terminal, connect directly to a database and safely run a query in read only mode, or compare two plans against each other to catch a performance regression, which is useful in an automated testing pipeline. Reports can be produced in several formats including plain terminal output, Markdown, HTML, and JSON. There is also an optional local web interface called Studio that runs entirely on your own computer, showing an interactive, color coded diagram of the query plan, a history of past runs, and side by side comparisons between them. Any saved database passwords are stored using your operating system's secure credential storage when available. The tool requires Node.js version 22 or newer and is released under the MIT license.