When Your Database Explains Itself: Making Sense of Postgres Query Plans
You've written a query, hit run, and watched it crawl. The database gives you an execution plan—a wall of nested text with cryptic numbers like cost=12.50..12.51 rows=1. It's technically informative, but practically opaque. If you've ever squinted at a Postgres EXPLAIN output and wished it came with a diagram, you're not alone. That's exactly the problem PEV2 solves.
PEV2 is a VueJS component that turns a PostgreSQL execution plan into a visual, graphical representation. It's a rewrite of the abandoned Postgres Explain Visualizer (pev) project, which hasn't seen activity in over three years despite having open issues and pending pull requests. The folks at Dalibo picked up the torch, modernized it with Vue 3, and made it available as a drop-in component or a standalone file.
What It Does
At its core, PEV2 takes the text output of a EXPLAIN query and renders it as an interactive visual diagram. You paste in a plan—something like Aggregate (cost=12.50..12.51 rows=1 width=8) -> Seq Scan on employees—and PEV2 draws it out as nodes and connections, showing you the flow of execution at a glance.
The project is built as a VueJS component, which means it's designed to be embedded into larger web applications rather than standing alone. It depends on Bootstrap 5 for styling, so you'll need that CSS loaded alongside it. The component accepts two key props: plan-source for the actual plan text and plan-query for the associated query string.
Architecturally, PEV2 offers multiple deployment paths to match how you're working. You can use the hosted service at explain.dalibo.com, grab a self-contained HTML file that runs entirely offline, or integrate the component into your own app—either with or without a build toolchain.
Why It's Cool
It rescues a genuinely useful tool from abandonment. The original pev project was excellent but stale. PEV2 doesn't just fork it—it rewrites it with modern Vue 3, bringing the codebase into the present while giving credit where it's due to Alex Tatiyants for the original concept.
The all-in-one local file is a killer feature. You can download pev2.html, double-click it, and have a working visualizer with zero installation and zero network access. No npm install, no server setup, no CDN dependencies. For anyone who's ever been stuck on a locked-down machine or an airplane with a gnarly query to debug, that's genuinely useful.
Multiple integration paths show real-world thinking. Not everyone wants to build a full SPA around a plan visualizer. PEV2 covers the spectrum: use the hosted service for quick sharing with colleagues, use the standalone file for privacy-sensitive work, or drop the component into an existing Vue app. The README even includes examples for both vanilla script-tag setups and proper build-tool workflows with Vite.
It's honest about its dependencies. The README clearly states that PEV2 requires Bootstrap CSS to function. That's refreshingly direct—no pretending it's a zero-dependency miracle. You know what you're getting into before you start.
The component API is minimal and sensible. Two props (plan-source and plan-query), one component registration, and you're done. The example code is short enough to read in under a minute, which is exactly how library documentation should work.
How to Try It
The fastest way to see PEV2 in action is to use the hosted service at explain.dalibo.com—paste in your plan and you're done. But if you want to run it locally, here's the no-fuss approach:
- Download the standalone file from the releases page
- Open it in your browser—no installation, no network connection needed
If you're integrating it into a web app with build tools, install it via npm:
npm install pev2
Then import the component and its styles:
import { Plan } from "pev2"
import "pev2/dist/pev2.css"
Register it in your component, add Bootstrap 5 CSS to your header, and use it in your template:
<pev2 :plan-source="plan" :plan-query="query"></pev2>
The README includes live demos on StackBlitz for both the vanilla script-tag approach and the Vite-based build setup, which are worth checking out to see the component in action before you commit to an integration path.
Final Thoughts
PEV2 is a focused tool that does one thing well: making Postgres execution plans legible. It's not trying to be a full database monitoring suite or a query optimizer—it's a visualizer, and it sticks to that lane. The project is particularly valuable if you're already working in a Vue environment or if you frequently need to explain query performance to others (the hosted service makes sharing plans with colleagues trivial). The rewrite breathes life into a tool that deserved better than abandonment, and the multiple deployment options mean you can use it however fits your workflow. If you've ever struggled to explain why a query is slow—to yourself or to someone else—this is worth a look.
Follow @githubprojects for more developer tools and open source projects.