From 42bc104f5fdaebd51336ae11f45b081a771ab61a Mon Sep 17 00:00:00 2001 From: Sonu Khobragade Date: Thu, 3 Sep 2026 09:53:45 +0530 Subject: [PATCH] docs: say why before showing the verification The README opened with how the queries are verified against a live server -- methodology, before the reader had any reason to care. The section explaining the problem (the catalogue views already hold the answer; reading them means a dozen queries and ratio maths by hand) sat at line 63. Move it above. --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 0d8faa8..8445562 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,14 @@ Every query it runs targets `pg_catalog` and the `pg_stat_*` views. It never reads your application tables, and it never writes anything. Point it at a read-only role and it still works fully. +## Why + +`pg_stat_statements` and friends already contain the answer to "why is this +database slow". The problem is that reading them means remembering a dozen +catalogue queries and doing the ratio maths by hand, per database, every time. +This runs the catalogue queries, does the arithmetic, and ranks the findings so +the worst thing is at the top. + ## It is checked against a real server Unit tests cannot tell you a query returns the right answer -- valid SQL can @@ -60,14 +68,6 @@ flowchart LR Read-only by construction: every statement targets `pg_catalog` or a `pg_stat_*` view, so a read-only role loses no functionality. -## Why - -`pg_stat_statements` and friends already contain the answer to "why is this -database slow". The problem is that reading them means remembering a dozen -catalogue queries and doing the ratio maths by hand, per database, every time. -This runs the catalogue queries, does the arithmetic, and ranks the findings so -the worst thing is at the top. - ## Running it Two processes: an Express API that talks to Postgres, and a React UI.