{"id":37147680,"url":"https://github.com/mickamy/xplain","last_synced_at":"2026-01-14T17:25:29.400Z","repository":{"id":322913172,"uuid":"1090675415","full_name":"mickamy/xplain","owner":"mickamy","description":"xplain transforms PostgreSQL EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) output into actionable insights.","archived":false,"fork":false,"pushed_at":"2025-11-07T01:32:45.000Z","size":121,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-07T03:22:14.099Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mickamy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-06T01:41:29.000Z","updated_at":"2025-11-07T01:32:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mickamy/xplain","commit_stats":null,"previous_names":["mickamy/xplain"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mickamy/xplain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mickamy%2Fxplain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mickamy%2Fxplain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mickamy%2Fxplain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mickamy%2Fxplain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mickamy","download_url":"https://codeload.github.com/mickamy/xplain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mickamy%2Fxplain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28427500,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T16:38:47.836Z","status":"ssl_error","status_checked_at":"2026-01-14T16:34:59.695Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T17:25:28.897Z","updated_at":"2026-01-14T17:25:29.394Z","avatar_url":"https://github.com/mickamy.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xplain\n\n`xplain` transforms PostgreSQL `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` output into actionable insights.  \nIt highlights bottlenecks, surfaces skew between estimated and actual rows, and produces human-friendly reports for\nterminals, HTML, and CI diff workflows.\n\n## Features\n\n- **Parser \u0026 model** – Reads native JSON plans and normalises them into a rich plan tree.\n- **Analyzer** – Computes inclusive/exclusive timings, buffer usage, and estimation drift metrics.\n- **TUI renderer** – Prints a colour-coded tree with ratio bars and warnings for hot nodes.\n- **HTML renderer** – Generates a compact, shareable report with heat-mapped cards and summaries.\n- **Insight engine** – Highlights hotspots, estimation drift, buffer churn, and parallel inefficiencies with quick\n  remediation hints.\n  - Spots issues such as nested-loop explosions, buffer churn, new temp spills, parallel worker shortfall/imbalance.\n- **Diff mode** – Compares two plans and emits Markdown summaries suited for PRs/CI.\n- **Runner** – Executes `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` against a PostgreSQL DSN.\n\n## Getting Started\n\n```bash\ngo install github.com/mickamy/xplain@latest\nxplain version\n```\n\n\u003e Note: The CLI requires access to PostgreSQL when using `xplain run`. Supply the connection string via `--url` or the\n`DATABASE_URL` environment variable. The other commands operate on saved explain JSON files.\n\n### 1. Capture a plan\n\n```bash\nDATABASE_URL=\"postgres://postgres:password@localhost:5432/bench\" \\\n  xplain run --sql ./samples/pgbench_hot.sql \\\n  --out ./plans/pgbench_hot.json\n```\n\nOr capture **and** inspect in one go:\n\n```bash\nDATABASE_URL=\"postgres://postgres:password@localhost:5432/bench\" \\\n  xplain analyze --sql ./samples/pgbench_hot.sql --mode tui\n```\n\nPass `--query \"SELECT ...\"` if you prefer to provide SQL inline.\n\n### 2. Inspect in the terminal\n\n```bash\nxplain report --input ./plans/pgbench_hot.json --mode tui\n```\n\n### 3. Produce an HTML report\n\n```bash\nxplain report --input ./plans/pgbench_hot.json --mode html --out report.html\n```\n\n### 4. Diff two plans\n\n```bash\nxplain diff --base ./plans/before.json \\\n  --target ./plans/after.json \\\n  --format md --out plan-regression.md\n```\n\n## Samples\n\nThe repository includes pgbench-derived examples to try locally:\n\n- `samples/pgbench_hot.sql` / `pgbench_hot.json` — a buffer-intensive query that highlights hotspots\n- `samples/pgbench_branches.sql` / `pgbench_branches.json` — a lightweight lookup over the branches table\n- `samples/nested_loop_noindex.sql` / `nloop_base.json` / `nloop_index.json` — nested loop before/after adding an index\n- `samples/nloop_diff.md` / `nloop_diff.json` — Markdown and JSON diff comparing those two plans\n- `samples/config.example.json` — configuration template for tuning thresholds\n\nRender it in the terminal or export HTML:\n\n```bash\nxplain report --input samples/pgbench_hot.json --mode tui\nxplain report --input samples/pgbench_hot.json --mode html --out samples/pgbench_hot.html\nxplain report --input samples/pgbench_branches.json --mode tui\n```\n\nEach report starts with an *Insights* block that calls out the dominant hotspots, estimator drift, buffer churn, and\nparallel inefficiencies so you know where to focus first.\n\nTo regenerate the plan yourself, point `DATABASE_URL` at a pgbench instance and run:\n\n```bash\ndatabase_url=\"postgres://postgres:password@localhost:5432/bench\"\nDATABASE_URL=\"$database_url\" xplain run --sql samples/pgbench_hot.sql --out samples/pgbench_hot.json\nDATABASE_URL=\"$database_url\" xplain run --sql samples/pgbench_branches.sql --out samples/pgbench_branches.json\n\n# diff the nested loop scenario once index is added\nxplain diff --base samples/nloop_base.json \\\n  --target samples/nloop_index.json \\\n  --format md --min-delta 0.5 --min-percent 1 \\\n  --out samples/nloop_diff.md\n```\n\n### Diff Output Formats\n\nMarkdown is the default. For CI or tooling, you can request JSON:\n\n```bash\nxplain diff --base samples/nloop_base.json \\\n  --target samples/nloop_index.json \\\n  --format json --min-delta 0.5 --min-percent 1 |\n  jq .\n```\n\nSee `samples/nloop_diff.json` for a full example payload.\n\n## Configuration\n\nThresholds used by the insight engine and diff output can be tuned via JSON configuration.\n\n```json\n{\n  \"insights\": {\n    \"hotspot_critical_percent\": 0.5,\n    \"buffer_warning_blocks\": 2000,\n    \"nested_loop_warn_loops\": 200\n  },\n  \"diff\": {\n    \"min_self_delta_ms\": 1.0,\n    \"min_percent_change\": 2.5\n  }\n}\n```\n\nSpecify `--config path/to/config.json` (or set `XPLAIN_CONFIG`) to override thresholds globally. Any field you omit keeps its default value.\n\n## Roadmap Ideas\n\n- Enrich the analyser with pattern-based tuning hints (indexes, stats, batching).\n- Deeper diff alignment for complex plan reshapes (fingerprints per subtree).\n- Optional web UI with interactive sunburst/heatmap navigation.\n- Exporters for JSON/CSV metrics to feed dashboards or notebooks.\n\n## Development\n\n```bash\ngo test ./...\n```\n\nYou can also drive common tasks via the Makefile:\n\n```bash\nmake build VERSION=0.1.0\nmake test\nmake version\n```\n\nDuring development you can regenerate module metadata with:\n\n```bash\ngo mod tidy\n```\n\nThe repository defaults to ASCII output for portability; ANSI colour can be disabled with `--color=false`.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmickamy%2Fxplain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmickamy%2Fxplain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmickamy%2Fxplain/lists"}