rsc-universal 0.1.1

package/skills/postgresdb/references/schema-and-indexing.md

@@ -0,0 +1,379 @@
+# PostgreSQL schema & indexing
+
+Deep dive on types, constraints, normalization, and every index access method on PostgreSQL 16.
+Running example tables: `orders`, `users`, `jobs` (+ `order_items`, `bookings`, `events`, `docs`,
+`order_statuses`, `rooms`).
+
+## Naming conventions
+
+- `snake_case` for everything; plural table names (`orders`, `users`, `jobs`).
+- Index/constraint prefixes: `pk_` (primary key), `fk_` (foreign key), `uq_` (unique), `ix_` (plain
+  index), `ck_` (check). Use the `ix_<table>_<cols>` form and be consistent — this skill uses `ix_`.
+- Avoid reserved words as identifiers (`user`, `order` require quoting forever) — use `users`, `orders`.
+- Always name constraints explicitly so error messages and migrations are stable:
+
+```sql
+ALTER TABLE orders
+    ADD CONSTRAINT ck_orders_amount_nonneg CHECK (amount >= 0);
+```
+
+## Types, in depth
+
+### Surrogate keys
+
+Prefer identity over `serial`. `serial` is sugar for an owned sequence; it leaks sequence-ownership
+edge cases (you can `GRANT`/`REVOKE` the sequence separately, dumps can desync the `OWNED BY`, and an
+explicit insert into the column silently consumes nothing). Identity is SQL-standard and the column
+is protected.
+
+```sql
+-- GOOD: protected identity. An explicit insert is rejected unless you opt in.
+CREATE TABLE users (
+    id    bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    email text NOT NULL
+);
+-- Data-migration escape hatch when you must preserve old ids:
+INSERT INTO users (id, email) OVERRIDING SYSTEM VALUE VALUES (42, 'a@b.co');
+```
+
+For public/distributed ids use a time-ordered UUID (v7). Native `gen_random_uuid()` returns **v4
+(random)**, which scatters inserts across the B-tree, causing page splits and WAL amplification on
+high-write tables. PostgreSQL gains a native `uuidv7()` only in **PG18**; on PG16 use the `pg_uuidv7`
+extension or generate v7 in the application.
+
+```sql
+-- PG16: native gen_random_uuid() is v4 (random). For time-ordered keys:
+CREATE EXTENSION IF NOT EXISTS pg_uuidv7;   -- provides uuid_generate_v7()
+ALTER TABLE orders ALTER COLUMN public_id SET DEFAULT uuid_generate_v7();
+```
+
+### Time
+
+`timestamptz` stores a UTC instant — it does **not** store a zone. On input the session `TimeZone`
+converts to UTC; on output it converts back. Naive `timestamp` records wall-clock with no instant, so
+the same value means different moments in different sessions. Always use `timestamptz` for events.
+
+```sql
+-- Store the instant; convert only for display.
+SELECT created_at AT TIME ZONE 'Europe/Madrid' AS local_wall_clock FROM orders;
+-- Durations are first-class:
+SELECT now() - created_at AS age, interval '15 minutes' AS sla FROM orders;
+```
+
+### Numbers / money
+
+```sql
+-- Exact decimal for anything that must add up. 19 digits, 4 fractional.
+amount   numeric(19,4) NOT NULL CHECK (amount >= 0),
+-- Counters: bigint, not int (2.1B is reachable).
+view_count bigint NOT NULL DEFAULT 0,
+```
+
+`double precision` is fine for scientific magnitudes where relative error is acceptable; never for
+money — binary floats cannot represent `0.10` exactly and drift across arithmetic.
+
+### Text
+
+```sql
+-- Length as a CHECK on text: no rewrite needed to relax it later.
+email text NOT NULL CHECK (length(email) <= 320),
+```
+
+`citext` (extension) gives case-insensitive equality/uniqueness without rewriting every query with
+`lower()`. Use `varchar(n)` only when an external contract mandates a hard byte limit.
+
+```sql
+CREATE EXTENSION IF NOT EXISTS citext;
+ALTER TABLE users ALTER COLUMN email TYPE citext;   -- 'A@B.co' = 'a@b.co'
+```
+
+### Enum vs lookup table
+
+| Aspect | `enum` type | lookup table + FK |
+| --- | --- | --- |
+| Add a value | `ALTER TYPE ... ADD VALUE` (cannot be used in same txn before commit) | `INSERT` row |
+| Remove a value | not supported (must recreate the type) | `UPDATE active = false` (soft retire) |
+| Joins to metadata | none | natural `JOIN` |
+| FK integrity | implicit (the type) | explicit `REFERENCES` |
+| i18n / labels | none | extra columns |
+| Ordering | declaration order | a `sort_order` column |
+
+```sql
+-- enum: stable, tiny, closed set
+CREATE TYPE order_kind AS ENUM ('standard', 'rush', 'gift');
+
+-- lookup table: evolving set, joinable, soft-retire (recommended for status)
+CREATE TABLE order_statuses (
+    code       text PRIMARY KEY,
+    label      text NOT NULL,
+    is_active  boolean NOT NULL DEFAULT true,
+    sort_order int  NOT NULL DEFAULT 0
+);
+ALTER TABLE orders
+    ADD CONSTRAINT fk_orders_status
+    FOREIGN KEY (status) REFERENCES order_statuses (code);
+```
+
+Recommend the lookup table for any set that will grow. `ALTER TYPE ... ADD VALUE` cannot run inside a
+transaction block before the new value is committed, and an enum value can never be removed.
+
+### Arrays vs jsonb vs join table
+
+- `text[]` + GIN: read-mostly tag lists with containment queries; no per-tag FK.
+- `jsonb` + GIN: heterogeneous semi-structured attributes; promote hot keys to columns later.
+- Join table: when you need FK integrity, per-tag rows, or tag-level metadata.
+
+```sql
+-- array of tags + containment index
+ALTER TABLE orders ADD COLUMN tags text[] NOT NULL DEFAULT '{}';
+CREATE INDEX ix_orders_tags ON orders USING gin (tags);          -- WHERE tags @> ARRAY['vip']
+
+-- jsonb attributes; jsonb_path_ops is smaller when you only use @>
+ALTER TABLE orders ADD COLUMN meta jsonb NOT NULL DEFAULT '{}';
+CREATE INDEX ix_orders_meta ON orders USING gin (meta jsonb_path_ops);
+```
+
+## Constraints
+
+### Primary keys
+
+```sql
+-- single-column surrogate PK (preferred)
+id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+-- composite natural PK for a join table
+CREATE TABLE order_tags (
+    order_id bigint NOT NULL REFERENCES orders (id) ON DELETE CASCADE,
+    tag      text   NOT NULL,
+    PRIMARY KEY (order_id, tag)
+);
+```
+
+### Foreign keys
+
+| `ON DELETE` action | Effect on child | Use when |
+| --- | --- | --- |
+| `NO ACTION` (default) | error if children exist (checked at stmt/txn end) | default; defer checks |
+| `RESTRICT` | error immediately, cannot defer | block deletes hard |
+| `CASCADE` | delete children too | owned children (order_items) |
+| `SET NULL` | child FK → NULL | optional parent |
+| `SET DEFAULT` | child FK → its default | rare; default must exist |
+
+```sql
+-- owned child cascades; optional reference nulls out
+ALTER TABLE order_items
+    ADD CONSTRAINT fk_items_order
+    FOREIGN KEY (order_id) REFERENCES orders (id) ON DELETE CASCADE;
+
+-- circular or bulk-load FKs: defer the check to COMMIT
+ALTER TABLE orders
+    ADD CONSTRAINT fk_orders_user FOREIGN KEY (user_id) REFERENCES users (id)
+    DEFERRABLE INITIALLY DEFERRED;
+```
+
+Index every FK child column — Postgres does not, and a parent `DELETE`/`UPDATE` must scan the child to
+enforce the constraint:
+
+```sql
+CREATE INDEX ix_order_items_order_id ON order_items (order_id);
+```
+
+### Unique
+
+```sql
+-- standard unique
+ALTER TABLE users ADD CONSTRAINT uq_users_email UNIQUE (email);
+
+-- PG15+: treat multiple NULLs as colliding (one active row per (a) where b IS NULL)
+CREATE UNIQUE INDEX uq_orders_pubid ON orders (public_id) NULLS NOT DISTINCT;
+```
+
+### Check (named)
+
+```sql
+ALTER TABLE orders
+    ADD CONSTRAINT ck_orders_currency_iso CHECK (length(currency) = 3);
+```
+
+### Exclusion constraint (no-overlap booking)
+
+```sql
+CREATE EXTENSION IF NOT EXISTS btree_gist;   -- lets = and && share one GiST index
+CREATE TABLE bookings (
+    id        bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    room_id   bigint NOT NULL REFERENCES rooms (id),
+    during    tstzrange NOT NULL,
+    EXCLUDE USING gist (room_id WITH =, during WITH &&)   -- no two overlapping ranges per room
+);
+```
+
+### NOT VALID then VALIDATE (avoid the long lock)
+
+Adding a `CHECK` or FK normally scans the whole table under a heavy lock. Split it: add `NOT VALID`
+(no scan, brief lock), then `VALIDATE` (scans under SHARE UPDATE EXCLUSIVE, allowing reads and writes).
+
+```sql
+ALTER TABLE orders ADD CONSTRAINT ck_orders_amount_nonneg
+    CHECK (amount >= 0) NOT VALID;       -- new rows checked, existing rows not scanned
+ALTER TABLE orders VALIDATE CONSTRAINT ck_orders_amount_nonneg;   -- scans, light lock
+```
+
+## Generated & identity columns
+
+```sql
+-- STORED generated column: maintained by the engine, indexable.
+search tsvector GENERATED ALWAYS AS (to_tsvector('simple', coalesce(note, ''))) STORED,
+CREATE INDEX ix_orders_search ON orders USING gin (search);
+```
+
+Notes: PG16 supports only `STORED` generated columns (the value is materialized and re-computed on
+write); `VIRTUAL` generated columns arrive in PG18. Identity columns differ from `serial` in that
+`GENERATED ALWAYS` rejects explicit values unless you write `OVERRIDING SYSTEM VALUE` — useful exactly
+once, during a data migration that must preserve old ids.
+
+## Normalization & deliberate denormalization
+
+Default to 3NF: one fact in one place, referenced by FK. Denormalize only with a maintenance plan:
+
+- Read-heavy aggregates: a counter column kept fresh by a trigger.
+- Derived values: a `GENERATED ALWAYS AS (...) STORED` column (always correct, no trigger).
+- Expensive reporting rollups: a materialized view refreshed off the hot path.
+
+```sql
+-- Trigger-maintained counter on users.order_count
+CREATE FUNCTION bump_order_count() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+    IF TG_OP = 'INSERT' THEN
+        UPDATE users SET order_count = order_count + 1 WHERE id = NEW.user_id;
+    ELSIF TG_OP = 'DELETE' THEN
+        UPDATE users SET order_count = order_count - 1 WHERE id = OLD.user_id;
+    END IF;
+    RETURN NULL;
+END $$;
+CREATE TRIGGER trg_orders_count
+    AFTER INSERT OR DELETE ON orders
+    FOR EACH ROW EXECUTE FUNCTION bump_order_count();
+```
+
+```sql
+-- Materialized view; REFRESH CONCURRENTLY requires a UNIQUE index on the MV.
+CREATE MATERIALIZED VIEW order_daily AS
+    SELECT user_id, date_trunc('day', created_at) AS day, sum(amount) AS total
+    FROM orders GROUP BY 1, 2;
+CREATE UNIQUE INDEX uq_order_daily ON order_daily (user_id, day);
+REFRESH MATERIALIZED VIEW CONCURRENTLY order_daily;   -- no read lock; needs the unique index
+```
+
+The `updated_at` column has no native `ON UPDATE`; maintain it with a trigger:
+
+```sql
+CREATE FUNCTION set_updated_at() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN NEW.updated_at := now(); RETURN NEW; END $$;
+CREATE TRIGGER trg_orders_updated_at
+    BEFORE UPDATE ON orders FOR EACH ROW EXECUTE FUNCTION set_updated_at();
+```
+
+## Indexing deep dive
+
+### btree (default)
+
+Handles `=`, `<`, `>`, `BETWEEN`, `IN`, prefix `LIKE`, `ORDER BY`, and uniqueness. Multicolumn order:
+**equality columns first, then the range/sort column** — the index is only usable left-to-right.
+
+```sql
+-- equality then range; matches WHERE user_id = $1 AND created_at >= $2 ORDER BY created_at DESC
+CREATE INDEX ix_orders_user_created ON orders (user_id, created_at DESC);
+
+-- prefix LIKE in a non-C locale needs text_pattern_ops
+CREATE INDEX ix_users_email_pat ON users (email text_pattern_ops);   -- WHERE email LIKE 'foo%'
+
+-- match an ORDER BY with NULLS LAST so the scan needs no sort node
+CREATE INDEX ix_orders_created ON orders (created_at DESC NULLS LAST);
+```
+
+### GIN
+
+For containment and full-text. Default `jsonb_ops` indexes every key/value and supports `@>`, `?`,
+`?|`, `?&`; `jsonb_path_ops` is smaller and faster but supports only `@>`.
+
+```sql
+CREATE INDEX ix_orders_meta_full ON orders USING gin (meta);                 -- all operators
+CREATE INDEX ix_orders_meta_path ON orders USING gin (meta jsonb_path_ops);  -- @> only, smaller
+```
+
+GIN buffers inserts in a pending list (`fastupdate = on`); a huge `gin_pending_list_limit` speeds
+bulk loads but slows reads until merged. Lower it for read-latency-sensitive tables, or
+`fastupdate = off`.
+
+### GiST
+
+Ranges, exclusion constraints, nearest-neighbor, and PostGIS geometry.
+
+```sql
+CREATE INDEX ix_bookings_during ON bookings USING gist (during);   -- && overlap, @> contains
+-- geo: CREATE INDEX ... USING gist (geom);  (see PostGIS docs)
+```
+
+### BRIN
+
+Tiny block-range index for huge append-only tables where physical order correlates with the column
+(insert order ≈ `created_at`). Costs almost nothing to maintain; gives big gains on range scans.
+
+```sql
+CREATE INDEX ix_events_ts ON events USING brin (created_at) WITH (pages_per_range = 64);
+```
+
+If rows are not physically correlated (random insert order, heavy updates), BRIN degrades to scanning
+everything — use btree instead.
+
+### Hash
+
+Equality-only, no multicolumn, no ordering, no uniqueness. WAL-logged since PG10 but still rarely beats
+btree; reach for it only for very wide keys where btree size matters, after measuring.
+
+```sql
+CREATE INDEX ix_jobs_dedup_hash ON jobs USING hash (dedup_key);   -- = only
+```
+
+### Partial, expression, covering
+
+```sql
+-- partial: index only the hot subset
+CREATE INDEX ix_jobs_pending ON jobs (created_at) WHERE status = 'pending';
+
+-- expression: must match the query expression exactly
+CREATE INDEX ix_users_lower_email ON users (lower(email));   -- WHERE lower(email) = $1
+
+-- covering: INCLUDE payload columns for index-only scans
+CREATE INDEX ix_orders_user_cover ON orders (user_id) INCLUDE (amount, created_at);
+
+-- conditional uniqueness: one active row per email, ignoring soft-deleted rows
+CREATE UNIQUE INDEX uq_users_email_active ON users (email) WHERE deleted_at IS NULL;
+```
+
+### Index-only scans
+
+The planner can answer entirely from the index when all selected columns are in the index (key or
+`INCLUDE`) **and** the visibility map marks the pages all-visible. Stale visibility forces heap
+fetches. Confirm with `EXPLAIN (ANALYZE)` → `Heap Fetches: 0`; if non-zero, `VACUUM` the table to
+refresh the visibility map.
+
+## Bloat & maintenance
+
+Updates and deletes leave dead tuples; autovacuum reclaims them but indexes can still bloat.
+
+```sql
+-- Unused indexes (drop after confirming across a full traffic cycle)
+SELECT relname, indexrelname, idx_scan
+FROM pg_stat_user_indexes WHERE idx_scan = 0 ORDER BY relname;
+
+-- Measure real bloat for a suspect index/table
+CREATE EXTENSION IF NOT EXISTS pgstattuple;
+SELECT * FROM pgstattuple('ix_orders_user_created');
+
+-- Rebuild an index without blocking writes
+REINDEX INDEX CONCURRENTLY ix_orders_user_created;
+```
+
+Never run `VACUUM FULL` on a live hot table — it takes ACCESS EXCLUSIVE and rewrites the whole table,
+blocking all reads and writes. For online table compaction use `pg_repack` (extension + CLI), which
+rebuilds the table in the background and swaps it in with only a brief lock.

