feat(pg_top_queries): add io_read_time_ms / io_write_time_ms for pg_stat_statements >= 1.10

[HighviewOne]

Closes #11.

What

pg_top_queries previously had no way to tell whether a slow query was CPU-bound or IO-bound. pg_stat_statements 1.10 (Postgres 16) added shared_blk_read_time and shared_blk_write_time which answer exactly that question.

How

• Gate on compareVersions(extVersion, "1.10") >= 0 — same pattern already used for the 1.8 column-rename detection
• NULLIF(shared_blk_read_time, 0) converts zero (meaning track_io_timing = off) to null so callers can distinguish "timing disabled" from "query did no IO"
• When pg_stat_statements < 1.10, the columns are absent from the result entirely (not null, not zero — just not there)
• Tool description updated to mention the columns and how to enable track_io_timing

Test

Added an integration test that:

• Checks the installed extversion and skips the column assertion if < 1.10 (environment-independent)
• When >= 1.10: asserts io_read_time_ms and io_write_time_ms are present as keys on every row
• Asserts values are either null or a JS number (not a string)

Tested locally against pg_stat_statements 1.12 on Postgres 18. All 87 integration tests pass.

🤖 Generated with Claude Code

[jeffyaw]

Review punch list for this PR. Item 1 is a blocker -- as written the feature breaks pg_top_queries on every PG 15/16 cluster, and the PG17/PG18-only test matrix can't see it. Verified against the PG 16 docs: pg_stat_statements 1.10 has only blk_read_time / blk_write_time; the shared_blk_* names arrive with 1.11 (PG 17).

1. src/tools/stats.ts (new ioTimingCols block) -- bug, breaks the tool on PG 15/16: the gate fires at compareVersions(extVersion, "1.10") >= 0 but selects shared_blk_read_time / shared_blk_write_time, which only exist in pg_stat_statements 1.11. On a 1.10 cluster every pg_top_queries call hard-errors with column "shared_blk_read_time" does not exist. Fix: pick the column name by version (blk_read_time for < 1.11, shared_blk_* for >= 1.11 -- the old names have existed with identical ms semantics since 1.1), or at minimum bump the gate to "1.11". The comment "added in pg_stat_statements 1.10 (Postgres 16)" is also off -- 1.10 shipped with PG 15.

2. src/tools/stats.ts NULLIF comment + tool description -- the NULLIF(x, 0) rationale is backwards: it claims callers can tell "IO timing disabled" from "no IO occurred", but NULLIF maps both cases to the same null. The description's "null when track_io_timing = off" is also wrong for a fully-cached query under timing-on. Fix: either query current_setting('track_io_timing') and null the columns only when it's actually off, or reword comment + description to "null = no IO time recorded (track_io_timing off, or the query did no measurable IO)".

3. src/integration/query.integration.test.ts (new io-timing test) -- mirrors the wrong "1.10" constant and the same null-semantics claim. On a PG 15/16 cluster it would fail confusingly at assert.match(res.error, /pg_stat_statements/) (the column-not-exist error never mentions the extension) instead of pointing at the real bug. Keep the test's gate in lockstep with whichever handler fix lands.

4. Branch hygiene -- this PR is stacked on test: gate pg_current_wal_lsn REVOKE behind POSTGRES_MCP_DESTRUCTIVE_TESTS=1 #15 (it carries 0e97683, the destructive-test-gate commit), so the diff-vs-main shows test: gate pg_current_wal_lsn REVOKE behind POSTGRES_MCP_DESTRUCTIVE_TESTS=1 #15's changes too. Mark it "depends on test: gate pg_current_wal_lsn REVOKE behind POSTGRES_MCP_DESTRUCTIVE_TESTS=1 #15" or rebase onto main after test: gate pg_current_wal_lsn REVOKE behind POSTGRES_MCP_DESTRUCTIVE_TESTS=1 #15 merges so it reviews in isolation.

5. Minor -- the new description text uses ≥ and an em-dash where the repo's tool descriptions and comments are deliberately ASCII (mojibake-avoidance stance documented in release.sh); use >= and --.

🤖 Generated with Claude Code

[HighviewOne]

Addressed all review points. Blocker and branch hygiene resolved:

1. Blocker fixed — Added hasSharedBlkCols gate at "1.11". Clusters on 1.10 (PG 15) now get blk_read_time / blk_write_time; clusters on >= 1.11 (PG 17) get shared_blk_read_time / shared_blk_write_time. Both exposed under the same io_*_time_ms output names.
2. NULLIF comment — corrected; no longer claims the two null cases are distinguishable. Description now says "null = no IO time recorded (track_io_timing off, or the query did no measurable IO)".
3. Integration test — comments updated to describe the 1.10/1.11 branch; gate stays at >= 1.10 (correct -- that's when the feature first appears).
4. Branch hygiene — rebased onto the latest fix/destructive-test-gate (PR test: gate pg_current_wal_lsn REVOKE behind POSTGRES_MCP_DESTRUCTIVE_TESTS=1 #15); the stacked commit is gone, diff is now isolated to this feature.
5. ASCII — replaced ≥ and em-dash with >= and -- throughout.