pgbot

A read-only PostgreSQL diagnostic that ships as one static Go binary. It connects with a pg_monitor role, reads the server’s own statistics views — pg_stat_activity, pg_stat_statements, pg_stat_database, WAL, IO, checkpoints, replication slots, locks, table and index sizes — and prints a graded report: a four-row gauge strip of vital signs, a checked line naming the subsystems that came back clean, a health score out of 100, then findings bucketed CRITICAL, WARNING and NOTE. Every run also writes a local SQLite baseline, so from the third run on it can say what changed and by how much, and pgbot why chains a symptom to its mechanism and antecedent out of that stored history. Output fans out to a versioned, PII-free JSON contract with a published JSON Schema, SARIF for the GitHub Security tab, JUnit, Prometheus textfile format and a self-contained HTML page. pgbot mcp exposes the same findings to an agent over the Model Context Protocol, while ask and explain let a model read them, never generate them.

Who built itThe repository belongs to the pgrundev organization, and 252 of its 310 commits carry Shapalov’s account, name and email; he also wrote the pull request that swapped the Postgres driver and the one that put the mark into the README header. Dependabot accounts for 22 commits, and twelve other people appear in the contributor list: 10xdev4u-alt and DivyamTalwar with eight each, lofoneh with seven, DiegoDAF with three, edwardsb and GitHub’s Copilot with two, and six contributors with one apiece. All 310 commits resolve to a linked account, and 65 carry co-author trailers — 21 Claude Opus 4.8, thirteen dependabot, ten Claude Fable 5, nine Claude Fable 5.1 and eight the-ai-developer.

1. 01

   Twelve minutes from an empty repository to the first commit

   The repository was created at 23:41:52 on 2026-08-11 and its oldest commit — Add files via upload — lands twelve minutes later, at 23:54:02 on the same day, so the project begins as an upload rather than a first push. Nine weeks on it holds 310 commits, 229 of them in August and 81 in September, and twenty releases from v0.2.0 on 2026-08-17 to v0.8.1 on 2026-09-06. The rhythm is bursty rather than steady: four releases inside 25 minutes on the evening of 2026-08-31, from v0.6.0 at 19:09:30 to v0.6.3 at 19:34:56; three more across 2026-09-01; four within eighteen hours on 2026-08-18. Around that sit 1,348 stars, 66 forks, four watchers and 32 open issues, and a tag list that carries the v1 the GitHub Action pins as well as a v0.8.0 that appears in no release entry. Fourteen accounts have contributed: Shapalov with 252 commits, dependabot with 22, and DivyamTalwar and 10xdev4u-alt with eight each.

2. 02

   A specification approved in chat, then edited by its own implementation

   docs/superpowers/specs/2026-08-23-pgbot-why-design.md is the repository’s one architecture document — 6,715 bytes — and it opens by dating itself: approved in chat on 2026-08-23. It designs pgbot why as rule-based causal chains over the stored snapshot history, and it names what it rejected: generic statistical cross-correlation, because that is “spurious, unexplainable — off-brand”, and any LLM-generated causation, because it “violates AI never generates findings”. The document specifies five mechanism rules, an onset detector, a confidence score whose hard gate is temporal alignment, a single new store read, a new MCP tool, and a testing plan that starts every rule red. Then comes the section this archive rarely gets to read: “Implementation deviations (v1, 2026-08-24)”, written the next day. why shipped fully offline, with no --offline flag, following the repository’s existing diff convention — the store already holds a fresh snapshot from the user’s last inspect, so connecting added “a failure mode without adding signal”. One of the five rules shipped and the other four are follow-ups on the same engine; the target argument was dropped because the report already caps at the three worst chains.

3. 03

   Replacing the Postgres driver, and a test that failed for the right reason

   Pull request 114, from the maintainer on 2026-09-30, takes pgbot off pgx and onto pggo v0.1.0 — a dependency-free wire-protocol client from the same organization — so that pgx, pgpassfile, pgservicefile and puddle leave the module graph. The connection layer went first: pool, session pins, read-only transactions, the SSH DialFunc, the pooler and PgDog probes, the Aurora --all-instances host override. Then the collectors, erd, logs, advise with its EXPLAIN (GENERIC_PLAN), the MCP tools and the integration tests, verified against PostgreSQL 13 through 18 and 19beta1 over TLS. The first CI run failed TestIntegration_ratesArePresent on PostgreSQL 15 and up while 14 passed, and the maintainer’s comment on the pull request is why this is worth recording: since PostgreSQL 15 a backend flushes its counters to pg_stat_database only when it goes idle, and CI’s write load was one long DO loop, so those commits were invisible while the test sampled. Reproduced locally, xact_commit moved by exactly one per sample — the sampler counting itself. Under that load the old build passed by measuring its own traffic, and the maintainer writes that it “would also have passed with the stats-caching bug the guard exists to catch”; the new build, leaving less self-traffic in the window, correctly saw zero transactions per second.