package/skills/postgresdb/scripts/verify.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — postgresdb skill gate. Run from your PROJECT root.
+#
+# What it does (read-only, idempotent, never writes):
+#   1. Lints discovered SQL with sqlfluff IF sqlfluff + a .sqlfluff config exist.
+#   2. Syntax-sanity-checks migration *.sql files: balanced quotes/parens (advisory — it is
+#      dollar-quote and block-comment aware, but still heuristic), and flags foot-guns
+#      (CREATE INDEX without CONCURRENTLY in a migration, ADD COLUMN ... NOT NULL without
+#      DEFAULT, VACUUM FULL).
+#   3. IF DATABASE_URL is set AND psql is present: checks pg_stat_statements is enabled.
+#      It NEVER connects unless DATABASE_URL is set, and a down/unreachable DB is a skip, not a fail.
+#
+# Exit code: non-zero ONLY on sqlfluff lint errors. Everything else is advisory
+# (yellow [skip] / [warn]) — unbalanced quotes/parens are a heuristic warning, not a hard fail,
+# because dollar-quoted PL/pgSQL and string literals can legitimately look "unbalanced".
+# Missing tools never fail the gate.
+#
+# Portability: runs on stock macOS bash 3.2 (no mapfile, no associative arrays). All arrays are
+# initialised so they are safe to expand under `set -u`.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+warn() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+ROOT="$(pwd)"
+
+# Discover SQL/migration files (exclude vendor dirs). bash 3.2 has no mapfile; read NUL-delimited
+# names into an explicitly-initialised array so expansion is safe under `set -u`.
+SQL_FILES=()
+while IFS= read -r -d '' f; do
+  SQL_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f -name '*.sql' -print0 2>/dev/null
+)
+
+# strip_for_counting <file> — emit the SQL with line comments (--…), block comments (/* … */),
+# single-quoted string literals, and dollar-quoted blocks ($$…$$ / $tag$…$tag$) removed, so the
+# quote/paren balance heuristic does not trip on PL/pgSQL function bodies or literals. Pure awk,
+# so it works identically on macOS (BSD) and Linux (GNU) awk.
+strip_for_counting() {
+  awk '
+    BEGIN { inblock = 0; dq = "" }
+    {
+      line = $0
+      out = ""
+      i = 1
+      n = length(line)
+      while (i <= n) {
+        rest = substr(line, i)
+
+        # Inside a /* */ block comment: consume until the closing */.
+        if (inblock) {
+          p = index(rest, "*/")
+          if (p == 0) { i = n + 1; continue }
+          i += p + 1
+          inblock = 0
+          continue
+        }
+
+        # Inside a dollar-quoted block: consume until the matching close tag.
+        if (dq != "") {
+          p = index(rest, dq)
+          if (p == 0) { i = n + 1; continue }
+          i += p + length(dq) - 1
+          dq = ""
+          continue
+        }
+
+        ch  = substr(line, i, 1)
+        ch2 = substr(line, i, 2)
+
+        # Start of a line comment: drop the remainder of the line.
+        if (ch2 == "--") { i = n + 1; continue }
+
+        # Start of a block comment.
+        if (ch2 == "/*") { inblock = 1; i += 2; continue }
+
+        # Start of a dollar-quote tag: $$ or $tag$.
+        if (ch == "$") {
+          if (match(rest, /^\$[A-Za-z_]*\$/)) {
+            dq = substr(rest, RSTART, RLENGTH)
+            i += RLENGTH
+            continue
+          }
+        }
+
+        # Start of a single-quoted string literal: consume to the closing quote,
+        # honouring the '' escape (a doubled quote stays inside the literal).
+        if (ch == "'\''") {
+          i += 1
+          while (i <= n) {
+            c = substr(line, i, 1)
+            if (c == "'\''") {
+              if (substr(line, i + 1, 1) == "'\''") { i += 2; continue }
+              i += 1
+              break
+            }
+            i += 1
+          }
+          continue
+        }
+
+        out = out ch
+        i += 1
+      }
+      print out
+    }
+  ' "$1"
+}
+
+# ---- 1. sqlfluff ----
+if command -v sqlfluff >/dev/null 2>&1; then
+  if [ -f "$ROOT/.sqlfluff" ]; then
+    if [ "${#SQL_FILES[@]}" -gt 0 ]; then
+      if sqlfluff lint --dialect postgres "${SQL_FILES[@]}"; then
+        ok "sqlfluff lint clean"
+      else
+        err "sqlfluff lint reported errors"
+      fi
+    else
+      warn "sqlfluff: no .sql files found"
+    fi
+  else
+    warn "sqlfluff present but no .sqlfluff config — skipping lint"
+  fi
+else
+  warn "sqlfluff not installed — skipping SQL lint"
+fi
+
+# ---- 2. SQL syntax sanity + foot-gun scan ----
+if [ "${#SQL_FILES[@]}" -eq 0 ]; then
+  warn "no .sql files to syntax-check"
+else
+  for f in "${SQL_FILES[@]}"; do
+    # Strip comments, string literals and dollar-quoted bodies before counting.
+    body="$(strip_for_counting "$f")"
+    sq=$(printf '%s' "$body" | tr -cd "'" | wc -c | tr -d ' ')
+    op=$(printf '%s' "$body" | tr -cd '(' | wc -c | tr -d ' ')
+    cp=$(printf '%s' "$body" | tr -cd ')' | wc -c | tr -d ' ')
+    # Advisory only: dollar-quoting/literals are heuristically stripped, but an odd count here is a
+    # hint to eyeball the file, not a build-breaker.
+    if [ $((sq % 2)) -ne 0 ]; then note "$f: odd number of single quotes (after stripping literals/comments) — eyeball it"; fi
+    if [ "$op" -ne "$cp" ]; then note "$f: unbalanced parentheses ($op '(' vs $cp ')') — eyeball it"; fi
+
+    # Foot-guns (advisory only) — only flag for files that look like migrations.
+    case "$f" in
+      *migration*|*migrations*|*alembic/versions*|*prisma/migrations*)
+        if grep -Eiq 'create[[:space:]]+(unique[[:space:]]+)?index' "$f" \
+           && ! grep -Eiq 'create[[:space:]]+(unique[[:space:]]+)?index[[:space:]]+concurrently' "$f"; then
+          note "$f: CREATE INDEX without CONCURRENTLY in a migration"
+        fi
+        if grep -Eiq 'add[[:space:]]+column[^;]*not[[:space:]]+null' "$f" \
+           && ! grep -Eiq 'add[[:space:]]+column[^;]*default' "$f"; then
+          note "$f: ADD COLUMN ... NOT NULL without DEFAULT (table rewrite / lock risk)"
+        fi
+        if grep -Eiq 'vacuum[[:space:]]+full' "$f"; then
+          note "$f: VACUUM FULL takes ACCESS EXCLUSIVE — avoid on live tables"
+        fi
+        ;;
+    esac
+  done
+  ok "SQL syntax sanity scanned (${#SQL_FILES[@]} files)"
+fi
+
+# ---- 3. pg_stat_statements guidance ----
+GUIDE='Enable pg_stat_statements: add "pg_stat_statements" to shared_preload_libraries, restart, then run CREATE EXTENSION pg_stat_statements;'
+if [ -n "${DATABASE_URL:-}" ] && command -v psql >/dev/null 2>&1; then
+  if res="$(psql "$DATABASE_URL" -At -c \
+        "SELECT 1 FROM pg_extension WHERE extname='pg_stat_statements'" 2>/dev/null)"; then
+    if [ "$res" = "1" ]; then
+      ok "pg_stat_statements is enabled"
+    else
+      note "pg_stat_statements not enabled. $GUIDE"
+    fi
+  else
+    warn "could not connect to DATABASE_URL (DB down or unreachable) — skipping pg_stat_statements check"
+  fi
+else
+  warn "DATABASE_URL unset or psql missing — skipping DB checks. $GUIDE"
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found failures"; fi
+exit "$EXIT"