rustcmdpev 0.2.0

Visualize PostgreSQL EXPLAIN JSON output in a terminal-friendly tree
rustcmdpev-0.2.0 is not a library.
Visit the last successful build: rustcmdpev-0.1.0

Rustcmdpev

Crates.io Docs.rs CI Release

A command-line Rust Postgres query visualizer, heavily inspired by the excellent (web-based) pev. It started out being ported from gocmdpev

Demo

rustcmdpev screenshot

Documentation

  • Docs site source: docs/
  • Docs site instructions: docs/README.md
  • Build the docs site (requires mdbook):
mdbook build docs

Installation

Use the crates.io install path once a tagged release is published:

cargo install rustcmdpev --locked
rustcmdpev --help

For local checkout work before a release is published, install from the workspace:

cargo install --path rustcmdpev --locked
rustcmdpev --help

If you prefer not to install globally, a source-first build still works:

  1. Install Rust
  2. Build the workspace:
cargo build --release -p rustcmdpev
  1. Run the binary:
./target/release/rustcmdpev --help

Tagged releases publish platform archives with checksums through .github/workflows/release.yml.

Release tags follow semantic versioning: use vMAJOR.MINOR.PATCH for stable releases and vMAJOR.MINOR.PATCH-PRERELEASE for pre-release builds.

Stability: rustcmdpev and rustcmdpev-core are currently in the 0.x series and should be treated as pre-stable. Both the CLI surface and the library API may change between 0.MINOR releases; patch releases remain backward-compatible bug fixes. See docs/src/versioning.md for the full pre-1.0 stability posture. The 0.1.0 on crates.io is the legacy 2020 release of the original port; the rewrite ships as 0.2.0 (see docs/src/adr-0001-v0.2.0-supersedes-0.1.0.md).

Homebrew is not published yet; the roadmap is to add a tap/formula after v1.0.0 release automation and install smoke verification are stable. Until then, use cargo install or the tagged release archives.

Quickstart

  1. Build the CLI:
cargo build --release -p rustcmdpev
  1. Run the bundled example plan:
./target/release/rustcmdpev --input example.json --format pretty --width 80
  1. Or use the reproducible demo alias:
cargo demo

Overview

Usage

Generate a query plan with all the trimmings by prefixing your query with:

EXPLAIN (ANALYZE, COSTS, VERBOSE, BUFFERS, FORMAT JSON)

Then pipe the resulting query plan into rustcmdpev.

On MacOS you can just grab a query on your clipboard and run this one-liner:

pbpaste | sed '1s/^/EXPLAIN (ANALYZE, COSTS, VERBOSE, BUFFERS, FORMAT JSON) /' | psql -qXAt <DATABASE> | rustcmdpev

Cross-platform psql examples for Linux, macOS, PowerShell, and CMD are documented in docs/src/workflows.md.

Quickstart with a bundled example:

cargo run -p rustcmdpev -- --input example.json --format pretty --width 80

Reproducible local demo alias:

cargo demo

Stdin JSON contract (MVP parity)

  • When --input is not provided, stdin must contain JSON text.
  • Top-level JSON must be an array with at least one object containing Plan.
  • Empty stdin, invalid JSON, or unsupported top-level shape are contract errors and should exit non-zero.

Source of truth: docs/src/parity.md -> "MVP v1 stdin JSON contract".

CLI flags

rustcmdpev [--input <PATH>] [--format pretty|json|table] [--color auto|always|never] [--width <N>] [--compat]
  • --input, -i <PATH>: read EXPLAIN JSON from a file instead of stdin
  • --format: output format (pretty, json, table)
  • --color: color policy (always force ANSI, never disable, auto = TTY-detect and respect NO_COLOR)
  • --width: tree render width (default: 60)
  • --compat: parity-target mode (--format pretty only, legacy width 60)
  • -v, --verbose: increase log verbosity (warn default, -v = info, -vv+ = debug)
  • -q, --quiet: reduce logs to error only
  • RUST_LOG: override log filter via tracing-subscriber env filter syntax

Exit codes

  • 0: success
  • 2: input read error (stdin/file)
  • 3: invalid/contract-violating input payload
  • 4: invalid compatibility flag combination
  • 5: output serialization error
  • 6: core processing/render error

Run help:

rustcmdpev --help

Examples

  • example.json: canonical bundled sample plan for docs, CI smoke tests, and install verification.
  • examples/basic_seq_scan.json: smallest useful sample plan for smoke tests and docs.
  • examples/hash_join.json: nested tree sample for demos and screenshots.

Local development

View sample output

cargo demo

Testing

To see output from print statements, run with nocapture flag:

cargo test -- --nocapture

Project hygiene commands:

  • cargo fmt --all -- --check
  • cargo clippy --workspace --all-targets -- -D warnings
  • cargo deny check --all-features
  • git cliff --config cliff.toml