4. 04

   Twenty issue numbers in one afternoon

   Between 00:18 and 19:44 on 2026-09-22 a contributor named DivyamTalwar opened twenty consecutive numbered items — 85 through 104 — nine of them an issue paired with the pull request that fixes it, plus two lone pull requests. All but the first are still open on the last day of the record. The pairs read like a method: reproduce against a named upstream commit, say which parts of the test are real (the actual Cobra command, the real file-backed SQLite store, the real npm layout) and which are injected, record the verified commit hash, and show bash scripts/gate.sh or the race suite passing on that committed HEAD. The defects are one theme — an observation that was never made is indistinguishable from a measured zero. A failed collector returns a section marked unavailable, and store.Save lifted its zero-valued fields into trend columns, inventing a database size of zero; unavailable sections in a stored baseline resurfaced as false connection drops and standby losses; WAL archiving findings were measured against the viewer’s clock instead of the snapshot’s collection time, so an unchanged serialized Context changed its verdict when recomputed later. The fix proposed in each case has the same shape: leave unknown as SQL NULL, keep a measured zero, and refuse to compare sections whose provenance is not observable.

5. 05

   A schema version is not a free number

   The JSON contract is published as one schema file per version — schema/pgbot-context-1.1.0.json through 1.5.0.json, 175 KB in total, generated by a 1,512-byte tools/schemagen/main.go — and because the file name carries the version, two pull requests that both bump it collide. That is what happened to the replica-identity finding in pull request 113: it began as 1.4.0, another pull request took the number, and the contributor’s last comment reports the conflicts resolved and the schema regenerated as 1.5.0. The maintainer’s side of that exchange is one line — “@lofoneh, tnx, pls resolve conflicts” — and the same line appears under DivyamTalwar’s advisor pull request at 04:27:01 on 2026-09-30, one minute after the newest commit in the material, a dependabot bump. That contributor had already answered his own CI failure in the thread: the PostgreSQL 16 to 18 containers lacked the HypoPG server package the new regression needed, a follow-up commit installs it and documents the prerequisite, and he notes that no assertion or integration check was disabled. The finding itself was established by running the real UPDATE on each published table of a wal_level=logical server, and it reports the case he “wouldn’t have guessed”: after DROP INDEX, relreplident stays i with nothing behind it.

6. 06

   Documentation treated as an artifact, down to the alpha channel

   The README alone is 60,582 bytes, and the repository’s prose is not an afterthought: 61 finding pages under docs/findings/, 296 KB, from a 2,126-byte note on double-logged pgaudit output to an 8,364-byte page on a blocked vacuum horizon, with an index that browses them by symptom and a template for the next one. Nor is it prose that nothing checks: internal/findings/docs_catalog_test.go and internal/collect/docverify_integration_test.go hold the catalogue against the findings the engine actually emits, and pgbot explain-finding <id> serves the same page from the binary, so an agent explains a recommendation in pgbot’s words instead of inventing them. The same instinct covers the invariants the README calls load-bearing — read-only, deterministic findings, PII-free output — which are held by tests rather than by review: a readonly_sql_test.go for the collected SQL, a 1,877-byte no_explain_analyze_test.go keeping the executing form of EXPLAIN out of the collectors, a 10,195-byte redaction test, and safety-surface tests in the findings and render packages. It shows in a one-file change too: pull request 106 puts the project’s mark in the README header and explains it in three paragraphs — the image is committed rather than hotlinked, because the avatar URL is bound to the organization avatar and its ?s= sizes are too small for a HiDPI display; the dark frame stays, because the uploaded file is RGB with no transparency, so the rounded corners visible on GitHub are GitHub’s own crop, and dropped in as-is the mark rendered as a hard black square on the light theme; and cutting out just the circle was tried first and failed, because the face is white and vanishes against the light theme. A rounded rectangle was masked into the alpha channel instead.