Merge pull request 'build(deps): align with Gitea registry (parent 2.2.1, QQQ 4.1.0-RC.26)' (#39) from deps/align-gitea into develop

QQQ RC.26 adds the shared BasicErrorResponseV1 schema to extension models; regenerate the committed fragment and allow that core schema.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.circleci/config.yml

@@ -1,60 +1,14 @@
 version: 2.1
-
+setup: true
 orbs:
-   qqq-orb: kingsrook/qqq-orb@0.6.9
-
-commands:
-   configure-package-install:
-      steps:
-         - run:
-              name: Keep package installation unattended
-              command: |
-                 # These build machines are discarded after the job.
-                 sudo install -d /etc/needrestart/conf.d
-                 printf '%s\n' '$nrconf{restart} = "l";' | sudo tee /etc/needrestart/conf.d/99-qqq-ci.conf >/dev/null
-
+  qqq-orb: kingsrook/qqq-orb@0.8
 workflows:
-   test_only:
-      jobs:
-         - qqq-orb/mvn_test_only:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              filters:
-                 branches:
-                    ignore: /(develop|release\/.*)/
-
-   publish_snapshot:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: snapshot
-              filters:
-                 branches:
-                    only: [develop]
-
-   publish_release_candidate:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: release_candidate
-              filters:
-                 branches:
-                    only: [/release\/.*/]
-
-   publish_release:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: release
-              filters:
-                 branches:
-                    ignore: /.*/
-                 tags:
-                    only: [/^v\d+\.\d+\.\d+$/]
+  setup:
+    jobs:
+    - qqq-orb/generate_pipeline:
+        orb_version: '0.8'
+        filters:
+          branches:
+            ignore: automation/qbit-rc-pending
+          tags:
+            only: /^v\d+\.\d+\.\d+$/

.gitea/workflows/build.yaml

@@ -0,0 +1,7 @@
+name: build
+on:
+  push:
+jobs:
+  maven:
+    uses: self:KofTwentyTwo/ci-workflows/.gitea/workflows/maven.yaml@v1
+    secrets: inherit

.github/workflows/codeql.yml

@@ -0,0 +1,23 @@
+name: CodeQL
+'on':
+  push:
+    branches:
+    - main
+    - develop
+    - release/**
+    - hotfix/**
+  pull_request: {}
+  schedule:
+  - cron: 41 16 * * 0
+  workflow_dispatch: {}
+permissions:
+  contents: read
+  actions: read
+  security-events: write
+  packages: read
+concurrency:
+  group: codeql-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  analyze:
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-codeql.yml@c288a8864fe9054f68410e1d78f5863aea4c4d22

.github/workflows/release-rc.yml

@@ -1,25 +1,74 @@
-# Cut the next release candidate (QRun-IO/qqq docs/QRUN-QBIT-REPO-STANDARD.md, C6):
-# run this workflow by hand, or merge a develop PR labelled `release:rc`. It merges develop into
-# the release line and the release/* push runs CircleCI publish_release_candidate.
 name: Release candidate
-
-on:
+'on':
   workflow_dispatch:
     inputs:
       dry_run:
-        description: Print the plan without merging or creating branches
+        description: Plan a cut without changing release state
         type: boolean
         default: false
+      finalize:
+        description: Retry finalization of an existing cut; do not cut another RC
+        type: boolean
+        default: false
+      recover:
+        description: Recover the same published RC after a deployment timeout; never
+          reupload
+        type: boolean
+        default: false
+      circle_build:
+        description: Original Circle publisher build number (recovery only)
+        type: string
+        default: ''
+      merge_sha:
+        description: Existing cut merge_sha (finalize retry only)
+        type: string
+        default: ''
+      bump_sha:
+        description: Existing cut bump_sha (finalize retry only)
+        type: string
+        default: ''
+      branch:
+        description: Existing cut branch (finalize retry only)
+        type: string
+        default: ''
+      version:
+        description: Existing cut version (finalize retry only)
+        type: string
+        default: ''
   pull_request:
-    types: [closed]
-    branches: [develop]
-
+    types:
+    - closed
+    branches:
+    - develop
+  repository_dispatch:
+    types:
+    - qbit-rc-published
 permissions:
   contents: write
-
+  actions: read
+  checks: read
 jobs:
   release-rc:
-    if: github.event_name == 'workflow_dispatch' || (github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release:rc'))
-    uses: QRun-IO/.github/.github/workflows/qbit-release-rc.yml@main
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch'
+      || (github.event_name == 'pull_request' && github.event.pull_request.merged
+      == true && github.event.pull_request.base.ref == 'develop' && contains(github.event.pull_request.labels.*.name,
+      'release:rc'))
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-release-rc.yml@cc30f599e63c8e41629c99d23395bac1adb8bc44
     with:
-      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
+      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false
+        }}
+      finalize: ${{ github.event_name == 'repository_dispatch' || (github.event_name
+        == 'workflow_dispatch' && inputs.finalize) }}
+      recover: ${{ github.event_name == 'workflow_dispatch' && inputs.recover || false
+        }}
+      circle_build: ${{ github.event_name == 'workflow_dispatch' && inputs.circle_build
+        || '' }}
+      merge_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.merge_sha
+        || inputs.merge_sha || '' }}
+      bump_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.bump_sha
+        || inputs.bump_sha || '' }}
+      branch: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.branch
+        || inputs.branch || '' }}
+      version: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.version
+        || inputs.version || '' }}
+    secrets: inherit

.qqq-ci.yml

@@ -0,0 +1,16 @@
+profile: qbit
+orb_version: '0.8'
+default_branch: develop
+java_version: '21'
+browsers: true
+api_checks: false
+docs_only: false
+release_on_main: false
+release_tag_policy: stable
+test_branch_policy: non-release
+publish:
+  snapshot: true
+  release_candidate: true
+  release: true
+  asciidoc: false
+release_completion: true

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes are documented here. This project follows Keep a Changelog a
 ## [Unreleased]
 
 ### Added
+- H2 2.x support (`H2StatsProvider`) from `INFORMATION_SCHEMA`: statement statistics from `QUERY_STATISTICS` (when the database runs with `QUERY_STATISTICS=TRUE`), sessions with blocking and idle-in-transaction detection, connection counts, table row estimates and sizes, index definitions, settings, and text query plans (`EXPLAIN`; `EXPLAIN ANALYZE` only for non-admin H2 users, since H2 has no read-only transaction: plans refuse side-effecting functions such as `FILE_WRITE`, DDL/DML keywords, user-defined aliases and multiple statements). The enterprise test server showed UNSUPPORTED on H2; it now collects.
+- Per-area capabilities (`StatsFeature`): providers declare which statistics areas they can supply and `ProviderCapabilities.features()` reports what is available on a connection. Snapshot cache-hit ratio and connection limit stay empty when the vendor has none, and analysis rules declare the areas they need (`DbPerfRule.requires()`) and are skipped on providers that cannot supply them, so H2 never gets "unused index" or "low cache hit" findings from missing counters.
+- Provider registry keyed by JDBC product name (`DbStatsProviders.register`), with `docs/PROVIDERS.md` describing what MySQL/MariaDB and SQLite would map to.
+- **Enable statement statistics** action on Settings (`dbPerfEnableStatementStatistics`, manage settings): on H2 runs `SET QUERY_STATISTICS_MAX_ENTRIES 1000` and `SET QUERY_STATISTICS TRUE` as an admin; on PostgreSQL explains the manual extension setup. It is the qbit's only change to the monitored database and is explicit.
+
+### Changed
+- Health and the Setup panel take their prerequisite checks and remedies from the backend's provider: PostgreSQL still names `pg_stat_statements` and `pg_read_all_stats`; H2 names `QUERY_STATISTICS` and the admin role (new access codes `NO_QUERY_STATISTICS` and `NOT_ADMIN`).
+- The previous-snapshot baseline no longer depends on a PostgreSQL-only counter (it uses the database size every supported provider records).
+
+### Fixed
+- Query-spike alerts no longer hold seven days of query snapshots as records on every snapshot evaluation (~230,000 rows at kof22's rate). `SnapshotEvaluator` reads the window in 1,000-row keyset pages and keeps only each statement's current interval time, latest capture time and earlier interval times as primitive doubles; the spike rule (twelve prior samples, median, absence after an hour) is unchanged.
+- The Attribution home panel no longer loads a day of attribution detail into the heap. It sums statements and time per unit and table in the database (at most 5,000 groups), so a render holds about a thousand aggregate rows instead of the roughly 570,000 detail rows (540 MB in PostgreSQL) that ran the kof22 web pod out of memory on 2026-10-16. The daily attribution rollup reads the day in 1,000-row keyset pages (`DbPerfStore.forEachPage`), so worker memory is bounded by distinct dimension keys, not by the day's row count. The hourly analysis (`dbPerfAnalyze`) reads attribution the same way: `RuleContext.window("attribution", ...)` returns database sums per unit, table and operation instead of every detail row (it filled the kof22 worker heap to ~1.8 GB every hour).
+- Collection no longer stops at RUNNING on large production statement sets: list folding in the SQL normalizer is a linear token scan (the nested-repetition regular expressions overflowed the stack on 60 KB statements with long IN/VALUES lists). Any failure, including an `Error`, now closes the run as FAILED with the exception class, logs it at ERROR (class and frame only, never SQL text) and raises the collection alert; runs left RUNNING by a crash are closed as FAILED after three intervals.
+- Only one runtime attributes per JVM: starting attribution on a newer instance (a hot swap, or repeated server starts in tests) stops the previous one, so old instances are never pinned by a forgotten listener and flusher.
+- Each table has its own icon (the app icon is now `storage`), so nav entries are distinguishable and do not repeat icons used elsewhere.
+- Home tables keep at most four columns with plain headers (readable at every width): secondary facts such as calls and mean time, the session's query text, and a unit's kind and top table move into a second line of the first cell.
+
+### Added
+- QQQ attribution and N+1 detection: a core statement execution listener (QQQ 4.1.0-RC.13) aggregates database time per route, scheduled job, process, table and statement shape in bounded memory, records repeated statement shapes per unit of work, and each pod flushes one batched insert per table every `attribution_flush_seconds`. Hosts without QQQ's application launcher call `DbPerfRuntime.of(instance).startAttribution()` after startup.
 
 - Secured database-performance tables, PostgreSQL statistics snapshots, daily rollups and configurable retention.
 - Audited PLAN/GENERIC and read-only ANALYZE query viewer with SQL validation, timeout, rollback and transient parameter handling.

README.md

@@ -1,13 +1,14 @@
 # QBit DB Performance
 
-Database performance for QQQ apps: PostgreSQL statement deltas, table and index statistics, live sessions and blocking, connection capacity, audited query plans, and typed home dashboards in standard secured QQQ tables. Approved design: [docs/SPEC.md](docs/SPEC.md). This branch implements collection and the presentation/plan-viewer phase; attribution listeners, findings evaluation, alerts and health are developed in a separate phase. No release has been published yet.
+Database performance for QQQ apps: PostgreSQL and H2 statement deltas, table and index statistics, live sessions and blocking, connection capacity, audited query plans, and typed home dashboards in standard secured QQQ tables. Approved design: [docs/SPEC.md](docs/SPEC.md). This branch implements collection and the presentation/plan-viewer phase; attribution listeners, findings evaluation, alerts and health are developed in a separate phase. No release has been published yet.
 
 ## Requirements
 
-- Java 21 and QQQ **4.1.0-RC.11+**.
+- Java 21 and QQQ **4.1.0-RC.13+** (the statement execution listener SPI used for QQQ attribution).
 - PostgreSQL **13+**; **16+** for parameterized generic plans, with the pgJDBC driver (built against 42.7.14).
 - `pg_stat_statements` preloaded, created in the monitored database, and readable by the application role.
 - `pg_read_all_stats` granted to that role for complete statistics and other sessions' visibility.
+- Or H2 **2.x** (embedded or server), with `QUERY_STATISTICS=TRUE` for statement statistics (see [H2](#h2)).
 - A host scheduler for automatic collection and rollups. Docker is required for the PostgreSQL acceptance tests.
 
 ## Install
@@ -47,6 +48,16 @@ GRANT pg_read_all_stats TO your_application_role;
 
 Configure `shared_preload_libraries` with `pg_stat_statements` and create the extension in the monitored database through your normal deployment process. Missing access produces reduced-capability status and setup guidance.
 
+### H2
+
+The same qbit runs on an H2 backend; the provider is chosen from the JDBC product name, so no configuration is needed. Add query statistics to the H2 JDBC URL (or run **Enable statement statistics** on Settings as an H2 admin user; H2 forgets it when the database closes):
+
+```
+jdbc:h2:file:/data/app;MODE=MySQL;DB_CLOSE_DELAY=-1;QUERY_STATISTICS=TRUE;QUERY_STATISTICS_MAX_ENTRIES=1000
+```
+
+The cap matters: H2 keeps 100 statements by default and evicts a third of them, oldest first, whenever it is passed. Use an admin user (the default `sa` is one) to see other sessions and blocking. H2 keeps no transaction, cache-hit, scan, vacuum or index-usage counters, so those dashboard figures stay empty and the rules that need them (missing/unused index, bloat, vacuum, cache hit, temp spill, deadlocks, pool sizing) are skipped rather than reporting zeros. Plans are H2 text (index choice and scan counts), not a cost tree. [docs/PROVIDERS.md](docs/PROVIDERS.md) has the full capability table and what other vendors would need.
+
 With `schedulerName`, `dbPerfCollectSnapshot` runs every five minutes and `dbPerfRollupAndPurge` daily at 03:15 (UTC by default). Omitting it registers no schedules. Use **Collect now** on Snapshots for the first baseline and a second collection for deltas. Table and index statistics normally update hourly. The scheduled processes are durable-eligible when the host has durable jobs enabled.
 
 UI hosts must include `qqq-middleware-javalin` (an optional dependency of this qbit). The producer registers UI API extension `db-performance` version `1.0.0` under `/qqq/v1/qbit/db-performance`. Core-only hosts can use tables and collection without middleware.
@@ -80,7 +91,7 @@ Snapshot totals include all observed statement deltas. Only the top configured d
 | `db_performance.view_live_text` | Raw SQL in the transient activity API only; also requires view |
 | `db_performance.explain` | PLAN/GENERIC requests and Query plan record action |
 | `db_performance.explain_analyze` | Execute the guarded ANALYZE service; the record action also needs explain |
-| `db_performance.manage_settings` | Settings/rule edits and Collect now |
+| `db_performance.manage_settings` | Settings/rule edits, Collect now and Enable statement statistics |
 | `db_performance.manage_findings` | Finding status actions supplied by the findings phase |
 
 Hosts can change `permissionBaseName`; grant the corresponding complete names. Persistent collector and explain-audit writes run as the system user, retaining the requesting session's user ID for plans. Dashboard and API reads retain the viewer's session.
@@ -116,6 +127,8 @@ Paths above are relative to `/qqq/v1/qbit/db-performance`. The [committed OpenAP
 
 Stored SQL is normalized and fingerprinted. Raw `pg_stat_activity` text is never persisted and appears only in the activity API with `view_live_text`; home widgets always use normalized text. SQL literals and parameter values must not be used as identifiers: normalization preserves quoted identifiers. Settings and rules are excluded from AI exposure.
 
+On H2, PLAN runs `EXPLAIN` (not executed; `?n` slots stay unbound for generic plans) and ANALYZE runs `EXPLAIN ANALYZE` with the values bound. H2 has no READ ONLY transaction and a rollback does not undo file, session, sequence or DDL side effects, so on H2 both PLAN and ANALYZE refuse more than one statement and any SQL that names a side-effecting function (`FILE_WRITE`, `FILE_READ`, `CSVWRITE`, `CSVREAD`, `LINK_SCHEMA`, `SCRIPT`, `RUNSCRIPT`, `DISK_SPACE_USED`, `CANCEL_SESSION`, `ABORT_SESSION`, `SLEEP`, sequences), a DDL/DML or session keyword, or any user-defined alias; quoted names count. ANALYZE executes the query, so it is offered only to non-admin H2 users (an admin can call file functions) and only for a single SELECT/WITH; capabilities report it as unavailable otherwise. The connection is marked read-only (a hint in H2) and the transaction always rolls back.
+
 PLAN executes EXPLAIN in a read-only transaction with a local timeout and rollback. Parameterized PLAN uses PostgreSQL 16+ GENERIC_PLAN. Only eligible literal-free PLAN/GENERIC plans are stored. A user's SQL must equal its own normalized form to qualify; SQL loaded from the normalized statement table also qualifies.
 
 ANALYZE accepts one SELECT or a non-modifying WITH, rejects INTO and row locks, binds supplied strings as unknown JDBC parameters, and executes inside a read-only transaction. Functions are still constrained by PostgreSQL READ ONLY. The EXPLAIN command uses pgJDBC simple-query execution with JDBC-managed parameter quoting, so PostgreSQL can coerce unknown-typed EXECUTE arguments. The transaction always rolls back and the prepared statement is explicitly deallocated before the connection returns to its pool. SQLSTATE 57014 records TIMEOUT. The service stores only a sanitized audit, never ANALYZE plans or parameter values. Returned ANALYZE plans are transient and can contain values; the assistant prompt redacts literals in plan expressions. Review transient plans before copying them elsewhere.

docs/ATTRIBUTION.md

@@ -0,0 +1,58 @@
+# Attribution runtime (phase B2)
+
+The producer registers `AttributionRuntimeService` with the QQQ application
+launcher. It starts one daemon per application instance after initialization,
+independently of scheduled-job leadership. Hosts without `QApplicationLauncher`
+should call `DbPerfRuntime.of(instance).startAttribution()` after migrations and
+instance validation, and `stopAttribution()` before disposing of the instance.
+`attributionEnabled=false` prevents listener registration and background work.
+Metadata production itself starts no threads, so existing metadata tests remain
+isolated.
+
+`AttributionFlusher` can also be constructed directly for deterministic tests:
+`refreshSettings()`, register `getListener()` with `StatementExecutionListeners`,
+and call `flushNow()`. Always close it to unregister. Production `start()` loads
+settings, registers the listener, schedules flushing, and installs a JVM shutdown
+hook. Closing stops scheduling, unregisters, and flushes once. Shutdown only
+persists completed units; hosts should drain application requests first.
+
+Statements never read settings from the database. A successful settings refresh
+publishes an immutable cached copy; a failed refresh keeps the previous copy.
+The initial copy disables recording until settings can be read. The configured
+flush interval takes effect when the next pass is scheduled. Disabled attribution
+still refreshes settings so administrators can re-enable it.
+
+Units are sampled once and buffered until completion, allowing HTTP route names
+to be finalized. A completed unit belongs to the window in which it ends; an
+abandoned unit is merged when that worker sees a different unit. No-unit work is
+sampled per statement and counted as one unit per statement. Sampling transitions
+retain separate aggregates for each effective rate. Values are observed counts,
+not extrapolated estimates. Daily rollups sum those counts across windows and
+pods and take the maximum duration.
+
+Each global map includes its overflow bucket within `attribution_max_keys`.
+One slot is reserved for a universal `(other)` key (all dimensions collapse,
+fingerprint is SHA-256 of `(other)`). Per-unit maps use the same bound with a
+minimum of two slots. Collapsed per-unit shapes cannot establish N+1 evidence
+and are excluded from repeat detection, avoiding false positives. Global repeat
+overflow sums qualifying repetitions but counts each affected unit only once.
+A mixed-rate overflow row has a null sample rate because there is no single
+valid rate for it. The SQL normalization cache holds at most 5,000 raw SQL keys
+in memory and clears on overflow; only normalized SQL is persisted, capped at
+4,000 characters.
+
+Window swaps and counter merges synchronize only in memory. Database work runs
+under the system user on the flusher thread with attribution suppressed. Each
+nonempty table receives one `InsertAction`, even above 1,000 rows; QQQ may page
+the underlying SQL. Both tables are written in one transaction. Failed windows
+are dropped, with rate-limited fixed-text logging, and never queued for retry.
+The repeat-pattern migration adds `sample_rate` without changing prior
+changesets. Existing retention already includes repeat patterns.
+
+Build using the locally installed statement-listener API:
+
+```powershell
+.\mvnw.cmd -o verify '-Dqqq.snapshot.version=4.1.0-dbperf-SNAPSHOT'
+```
+
+The normal POM default is `4.1.0-RC.13`.

docs/PROVIDERS.md

@@ -0,0 +1,73 @@
+# Statistics providers
+
+The qbit reads database statistics through `DbStatsProvider`. `DbStatsProviders` picks the provider from the JDBC product name (`DatabaseMetaData.getDatabaseProductName()`); anything unregistered gets `UnsupportedStatsProvider`, which shows a setup message instead of failing. Each provider declares the statistics areas (`StatsFeature`) its vendor can supply; `ProviderCapabilities.features()` says which are available on the current connection. Dashboards leave unavailable figures empty and analysis rules that need a missing area (`DbPerfRule.requires()`) are skipped, so a vendor with fewer counters produces fewer findings, never false ones.
+
+| JDBC product name | Provider | Saved name | Status |
+|---|---|---|---|
+| `PostgreSQL` | `PostgresStatsProvider` | `POSTGRES` | Supported (13+) |
+| `H2` | `H2StatsProvider` | `H2` | Supported (2.x) |
+| `MySQL`, `MariaDB` | none yet | `MYSQL` (reserved) | Unsupported |
+| `SQLite` | none yet | | Unsupported |
+
+## Areas by provider
+
+S = supported, A = approximated, - = not available from the vendor.
+
+| Area (`StatsFeature`) | PostgreSQL | H2 | H2 source and notes |
+|---|---|---|---|
+| Database counters (commits, rollbacks, temp, deadlocks) | S | - | H2 keeps no transaction or temp-file counters |
+| Cache hit ratio | S | - | `info.CACHE_HIT_RATIO` exists but is not a cumulative hit/read pair; shown in settings only |
+| Database size | S | S | `SETTINGS` `info.FILE_SIZE` (0 for in-memory databases) |
+| Connection limit | S | - | H2 has no connection limit |
+| Statement statistics | S | S | `QUERY_STATISTICS` with `QUERY_STATISTICS=TRUE`: calls, total/mean/max ms, rows. No query id or user: the id is a stable SHA-256 hash of the text and the user is empty. The collector's own `INFORMATION_SCHEMA` and `DISK_SPACE_USED` reads and connection setup (`SET ...`, which H2 replays for every JDBC URL setting on each new connection, and `CALL DATABASE()`) are excluded. H2 keeps `QUERY_STATISTICS_MAX_ENTRIES` statements (default 100, set 1000) and evicts the oldest third past the cap |
+| Statement I/O (blocks, temp) | S | - | |
+| Statement reset time | S (14+) | - | A restart or eviction shows as falling call counts, which the delta logic treats as a reset |
+| Table row estimates | S | A | `TABLES.ROW_COUNT_ESTIMATE` |
+| Table sizes | S | A | `DISK_SPACE_USED(table)`: table data only; H2 cannot size indexes, so total = table bytes |
+| Table access counters (scans, tuple writes) | S | - | |
+| Table maintenance (dead rows, vacuum, freeze) | S | - | MVStore has no vacuum |
+| Index definitions | S | S | `INDEXES` + `INDEX_COLUMNS`; constraint-generated indexes are marked `USING CONSTRAINT` and never proposed for removal |
+| Index usage and size | S | - | |
+| Live sessions | S | S | `SESSIONS`: RUNNING = active, SLEEP with uncommitted changes = idle in transaction. Non-admin users see only their own session |
+| Blocking | S | S | `SESSIONS.BLOCKER_ID` (admin users) |
+| Wait events | S | A | Blocked sessions report wait type `Lock` |
+| Transaction age | S | A | No transaction start in H2: an idle transaction's age is the time since it went idle (a lower bound) |
+| Connection counts | S | S | `SESSIONS` grouped by user, client info and state |
+| Plans | JSON tree with costs | Text | `EXPLAIN` / `EXPLAIN ANALYZE` (index choice, scan counts); generic plans keep `?n` unbound. ANALYZE only for non-admin users (see below) |
+
+Access codes saved on settings: PostgreSQL `FULL`, `NO_READ_ALL_STATS`, `NO_PG_STAT_STATEMENTS`, `UNSUPPORTED`; H2 `FULL`, `NOT_ADMIN`, `NO_QUERY_STATISTICS`, `UNSUPPORTED`. Health and the Setup panel ask the provider for the remedy text (`remedy`, `setupChecks`). **Enable statement statistics** on Settings calls `enableStatementStatistics`: H2 runs `SET QUERY_STATISTICS_MAX_ENTRIES 1000` and `SET QUERY_STATISTICS TRUE` (admin, until the database closes); PostgreSQL cannot do it at runtime.
+
+## H2 query plan rule
+
+H2 has no READ ONLY transaction and a rollback does not undo file, session, sequence or DDL side effects, so on H2 both PLAN and ANALYZE refuse more than one statement and any SQL that names a side-effecting function (`FILE_WRITE`, `FILE_READ`, `CSVWRITE`, `CSVREAD`, `LINK_SCHEMA`, `SCRIPT`, `RUNSCRIPT`, `DISK_SPACE_USED`, `CANCEL_SESSION`, `ABORT_SESSION`, `SLEEP`, sequences), a DDL/DML or session keyword, or any user-defined alias; quoted names count. ANALYZE executes the query, so it is offered only to non-admin H2 users (an admin can call file functions) and only for a single SELECT/WITH; capabilities report it as unavailable otherwise. The connection is marked read-only (a hint in H2) and the transaction always rolls back. A host whose H2 user is `sa` (an admin, as in the enterprise test server) therefore gets PLAN only.
+
+## Adding a vendor
+
+1. Implement `DbStatsProvider`: the reads, `capabilities`, `features`, `remedy`, `setupChecks`, and optionally `enableStatementStatistics` and `explainText`. Map session states to `active` / `idle` / `idle in transaction` and leave unavailable counters out of the maps rather than writing zeros.
+2. Register it under the JDBC product name: add it to the table in `DbStatsProviders`, or call `DbStatsProviders.register("ProductName", MyProvider::new)` from the host before collection.
+3. Add its saved name to `DbPerfPossibleValues.Provider` and any new access codes to `StatsAccess` and the health check.
+4. Make sure the qbit's Liquibase changelog runs on the vendor (the qbit stores its tables in the monitored backend).
+5. Test every read against a real database (Testcontainers or embedded), with and without the vendor's statistics prerequisites.
+
+## MySQL and MariaDB
+
+What a provider would map (MySQL 8.0+, MariaDB 10.6+ with `performance_schema=ON`, which needs a server restart):
+
+| Area | Source | Notes |
+|---|---|---|
+| Statements | `performance_schema.events_statements_summary_by_digest` | Digest id and normalized text, calls, timer (picoseconds), rows examined/sent, temp tables, `FIRST_SEEN`; `TRUNCATE` resets. Needs `SELECT` on `performance_schema` |
+| Database counters | `SHOW GLOBAL STATUS` (`Com_commit`, `Com_rollback`, `Created_tmp_disk_tables`, `Innodb_deadlocks`) | Server-wide, not per schema |
+| Cache hit ratio | `Innodb_buffer_pool_read_requests` / `Innodb_buffer_pool_reads` | |
+| Connection limit and counts | `max_connections`, `information_schema.PROCESSLIST` / `performance_schema.threads` | Needs `PROCESS` to see other users |
+| Sessions and blocking | `PROCESSLIST`, `sys.innodb_lock_waits` (MySQL) / `information_schema.INNODB_LOCK_WAITS` (MariaDB) | |
+| Tables | `information_schema.TABLES` (`TABLE_ROWS` estimate, `DATA_LENGTH`, `INDEX_LENGTH`) | Sizes are estimates |
+| Table access | `performance_schema.table_io_waits_summary_by_table` | Read/write counts, no seq-vs-index split |
+| Index usage | `performance_schema.table_io_waits_summary_by_index_usage`, `sys.schema_unused_indexes` | |
+| Maintenance | - | InnoDB purge is automatic; no vacuum or dead-row counters |
+| Plans | `EXPLAIN FORMAT=JSON`, `EXPLAIN ANALYZE` (MySQL 8.0.18+, tree text) | MariaDB uses `ANALYZE FORMAT=JSON`; a JSON renderer would be needed |
+
+Beyond the provider class, MySQL support also needs: the MySQL/MariaDB Connector/J on the host classpath; a provider-neutral `ExplainService` path for JSON plans (today JSON plans are PostgreSQL's format and the renderer is PostgreSQL-specific); MySQL-compatible SQL in the changelog (verify it runs, since the qbit stores its own tables there) and in the migration snippets the findings suggest (`CREATE INDEX CONCURRENTLY` is PostgreSQL syntax; MySQL needs `ALGORITHM=INPLACE, LOCK=NONE`); help text that currently names PostgreSQL views; and Testcontainers tests for both MySQL and MariaDB, since their lock views differ.
+
+## SQLite
+
+SQLite has no server, sessions, statement statistics or users. A provider could supply only: database size (`PRAGMA page_count` x `page_size`), tables and row counts (`sqlite_schema` plus `COUNT(*)` or `sqlite_stat1` after `ANALYZE`), table and index sizes (the `dbstat` virtual table, when compiled in), index definitions (`sqlite_schema.sql`, `PRAGMA index_list` / `index_info`), and text plans (`EXPLAIN QUERY PLAN`). Statement statistics would have to come from QQQ attribution (the qbit's own statement listener), not the database. It is useful only as an inventory and plan viewer.

docs/SPEC.md

@@ -47,7 +47,9 @@ actions      └► Attribution aggregator (memory) │        │ Analyze → f
   `explain(...)`. `PostgresStatsProvider` is the v1 implementation (PostgreSQL 13+, features that
   need 16+/17 such as `EXPLAIN (GENERIC_PLAN)` and per-entry `stats_since` are detected).
   The provider is chosen per monitored backend from the JDBC vendor; an unsupported vendor is
-  reported in the Setup card, never a crash.
+  reported in the Setup card, never a crash. `H2StatsProvider` (H2 2.x, `INFORMATION_SCHEMA`)
+  followed; providers declare per-area `StatsFeature`s and rules are skipped where an area is
+  missing. See [PROVIDERS.md](PROVIDERS.md).
 - **Connections** are the backend's own (QQQ `ConnectionManager`), so they run as the app's
   database user. That user needs the built-in `pg_read_all_stats` role to see other sessions'
   query text and all statements; without it the qbit runs in a reduced mode and the Setup card and

pom.xml

@@ -18,6 +18,7 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 
    <properties>
+      <qqq.version>4.1.0-RC.26</qqq.version> <!-- feeds qbit-build-parent's qqq-bom-pom import -->
       <revision>0.1.0-SNAPSHOT</revision>
       <maven.compiler.source>21</maven.compiler.source>
       <maven.compiler.target>21</maven.compiler.target>
@@ -28,7 +29,7 @@
    <parent>
       <groupId>com.kingsrook</groupId>
       <artifactId>qbit-build-parent</artifactId>
-      <version>2.0.0</version>
+      <version>2.2.1</version>
    </parent>
 
    <groupId>com.kingsrook.qbits</groupId>
@@ -241,14 +242,14 @@
    <profiles>
       <!-- Built against qqq 4.1 (QBitMetaDataProducer). Until qbit-build-parent  -->
       <!-- imports the released 4.1 BOM, this profile is active by default and     -->
-      <!-- imports qqq-bom-pom 4.1.0-RC.11 ahead of the parent's 4.0.0 BOM.         -->
+      <!-- imports qqq-bom-pom 4.1.0-RC.13 ahead of the parent's 4.0.0 BOM.         -->
       <profile>
          <id>qqq-snapshot</id>
          <activation>
             <activeByDefault>true</activeByDefault>
          </activation>
          <properties>
-            <qqq.snapshot.version>4.1.0-RC.11</qqq.snapshot.version>
+            <qqq.snapshot.version>4.1.0-RC.26</qqq.snapshot.version>
          </properties>
          <dependencyManagement>
             <dependencies>

src/main/java/com/kingsrook/qbits/dbperformance/DbPerfQBitProducer.java

@@ -25,6 +25,7 @@ import java.util.ArrayList;
 import java.util.List;
 import com.kingsrook.qbits.dbperformance.alerts.SnapshotEvaluator;
 import com.kingsrook.qbits.dbperformance.api.DbPerformanceUiApi;
+import com.kingsrook.qbits.dbperformance.attribution.AttributionRuntimeService;
 import com.kingsrook.qbits.dbperformance.explain.QueryPlanProcess;
 import com.kingsrook.qbits.dbperformance.health.DbPerfHealthChecks;
 import com.kingsrook.qbits.dbperformance.metadata.DbPerfHelp;
@@ -34,6 +35,7 @@ import com.kingsrook.qbits.dbperformance.widgets.DbPerfWidgets;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitConfigValidationException;
 import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaDataProducer;
@@ -144,6 +146,7 @@ public class DbPerfQBitProducer implements QBitMetaDataProducer<DbPerfQBitConfig
       instance.addQBit(getQBitMetaData());
       DbPerfMetaData.addTo(instance, qBitConfig);
       new DbPerfRuntime(instance, qBitConfig).addSelfToInstance(instance);
+      instance.withRuntimeService(new QCodeReference(AttributionRuntimeService.class));
       DbPerfProcesses.addTo(instance, qBitConfig);
       SnapshotEvaluator.register(instance, qBitConfig);
       DbPerfHealthChecks.register(instance);

src/main/java/com/kingsrook/qbits/dbperformance/DbPerfRuntime.java

@@ -22,6 +22,7 @@ package com.kingsrook.qbits.dbperformance;
 
 
 import java.util.concurrent.atomic.AtomicReference;
+import com.kingsrook.qbits.dbperformance.attribution.AttributionFlusher;
 import com.kingsrook.qqq.backend.core.actions.QBackendTransaction;
 import com.kingsrook.qqq.backend.core.context.CapturedContext;
 import com.kingsrook.qqq.backend.core.context.QContext;
@@ -39,6 +40,13 @@ public class DbPerfRuntime implements QSupplementalInstanceMetaData
    public static final String NAME = "dbPerformance";
    private final QInstance instance;
    private final DbPerfQBitConfig config;
+   private AttributionFlusher attributionFlusher;
+
+   /////////////////////////////////////////////////////////////////////////////
+   // statement listeners are JVM-wide: only one runtime attributes at a time //
+   // (a newer instance, e.g. after a hot swap or in tests, replaces the old) //
+   /////////////////////////////////////////////////////////////////////////////
+   private static final AtomicReference<DbPerfRuntime> ACTIVE_ATTRIBUTION = new AtomicReference<>();
 
 
    /*******************************************************************************
@@ -140,6 +148,38 @@ public class DbPerfRuntime implements QSupplementalInstanceMetaData
    }
 
 
+   /*******************************************************************************
+    ** Called by the launcher, or explicitly by hosts without a launcher.
+    *******************************************************************************/
+   public synchronized void startAttribution()
+   {
+      if(attributionFlusher == null && Boolean.TRUE.equals(config.getAttributionEnabled()))
+      {
+         DbPerfRuntime previous = ACTIVE_ATTRIBUTION.getAndSet(this);
+         if(previous != null && previous != this)
+         {
+            previous.stopAttribution();
+         }
+         attributionFlusher = new AttributionFlusher(this);
+         attributionFlusher.start();
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Stop the per-instance listener and its daemon; safe to call repeatedly.
+    *******************************************************************************/
+   public synchronized void stopAttribution()
+   {
+      ACTIVE_ATTRIBUTION.compareAndSet(this, null);
+      if(attributionFlusher != null)
+      {
+         attributionFlusher.close();
+         attributionFlusher = null;
+      }
+   }
+
+
    /*******************************************************************************
     ** Checked service operation.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/dbperformance/alerts/SnapshotEvaluator.java

@@ -22,9 +22,11 @@ package com.kingsrook.qbits.dbperformance.alerts;
 
 
 import java.time.Instant;
-import java.util.Comparator;
+import java.util.Arrays;
+import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.stream.Collectors;
 import com.kingsrook.qbits.dbperformance.DbPerfQBitConfig;
 import com.kingsrook.qbits.dbperformance.DbPerfRuntime;
@@ -38,6 +40,9 @@ import com.kingsrook.qqq.backend.core.alerts.AlertsInstanceMetaData;
 import com.kingsrook.qqq.backend.core.alerts.QAlertTypeMetaData;
 import com.kingsrook.qqq.backend.core.alerts.QAlerts;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
 
@@ -146,7 +151,7 @@ public class SnapshotEvaluator
       long blocked = activity.stream().filter(r -> "BLOCKED".equals(r.getValueString("reason")))
          .filter(r -> Math.max(RuleContext.number(r, "querySeconds"), RuleContext.number(r, "xactSeconds")) >= RuleContext.number(settings, "blockedAlertSeconds")).count();
       signal(BLOCKED_CHAIN, backend, null, blocked > 0, "Database blocking chain", blocked + " blocked sessions exceed the duration threshold", snapshot, "db_perf_snapshot");
-      if("OK".equals(status) || "NO_READ_ALL_STATS".equals(settings.getValueString("statsAccess")))
+      if("OK".equals(status) || List.of("NO_READ_ALL_STATS", "NOT_ADMIN").contains(settings.getValueString("statsAccess")))
       {
          spikes(ctx, snapshot);
       }
@@ -159,33 +164,31 @@ public class SnapshotEvaluator
     *******************************************************************************/
    private void spikes(RuleContext ctx, QRecord snapshot) throws Exception
    {
-      Map<Integer, List<QRecord>> history = ctx.window("query_snapshot", 7).stream().collect(Collectors.groupingBy(r -> r.getValueInteger("statementId")));
+      Map<Integer, StatementHistory> history = history(ctx, snapshot.getValueInteger("id"));
       for(QRecord statement : ctx.identities("statement"))
       {
-         List<QRecord> samples = history.getOrDefault(statement.getValueInteger("id"), List.of());
-         QRecord current = samples.stream().filter(r -> snapshot.getValueInteger("id").equals(r.getValueInteger("snapshotId"))).findFirst().orElse(null);
-         if(current == null)
+         StatementHistory samples = history.getOrDefault(statement.getValueInteger("id"), new StatementHistory());
+         if(samples.current == null)
          {
-            Instant last = samples.stream().map(r -> r.getValueInstant("capturedAt")).max(Comparator.naturalOrder()).orElse(Instant.EPOCH);
+            Instant last = samples.last == null ? Instant.EPOCH : samples.last;
             if(!last.plusSeconds(3600).isAfter(ctx.now))
             {
                signal(QUERY_SPIKE, ctx.backend, statement.getValueString("id"), false, "Query absent", "Statement absent from snapshots for at least one hour", statement, "db_perf_statement");
             }
             continue;
          }
-         List<Double> previous = samples.stream().filter(r -> r.getValueInstant("capturedAt").isBefore(ctx.now))
-            .map(r -> RuleContext.number(r, "totalMs")).sorted().toList();
-         if(previous.size() < 12)
+         double[] previous = samples.sortedPrevious();
+         if(previous.length < 12)
          {
-            if(RuleContext.number(current, "totalMs") < RuleContext.number(ctx.settings, "spikeMinTotalMs"))
+            if(samples.current < RuleContext.number(ctx.settings, "spikeMinTotalMs"))
             {
                signal(QUERY_SPIKE, ctx.backend, statement.getValueString("id"), false, "Query recovered", "Interval time is below the configured floor", statement, "db_perf_statement");
             }
             continue;
          }
-         int middle = previous.size() / 2;
-         double median = previous.size() % 2 == 0 ? (previous.get(middle - 1) + previous.get(middle)) / 2 : previous.get(middle);
-         double time = RuleContext.number(current, "totalMs");
+         int middle = previous.length / 2;
+         double median = previous.length % 2 == 0 ? (previous[middle - 1] + previous[middle]) / 2 : previous[middle];
+         double time = samples.current;
          boolean spike = time >= RuleContext.number(ctx.settings, "spikeMinTotalMs") && time >= median * RuleContext.number(ctx.settings, "spikeFactor");
          String normalized = SqlNormalizer.normalize(statement.getValueString("queryText"));
          String text = normalized.substring(0, Math.min(200, normalized.length()));
@@ -195,6 +198,90 @@ public class SnapshotEvaluator
    }
 
 
+   /*******************************************************************************
+    ** Seven days of per-statement interval times, read in keyset pages and kept
+    ** as primitive doubles. kof22 writes ~33,000 query snapshots a day, so the
+    ** window is ~230,000 rows; holding them as QRecords on every snapshot
+    ** evaluation cost hundreds of MB of worker heap.
+    *******************************************************************************/
+   static Map<Integer, StatementHistory> history(RuleContext ctx, Integer currentSnapshotId) throws Exception
+   {
+      Set<Integer> valid = ctx.window("snapshot", 7).stream().filter(r -> List.of("OK", "PARTIAL").contains(r.getValueString("status")))
+         .map(r -> r.getValueInteger("id")).collect(Collectors.toSet());
+      QQueryFilter filter = new QQueryFilter(new QFilterCriteria("capturedAt", QCriteriaOperator.GREATER_THAN, ctx.now.minusSeconds(7 * 86400L)),
+         new QFilterCriteria("capturedAt", QCriteriaOperator.LESS_THAN_OR_EQUALS, ctx.now));
+      Map<Integer, StatementHistory> history = new HashMap<>();
+      DbPerfStore.forEachPage("db_perf_query_snapshot", filter, DbPerfStore.BATCH_SIZE, page ->
+      {
+         for(QRecord row : page)
+         {
+            Integer snapshotId = row.getValueInteger("snapshotId");
+            if(!valid.contains(snapshotId))
+            {
+               continue;
+            }
+            StatementHistory statement = history.computeIfAbsent(row.getValueInteger("statementId"), ignored -> new StatementHistory());
+            Instant at = row.getValueInstant("capturedAt");
+            double totalMs = RuleContext.number(row, "totalMs");
+            if(statement.last == null || at.isAfter(statement.last))
+            {
+               statement.last = at;
+            }
+            if(snapshotId.equals(currentSnapshotId) && statement.current == null)
+            {
+               statement.current = totalMs;
+            }
+            if(at.isBefore(ctx.now))
+            {
+               statement.add(totalMs);
+            }
+         }
+      });
+      return (history);
+   }
+
+
+
+   /*******************************************************************************
+    ** One statement's samples: the current interval, the latest capture time
+    ** and earlier interval times.
+    *******************************************************************************/
+   static final class StatementHistory
+   {
+      private Double   current;
+      private Instant  last;
+      private double[] previous = new double[16];
+      private int      size;
+
+
+
+      /***************************************************************************
+       ** Append an earlier interval time.
+       ***************************************************************************/
+      void add(double value)
+      {
+         if(size == previous.length)
+         {
+            previous = Arrays.copyOf(previous, size * 2);
+         }
+         previous[size++] = value;
+      }
+
+
+
+      /***************************************************************************
+       ** Earlier interval times, ascending.
+       ***************************************************************************/
+      double[] sortedPrevious()
+      {
+         double[] sorted = Arrays.copyOf(previous, size);
+         Arrays.sort(sorted);
+         return (sorted);
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Stable backend/subject keys make raises and resolutions restart-safe.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/dbperformance/analyze/AnalyzeService.java

@@ -25,9 +25,12 @@ import java.time.Clock;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
+import java.util.Set;
 import com.kingsrook.qbits.dbperformance.DbPerfRuntime;
 import com.kingsrook.qbits.dbperformance.collect.DbPerfSettingsService;
 import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
+import com.kingsrook.qbits.dbperformance.provider.DbStatsProviders;
+import com.kingsrook.qbits.dbperformance.provider.StatsFeature;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 
 
@@ -70,7 +73,8 @@ public class AnalyzeService
 
 
    /*******************************************************************************
-    ** Disabled rules are neither evaluated nor reconciled.
+    ** Disabled rules, and rules whose evidence the backend's provider cannot
+    ** supply (unknown before the first collection), are neither evaluated nor reconciled.
     *******************************************************************************/
    public List<Result> run(String backend) throws Exception
    {
@@ -79,9 +83,15 @@ public class AnalyzeService
          throw (new IllegalArgumentException("Backend is not configured for this runtime"));
       }
       QRecord settings = new DbPerfSettingsService(runtime).ensure(backend);
+      String provider = settings.getValueString("provider");
+      Set<StatsFeature> available = provider == null ? null : DbStatsProviders.forProviderName(provider).features();
       List<Result> results = new ArrayList<>();
       for(DbPerfRule rule : rules)
       {
+         if(available != null && !available.containsAll(rule.requires()))
+         {
+            continue;
+         }
          try
          {
             QRecord row = runtime.asSystem(() -> DbPerfStore.first("db_perf_rule", DbPerfStore.eq("code", rule.code())));

src/main/java/com/kingsrook/qbits/dbperformance/analyze/DbPerfRule.java

@@ -22,6 +22,8 @@ package com.kingsrook.qbits.dbperformance.analyze;
 
 
 import java.util.List;
+import java.util.Set;
+import com.kingsrook.qbits.dbperformance.provider.StatsFeature;
 
 
 /*******************************************************************************
@@ -39,4 +41,15 @@ public interface DbPerfRule
     ** Evaluate the configured thresholds against stored observations.
     *******************************************************************************/
    List<FindingDraft> evaluate(RuleContext ctx) throws Exception;
+
+
+
+   /*******************************************************************************
+    ** Statistics areas the evidence comes from. A rule is skipped (neither
+    ** evaluated nor reconciled) when the backend's provider cannot supply them.
+    *******************************************************************************/
+   default Set<StatsFeature> requires()
+   {
+      return (Set.of());
+   }
 }

src/main/java/com/kingsrook/qbits/dbperformance/analyze/RuleContext.java

@@ -25,17 +25,27 @@ import java.time.Duration;
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.stream.Collectors;
 import com.kingsrook.qbits.dbperformance.DbPerfRuntime;
 import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
+import com.kingsrook.qqq.backend.core.actions.tables.AggregateAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.Aggregate;
+import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.AggregateInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.AggregateOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.AggregateResult;
+import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.GroupBy;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
 
 
 /*******************************************************************************
@@ -130,7 +140,7 @@ public class RuleContext
          {
             filter.withCriteria(new QFilterCriteria("backendName", QCriteriaOperator.EQUALS, backend));
          }
-         List<QRecord> rows = read("db_perf_" + suffix, filter);
+         List<QRecord> rows = suffix.equals("attribution") ? attributionTotals(filter) : read("db_perf_" + suffix, filter);
          if(!Set.of("snapshot", "attribution", "repeat_pattern").contains(suffix))
          {
             Set<Integer> ids = window("snapshot", days).stream()
@@ -144,6 +154,52 @@ public class RuleContext
    }
 
 
+   /*******************************************************************************
+    ** Most attribution groups the rules receive (prod: ~2,000 per day).
+    *******************************************************************************/
+   public static final int MAX_ATTRIBUTION_GROUPS = 50_000;
+
+
+
+   /*******************************************************************************
+    ** Attribution summed in the database per unit, table and operation: the
+    ** fields the rules read (statements, totalMs and the other counters), never
+    ** the day's detail rows. A day is ~570,000 rows in kof22 and loading it made
+    ** every hourly dbPerfAnalyze fill the worker heap (2026-10-16).
+    *******************************************************************************/
+   private static List<QRecord> attributionTotals(QQueryFilter filter) throws QException
+   {
+      List<String> dimensions = List.of("unitKind", "unitName", "tableName", "operation");
+      AggregateInput input = new AggregateInput("db_perf_attribution").withFilter(filter).withLimit(MAX_ATTRIBUTION_GROUPS)
+         .withTransaction(QContext.getQBackendTransaction());
+      Map<String, GroupBy> groupBys = new LinkedHashMap<>();
+      for(String dimension : dimensions)
+      {
+         GroupBy groupBy = new GroupBy(QFieldType.STRING, dimension);
+         groupBys.put(dimension, groupBy);
+         input.withGroupBy(groupBy);
+      }
+      Map<String, Aggregate> aggregates = new LinkedHashMap<>();
+      for(String counter : List.of("units", "statements", "rowsCount", "errors", "totalMs"))
+      {
+         aggregates.put(counter, new Aggregate(counter, AggregateOperator.SUM));
+      }
+      aggregates.put("maxMs", new Aggregate("maxMs", AggregateOperator.MAX));
+      aggregates.values().forEach(input::withAggregate);
+
+      List<QRecord> rows = new ArrayList<>();
+      for(AggregateResult result : new AggregateAction().execute(input).getResults())
+      {
+         QRecord row = new QRecord();
+         groupBys.forEach((field, groupBy) -> row.setValue(field, result.getGroupByValue(groupBy)));
+         aggregates.forEach((field, aggregate) -> row.setValue(field, result.getAggregateValue(aggregate)));
+         rows.add(row);
+      }
+      return (rows);
+   }
+
+
+
    /*******************************************************************************
     ** Latest inventory only: retired tables and dropped indexes cannot recur.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/dbperformance/analyze/StoredRule.java

@@ -36,6 +36,7 @@ import java.util.Objects;
 import java.util.Set;
 import java.util.stream.Collectors;
 import com.kingsrook.qbits.dbperformance.normalize.SqlNormalizer;
+import com.kingsrook.qbits.dbperformance.provider.StatsFeature;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 
 
@@ -60,6 +61,30 @@ public enum StoredRule implements DbPerfRule
    }
 
 
+   /*******************************************************************************
+    ** Provider areas behind each rule's evidence; attribution rules need none.
+    *******************************************************************************/
+   @Override
+   public Set<StatsFeature> requires()
+   {
+      return (switch(this)
+      {
+         case SLOW_QUERY -> Set.of(StatsFeature.STATEMENTS);
+         case MISSING_INDEX, OVER_AUDITED -> Set.of(StatsFeature.TABLE_ACCESS);
+         case UNUSED_INDEX -> Set.of(StatsFeature.INDEX_USAGE);
+         case DUPLICATE_INDEX -> Set.of(StatsFeature.INDEX_DEFINITIONS);
+         case BLOAT, VACUUM_STALE -> Set.of(StatsFeature.TABLE_MAINTENANCE);
+         case POOL_SIZING -> Set.of(StatsFeature.MAX_CONNECTIONS, StatsFeature.CONNECTIONS);
+         case IDLE_IN_TRANSACTION -> Set.of(StatsFeature.SESSIONS);
+         case CACHE_HIT_LOW -> Set.of(StatsFeature.CACHE_COUNTERS);
+         case TEMP_SPILL -> Set.of(StatsFeature.STATEMENT_IO);
+         case DEADLOCKS -> Set.of(StatsFeature.DATABASE_COUNTERS);
+         case N_PLUS_ONE, HOT_JOB -> Set.of();
+      });
+   }
+
+
+
    /*******************************************************************************
     ** Disabled evaluation is inert even when called outside AnalyzeService.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/dbperformance/api/ExplainSpec.java

@@ -50,7 +50,7 @@ public class ExplainSpec extends DbPerformanceJsonSpec
    public BasicOperation defineBasicOperation()
    {
       return (new BasicOperation().withHttpMethod(HttpMethod.POST).withPath("/qbit/db-performance/explain")
-         .withShortSummary("Explain a PostgreSQL query").withLongDescription("PLAN requires db_performance.explain; ANALYZE requires db_performance.explain_analyze. Values and ANALYZE plans are never persisted."));
+         .withShortSummary("Explain a query (PostgreSQL JSON or H2 text plan)").withLongDescription("PLAN requires db_performance.explain; ANALYZE requires db_performance.explain_analyze. Values and ANALYZE plans are never persisted."));
    }
 
 

src/main/java/com/kingsrook/qbits/dbperformance/attribution/AttributionFlusher.java

@@ -0,0 +1,270 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance.attribution;
+
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+import com.kingsrook.qbits.dbperformance.DbPerfRuntime;
+import com.kingsrook.qbits.dbperformance.collect.DbPerfSettingsService;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.instrumentation.StatementExecutionListeners;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** One daemon per runtime. Windows are detached before any database operation;
+ ** failed windows are dropped and later windows continue without retry queues.
+ *******************************************************************************/
+public class AttributionFlusher implements AutoCloseable
+{
+   private static final QLogger LOG = QLogger.getLogger(AttributionFlusher.class);
+   private final DbPerfRuntime runtime;
+   private final AttributionListener listener;
+   private ScheduledExecutorService executor;
+   private Thread shutdownHook;
+   private boolean closed;
+   private long failures;
+
+
+   /*******************************************************************************
+    ** Construct without starting threads, for hosts and deterministic tests.
+    *******************************************************************************/
+   public AttributionFlusher(DbPerfRuntime runtime)
+   {
+      this.runtime = runtime;
+      this.listener = new AttributionListener(runtime);
+   }
+
+
+   /*******************************************************************************
+    ** Register once after the instance and schema are ready.
+    *******************************************************************************/
+   public synchronized void start()
+   {
+      if(executor != null || closed || !Boolean.TRUE.equals(runtime.getConfig().getAttributionEnabled()))
+      {
+         return;
+      }
+      refreshSettings();
+      StatementExecutionListeners.register(listener);
+      executor = Executors.newSingleThreadScheduledExecutor(task ->
+      {
+         Thread thread = new Thread(task, "db-perf-attribution");
+         thread.setDaemon(true);
+         return (thread);
+      });
+      shutdownHook = new Thread(this::close, "db-perf-attribution-shutdown");
+      Runtime.getRuntime().addShutdownHook(shutdownHook);
+      schedule();
+   }
+
+
+   /*******************************************************************************
+    ** Reschedule after each pass so administrative interval changes take effect.
+    *******************************************************************************/
+   private synchronized void schedule()
+   {
+      if(!closed)
+      {
+         executor.schedule(() ->
+         {
+            flushNow();
+            schedule();
+         }, listener.settings().flushSeconds(), TimeUnit.SECONDS);
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Exactly one InsertAction per nonempty table, with all rows in the window.
+    ** Serialize flushers only; statement threads never acquire this monitor.
+    *******************************************************************************/
+   public synchronized void flushNow()
+   {
+      boolean previous = AttributionListener.suppress(true);
+      try
+      {
+         Instant end = Instant.now();
+         AttributionListener.Window window = listener.drain(end);
+         List<QRecord> attribution = records(window.attribution(), window.start(), end, false);
+         List<QRecord> repeats = records(window.repeats(), window.start(), end, true);
+         if(!attribution.isEmpty() || !repeats.isEmpty())
+         {
+            runtime.transaction(() ->
+            {
+               insert("db_perf_attribution", attribution);
+               insert("db_perf_repeat_pattern", repeats);
+               return (null);
+            });
+         }
+      }
+      catch(Exception e)
+      {
+         failed();
+      }
+      finally
+      {
+         refreshSettings();
+         AttributionListener.suppress(previous);
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Refresh even after failed writes, including while attribution is disabled.
+    *******************************************************************************/
+   public synchronized void refreshSettings()
+   {
+      boolean previous = AttributionListener.suppress(true);
+      try
+      {
+         listener.refresh(new DbPerfSettingsService(runtime).ensure(runtime.getConfig().getBackendName()));
+      }
+      catch(Exception e)
+      {
+         failed();
+      }
+      finally
+      {
+         AttributionListener.suppress(previous);
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Rate-limited fixed text; database errors may contain sensitive SQL.
+    *******************************************************************************/
+   private void failed()
+   {
+      failures++;
+      if(failures == 1 || failures % 1000 == 0)
+      {
+         LOG.warn("Database Performance attribution write or settings refresh failed; the failed window is dropped");
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Convert nanoseconds to persisted milliseconds without floating point loss.
+    *******************************************************************************/
+   private List<QRecord> records(Map<AttributionListener.Key, AttributionListener.Counters> values, Instant start, Instant end, boolean repeat)
+   {
+      List<QRecord> records = new ArrayList<>(values.size());
+      for(Map.Entry<AttributionListener.Key, AttributionListener.Counters> entry : values.entrySet())
+      {
+         AttributionListener.Key key = entry.getKey();
+         AttributionListener.Counters counts = entry.getValue();
+         QRecord row = new QRecord().withValue("windowStart", start).withValue("windowEnd", end)
+            .withValue("podName", truncate(runtime.getConfig().getPodName(), 200)).withValue("unitKind", key.kind())
+            .withValue("unitName", truncate(key.name(), 300)).withValue("processName", truncate(key.process(), 200))
+            .withValue("tableName", truncate(key.table(), 200)).withValue("fingerprint", key.fingerprint())
+            .withValue("sqlText", truncate(counts.sql, 4000)).withValue("sampleRate", counts.sampleRate < 0 ? null : BigDecimal.valueOf(counts.sampleRate));
+         if(repeat)
+         {
+            row.withValue("unitsAffected", counts.units.sum()).withValue("totalRepeats", counts.statements.sum())
+               .withValue("maxRepeats", (int) Math.min(Integer.MAX_VALUE, counts.max.get()));
+         }
+         else
+         {
+            row.withValue("operation", key.operation()).withValue("units", counts.units.sum()).withValue("statements", counts.statements.sum())
+               .withValue("totalMs", BigDecimal.valueOf(counts.nanos.sum(), 6)).withValue("maxMs", BigDecimal.valueOf(counts.max.get(), 6))
+               .withValue("rowsCount", counts.rows.sum()).withValue("errors", counts.errors.sum());
+         }
+         records.add(row);
+      }
+      return (records);
+   }
+
+
+   /*******************************************************************************
+    ** Bound text at the persistence boundary after normalization.
+    *******************************************************************************/
+   private static String truncate(String value, int length)
+   {
+      return (value == null || value.length() <= length ? value : value.substring(0, length));
+   }
+
+
+   /*******************************************************************************
+    ** Reject record-level failures so the whole window transaction rolls back.
+    *******************************************************************************/
+   private static void insert(String table, List<QRecord> rows) throws Exception
+   {
+      if(!rows.isEmpty())
+      {
+         List<QRecord> inserted = InsertAction.executeForRecords(new InsertInput(table).withRecords(rows).withTransaction(QContext.getQBackendTransaction()));
+         if(inserted.size() != rows.size() || inserted.stream().anyMatch(row -> row.getErrors() != null && !row.getErrors().isEmpty()))
+         {
+            throw (new IllegalStateException("Attribution insert failed"));
+         }
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Listener exposed for deterministic delivery and registration tests.
+    *******************************************************************************/
+   public AttributionListener getListener()
+   {
+      return (listener);
+   }
+
+
+   /*******************************************************************************
+    ** Unregister first, stop scheduling, and flush one final detached window.
+    *******************************************************************************/
+   @Override
+   public synchronized void close()
+   {
+      if(closed)
+      {
+         return;
+      }
+      closed = true;
+      StatementExecutionListeners.unregister(listener);
+      if(executor != null)
+      {
+         executor.shutdownNow();
+      }
+      if(shutdownHook != null && Thread.currentThread() != shutdownHook)
+      {
+         try
+         {
+            Runtime.getRuntime().removeShutdownHook(shutdownHook);
+         }
+         catch(IllegalStateException expected)
+         {
+            // JVM shutdown is already running the hook.
+         }
+      }
+      flushNow();
+   }
+}

src/main/java/com/kingsrook/qbits/dbperformance/attribution/AttributionListener.java

@@ -0,0 +1,425 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance.attribution;
+
+
+import java.time.Instant;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ThreadLocalRandom;
+import java.util.concurrent.atomic.AtomicLong;
+import java.util.concurrent.atomic.LongAdder;
+import com.kingsrook.qbits.dbperformance.DbPerfQBitConfig;
+import com.kingsrook.qbits.dbperformance.DbPerfRuntime;
+import com.kingsrook.qbits.dbperformance.normalize.SqlNormalizer;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.instrumentation.StatementExecution;
+import com.kingsrook.qqq.backend.core.instrumentation.StatementExecutionListener;
+import com.kingsrook.qqq.backend.core.instrumentation.UnitOfWork;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Bounded, in-memory attribution. No table actions run on statement threads.
+ ** Completed units belong to the window in which they end, including long units.
+ *******************************************************************************/
+public class AttributionListener implements StatementExecutionListener
+{
+   private static final String OTHER = "(other)";
+   private static final Key OVERFLOW = new Key("OTHER", OTHER, OTHER, OTHER, "OTHER", SqlNormalizer.fingerprint(OTHER), -1);
+   private static final ThreadLocal<Boolean> SUPPRESSED = ThreadLocal.withInitial(() -> false);
+   private final DbPerfRuntime runtime;
+   private final ConcurrentHashMap<String, Shape> shapes = new ConcurrentHashMap<>();
+   private final ThreadLocal<Buffer> current = new ThreadLocal<>();
+   private volatile Settings settings = new Settings(false, 1.0, 60, 10000, 10);
+   private Window window = new Window(Instant.now(), new HashMap<>(), new HashMap<>());
+
+
+   /*******************************************************************************
+    ** Bind to one instance and monitored backend.
+    *******************************************************************************/
+   public AttributionListener(DbPerfRuntime runtime)
+   {
+      this.runtime = runtime;
+   }
+
+
+   /*******************************************************************************
+    ** Ignore self-observation, then sample and count without database access.
+    *******************************************************************************/
+   @Override
+   public void onStatement(StatementExecution execution)
+   {
+      Settings copy = settings;
+      if(!copy.enabled() || !Boolean.TRUE.equals(runtime.getConfig().getAttributionEnabled()) || SUPPRESSED.get()
+         || !runtime.getConfig().getBackendName().equals(execution.backendName())
+         || (execution.tableName() != null && execution.tableName().startsWith(DbPerfQBitConfig.TABLE_NAME_PREFIX))
+         || (QContext.getQInstance() != null && QContext.getQInstance() != runtime.getInstance()))
+      {
+         return;
+      }
+      UnitOfWork unit = execution.unitOfWork();
+      Buffer buffer = current.get();
+      if(buffer != null && (unit == null || buffer.unit.getId() != unit.getId()))
+      {
+         merge(buffer);
+         current.remove();
+         buffer = null;
+      }
+      if(unit != null && buffer == null)
+      {
+         buffer = new Buffer(unit, copy, sampled(unit.getId(), copy.sampleRate()));
+         current.set(buffer);
+      }
+      if(buffer == null ? !sampled(ThreadLocalRandom.current().nextLong(), copy.sampleRate()) : !buffer.sampled)
+      {
+         return;
+      }
+      Shape shape = shape(execution.sql());
+      Key key = new Key(unit == null ? "OTHER" : unit.getKind().name(), unit == null ? name(execution.processName()) : "",
+         execution.processName(), execution.tableName(), execution.operation() == null ? "OTHER" : execution.operation().name(), shape.fingerprint(), buffer == null ? copy.sampleRate() : buffer.settings.sampleRate());
+      if(buffer == null)
+      {
+         synchronized(this)
+         {
+            Key target = bounded(window.attribution(), key, copy.maxKeys());
+            Counters counts = window.attribution().computeIfAbsent(target, ignored -> new Counters(target == OVERFLOW ? OTHER : shape.sql(), key.sampleRate()));
+            counts.sampleRate(key.sampleRate());
+            counts.add(execution);
+            counts.units.increment();
+         }
+      }
+      else
+      {
+         Key target = bounded(buffer.counts, key, Math.max(2, buffer.settings.maxKeys()));
+         buffer.counts.computeIfAbsent(target, ignored -> new Counters(target == OVERFLOW ? OTHER : shape.sql(), key.sampleRate())).add(execution);
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Read the final route name, then release all per-thread counters.
+    *******************************************************************************/
+   @Override
+   public void onUnitOfWorkEnd(UnitOfWork unit)
+   {
+      Buffer buffer = current.get();
+      if(buffer != null && buffer.unit.getId() == unit.getId())
+      {
+         current.remove();
+         if(settings.enabled() && Boolean.TRUE.equals(runtime.getConfig().getAttributionEnabled()))
+         {
+            merge(buffer);
+         }
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Merge each unit once per destination, even when several shapes overflow.
+    ** Repeat counts are combined across operations before threshold evaluation.
+    *******************************************************************************/
+   private synchronized void merge(Buffer buffer)
+   {
+      Set<Key> touched = new HashSet<>();
+      Map<Key, Counters> repeats = new HashMap<>();
+      for(Map.Entry<Key, Counters> entry : buffer.counts.entrySet())
+      {
+         Key local = entry.getKey();
+         Key key = local == OVERFLOW ? OVERFLOW : new Key(local.kind(), name(buffer.unit.getName()), local.process(), local.table(), local.operation(), local.fingerprint(), buffer.settings.sampleRate());
+         Key target = bounded(window.attribution(), key, settings.maxKeys());
+         Counters counts = window.attribution().computeIfAbsent(target, ignored -> new Counters(target == OVERFLOW ? OTHER : entry.getValue().sql, entry.getValue().sampleRate));
+         counts.merge(entry.getValue());
+         if(touched.add(target))
+         {
+            counts.units.increment();
+         }
+         // Collapsed shapes cannot prove repetition of any one fingerprint.
+         if(local != OVERFLOW)
+         {
+            Key repeat = new Key(key.kind(), key.name(), key.process(), key.table(), null, key.fingerprint(), key.sampleRate());
+            repeats.computeIfAbsent(repeat, ignored -> new Counters(entry.getValue().sql, entry.getValue().sampleRate)).merge(entry.getValue());
+         }
+      }
+      Map<Key, Long> totals = new HashMap<>();
+      Map<Key, Long> maxima = new HashMap<>();
+      for(Map.Entry<Key, Counters> entry : repeats.entrySet())
+      {
+         long count = entry.getValue().statements.sum();
+         if(count >= buffer.settings.threshold())
+         {
+            Key target = bounded(window.repeats(), entry.getKey(), settings.maxKeys());
+            window.repeats().computeIfAbsent(target, ignored -> new Counters(target == OVERFLOW ? OTHER : entry.getValue().sql, entry.getValue().sampleRate));
+            window.repeats().get(target).sampleRate(entry.getValue().sampleRate);
+            totals.merge(target, count, Long::sum);
+            maxima.merge(target, count, Math::max);
+         }
+      }
+      for(Map.Entry<Key, Long> entry : totals.entrySet())
+      {
+         Counters counts = window.repeats().get(entry.getKey());
+         counts.units.increment();
+         counts.statements.add(entry.getValue());
+         counts.max.accumulateAndGet(maxima.get(entry.getKey()), Math::max);
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Reserve one slot for a universal overflow key, preserving the strict cap.
+    *******************************************************************************/
+   private static Key bounded(Map<Key, Counters> counts, Key key, int limit)
+   {
+      return (counts.containsKey(key) || (key != OVERFLOW && counts.size() < limit - (counts.containsKey(OVERFLOW) ? 0 : 1)) ? key : OVERFLOW);
+   }
+
+
+   /*******************************************************************************
+    ** Normalize once per raw SQL shape; cold-cache admission alone is serialized.
+    *******************************************************************************/
+   private Shape shape(String sql)
+   {
+      String raw = sql == null ? "" : sql;
+      Shape cached = shapes.get(raw);
+      if(cached != null)
+      {
+         return (cached);
+      }
+      String normalized = SqlNormalizer.normalize(raw);
+      Shape created = new Shape(normalized, SqlNormalizer.fingerprint(normalized));
+      synchronized(shapes)
+      {
+         if(shapes.size() >= 5000)
+         {
+            shapes.clear();
+         }
+         shapes.put(raw, created);
+      }
+      return (created);
+   }
+
+
+   /*******************************************************************************
+    ** SplitMix64 finalizer distributes sequential unit IDs without allocations.
+    *******************************************************************************/
+   private static boolean sampled(long id, double rate)
+   {
+      long hash = (id ^ (id >>> 30)) * 0xbf58476d1ce4e5b9L;
+      hash = (hash ^ (hash >>> 27)) * 0x94d049bb133111ebL;
+      hash ^= hash >>> 31;
+      return ((hash >>> 11) * 0x1.0p-53 < rate);
+   }
+
+
+   /*******************************************************************************
+    ** Use a stable label for units without a name.
+    *******************************************************************************/
+   private static String name(String value)
+   {
+      return (value == null || value.isBlank() ? "(none)" : value);
+   }
+
+
+   /*******************************************************************************
+    ** Detach an immutable-in-practice window; no writers retain its counters.
+    *******************************************************************************/
+   synchronized Window drain(Instant end)
+   {
+      Window previous = window;
+      window = new Window(end, new HashMap<>(), new HashMap<>());
+      return (previous);
+   }
+
+
+   /*******************************************************************************
+    ** Publish a validated immutable settings copy only from the flusher.
+    *******************************************************************************/
+   void refresh(QRecord row)
+   {
+      double rate = row.getValueBigDecimal("attributionSampleRate") == null ? 1.0 : row.getValueBigDecimal("attributionSampleRate").doubleValue();
+      settings = new Settings(!Boolean.FALSE.equals(row.getValueBoolean("attributionEnabled")), Math.max(0, Math.min(1, rate)),
+         positive(row, "attributionFlushSeconds", 60), positive(row, "attributionMaxKeys", 10000), positive(row, "nPlusOneThreshold", 10));
+   }
+
+
+   /*******************************************************************************
+    ** Invalid administrative values use defaults.
+    *******************************************************************************/
+   private static int positive(QRecord row, String field, int fallback)
+   {
+      Integer value = row.getValueInteger(field);
+      return (value == null || value <= 0 ? fallback : value);
+   }
+
+
+   /*******************************************************************************
+    ** Current settings for scheduling and window annotations.
+    *******************************************************************************/
+   Settings settings()
+   {
+      return (settings);
+   }
+
+
+   /*******************************************************************************
+    ** Set thread suppression, returning the previous state for nested callers.
+    *******************************************************************************/
+   static boolean suppress(boolean value)
+   {
+      boolean previous = SUPPRESSED.get();
+      if(value)
+      {
+         SUPPRESSED.set(true);
+      }
+      else
+      {
+         SUPPRESSED.remove();
+      }
+      return (previous);
+   }
+
+
+   /*******************************************************************************
+    ** Immutable administrative settings.
+    *******************************************************************************/
+   record Settings(boolean enabled, double sampleRate, int flushSeconds, int maxKeys, int threshold)
+   {
+   }
+
+
+   /*******************************************************************************
+    ** Attribution dimensions; sampling transitions remain separately interpretable.
+    ** Null operation denotes a repeat pattern.
+    *******************************************************************************/
+   record Key(String kind, String name, String process, String table, String operation, String fingerprint, double sampleRate)
+   {
+   }
+
+
+   /*******************************************************************************
+    ** Cached literal-free text and its digest.
+    *******************************************************************************/
+   private record Shape(String sql, String fingerprint)
+   {
+   }
+
+
+   /*******************************************************************************
+    ** Detached window transferred to the flusher.
+    *******************************************************************************/
+   record Window(Instant start, Map<Key, Counters> attribution, Map<Key, Counters> repeats)
+   {
+   }
+
+
+   /*******************************************************************************
+    ** Thread-confined unit, including its once-only sampling decision.
+    *******************************************************************************/
+   private static class Buffer
+   {
+      private final UnitOfWork unit;
+      private final Settings settings;
+      private final boolean sampled;
+      private final Map<Key, Counters> counts = new HashMap<>();
+
+
+      /*******************************************************************************
+       ** Capture unit settings so refresh cannot partially sample a unit.
+       *******************************************************************************/
+      private Buffer(UnitOfWork unit, Settings settings, boolean sampled)
+      {
+         this.unit = unit;
+         this.settings = settings;
+         this.sampled = sampled;
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Additive counters plus an atomic maximum, shared by both window tables.
+    *******************************************************************************/
+   static class Counters
+   {
+      final String sql;
+      double sampleRate;
+      final LongAdder units = new LongAdder();
+      final LongAdder statements = new LongAdder();
+      final LongAdder nanos = new LongAdder();
+      final AtomicLong max = new AtomicLong();
+      final LongAdder rows = new LongAdder();
+      final LongAdder errors = new LongAdder();
+
+
+      /*******************************************************************************
+       ** Retain only normalized SQL.
+       *******************************************************************************/
+      Counters(String sql, double sampleRate)
+      {
+         this.sql = sql;
+         this.sampleRate = sampleRate;
+      }
+
+
+      /*******************************************************************************
+       ** Count one completed statement, including failures and unknown row counts.
+       *******************************************************************************/
+      void add(StatementExecution execution)
+      {
+         statements.increment();
+         nanos.add(execution.elapsedNanos());
+         max.accumulateAndGet(execution.elapsedNanos(), Math::max);
+         rows.add(execution.rowCount() == null ? 0 : execution.rowCount());
+         if(!execution.succeeded())
+         {
+            errors.increment();
+         }
+      }
+
+
+      /*******************************************************************************
+       ** An overflow bucket spanning sampling rates has no single valid rate.
+       *******************************************************************************/
+      void sampleRate(double rate)
+      {
+         if(sampleRate != rate)
+         {
+            sampleRate = -1;
+         }
+      }
+
+
+      /*******************************************************************************
+       ** Fold statement totals; distinct units are managed by the caller.
+       *******************************************************************************/
+      void merge(Counters other)
+      {
+         sampleRate(other.sampleRate);
+         statements.add(other.statements.sum());
+         nanos.add(other.nanos.sum());
+         max.accumulateAndGet(other.max.get(), Math::max);
+         rows.add(other.rows.sum());
+         errors.add(other.errors.sum());
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/dbperformance/attribution/AttributionRuntimeService.java

@@ -0,0 +1,69 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance.attribution;
+
+
+import com.kingsrook.qbits.dbperformance.DbPerfRuntime;
+import com.kingsrook.qqq.backend.core.instances.QRuntimeServiceInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+
+
+/*******************************************************************************
+ ** QApplicationLauncher lifecycle, after instance initialization and migrations.
+ *******************************************************************************/
+public class AttributionRuntimeService implements QRuntimeServiceInterface
+{
+   private DbPerfRuntime runtime;
+
+
+   /*******************************************************************************
+    ** Name used by the host launcher.
+    *******************************************************************************/
+   @Override
+   public String getName()
+   {
+      return ("dbPerformanceAttribution");
+   }
+
+
+   /*******************************************************************************
+    ** Start on each application pod, independently of the job scheduler.
+    *******************************************************************************/
+   @Override
+   public void start(QInstance instance)
+   {
+      runtime = DbPerfRuntime.of(instance);
+      runtime.startAttribution();
+   }
+
+
+   /*******************************************************************************
+    ** Stop listener delivery and persist the final completed units.
+    *******************************************************************************/
+   @Override
+   public void stop()
+   {
+      if(runtime != null)
+      {
+         runtime.stopAttribution();
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/dbperformance/collect/DbPerfStore.java

@@ -66,6 +66,48 @@ public final class DbPerfStore
    }
 
 
+   /*******************************************************************************
+    ** Keyset-paged read for tables that can hold more rows than fit in the heap
+    ** (attribution writes hundreds of thousands per day). At most pageSize
+    ** records are held at once; the consumer must not keep the page.
+    *******************************************************************************/
+   public static void forEachPage(String table, QQueryFilter filter, int pageSize, PageConsumer consumer) throws Exception
+   {
+      Serializable lastId = 0;
+      while(true)
+      {
+         QQueryFilter page = new QQueryFilter().withSubFilter(filter).withCriteria(new QFilterCriteria("id", QCriteriaOperator.GREATER_THAN, lastId))
+            .withOrderBy(new QFilterOrderBy("id", true)).withLimit(pageSize);
+         List<QRecord> rows = query(table, page);
+         if(rows.isEmpty())
+         {
+            return;
+         }
+         consumer.accept(rows);
+         if(rows.size() < pageSize)
+         {
+            return;
+         }
+         lastId = rows.getLast().getValue("id");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Receives one bounded page from forEachPage.
+    *******************************************************************************/
+   @FunctionalInterface
+   public interface PageConsumer
+   {
+      /***************************************************************************
+       ** Handle one page.
+       ***************************************************************************/
+      void accept(List<QRecord> page) throws Exception;
+   }
+
+
+
    /*******************************************************************************
     ** First matching record.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/dbperformance/collect/RollupService.java

@@ -168,7 +168,19 @@ public class RollupService
    {
       Map<String, QRecord> groups = new LinkedHashMap<>();
       List<String> dimensions = List.of("unitKind", "unitName", "processName", "tableName", "operation", "fingerprint");
-      for(QRecord row : DbPerfStore.query("db_perf_attribution", range("windowStart", start, end)))
+      DbPerfStore.forEachPage("db_perf_attribution", range("windowStart", start, end), DbPerfStore.BATCH_SIZE, page -> mergeAttribution(day, page, dimensions, groups));
+      replace("db_perf_attribution_daily", day, new ArrayList<>(groups.values()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Fold one page of attribution detail into the day's groups. Memory is
+    ** bounded by distinct dimension keys, never by the day's detail row count.
+    *******************************************************************************/
+   private static void mergeAttribution(LocalDate day, List<QRecord> page, List<String> dimensions, Map<String, QRecord> groups)
+   {
+      for(QRecord row : page)
       {
          StringBuilder key = new StringBuilder();
          for(String field : dimensions)
@@ -187,7 +199,6 @@ public class RollupService
          sumDecimal(aggregate, row, "totalMs");
          aggregate.setValue("maxMs", SnapshotCollector.decimal(aggregate, "maxMs").max(SnapshotCollector.decimal(row, "maxMs")));
       }
-      replace("db_perf_attribution_daily", day, new ArrayList<>(groups.values()));
    }
 
 

src/main/java/com/kingsrook/qbits/dbperformance/collect/SnapshotCollector.java

@@ -47,7 +47,9 @@ import com.kingsrook.qbits.dbperformance.provider.IndexStats;
 import com.kingsrook.qbits.dbperformance.provider.ProviderCapabilities;
 import com.kingsrook.qbits.dbperformance.provider.SessionInfo;
 import com.kingsrook.qbits.dbperformance.provider.StatementStats;
+import com.kingsrook.qbits.dbperformance.provider.StatsFeature;
 import com.kingsrook.qbits.dbperformance.provider.TableStats;
+import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
@@ -55,6 +57,7 @@ import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
 import com.kingsrook.qqq.backend.module.rdbms.jdbc.ConnectionManager;
 import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
+import static com.kingsrook.qqq.backend.core.logging.LogUtils.logPair;
 
 
 /*******************************************************************************
@@ -62,6 +65,8 @@ import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaDat
  *******************************************************************************/
 public class SnapshotCollector
 {
+   private static final QLogger LOG = QLogger.getLogger(SnapshotCollector.class);
+
    private final DbPerfRuntime runtime;
    private final Clock clock;
    private final DbStatsProvider providerOverride;
@@ -104,6 +109,7 @@ public class SnapshotCollector
                throw (new IllegalArgumentException("Backend is not configured for this runtime"));
             }
             QRecord settings = new DbPerfSettingsService(runtime).ensure(backendName);
+            failAbandonedRuns(backendName, settings);
             QRecord inserted = runtime.asSystem(() -> DbPerfStore.insert("db_perf_snapshot", List.of(snapshot)).getFirst());
             snapshot.setValue("id", inserted.getValueInteger("id"));
             runtime.transaction(() ->
@@ -121,9 +127,19 @@ public class SnapshotCollector
                return (null);
             });
          }
-         catch(Exception e)
+         catch(Throwable e)
          {
-            // Never persist a JDBC exception message: it may contain SQL literals.
+            //////////////////////////////////////////////////////////////////////////
+            // Errors too (a StackOverflowError once left runs RUNNING with no log). //
+            // Never persist or log a JDBC exception message: it may contain SQL    //
+            // literals. The class and the throwing frame identify the cause.       //
+            //////////////////////////////////////////////////////////////////////////
+            if(e instanceof OutOfMemoryError outOfMemory)
+            {
+               throw (outOfMemory);
+            }
+            LOG.error("Database performance snapshot failed", logPair("backend", backendName), logPair("snapshotId", snapshot.getValueInteger("id")),
+               logPair("exception", e.getClass().getName()), logPair("at", e.getStackTrace().length == 0 ? null : e.getStackTrace()[0].toString()));
             snapshot.withValue("status", "FAILED").withValue("errorMessage", "Collection failed (" + e.getClass().getSimpleName() + "). Check database connectivity, schema and statistics access.")
                .withValue("durationMs", (int) Math.min(Integer.MAX_VALUE, (System.nanoTime() - started) / 1000000));
             if(snapshot.getValueInteger("id") != null)
@@ -149,6 +165,33 @@ public class SnapshotCollector
    }
 
 
+   /*******************************************************************************
+    ** Runs left RUNNING by a crashed pod or an earlier failure are closed as
+    ** FAILED once they are older than three collection intervals.
+    *******************************************************************************/
+   private void failAbandonedRuns(String backendName, QRecord settings) throws Exception
+   {
+      int     interval = positive(settings, "snapshotIntervalMinutes", 5);
+      Instant cutoff   = clock.instant().minus(Duration.ofMinutes(3L * interval));
+      List<QRecord> abandoned = runtime.asSystem(() -> DbPerfStore.query("db_perf_snapshot", DbPerfStore.eq("backendName", backendName)
+         .withCriteria(new QFilterCriteria("status", QCriteriaOperator.EQUALS, "RUNNING"))
+         .withCriteria(new QFilterCriteria("capturedAt", QCriteriaOperator.LESS_THAN, cutoff))));
+      if(abandoned.isEmpty())
+      {
+         return;
+      }
+      List<QRecord> updates = abandoned.stream().map(row -> new QRecord().withValue("id", row.getValueInteger("id")).withValue("status", "FAILED")
+         .withValue("errorMessage", "Collection did not finish (the run was interrupted or its pod stopped).")).toList();
+      runtime.asSystem(() ->
+      {
+         DbPerfStore.update("db_perf_snapshot", updates);
+         return (null);
+      });
+      LOG.warn("Closed abandoned database performance snapshots", logPair("backend", backendName), logPair("count", updates.size()));
+   }
+
+
+
    /*******************************************************************************
     ** Statistics read and writes under the ambient system transaction.
     *******************************************************************************/
@@ -175,7 +218,7 @@ public class SnapshotCollector
       Instant now = snapshot.getValueInstant("capturedAt");
       QQueryFilter filter = DbPerfStore.eq("backendName", backendName)
          .withCriteria(new QFilterCriteria("status", QCriteriaOperator.IN, List.of("OK", "PARTIAL")))
-         .withCriteria(new QFilterCriteria("rawXactCommit", QCriteriaOperator.IS_NOT_BLANK))
+         .withCriteria(new QFilterCriteria("databaseSizeBytes", QCriteriaOperator.IS_NOT_BLANK))
          .withOrderBy(new QFilterOrderBy("capturedAt", false));
       QRecord previous = DbPerfStore.first("db_perf_snapshot", filter);
       Instant previousCapture = previous == null ? null : previous.getValueInstant("capturedAt");
@@ -214,8 +257,9 @@ public class SnapshotCollector
                }
             }
             snapshot.withValue("rawStatsReset", database.statsReset()).withValue("statsResetDetected", databaseReset)
-               .withValue("databaseSizeBytes", database.sizeBytes()).withValue("maxConnections", database.maxConnections())
-               .withValue("cacheHitRatio", ratio(number(snapshot, "blksHit"), number(snapshot, "blksHit") + number(snapshot, "blksRead")));
+               .withValue("databaseSizeBytes", database.sizeBytes())
+               .withValue("cacheHitRatio", capability.has(StatsFeature.CACHE_COUNTERS) ? ratio(number(snapshot, "blksHit"), number(snapshot, "blksHit") + number(snapshot, "blksRead")) : null)
+               .withValue("maxConnections", capability.has(StatsFeature.MAX_CONNECTIONS) ? database.maxConnections() : null);
             if(capability.statements())
             {
                Instant reset = provider.readStatementResetInfo(connection).statsReset();
@@ -399,8 +443,8 @@ public class SnapshotCollector
          QRecord row = new QRecord().withValue("backendName", backend).withValue("schemaName", entry.schemaName()).withValue("tableName", entry.tableName()).withValue("relid", entry.relid()).withValue("lastSeenAt", now);
          entry.counters().forEach(row::setValue);
          entry.maintenance().forEach(row::setValue);
-         row.withValue("deadRatio", ratio(number(row, "nDeadTup"), number(row, "nLiveTup") + number(row, "nDeadTup")))
-            .withValue("seqScanShare", ratio(number(row, "seqScan"), number(row, "seqScan") + number(row, "idxScan")));
+         row.withValue("deadRatio", entry.counters().containsKey("nDeadTup") ? ratio(number(row, "nDeadTup"), number(row, "nLiveTup") + number(row, "nDeadTup")) : null)
+            .withValue("seqScanShare", entry.counters().containsKey("seqScan") ? ratio(number(row, "seqScan"), number(row, "seqScan") + number(row, "idxScan")) : null);
          if(old == null)
          {
             inserts.add(row);

src/main/java/com/kingsrook/qbits/dbperformance/explain/ExplainService.java

@@ -38,6 +38,10 @@ import com.kingsrook.qbits.dbperformance.collect.DbPerfSettingsService;
 import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
 import com.kingsrook.qbits.dbperformance.collect.SnapshotCollector;
 import com.kingsrook.qbits.dbperformance.normalize.SqlNormalizer;
+import com.kingsrook.qbits.dbperformance.provider.DbStatsProvider;
+import com.kingsrook.qbits.dbperformance.provider.DbStatsProviders;
+import com.kingsrook.qbits.dbperformance.provider.ProviderCapabilities;
+import com.kingsrook.qbits.dbperformance.provider.StatsFeature;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QBadRequestException;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
@@ -135,8 +139,9 @@ public class ExplainService
          boolean generic = !analyze && parsed.parameterCount() > 0;
          audit.setValue("mode", analyze ? "ANALYZE" : generic ? "GENERIC" : "PLAN");
          QRecord settings = new DbPerfSettingsService(runtime).ensure(request.backendName());
-         json = execute(parsed.sql(), parameters, analyze, generic, SnapshotCollector.positive(settings, "explainTimeoutMs", 10000));
-         plan = PlanTextRenderer.render(json);
+         Explained explained = execute(parsed, parameters, analyze, generic, SnapshotCollector.positive(settings, "explainTimeoutMs", 10000));
+         json = explained.json();
+         plan = explained.plan();
          if(!analyze && (storedStatement || sql.equals(SqlNormalizer.normalize(sql))))
          {
             audit.setValue("planJson", json);
@@ -181,7 +186,7 @@ public class ExplainService
       }
       return (new ExplainResult(audit.getValueString("mode"), json, plan.text(), plan.totalCost(), plan.actualTotalMs(), warnings,
          audit.getValueInteger("id"), runtime.getConfig().getSqlWorkbenchRunnerPath() + "?sql=" + encode("EXPLAIN " + sql) + "&backend=" + encode(request.backendName()),
-         "Explain this PostgreSQL query plan and suggest improvements.\n\nQuery:\n" + SqlNormalizer.normalize(sql) + "\n\nPlan:\n" + plan.safeText()));
+         "Explain this " + (json == null ? "database" : "PostgreSQL") + " query plan and suggest improvements.\n\nQuery:\n" + SqlNormalizer.normalize(sql) + "\n\nPlan:\n" + plan.safeText()));
    }
 
 
@@ -190,89 +195,141 @@ public class ExplainService
     ** Roll back even on parse, execution or timeout failure, deallocate after rollback,
     ** and restore pool state before releasing this dedicated connection.
     *******************************************************************************/
-   private String execute(String sql, List<String> parameters, boolean analyze, boolean generic, int timeout) throws Exception
+   private Explained execute(ExplainSql.Parsed parsed, List<String> parameters, boolean analyze, boolean generic, int timeout) throws Exception
    {
       try(Connection connection = openConnection())
       {
          if(!"PostgreSQL".equals(connection.getMetaData().getDatabaseProductName()))
          {
-            throw (new QBadRequestException("Query plans currently require PostgreSQL."));
-         }
-         if(generic && connection.getMetaData().getDatabaseMajorVersion() < 16)
-         {
-            throw (new QBadRequestException("Generic plans require PostgreSQL 16 or later. Use ANALYZE with parameter values if authorized."));
-         }
-         boolean autoCommit = connection.getAutoCommit();
-         boolean readOnly = connection.isReadOnly();
-         String preparedName = "dbperf_" + UUID.randomUUID().toString().replace("-", "");
-         boolean prepared = false;
-         try
-         {
-            connection.setAutoCommit(false);
-            try(Statement statement = connection.createStatement())
+            //////////////////////////////////////////////////////////////////
+            // other vendors plan through their provider as text (no JSON) //
+            //////////////////////////////////////////////////////////////////
+            DbStatsProvider provider = DbStatsProviders.forConnection(connection);
+            ProviderCapabilities capability = provider.capabilities(connection);
+            if(!capability.has(StatsFeature.EXPLAIN_TEXT) || generic && !capability.has(StatsFeature.EXPLAIN_GENERIC))
             {
-               statement.execute("SET TRANSACTION READ ONLY");
-               statement.execute("SET LOCAL statement_timeout = " + timeout);
-               statement.execute("SET LOCAL standard_conforming_strings = on");
-               if(!analyze)
-               {
-                  // GENERIC_PLAN must not be parsed as an external JDBC bind request.
-                  statement.unwrap(PgStatement.class).executeWithFlags("EXPLAIN (" + (generic ? "GENERIC_PLAN, " : "") + "FORMAT JSON) " + sql, QueryExecutor.QUERY_EXECUTE_AS_SIMPLE);
-                  try(ResultSet rows = statement.getResultSet())
-                  {
-                     rows.next();
-                     return (rows.getString(1));
-                  }
-               }
-               statement.execute("PREPARE " + preparedName + " AS " + sql);
-               prepared = true;
+               throw (new QBadRequestException("Query plans are not available for this database (" + provider.getName() + ")."));
             }
-            String arguments = parameters.isEmpty() ? "" : "(" + String.join(", ", Collections.nCopies(parameters.size(), "?")) + ")";
-            try(PreparedStatement statement = connection.prepareStatement("EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) EXECUTE " + preparedName + arguments))
+            if(analyze && !capability.has(StatsFeature.EXPLAIN_ANALYZE))
             {
-               for(int i = 0; i < parameters.size(); i++)
+               throw (new QBadRequestException("ANALYZE is not available on this " + provider.getName() + " connection (it would execute the query without a read-only transaction). Use PLAN."));
+            }
+            String text;
+            try
+            {
+               text = provider.explainText(connection, parsed.indexedSql(), parameters, analyze, timeout);
+            }
+            catch(java.sql.SQLException e)
+            {
+               if("42000".equals(e.getSQLState()) && e.getMessage() != null && e.getMessage().contains("H2"))
                {
-                  statement.setObject(i + 1, parameters.get(i), Types.OTHER);
+                  throw (new QBadRequestException(e.getMessage()));
                }
-               // EXECUTE's arguments are utility expressions: unknown bind types cannot
-               // be inferred in extended Parse. Keep JDBC binding/escaping, but send this
-               // one command in simple mode so PostgreSQL coerces the quoted strings.
-               statement.unwrap(PgStatement.class).executeWithFlags(QueryExecutor.QUERY_EXECUTE_AS_SIMPLE);
+               throw (e);
+            }
+            return (new Explained(null, new PlanTextRenderer.Plan(text, PlanTextRenderer.redactText(text), null, null)));
+         }
+         return (new Explained(postgres(connection, parsed.sql(), parameters, analyze, generic, timeout), null).rendered());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** PostgreSQL JSON plan; see {@link #execute}.
+    *******************************************************************************/
+   private String postgres(Connection connection, String sql, List<String> parameters, boolean analyze, boolean generic, int timeout) throws Exception
+   {
+      if(generic && connection.getMetaData().getDatabaseMajorVersion() < 16)
+      {
+         throw (new QBadRequestException("Generic plans require PostgreSQL 16 or later. Use ANALYZE with parameter values if authorized."));
+      }
+      boolean autoCommit = connection.getAutoCommit();
+      boolean readOnly = connection.isReadOnly();
+      String preparedName = "dbperf_" + UUID.randomUUID().toString().replace("-", "");
+      boolean prepared = false;
+      try
+      {
+         connection.setAutoCommit(false);
+         try(Statement statement = connection.createStatement())
+         {
+            statement.execute("SET TRANSACTION READ ONLY");
+            statement.execute("SET LOCAL statement_timeout = " + timeout);
+            statement.execute("SET LOCAL standard_conforming_strings = on");
+            if(!analyze)
+            {
+               // GENERIC_PLAN must not be parsed as an external JDBC bind request.
+               statement.unwrap(PgStatement.class).executeWithFlags("EXPLAIN (" + (generic ? "GENERIC_PLAN, " : "") + "FORMAT JSON) " + sql, QueryExecutor.QUERY_EXECUTE_AS_SIMPLE);
                try(ResultSet rows = statement.getResultSet())
                {
                   rows.next();
                   return (rows.getString(1));
                }
             }
+            statement.execute("PREPARE " + preparedName + " AS " + sql);
+            prepared = true;
+         }
+         String arguments = parameters.isEmpty() ? "" : "(" + String.join(", ", Collections.nCopies(parameters.size(), "?")) + ")";
+         try(PreparedStatement statement = connection.prepareStatement("EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) EXECUTE " + preparedName + arguments))
+         {
+            for(int i = 0; i < parameters.size(); i++)
+            {
+               statement.setObject(i + 1, parameters.get(i), Types.OTHER);
+            }
+            // EXECUTE's arguments are utility expressions: unknown bind types cannot
+            // be inferred in extended Parse. Keep JDBC binding/escaping, but send this
+            // one command in simple mode so PostgreSQL coerces the quoted strings.
+            statement.unwrap(PgStatement.class).executeWithFlags(QueryExecutor.QUERY_EXECUTE_AS_SIMPLE);
+            try(ResultSet rows = statement.getResultSet())
+            {
+               rows.next();
+               return (rows.getString(1));
+            }
+         }
+      }
+      finally
+      {
+         try
+         {
+            connection.rollback();
+            if(prepared)
+            {
+               try(Statement cleanup = connection.createStatement())
+               {
+                  cleanup.execute("DEALLOCATE " + preparedName);
+               }
+               finally
+               {
+                  connection.rollback();
+               }
+            }
          }
          finally
          {
-            try
-            {
-               connection.rollback();
-               if(prepared)
-               {
-                  try(Statement cleanup = connection.createStatement())
-                  {
-                     cleanup.execute("DEALLOCATE " + preparedName);
-                  }
-                  finally
-                  {
-                     connection.rollback();
-                  }
-               }
-            }
-            finally
-            {
-               connection.setReadOnly(readOnly);
-               connection.setAutoCommit(autoCommit);
-            }
+            connection.setReadOnly(readOnly);
+            connection.setAutoCommit(autoCommit);
          }
       }
    }
 
 
 
+   /*******************************************************************************
+    ** Raw plan (JSON for PostgreSQL, null for text-plan vendors) and its rendering.
+    *******************************************************************************/
+   private record Explained(String json, PlanTextRenderer.Plan plan)
+   {
+      /*******************************************************************************
+       ** Render a PostgreSQL JSON plan.
+       *******************************************************************************/
+      Explained rendered() throws Exception
+      {
+         return (new Explained(json, PlanTextRenderer.render(json)));
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Always obtain a dedicated connection, independent of any caller QQQ transaction.
     ** Protected for contract tests that verify pool state restoration on driver errors.

src/main/java/com/kingsrook/qbits/dbperformance/explain/ExplainSql.java

@@ -51,10 +51,21 @@ public final class ExplainSql
 
 
    /*******************************************************************************
-    ** Executable SQL with contiguous PostgreSQL bind slots and unquoted tokens.
+    ** Executable SQL with contiguous PostgreSQL bind slots and unquoted tokens,
+    ** plus the same SQL with JDBC-indexed ?n slots for vendors such as H2.
     *******************************************************************************/
-   public record Parsed(String sql, List<String> tokens, int parameterCount)
+   public record Parsed(String sql, List<String> tokens, int parameterCount, String indexedSql)
    {
+      /*******************************************************************************
+       ** PostgreSQL-only form (no JDBC-indexed variant).
+       *******************************************************************************/
+      public Parsed(String sql, List<String> tokens, int parameterCount)
+      {
+         this(sql, tokens, parameterCount, sql);
+      }
+
+
+
       /*******************************************************************************
        ** Reject writes, SELECT INTO and every locking SELECT, including nested CTEs.
        *******************************************************************************/
@@ -83,6 +94,7 @@ public final class ExplainSql
       StringBuilder result = new StringBuilder();
       List<String> tokens = new ArrayList<>();
       Set<Integer> positions = new HashSet<>();
+      List<int[]> slots = new ArrayList<>();
       int jdbc = 0;
       int i = 0;
       boolean ended = false;
@@ -186,6 +198,10 @@ public final class ExplainSql
                   throw (new QBadRequestException("SQL parameter positions must be between 1 and 65535."));
                }
             }
+            if(i > start + 1)
+            {
+               slots.add(new int[] {result.length(), result.length() + (i - start), Integer.parseInt(sql.substring(start + 1, i))});
+            }
             result.append(sql, start, i);
             continue;
          }
@@ -199,7 +215,9 @@ public final class ExplainSql
             }
             else
             {
-               result.append('$').append(++jdbc);
+               String slot = "$" + (++jdbc);
+               slots.add(new int[] {result.length(), result.length() + slot.length(), jdbc});
+               result.append(slot);
                i++;
             }
             continue;
@@ -223,7 +241,12 @@ public final class ExplainSql
       {
          throw (new QBadRequestException("Use either ? parameters or contiguous $1 through $n parameters."));
       }
-      return (new Parsed(result.toString().trim(), List.copyOf(tokens), Math.max(jdbc, maximum)));
+      StringBuilder indexed = new StringBuilder(result);
+      for(int slot = slots.size() - 1; slot >= 0; slot--)
+      {
+         indexed.replace(slots.get(slot)[0], slots.get(slot)[1], "?" + slots.get(slot)[2]);
+      }
+      return (new Parsed(result.toString().trim(), List.copyOf(tokens), Math.max(jdbc, maximum), indexed.toString().trim()));
    }
 
 

src/main/java/com/kingsrook/qbits/dbperformance/explain/PlanTextRenderer.java

@@ -55,6 +55,41 @@ public final class PlanTextRenderer
 
 
 
+   /*******************************************************************************
+    ** Literal-free form of a vendor text plan for prompts: quoted strings are
+    ** redacted everywhere, numbers outside comments (H2 keeps index names and
+    ** scan counts inside comments).
+    *******************************************************************************/
+   public static String redactText(String text)
+   {
+      if(text == null)
+      {
+         return (null);
+      }
+      StringBuilder result = new StringBuilder();
+      java.util.regex.Matcher comment = java.util.regex.Pattern.compile("/\\*.*?\\*/", java.util.regex.Pattern.DOTALL).matcher(text);
+      int last = 0;
+      while(comment.find())
+      {
+         result.append(redactLiterals(text.substring(last, comment.start()), true)).append(redactLiterals(comment.group(), false));
+         last = comment.end();
+      }
+      return (result.append(redactLiterals(text.substring(last), true)).toString());
+   }
+
+
+
+   /*******************************************************************************
+    ** Quoted strings, and optionally standalone numbers, become ?.
+    *******************************************************************************/
+   private static String redactLiterals(String text, boolean numbers)
+   {
+      String result = text.replaceAll("'(?:[^']|'')*'", "?");
+      return (numbers ? result.replaceAll("(?<![\\w?$.\"])\\d+(?:\\.\\d+)?(?![\\w\"])", "?") : result);
+   }
+
+
+
    /*******************************************************************************
     ** PostgreSQL emits an array containing the plan and optional execution timing.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/dbperformance/health/DbPerfHealthChecks.java

@@ -27,6 +27,7 @@ import java.util.List;
 import com.kingsrook.qbits.dbperformance.DbPerfRuntime;
 import com.kingsrook.qbits.dbperformance.analyze.RuleContext;
 import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
+import com.kingsrook.qbits.dbperformance.provider.DbStatsProviders;
 import com.kingsrook.qqq.backend.core.health.HealthCategory;
 import com.kingsrook.qqq.backend.core.health.HealthCheckKind;
 import com.kingsrook.qqq.backend.core.health.HealthCheckMetaData;
@@ -111,15 +112,15 @@ public class DbPerfHealthChecks
             return (HealthCheckOutcome.unknown("No statistics access observation yet"));
          }
          String user = ((RDBMSBackendMetaData) runtime.getInstance().getBackend(backend)).getUsername();
+         String remedy = DbStatsProviders.forProviderName(settings.getValueString("provider")).remedy(access, user);
          HealthCheckOutcome outcome = switch(access)
          {
             case "FULL" -> HealthCheckOutcome.up("Full statistics access");
-            case "NO_READ_ALL_STATS" -> HealthCheckOutcome.degraded("grant pg_read_all_stats to " + user);
-            case "NO_PG_STAT_STATEMENTS" -> HealthCheckOutcome.down("Enable pg_stat_statements in shared_preload_libraries and create the extension");
-            case "UNSUPPORTED" -> HealthCheckOutcome.down("Use a supported PostgreSQL version (13 or newer) and statistics provider");
+            case "NO_READ_ALL_STATS", "NOT_ADMIN", "NO_QUERY_STATISTICS" -> HealthCheckOutcome.degraded(remedy);
+            case "NO_PG_STAT_STATEMENTS", "UNSUPPORTED" -> HealthCheckOutcome.down(remedy);
             default -> HealthCheckOutcome.unknown("Statistics access has not been classified");
          };
-         String safe = List.of("FULL", "NO_READ_ALL_STATS", "NO_PG_STAT_STATEMENTS", "UNSUPPORTED").contains(access) ? access : "UNKNOWN";
+         String safe = List.of("FULL", "NO_READ_ALL_STATS", "NO_PG_STAT_STATEMENTS", "NO_QUERY_STATISTICS", "NOT_ADMIN", "UNSUPPORTED").contains(access) ? access : "UNKNOWN";
          return (outcome.withDetails(new HealthDetails().withValue("statsAccess", safe)));
       }
       var filter = DbPerfStore.eq("backendName", backend).withOrderBy(new QFilterOrderBy("capturedAt", false));

src/main/java/com/kingsrook/qbits/dbperformance/metadata/DbPerfMetaData.java

@@ -23,6 +23,7 @@ package com.kingsrook.qbits.dbperformance.metadata;
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 import com.kingsrook.qbits.dbperformance.DbPerfPermissions;
 import com.kingsrook.qbits.dbperformance.DbPerfQBitConfig;
 import com.kingsrook.qbits.dbperformance.model.DbPerfActivitySample;
@@ -549,9 +550,10 @@ public final class DbPerfMetaData
       repeatPattern.getField("unitsAffected").setBackendName("units_affected");
       repeatPattern.getField("maxRepeats").setBackendName("max_repeats");
       repeatPattern.getField("totalRepeats").setBackendName("total_repeats");
+      repeatPattern.getField("sampleRate").setBackendName("sample_rate");
       repeatPattern.withoutCapabilities(Capability.TABLE_INSERT, Capability.TABLE_UPDATE, Capability.TABLE_DELETE);
       repeatPattern.withSection(new QFieldSection("identity", new QIcon("table_rows"), Tier.T1, List.of("id", "windowStart", "windowEnd", "podName", "unitKind", "unitName", "processName")));
-      repeatPattern.withSection(new QFieldSection("details", new QIcon("table_rows"), Tier.T2, List.of("tableName", "fingerprint", "sqlText", "unitsAffected", "maxRepeats", "totalRepeats")));
+      repeatPattern.withSection(new QFieldSection("details", new QIcon("table_rows"), Tier.T2, List.of("tableName", "fingerprint", "sqlText", "unitsAffected", "maxRepeats", "totalRepeats", "sampleRate")));
       instance.addTable(repeatPattern);
 
       QTableMetaData finding = base(config, DbPerfFinding.TABLE_NAME, "Findings", DbPerfFinding.class);
@@ -668,7 +670,7 @@ public final class DbPerfMetaData
       child(instance, "db_perf_statement", "db_perf_finding", "statementId");
       child(instance, "db_perf_table_stat", "db_perf_finding", "tableStatId");
       child(instance, "db_perf_statement", "db_perf_explain", "statementId");
-      QAppMetaData app = new QAppMetaData().withName(config.getAppName()).withLabel("Database Performance").withIcon(new QIcon("speed"))
+      QAppMetaData app = new QAppMetaData().withName(config.getAppName()).withLabel("Database Performance").withIcon(new QIcon("storage"))
          .withPermissionRules(DbPerfPermissions.rules(config.getPermissionBaseName() + ".view"))
          .withSection(new QAppSection().withName("data").withLabel("Data").withIcon(new QIcon("table_rows"))
             .withTables(List.of("db_perf_finding", "db_perf_statement", "db_perf_table_stat", "db_perf_index_stat", "db_perf_snapshot", "db_perf_settings", "db_perf_rule")));
@@ -680,12 +682,36 @@ public final class DbPerfMetaData
    }
 
 
+   /*******************************************************************************
+    ** A distinct icon per table, so nav entries are told apart at a glance.
+    *******************************************************************************/
+   static final Map<String, String> TABLE_ICONS = Map.ofEntries(
+      Map.entry("db_perf_finding", "tips_and_updates"),
+      Map.entry("db_perf_statement", "query_stats"),
+      Map.entry("db_perf_table_stat", "grid_on"),
+      Map.entry("db_perf_index_stat", "bookmarks"),
+      Map.entry("db_perf_snapshot", "photo_camera"),
+      Map.entry("db_perf_settings", "settings_suggest"),
+      Map.entry("db_perf_rule", "playlist_add_check"),
+      Map.entry("db_perf_explain", "device_hub"),
+      Map.entry("db_perf_query_snapshot", "timeline"),
+      Map.entry("db_perf_query_daily", "calendar_month"),
+      Map.entry("db_perf_table_snapshot", "stacked_line_chart"),
+      Map.entry("db_perf_table_daily", "date_range"),
+      Map.entry("db_perf_activity_sample", "monitor_heart"),
+      Map.entry("db_perf_connection_sample", "lan"),
+      Map.entry("db_perf_attribution", "hub"),
+      Map.entry("db_perf_attribution_daily", "event_note"),
+      Map.entry("db_perf_repeat_pattern", "repeat"));
+
+
+
    /*******************************************************************************
     ** Common storage, permissions and write guard.
     *******************************************************************************/
    private static QTableMetaData base(DbPerfQBitConfig config, String name, String label, Class<? extends QRecordEntity> entity) throws QException
    {
-      QTableMetaData table = new QTableMetaData().withName(name).withLabel(label).withIcon(new QIcon("speed"))
+      QTableMetaData table = new QTableMetaData().withName(name).withLabel(label).withIcon(new QIcon(TABLE_ICONS.getOrDefault(name, "table_rows")))
          .withBackendName(config.getBackendName()).withBackendDetails(new RDBMSTableBackendDetails().withTableName(name))
          .withPrimaryKeyField("id").withFieldsFromEntity(entity)
          .withPermissionRules(DbPerfPermissions.rules(config.getPermissionBaseName() + ".view"));

src/main/java/com/kingsrook/qbits/dbperformance/metadata/DbPerfPossibleValues.java

@@ -43,7 +43,7 @@ public final class DbPerfPossibleValues
     *******************************************************************************/
    public enum Provider implements PossibleValueEnum<String>
    {
-      POSTGRES, MYSQL, UNSUPPORTED;
+      POSTGRES, H2, MYSQL, UNSUPPORTED;
 
 
       /*******************************************************************************
@@ -73,7 +73,7 @@ public final class DbPerfPossibleValues
     *******************************************************************************/
    public enum StatsAccess implements PossibleValueEnum<String>
    {
-      FULL, NO_READ_ALL_STATS, NO_PG_STAT_STATEMENTS, UNSUPPORTED;
+      FULL, NO_READ_ALL_STATS, NO_PG_STAT_STATEMENTS, NO_QUERY_STATISTICS, NOT_ADMIN, UNSUPPORTED;
 
 
       /*******************************************************************************

src/main/java/com/kingsrook/qbits/dbperformance/model/DbPerfRepeatPattern.java

@@ -21,6 +21,7 @@
 package com.kingsrook.qbits.dbperformance.model;
 
 
+import java.math.BigDecimal;
 import java.time.Instant;
 import com.kingsrook.qqq.backend.core.model.data.QField;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
@@ -73,6 +74,9 @@ public class DbPerfRepeatPattern extends QRecordEntity
    @QField
    private Long totalRepeats;
 
+   @QField
+   private BigDecimal sampleRate;
+
 
    /*******************************************************************************
     ** Default constructor.
@@ -453,4 +457,31 @@ public class DbPerfRepeatPattern extends QRecordEntity
       this.totalRepeats = totalRepeats;
       return (this);
    }
+
+   /*******************************************************************************
+    ** Getter for sampleRate.
+    *******************************************************************************/
+   public BigDecimal getSampleRate()
+   {
+      return (sampleRate);
+   }
+
+
+   /*******************************************************************************
+    ** Setter for sampleRate.
+    *******************************************************************************/
+   public void setSampleRate(BigDecimal sampleRate)
+   {
+      this.sampleRate = sampleRate;
+   }
+
+
+   /*******************************************************************************
+    ** Fluent setter for sampleRate.
+    *******************************************************************************/
+   public DbPerfRepeatPattern withSampleRate(BigDecimal sampleRate)
+   {
+      this.sampleRate = sampleRate;
+      return (this);
+   }
 }

src/main/java/com/kingsrook/qbits/dbperformance/normalize/SqlNormalizer.java

@@ -24,7 +24,10 @@ package com.kingsrook.qbits.dbperformance.normalize;
 import java.nio.charset.StandardCharsets;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.HexFormat;
+import java.util.List;
 import java.util.Locale;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -200,12 +203,86 @@ public final class SqlNormalizer
     *******************************************************************************/
    private static String collapseLists(String normalized)
    {
-      normalized = normalized.replaceAll("\\bin \\( \\?(?: , \\?)* \\)", "in ( ? )");
-      normalized = normalized.replaceAll("\\bvalues (\\( \\?(?: , \\?)* \\))(?: , \\( \\?(?: , \\?)* \\))+", "values $1");
-      return (normalized);
+      ///////////////////////////////////////////////////////////////////////////
+      // a linear scan over the space-separated tokens: regular expressions    //
+      // with nested repetition overflow the stack on very long IN and VALUES  //
+      // lists (seen with 60 KB statements in production)                      //
+      ///////////////////////////////////////////////////////////////////////////
+      ////////////////////////////////////////////////////////////////////////
+      // segments between quoted identifiers keep their edge spaces          //
+      ////////////////////////////////////////////////////////////////////////
+      String trimmed = normalized.strip();
+      if(trimmed.isEmpty())
+      {
+         return (normalized);
+      }
+      String       leading  = normalized.substring(0, normalized.indexOf(trimmed.charAt(0)));
+      String       trailing = normalized.substring(leading.length() + trimmed.length());
+      String[]     tokens   = trimmed.split(" ");
+      List<String> out    = new ArrayList<>(tokens.length);
+      int          i      = 0;
+      while(i < tokens.length)
+      {
+         String token = tokens[i];
+         if("in".equals(token))
+         {
+            int end = placeholderGroupEnd(tokens, i + 1);
+            if(end > 0)
+            {
+               out.addAll(List.of("in", "(", "?", ")"));
+               i = end;
+               continue;
+            }
+         }
+         if("values".equals(token))
+         {
+            int first = placeholderGroupEnd(tokens, i + 1);
+            if(first > 0)
+            {
+               int end = first;
+               while(end + 1 < tokens.length && ",".equals(tokens[end]))
+               {
+                  int next = placeholderGroupEnd(tokens, end + 1);
+                  if(next < 0)
+                  {
+                     break;
+                  }
+                  end = next;
+               }
+               out.add("values");
+               out.addAll(Arrays.asList(tokens).subList(i + 1, first));
+               i = end;
+               continue;
+            }
+         }
+         out.add(token);
+         i++;
+      }
+      return (leading + String.join(" ", out) + trailing);
    }
 
 
+
+   /*******************************************************************************
+    ** If tokens[start] opens "( ? , ? ... )" made only of placeholders, the index
+    ** just after its ")"; otherwise -1.
+    *******************************************************************************/
+   private static int placeholderGroupEnd(String[] tokens, int start)
+   {
+      if(start + 2 >= tokens.length || !"(".equals(tokens[start]) || !"?".equals(tokens[start + 1]))
+      {
+         return (-1);
+      }
+      int i = start + 2;
+      while(i + 1 < tokens.length && ",".equals(tokens[i]) && "?".equals(tokens[i + 1]))
+      {
+         i += 2;
+      }
+      return (i < tokens.length && ")".equals(tokens[i]) ? i + 1 : -1);
+   }
+
+
+
    /*******************************************************************************
     ** Consume a quote with SQL doubled-quote and optional escape handling.
     *******************************************************************************/

src/main/java/com/kingsrook/qbits/dbperformance/processes/DbPerfEnableStatisticsStep.java

@@ -0,0 +1,99 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance.processes;
+
+
+import java.sql.Connection;
+import java.sql.SQLException;
+import java.sql.SQLFeatureNotSupportedException;
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qbits.dbperformance.DbPerfRuntime;
+import com.kingsrook.qbits.dbperformance.collect.DbPerfSettingsService;
+import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
+import com.kingsrook.qbits.dbperformance.provider.DbStatsProvider;
+import com.kingsrook.qbits.dbperformance.provider.DbStatsProviders;
+import com.kingsrook.qbits.dbperformance.provider.ProviderCapabilities;
+import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLine;
+import com.kingsrook.qqq.backend.core.model.actions.processes.ProcessSummaryLineInterface;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.Status;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.module.rdbms.jdbc.ConnectionManager;
+import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
+
+
+/*******************************************************************************
+ ** Settings action: ask the backend's provider to turn on statement statistics
+ ** (H2: SET QUERY_STATISTICS TRUE as an admin), then record the new access.
+ ** This is the qbit's only change to the monitored database and it is explicit.
+ *******************************************************************************/
+public class DbPerfEnableStatisticsStep implements BackendStep
+{
+   /*******************************************************************************
+    ** Requires manage_settings; vendor errors become result lines.
+    *******************************************************************************/
+   @Override
+   public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+   {
+      DbPerfRuntime runtime = DbPerfRuntime.of(QContext.getQInstance());
+      if(QContext.getQSession() == null || !QContext.getQSession().hasPermission(runtime.getConfig().getPermissionBaseName() + ".manage_settings"))
+      {
+         throw (new QException("Managing settings permission is required"));
+      }
+      List<ProcessSummaryLineInterface> lines = new ArrayList<>();
+      String backend = runtime.getConfig().getBackendName();
+      try(Connection connection = ConnectionManager.getConnection((RDBMSBackendMetaData) runtime.getInstance().getBackend(backend)))
+      {
+         DbStatsProvider provider = DbStatsProviders.forConnection(connection);
+         try
+         {
+            lines.add(new ProcessSummaryLine(Status.OK, 1, provider.enableStatementStatistics(connection)));
+         }
+         catch(SQLFeatureNotSupportedException e)
+         {
+            lines.add(new ProcessSummaryLine(Status.ERROR, 0, e.getMessage()));
+         }
+         catch(SQLException e)
+         {
+            lines.add(new ProcessSummaryLine(Status.ERROR, 0, "The database refused the change (SQLSTATE " + e.getSQLState() + "); an admin database user is required."));
+         }
+         ProviderCapabilities capability = provider.capabilities(connection);
+         QRecord settings = new DbPerfSettingsService(runtime).ensure(backend);
+         DbPerfStore.update("db_perf_settings", List.of(new QRecord().withValue("id", settings.getValueInteger("id")).withValue("provider", provider.getName())
+            .withValue("statsAccess", capability.statsAccess()).withValue("statsAccessMessage", capability.message())));
+         lines.add(new ProcessSummaryLine(Status.INFO, 0, "statistics access: " + capability.statsAccess()));
+      }
+      catch(QException e)
+      {
+         throw (e);
+      }
+      catch(Exception e)
+      {
+         throw (new QException("Unable to enable statement statistics", e));
+      }
+      output.addValue("processResults", new ArrayList<>(lines));
+   }
+}

src/main/java/com/kingsrook/qbits/dbperformance/processes/DbPerfProcesses.java

@@ -54,6 +54,7 @@ public final class DbPerfProcesses
    public static final String COLLECT = "dbPerfCollectSnapshot";
    public static final String ROLLUP = "dbPerfRollupAndPurge";
    public static final String COLLECT_NOW = "dbPerfCollectNow";
+   public static final String ENABLE_STATISTICS = "dbPerfEnableStatementStatistics";
 
 
    /*******************************************************************************
@@ -100,6 +101,10 @@ public final class DbPerfProcesses
          .withTableName("db_perf_snapshot")
          .withStep(new QFrontendStepMetaData().withName("result").withLabel("Result")
             .withComponent(new QFrontendComponentMetaData().withType(QComponentType.PROCESS_SUMMARY_RESULTS))));
+      instance.addProcess(base(config, ENABLE_STATISTICS, "Enable statement statistics", DbPerfEnableStatisticsStep.class, false)
+         .withTableName("db_perf_settings")
+         .withStep(new QFrontendStepMetaData().withName("result").withLabel("Result")
+            .withComponent(new QFrontendComponentMetaData().withType(QComponentType.PROCESS_SUMMARY_RESULTS))));
    }
 
 

src/main/java/com/kingsrook/qbits/dbperformance/provider/DbStatsProvider.java

@@ -23,12 +23,17 @@ package com.kingsrook.qbits.dbperformance.provider;
 
 import java.sql.Connection;
 import java.sql.SQLException;
+import java.sql.SQLFeatureNotSupportedException;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 
 
 /*******************************************************************************
- ** Read-only database statistics SPI. Implementations never change the database.
+ ** Database statistics SPI. Every read is read-only and never changes the
+ ** database; {@link #enableStatementStatistics} is the one explicit, opt-in
+ ** change, run only from the settings action by a user who manages settings.
+ ** A provider is chosen per JDBC product name by {@link DbStatsProviders}.
  *******************************************************************************/
 public interface DbStatsProvider
 {
@@ -90,4 +95,57 @@ public interface DbStatsProvider
     ** readSettings using the supplied backend connection.
     *******************************************************************************/
    Map<String, String> readSettings(Connection connection) throws SQLException;
+
+
+
+   /*******************************************************************************
+    ** Statistics areas this vendor can supply at best, independent of a
+    ** connection. Analysis rules that need an absent area are skipped.
+    *******************************************************************************/
+   default Set<StatsFeature> features()
+   {
+      return (Set.of());
+   }
+
+
+
+   /*******************************************************************************
+    ** Operator next step for a persisted statsAccess code (health and setup).
+    *******************************************************************************/
+   default String remedy(String statsAccess, String databaseUser)
+   {
+      return ("FULL".equals(statsAccess) ? "Full statistics access" : "Use a supported database vendor and statistics provider");
+   }
+
+
+
+   /*******************************************************************************
+    ** Vendor prerequisite rows for the guided setup panel, from saved settings.
+    *******************************************************************************/
+   default List<SetupCheck> setupChecks(String statsAccess, String message)
+   {
+      return (List.of(new SetupCheck("Statistics access", statsAccess, message == null ? remedy(statsAccess, null) : message)));
+   }
+
+
+
+   /*******************************************************************************
+    ** Turn on statement statistics where the vendor allows it at runtime, and
+    ** return what was done. The default explains why it is not possible.
+    *******************************************************************************/
+   default String enableStatementStatistics(Connection connection) throws SQLException
+   {
+      throw (new SQLFeatureNotSupportedException("Statement statistics cannot be enabled at runtime for this database; see the setup panel."));
+   }
+
+
+
+   /*******************************************************************************
+    ** Vendor text plan for providers without structured JSON plans. The SQL uses
+    ** JDBC ?n slots; parameters are bound only for ANALYZE.
+    *******************************************************************************/
+   default String explainText(Connection connection, String sql, List<String> parameters, boolean analyze, int timeoutMs) throws SQLException
+   {
+      throw (new SQLFeatureNotSupportedException("Query plans are not available for this database."));
+   }
 }

src/main/java/com/kingsrook/qbits/dbperformance/provider/DbStatsProviders.java

@@ -23,13 +23,31 @@ package com.kingsrook.qbits.dbperformance.provider;
 
 import java.sql.Connection;
 import java.sql.SQLException;
+import java.util.Locale;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.function.Supplier;
 
 
 /*******************************************************************************
- ** Select a provider from JDBC product identity.
+ ** Provider registry keyed by JDBC {@code DatabaseMetaData.getDatabaseProductName()}.
+ ** Adding a vendor is one implementation of {@link DbStatsProvider} plus one
+ ** {@link #register} call (see docs/PROVIDERS.md); anything unregistered gets
+ ** {@link UnsupportedStatsProvider}.
  *******************************************************************************/
 public final class DbStatsProviders
 {
+   //////////////////////////////////////////////////////////////////////////
+   // JDBC product name (lower case) -> provider. MySQL reports "MySQL",   //
+   // MariaDB "MariaDB" (Connector/J 3) and SQLite "SQLite"; none are      //
+   // registered yet: docs/PROVIDERS.md says what each could supply.       //
+   //////////////////////////////////////////////////////////////////////////
+   private static final Map<String, Supplier<DbStatsProvider>> BY_PRODUCT = new ConcurrentHashMap<>(Map.of(
+      "postgresql", PostgresStatsProvider::new,
+      "h2", H2StatsProvider::new));
+
+
+
    /*******************************************************************************
     ** Utility class.
     *******************************************************************************/
@@ -38,11 +56,53 @@ public final class DbStatsProviders
    }
 
 
+
    /*******************************************************************************
-    ** PostgreSQL first; other vendors are explicitly unsupported.
+    ** Provider for the connection's JDBC product.
     *******************************************************************************/
    public static DbStatsProvider forConnection(Connection connection) throws SQLException
    {
-      return ("PostgreSQL".equalsIgnoreCase(connection.getMetaData().getDatabaseProductName()) ? new PostgresStatsProvider() : new UnsupportedStatsProvider());
+      return (forProductName(connection.getMetaData().getDatabaseProductName()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider for a JDBC product name; unsupported when not registered.
+    *******************************************************************************/
+   public static DbStatsProvider forProductName(String productName)
+   {
+      Supplier<DbStatsProvider> supplier = productName == null ? null : BY_PRODUCT.get(productName.toLowerCase(Locale.ROOT));
+      return (supplier == null ? new UnsupportedStatsProvider() : supplier.get());
+   }
+
+
+
+   /*******************************************************************************
+    ** Provider by its saved name (db_perf_settings.provider), for code that has
+    ** settings but no connection; unsupported for null or unknown names.
+    *******************************************************************************/
+   public static DbStatsProvider forProviderName(String providerName)
+   {
+      for(Supplier<DbStatsProvider> supplier : BY_PRODUCT.values())
+      {
+         DbStatsProvider provider = supplier.get();
+         if(provider.getName().equalsIgnoreCase(providerName))
+         {
+            return (provider);
+         }
+      }
+      return (new UnsupportedStatsProvider());
+   }
+
+
+
+   /*******************************************************************************
+    ** Register (or replace) the provider for a JDBC product name. Hosts may add
+    ** vendors before the qbit collects; the name must be a Provider possible value.
+    *******************************************************************************/
+   public static void register(String productName, Supplier<DbStatsProvider> provider)
+   {
+      BY_PRODUCT.put(productName.toLowerCase(Locale.ROOT), provider);
    }
 }

src/main/java/com/kingsrook/qbits/dbperformance/provider/H2StatsProvider.java

@@ -0,0 +1,691 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance.provider;
+
+
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+import java.nio.ByteBuffer;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.sql.Connection;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import static com.kingsrook.qbits.dbperformance.provider.JdbcReads.instant;
+import static com.kingsrook.qbits.dbperformance.provider.JdbcReads.read;
+import static com.kingsrook.qbits.dbperformance.provider.JdbcReads.scalar;
+
+
+/*******************************************************************************
+ ** H2 2.x statistics from INFORMATION_SCHEMA. Statement statistics need the
+ ** database setting QUERY_STATISTICS (URL {@code ;QUERY_STATISTICS=TRUE} or
+ ** {@code SET QUERY_STATISTICS TRUE} as an admin); every other area works
+ ** without it. H2 keeps no transaction, cache, scan or vacuum counters, so
+ ** those areas are reported as unavailable rather than as zeros. See
+ ** docs/PROVIDERS.md for what is exact, approximated and unsupported.
+ *******************************************************************************/
+public class H2StatsProvider implements DbStatsProvider
+{
+   public static final String NAME = "H2";
+
+   private static final String NO_QUERY_STATISTICS = "NO_QUERY_STATISTICS";
+   private static final String NOT_ADMIN = "NOT_ADMIN";
+   private static final int MAX_ENTRIES = 1000;
+   private static final Pattern WORD = Pattern.compile("[A-Za-z_][A-Za-z0-9_$]*");
+
+   //////////////////////////////////////////////////////////////////////////
+   // H2 has no READ ONLY transaction and a rollback does not undo file,  //
+   // session, sequence or DDL side effects, so plans refuse SQL naming   //
+   // these (and any user-defined alias) outright                          //
+   //////////////////////////////////////////////////////////////////////////
+   private static final Set<String> DENIED = Set.of("FILE_WRITE", "FILE_READ", "CSVWRITE", "CSVREAD", "LINK_SCHEMA", "SCRIPT", "RUNSCRIPT",
+      "DISK_SPACE_USED", "CANCEL_SESSION", "ABORT_SESSION", "BACKUP", "SHUTDOWN", "CALL", "SET", "DROP", "CREATE", "ALTER", "TRUNCATE", "GRANT",
+      "REVOKE", "COMMIT", "ROLLBACK", "SAVEPOINT", "CHECKPOINT", "NEXTVAL", "SETVAL", "CURRVAL", "LOCK", "EXECUTE", "INSERT", "UPDATE",
+      "DELETE", "MERGE", "UPSERT", "REPLACE", "INTO", "FOR", "JAVA_OBJECT", "SLEEP");
+
+   ///////////////////////////////////////////////////////////////////////////
+   // statement that guarantees QUERY_STATISTICS has a row when it is on;   //
+   // it and INFORMATION_SCHEMA reads (the collector's own) are not stored  //
+   ///////////////////////////////////////////////////////////////////////////
+   private static final String PROBE = "SELECT 1 AS DB_PERF_PROBE";
+   private static final String DISK_SPACE = "SELECT DISK_SPACE_USED(?)";
+
+   private static final Set<StatsFeature> FEATURES = StatsFeature.of(StatsFeature.DATABASE_SIZE, StatsFeature.STATEMENTS,
+      StatsFeature.TABLE_ROWS, StatsFeature.TABLE_SIZES, StatsFeature.INDEX_DEFINITIONS, StatsFeature.SESSIONS, StatsFeature.BLOCKING,
+      StatsFeature.CONNECTIONS, StatsFeature.EXPLAIN_TEXT, StatsFeature.EXPLAIN_GENERIC, StatsFeature.EXPLAIN_ANALYZE);
+
+   private static final List<String> SETTINGS = List.of("info.VERSION", "MODE", "MV_STORE", "info.FILE_SIZE", "info.PAGE_SIZE",
+      "info.CACHE_MAX_SIZE", "info.CACHE_SIZE", "info.CACHE_HIT_RATIO", "info.FILE_READ", "info.FILE_WRITE", "MAX_QUERY_TIMEOUT", "QUERY_TIMEOUT");
+
+
+
+   /*******************************************************************************
+    ** Provider name.
+    *******************************************************************************/
+   @Override
+   public String getName()
+   {
+      return (NAME);
+   }
+
+
+
+   /*******************************************************************************
+    ** Version, admin rights and whether QUERY_STATISTICS is collecting.
+    *******************************************************************************/
+   @Override
+   public ProviderCapabilities capabilities(Connection connection) throws SQLException
+   {
+      int major = connection.getMetaData().getDatabaseMajorVersion();
+      int version = version(connection);
+      boolean supported = major >= 2;
+      if(!supported)
+      {
+         return (new ProviderCapabilities(false, version, false, false, "UNSUPPORTED", "H2 2.0 or newer is required.", Set.of()));
+      }
+      boolean statistics = queryStatistics(connection);
+      boolean admin = admin(connection);
+      String access = !statistics ? NO_QUERY_STATISTICS : !admin ? NOT_ADMIN : "FULL";
+      String message = switch(access)
+      {
+         case NO_QUERY_STATISTICS -> "H2 query statistics are off. Run Enable statement statistics on Settings as an H2 admin user, or add ;QUERY_STATISTICS=TRUE;QUERY_STATISTICS_MAX_ENTRIES=1000 to the JDBC URL.";
+         case NOT_ADMIN -> "The H2 user is not an admin, so only its own session is visible. Use an admin user (ALTER USER ... ADMIN TRUE) to see every session and blocking.";
+         default -> "Full statistics access (H2 does not keep transaction, cache, scan or vacuum counters).";
+      };
+      EnumSet<StatsFeature> available = EnumSet.copyOf(FEATURES);
+      if(!statistics)
+      {
+         available.remove(StatsFeature.STATEMENTS);
+      }
+      if(!admin)
+      {
+         available.remove(StatsFeature.BLOCKING);
+      }
+      else
+      {
+         ////////////////////////////////////////////////////////////////////
+         // an admin may call file and session functions; ANALYZE executes //
+         // the query, so it is offered only to non-admin users            //
+         ////////////////////////////////////////////////////////////////////
+         available.remove(StatsFeature.EXPLAIN_ANALYZE);
+      }
+      return (new ProviderCapabilities(true, version, statistics, admin, access, message, available));
+   }
+
+
+
+   /*******************************************************************************
+    ** Areas H2 can supply at best.
+    *******************************************************************************/
+   @Override
+   public Set<StatsFeature> features()
+   {
+      return (FEATURES);
+   }
+
+
+
+   /*******************************************************************************
+    ** Size from the store; H2 has no cumulative counters, reset time or limit.
+    *******************************************************************************/
+   @Override
+   public DatabaseStats readDatabase(Connection connection) throws SQLException
+   {
+      List<Long> size = read(connection, "SELECT SETTING_VALUE FROM INFORMATION_SCHEMA.SETTINGS WHERE SETTING_NAME = 'info.FILE_SIZE'", row -> parseLong(row.getString(1)));
+      return (new DatabaseStats(Map.of(), null, 0, size.isEmpty() || size.getFirst() == null ? 0 : size.getFirst()));
+   }
+
+
+
+   /*******************************************************************************
+    ** QUERY_STATISTICS rows (times in milliseconds), without connection setup
+    ** (see {@link #excluded}). H2 has no query id or user, so the id is a stable
+    ** hash of the statement text and the user is null.
+    *******************************************************************************/
+   @Override
+   public List<StatementStats> readStatements(Connection connection) throws SQLException
+   {
+      List<StatementStats> result = new ArrayList<>();
+      read(connection, "SELECT SQL_STATEMENT, EXECUTION_COUNT, CUMULATIVE_EXECUTION_TIME, AVERAGE_EXECUTION_TIME, MAX_EXECUTION_TIME, CUMULATIVE_ROW_COUNT FROM INFORMATION_SCHEMA.QUERY_STATISTICS", row ->
+      {
+         String sql = row.getString("SQL_STATEMENT");
+         if(sql != null && !excluded(sql))
+         {
+            result.add(new StatementStats(hash(sql), null, true, sql, row.getLong("EXECUTION_COUNT"), millis(row.getDouble("CUMULATIVE_EXECUTION_TIME")),
+               millis(row.getDouble("AVERAGE_EXECUTION_TIME")), millis(row.getDouble("MAX_EXECUTION_TIME")), row.getLong("CUMULATIVE_ROW_COUNT"), 0, 0, 0, null, null));
+         }
+         return (null);
+      });
+      return (result);
+   }
+
+
+
+   /*******************************************************************************
+    ** Not application statements: the collector's own probe, table sizing and
+    ** INFORMATION_SCHEMA reads, and connection setup. H2 replays every JDBC URL setting as a SET on
+    ** each new connection and drivers call DATABASE() for the catalog, so with
+    ** unpooled connections these dominate the call counts without being work.
+    *******************************************************************************/
+   static boolean excluded(String sql)
+   {
+      String upper = sql.strip().toUpperCase(Locale.ROOT);
+      return (PROBE.equals(sql) || DISK_SPACE.equals(sql) || upper.contains("INFORMATION_SCHEMA.") || upper.startsWith("SET ") || upper.equals("CALL DATABASE()"));
+   }
+
+
+
+   /*******************************************************************************
+    ** H2 keeps no reset time; a reset shows as falling call counts instead.
+    *******************************************************************************/
+   @Override
+   public StatementResetInfo readStatementResetInfo(Connection connection)
+   {
+      return (new StatementResetInfo(null, 0));
+   }
+
+
+
+   /*******************************************************************************
+    ** Base tables with H2's row-count estimate and DISK_SPACE_USED (table data
+    ** only: H2 cannot size indexes, so totalBytes equals tableBytes).
+    *******************************************************************************/
+   @Override
+   public List<TableStats> readTables(Connection connection) throws SQLException
+   {
+      List<TableStats> result = new ArrayList<>();
+      List<String[]> tables = read(connection, "SELECT TABLE_SCHEMA, TABLE_NAME, ROW_COUNT_ESTIMATE FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE = 'BASE TABLE' AND TABLE_SCHEMA <> 'INFORMATION_SCHEMA' ORDER BY TABLE_SCHEMA, TABLE_NAME",
+         row -> new String[] {row.getString(1), row.getString(2), row.getString(3)});
+      try(PreparedStatement size = connection.prepareStatement(DISK_SPACE))
+      {
+         size.setQueryTimeout(30);
+         for(String[] table : tables)
+         {
+            Map<String, Long> counters = new LinkedHashMap<>();
+            counters.put("nLiveTup", table[2] == null ? 0L : Long.parseLong(table[2]));
+            Long bytes = diskSpace(size, quote(table[0]) + "." + quote(table[1]));
+            if(bytes != null)
+            {
+               counters.put("tableBytes", bytes);
+               counters.put("totalBytes", bytes);
+            }
+            result.add(new TableStats(table[0], table[1], hash("TABLE:" + table[0] + "." + table[1]) & Long.MAX_VALUE, counters, Map.of()));
+         }
+      }
+      return (result);
+   }
+
+
+
+   /*******************************************************************************
+    ** Index definitions and ordered key columns. H2 has no index usage or size
+    ** statistics; constraint-generated indexes are marked USING CONSTRAINT so
+    ** they are never proposed for removal.
+    *******************************************************************************/
+   @Override
+   public List<IndexStats> readIndexes(Connection connection) throws SQLException
+   {
+      Map<String, IndexBuilder> indexes = new LinkedHashMap<>();
+      String sql = "SELECT i.INDEX_SCHEMA, i.TABLE_NAME, i.INDEX_NAME, i.INDEX_TYPE_NAME, i.IS_GENERATED, c.COLUMN_NAME, c.ORDERING_SPECIFICATION FROM INFORMATION_SCHEMA.INDEXES i "
+         + "JOIN INFORMATION_SCHEMA.INDEX_COLUMNS c ON c.INDEX_SCHEMA = i.INDEX_SCHEMA AND c.TABLE_NAME = i.TABLE_NAME AND c.INDEX_NAME = i.INDEX_NAME "
+         + "WHERE i.INDEX_SCHEMA <> 'INFORMATION_SCHEMA' ORDER BY i.INDEX_SCHEMA, i.TABLE_NAME, i.INDEX_NAME, c.ORDINAL_POSITION";
+      read(connection, sql, row ->
+      {
+         IndexBuilder index = indexes.computeIfAbsent(row.getString(1) + "." + row.getString(3), key -> new IndexBuilder());
+         index.schema = row.getString(1);
+         index.table = row.getString(2);
+         index.name = row.getString(3);
+         index.type = row.getString(4) == null ? "" : row.getString(4).toUpperCase(Locale.ROOT);
+         index.generated = row.getBoolean(5);
+         String order = "DESC".equalsIgnoreCase(row.getString(7)) ? " DESC" : "";
+         index.columns.add(row.getString(6) + order);
+         index.quoted.add(quote(row.getString(6)) + order);
+         return (null);
+      });
+      List<IndexStats> result = new ArrayList<>();
+      for(IndexBuilder index : indexes.values())
+      {
+         boolean primary = index.type.contains("PRIMARY");
+         boolean unique = primary || index.type.contains("UNIQUE");
+         String columns = String.join(", ", index.columns);
+         String keys = String.join(", ", index.quoted);
+         String definition = primary ? "ALTER TABLE " + quote(index.schema) + "." + quote(index.table) + " ADD PRIMARY KEY (" + keys + ")"
+            : "CREATE " + (unique ? "UNIQUE " : "") + "INDEX " + quote(index.name) + " ON " + quote(index.schema) + "." + quote(index.table) + (index.generated ? " USING CONSTRAINT" : "") + " (" + keys + ")";
+         result.add(new IndexStats(index.schema, index.table, index.name, hash("INDEX:" + index.schema + "." + index.name) & Long.MAX_VALUE, definition, columns, unique, primary, true, 0, 0, 0, 0, 0));
+      }
+      return (result);
+   }
+
+
+
+   /*******************************************************************************
+    ** Other sessions in PostgreSQL's state vocabulary: RUNNING is active, BLOCKED
+    ** is active waiting on a Lock, SLEEP with uncommitted changes is idle in
+    ** transaction. H2 has no transaction start, so an idle transaction's age is
+    ** the time since it went idle (a lower bound).
+    *******************************************************************************/
+   @Override
+   public List<SessionInfo> readSessions(Connection connection) throws SQLException
+   {
+      Instant now = Instant.now();
+      String sql = "SELECT SESSION_ID, USER_NAME, CLIENT_INFO, CLIENT_ADDR, SERVER, SESSION_STATE, CONTAINS_UNCOMMITTED, BLOCKER_ID, EXECUTING_STATEMENT, EXECUTING_STATEMENT_START, SLEEP_SINCE "
+         + "FROM INFORMATION_SCHEMA.SESSIONS WHERE SESSION_ID <> SESSION_ID() ORDER BY SESSION_ID";
+      return (read(connection, sql, row ->
+      {
+         String state = state(row.getString("SESSION_STATE"), row.getBoolean("CONTAINS_UNCOMMITTED"));
+         boolean blocked = "BLOCKED".equalsIgnoreCase(row.getString("SESSION_STATE"));
+         Instant queryStart = instant(row, "EXECUTING_STATEMENT_START");
+         Instant sleepSince = instant(row, "SLEEP_SINCE");
+         boolean active = "active".equals(state);
+         String query = row.getString("EXECUTING_STATEMENT");
+         Integer blocker = row.getObject("BLOCKER_ID") == null ? null : row.getInt("BLOCKER_ID");
+         return (new SessionInfo(row.getInt("SESSION_ID"), row.getString("USER_NAME"), row.getString("CLIENT_INFO"), row.getString("CLIENT_ADDR"), state,
+            blocked ? "Lock" : null, blocked ? "row lock" : null, row.getString("SERVER") == null ? "embedded" : row.getString("SERVER"),
+            null, queryStart, active ? queryStart : sleepSince, active ? seconds(queryStart, now) : null,
+            state.startsWith("idle in transaction") ? seconds(sleepSince, now) : null, blocker == null ? List.of() : List.of(blocker), query == null ? null : hash(query), query));
+      }));
+   }
+
+
+
+   /*******************************************************************************
+    ** Every visible session, including this one, by user, client and state.
+    *******************************************************************************/
+   @Override
+   public List<ConnectionCount> readConnections(Connection connection) throws SQLException
+   {
+      Map<List<String>, Integer> counts = new LinkedHashMap<>();
+      read(connection, "SELECT USER_NAME, CLIENT_INFO, SESSION_STATE, CONTAINS_UNCOMMITTED FROM INFORMATION_SCHEMA.SESSIONS ORDER BY SESSION_ID", row ->
+         counts.merge(Arrays.asList(row.getString(1), row.getString(2), state(row.getString(3), row.getBoolean(4))), 1, Integer::sum));
+      List<ConnectionCount> result = new ArrayList<>();
+      counts.forEach((key, count) -> result.add(new ConnectionCount(key.get(0), key.get(1), key.get(2), count)));
+      return (result);
+   }
+
+
+
+   /*******************************************************************************
+    ** Operational, non-secret settings plus the QUERY_STATISTICS state.
+    *******************************************************************************/
+   @Override
+   public Map<String, String> readSettings(Connection connection) throws SQLException
+   {
+      Map<String, String> result = new LinkedHashMap<>();
+      read(connection, "SELECT SETTING_NAME, SETTING_VALUE FROM INFORMATION_SCHEMA.SETTINGS", row -> SETTINGS.contains(row.getString(1)) ? result.put(row.getString(1), row.getString(2)) : null);
+      result.put("QUERY_STATISTICS", queryStatistics(connection) ? "TRUE" : "FALSE");
+      return (result);
+   }
+
+
+
+   /*******************************************************************************
+    ** Health and setup next steps for H2's access codes.
+    *******************************************************************************/
+   @Override
+   public String remedy(String statsAccess, String databaseUser)
+   {
+      return (switch(statsAccess == null ? "" : statsAccess)
+      {
+         case "FULL" -> "Full statistics access";
+         case NO_QUERY_STATISTICS -> "Turn on H2 query statistics: run Enable statement statistics on Settings, or add ;QUERY_STATISTICS=TRUE to the JDBC URL";
+         case NOT_ADMIN -> "Make " + databaseUser + " an H2 admin (ALTER USER " + databaseUser + " ADMIN TRUE) to see every session";
+         default -> "Use H2 2.0 or newer";
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** Guided setup rows: query statistics and the admin role.
+    *******************************************************************************/
+   @Override
+   public List<SetupCheck> setupChecks(String statsAccess, String message)
+   {
+      return (List.of(new SetupCheck("H2 QUERY_STATISTICS", statsAccess, "Run Enable statement statistics on Settings (admin user), or add ;QUERY_STATISTICS=TRUE;QUERY_STATISTICS_MAX_ENTRIES=1000 to the JDBC URL; then run Collect now."),
+         new SetupCheck("H2 admin user", statsAccess, message == null ? "Use an H2 admin user to see every session and blocking." : message)));
+   }
+
+
+
+   /*******************************************************************************
+    ** SET QUERY_STATISTICS TRUE (admin only), raising H2's default of 100 kept
+    ** statements: H2 evicts a third of them, oldest first, whenever the cap is
+    ** passed, and an application easily runs more distinct statements. H2 does
+    ** not persist either setting: they last until the database closes, so also
+    ** put them in the JDBC URL. An existing setup is left untouched.
+    *******************************************************************************/
+   @Override
+   public String enableStatementStatistics(Connection connection) throws SQLException
+   {
+      if(queryStatistics(connection))
+      {
+         return ("H2 query statistics are already on.");
+      }
+      try(Statement statement = connection.createStatement())
+      {
+         statement.execute("SET QUERY_STATISTICS_MAX_ENTRIES " + MAX_ENTRIES);
+         statement.execute("SET QUERY_STATISTICS TRUE");
+      }
+      return ("H2 query statistics are on (up to " + MAX_ENTRIES + " statements) until the database closes. Add ;QUERY_STATISTICS=TRUE;QUERY_STATISTICS_MAX_ENTRIES=" + MAX_ENTRIES + " to the JDBC URL to keep them on after a restart.");
+   }
+
+
+
+   /*******************************************************************************
+    ** EXPLAIN (not executed) or EXPLAIN ANALYZE (executed with bound values).
+    ** H2 has no READ ONLY transaction, so both refuse more than one statement
+    ** and any SQL naming a side-effecting function, DDL/DML keyword or
+    ** user-defined alias; ANALYZE additionally requires a single SELECT/WITH
+    ** and a non-admin user. The connection is marked read-only (a hint in H2)
+    ** and the transaction always rolls back.
+    *******************************************************************************/
+   @Override
+   public String explainText(Connection connection, String sql, List<String> parameters, boolean analyze, int timeoutMs) throws SQLException
+   {
+      List<String> words = words(sql);
+      if(statements(sql) > 1)
+      {
+         throw (new SQLException("Query plans on H2 accept exactly one statement.", "42000"));
+      }
+      List<String> aliases = read(connection, "SELECT UPPER(ROUTINE_NAME) FROM INFORMATION_SCHEMA.ROUTINES WHERE ROUTINE_SCHEMA <> 'INFORMATION_SCHEMA'", row -> row.getString(1));
+      for(String word : words)
+      {
+         if(DENIED.contains(word) || aliases.contains(word))
+         {
+            throw (new SQLException("Query plans on H2 refuse " + word + ": H2 cannot run it read-only.", "42000"));
+         }
+      }
+      if(analyze)
+      {
+         if(words.isEmpty() || !Set.of("SELECT", "WITH").contains(words.getFirst()))
+         {
+            throw (new SQLException("EXPLAIN ANALYZE on H2 accepts a single SELECT only.", "42000"));
+         }
+         if(admin(connection))
+         {
+            throw (new SQLException("EXPLAIN ANALYZE on H2 is disabled for admin users (it executes the query and H2 has no read-only transactions). Use PLAN, or connect as a non-admin user.", "42000"));
+         }
+      }
+      boolean autoCommit = connection.getAutoCommit();
+      boolean readOnly = connection.isReadOnly();
+      try
+      {
+         connection.setReadOnly(true);
+         connection.setAutoCommit(false);
+         if(!analyze)
+         {
+            ////////////////////////////////////////////////////////////////
+            // a plain statement plans ?n slots without values (generic) //
+            ////////////////////////////////////////////////////////////////
+            try(Statement statement = connection.createStatement())
+            {
+               statement.setQueryTimeout(Math.max(1, (timeoutMs + 999) / 1000));
+               return (plan(statement.executeQuery("EXPLAIN " + sql)));
+            }
+         }
+         try(PreparedStatement statement = connection.prepareStatement("EXPLAIN ANALYZE " + sql))
+         {
+            statement.setQueryTimeout(Math.max(1, (timeoutMs + 999) / 1000));
+            for(int i = 0; i < parameters.size(); i++)
+            {
+               statement.setString(i + 1, parameters.get(i));
+            }
+            return (plan(statement.executeQuery()));
+         }
+      }
+      finally
+      {
+         try
+         {
+            connection.rollback();
+         }
+         finally
+         {
+            connection.setAutoCommit(autoCommit);
+            connection.setReadOnly(readOnly);
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Upper-case words outside string literals and comments; double-quoted
+    ** identifiers count as words, since H2 resolves quoted function names.
+    *******************************************************************************/
+   static List<String> words(String sql)
+   {
+      String code = code(sql);
+      List<String> words = new ArrayList<>();
+      Matcher matcher = WORD.matcher(code);
+      while(matcher.find())
+      {
+         words.add(matcher.group().toUpperCase(Locale.ROOT));
+      }
+      return (words);
+   }
+
+
+
+   /*******************************************************************************
+    ** Statements separated by semicolons outside literals and comments.
+    *******************************************************************************/
+   static int statements(String sql)
+   {
+      int count = 0;
+      for(String part : code(sql).split(";"))
+      {
+         count += part.isBlank() ? 0 : 1;
+      }
+      return (count);
+   }
+
+
+
+   /*******************************************************************************
+    ** SQL with string literals and comments blanked, quoted identifiers unquoted.
+    *******************************************************************************/
+   private static String code(String sql)
+   {
+      return (sql.replaceAll("(?s)/\\*.*?\\*/", " ").replaceAll("--[^\n]*", " ").replaceAll("'(?:[^']|'')*'", " ").replace('"', ' '));
+   }
+
+
+
+   /*******************************************************************************
+    ** Plan rows joined as text; closes the result.
+    *******************************************************************************/
+   private static String plan(ResultSet rows) throws SQLException
+   {
+      try(rows)
+      {
+         StringBuilder plan = new StringBuilder();
+         while(rows.next())
+         {
+            plan.append(plan.isEmpty() ? "" : "\n").append(rows.getString(1));
+         }
+         return (plan.toString());
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** QUERY_STATISTICS is not exposed in SETTINGS; when it is on, the probe just
+    ** run is always recorded, and when it is off the view is empty.
+    *******************************************************************************/
+   boolean queryStatistics(Connection connection) throws SQLException
+   {
+      read(connection, PROBE, row -> null);
+      return (scalar(connection, "SELECT COUNT(*) FROM INFORMATION_SCHEMA.QUERY_STATISTICS") > 0);
+   }
+
+
+
+   /*******************************************************************************
+    ** Non-admin users see only their own USERS row and session.
+    *******************************************************************************/
+   private boolean admin(Connection connection) throws SQLException
+   {
+      return (!read(connection, "SELECT IS_ADMIN FROM INFORMATION_SCHEMA.USERS WHERE USER_NAME = CURRENT_USER", row -> row.getBoolean(1)).stream().filter(Boolean::booleanValue).toList().isEmpty());
+   }
+
+
+
+   /*******************************************************************************
+    ** major*1000000 + minor*1000 + build, e.g. 2004240 for 2.4.240.
+    *******************************************************************************/
+   private int version(Connection connection) throws SQLException
+   {
+      String[] parts = read(connection, "SELECT H2VERSION()", row -> row.getString(1)).getFirst().split("[.\\s]");
+      int version = 0;
+      for(int i = 0; i < 3; i++)
+      {
+         version = version * 1000 + (i < parts.length && parts[i].matches("\\d+") ? Integer.parseInt(parts[i]) : 0);
+      }
+      return (version);
+   }
+
+
+
+   /*******************************************************************************
+    ** PostgreSQL-compatible state names used by collection and presentation.
+    *******************************************************************************/
+   static String state(String h2State, boolean uncommitted)
+   {
+      String value = h2State == null ? "" : h2State.toUpperCase(Locale.ROOT);
+      return (switch(value)
+      {
+         case "RUNNING", "BLOCKED" -> "active";
+         case "SLEEP" -> uncommitted ? "idle in transaction" : "idle";
+         default -> value.toLowerCase(Locale.ROOT);
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** Stable 64-bit identity for text (statement, table or index key).
+    *******************************************************************************/
+   static long hash(String text)
+   {
+      try
+      {
+         return (ByteBuffer.wrap(MessageDigest.getInstance("SHA-256").digest(text.getBytes(StandardCharsets.UTF_8))).getLong());
+      }
+      catch(NoSuchAlgorithmException e)
+      {
+         throw (new IllegalStateException("SHA-256 is required", e));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** DISK_SPACE_USED for one quoted table; null when H2 cannot size it.
+    *******************************************************************************/
+   private static Long diskSpace(PreparedStatement size, String table)
+   {
+      try
+      {
+         size.setString(1, table);
+         try(ResultSet rows = size.executeQuery())
+         {
+            return (rows.next() ? rows.getLong(1) : null);
+         }
+      }
+      catch(SQLException e)
+      {
+         return (null);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Quoted identifier.
+    *******************************************************************************/
+   private static String quote(String identifier)
+   {
+      return ("\"" + identifier.replace("\"", "\"\"") + "\"");
+   }
+
+
+
+   /*******************************************************************************
+    ** Milliseconds as a 3-decimal BigDecimal.
+    *******************************************************************************/
+   private static BigDecimal millis(double value)
+   {
+      return (BigDecimal.valueOf(value).setScale(3, RoundingMode.HALF_UP));
+   }
+
+
+
+   /*******************************************************************************
+    ** Elapsed seconds, or null without a start.
+    *******************************************************************************/
+   private static BigDecimal seconds(Instant start, Instant now)
+   {
+      return (start == null ? null : BigDecimal.valueOf(Math.max(0, Duration.between(start, now).toMillis())).divide(BigDecimal.valueOf(1000), 3, RoundingMode.HALF_UP));
+   }
+
+
+
+   /*******************************************************************************
+    ** Numeric setting value, or null.
+    *******************************************************************************/
+   private static Long parseLong(String value)
+   {
+      return (value != null && value.matches("\\d+") ? Long.parseLong(value) : null);
+   }
+
+
+
+   /*******************************************************************************
+    ** Index rows folded per index.
+    *******************************************************************************/
+   private static class IndexBuilder
+   {
+      private String schema;
+      private String table;
+      private String name;
+      private String type;
+      private boolean generated;
+      private final List<String> columns = new ArrayList<>();
+      private final List<String> quoted = new ArrayList<>();
+   }
+}

src/main/java/com/kingsrook/qbits/dbperformance/provider/JdbcReads.java

@@ -0,0 +1,101 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance.provider;
+
+
+import java.sql.Connection;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.sql.Timestamp;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+
+
+/*******************************************************************************
+ ** Bounded-time JDBC reads shared by statistics providers.
+ *******************************************************************************/
+final class JdbcReads
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private JdbcReads()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Execute one bounded-time read and close JDBC resources.
+    *******************************************************************************/
+   static <T> List<T> read(Connection connection, String sql, RowReader<T> mapper) throws SQLException
+   {
+      List<T> result = new ArrayList<>();
+      try(Statement statement = connection.createStatement())
+      {
+         statement.setQueryTimeout(30);
+         try(ResultSet rows = statement.executeQuery(sql))
+         {
+            while(rows.next())
+            {
+               result.add(mapper.read(rows));
+            }
+         }
+      }
+      return (result);
+   }
+
+
+
+   /*******************************************************************************
+    ** A single numeric read.
+    *******************************************************************************/
+   static long scalar(Connection connection, String sql) throws SQLException
+   {
+      return (read(connection, sql, row -> row.getLong(1)).getFirst());
+   }
+
+
+
+   /*******************************************************************************
+    ** Timestamp conversion preserves null values.
+    *******************************************************************************/
+   static Instant instant(ResultSet row, String column) throws SQLException
+   {
+      Timestamp timestamp = row.getTimestamp(column);
+      return (timestamp == null ? null : timestamp.toInstant());
+   }
+
+
+
+   /*******************************************************************************
+    ** Checked JDBC row mapping.
+    *******************************************************************************/
+   interface RowReader<T>
+   {
+      /*******************************************************************************
+       ** Map one row.
+       *******************************************************************************/
+      T read(ResultSet row) throws SQLException;
+   }
+}

src/main/java/com/kingsrook/qbits/dbperformance/provider/PostgresStatsProvider.java

@@ -24,13 +24,16 @@ package com.kingsrook.qbits.dbperformance.provider;
 import java.sql.Connection;
 import java.sql.ResultSet;
 import java.sql.SQLException;
-import java.sql.Statement;
-import java.sql.Timestamp;
 import java.time.Instant;
 import java.util.ArrayList;
+import java.util.EnumSet;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
+import static com.kingsrook.qbits.dbperformance.provider.JdbcReads.instant;
+import static com.kingsrook.qbits.dbperformance.provider.JdbcReads.read;
+import static com.kingsrook.qbits.dbperformance.provider.JdbcReads.scalar;
 
 
 /*******************************************************************************
@@ -85,7 +88,60 @@ public class PostgresStatsProvider implements DbStatsProvider
             }
          }
       }
-      return (new ProviderCapabilities(version >= 130000, version, installed, privileged, access, message));
+      EnumSet<StatsFeature> available = EnumSet.copyOf(features());
+      if(!installed)
+      {
+         available.removeAll(EnumSet.of(StatsFeature.STATEMENTS, StatsFeature.STATEMENT_IO, StatsFeature.STATEMENT_RESET));
+      }
+      if(version < 140000)
+      {
+         available.remove(StatsFeature.STATEMENT_RESET);
+      }
+      if(version < 160000)
+      {
+         available.remove(StatsFeature.EXPLAIN_GENERIC);
+      }
+      return (new ProviderCapabilities(version >= 130000, version, installed, privileged, access, message, version >= 130000 ? available : EnumSet.noneOf(StatsFeature.class)));
+   }
+
+
+
+   /*******************************************************************************
+    ** Every area: the cumulative statistics views cover them all.
+    *******************************************************************************/
+   @Override
+   public Set<StatsFeature> features()
+   {
+      return (StatsFeature.of(StatsFeature.values()));
+   }
+
+
+
+   /*******************************************************************************
+    ** Role and extension prerequisites for each access code.
+    *******************************************************************************/
+   @Override
+   public String remedy(String statsAccess, String databaseUser)
+   {
+      return (switch(statsAccess == null ? "" : statsAccess)
+      {
+         case "FULL" -> "Full statistics access";
+         case "NO_READ_ALL_STATS" -> "grant pg_read_all_stats to " + databaseUser;
+         case "NO_PG_STAT_STATEMENTS" -> "Enable pg_stat_statements in shared_preload_libraries and create the extension";
+         default -> "Use a supported PostgreSQL version (13 or newer) and statistics provider";
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** Guided setup rows: the extension and the statistics role.
+    *******************************************************************************/
+   @Override
+   public List<SetupCheck> setupChecks(String statsAccess, String message)
+   {
+      return (List.of(new SetupCheck("pg_stat_statements", statsAccess, "Preload and create pg_stat_statements; then run Collect now."),
+         new SetupCheck("pg_read_all_stats", statsAccess, message == null ? "Grant pg_read_all_stats to the application's database role." : message)));
    }
 
 
@@ -237,25 +293,6 @@ public class PostgresStatsProvider implements DbStatsProvider
    }
 
 
-   /*******************************************************************************
-    ** A single numeric read.
-    *******************************************************************************/
-   private long scalar(Connection connection, String sql) throws SQLException
-   {
-      return (read(connection, sql, row -> row.getLong(1)).getFirst());
-   }
-
-
-   /*******************************************************************************
-    ** Timestamp conversion preserves null reset/maintenance values.
-    *******************************************************************************/
-   private static Instant instant(ResultSet row, String column) throws SQLException
-   {
-      Timestamp timestamp = row.getTimestamp(column);
-      return (timestamp == null ? null : timestamp.toInstant());
-   }
-
-
    /*******************************************************************************
     ** Copy cumulative counters to the entity's camelCase names.
     *******************************************************************************/
@@ -282,37 +319,4 @@ public class PostgresStatsProvider implements DbStatsProvider
       }
       return (value.toString());
    }
-
-
-   /*******************************************************************************
-    ** Execute one bounded-time read and close JDBC resources.
-    *******************************************************************************/
-   private static <T> List<T> read(Connection connection, String sql, RowReader<T> mapper) throws SQLException
-   {
-      List<T> result = new ArrayList<>();
-      try(Statement statement = connection.createStatement())
-      {
-         statement.setQueryTimeout(30);
-         try(ResultSet rows = statement.executeQuery(sql))
-         {
-            while(rows.next())
-            {
-               result.add(mapper.read(rows));
-            }
-         }
-      }
-      return (result);
-   }
-
-
-   /*******************************************************************************
-    ** Checked JDBC row mapping.
-    *******************************************************************************/
-   private interface RowReader<T>
-   {
-      /*******************************************************************************
-       ** Map one row.
-       *******************************************************************************/
-      T read(ResultSet row) throws SQLException;
-   }
 }

src/main/java/com/kingsrook/qbits/dbperformance/provider/ProviderCapabilities.java

@@ -21,11 +21,44 @@
 package com.kingsrook.qbits.dbperformance.provider;
 
 
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.Set;
 
 
 /*******************************************************************************
- ** ProviderCapabilities read from database statistics; no persistence or side effects.
+ ** What one provider can read on one connection; no persistence or side effects.
+ ** {@code statsAccess} is a stable code persisted on settings (FULL, or the most
+ ** important missing prerequisite); {@code message} is the provider's own
+ ** next step; {@code features} lists the statistics areas available right now.
  *******************************************************************************/
-public record ProviderCapabilities(boolean supported, int version, boolean statements, boolean readAllStats, String statsAccess, String message)
+public record ProviderCapabilities(boolean supported, int version, boolean statements, boolean readAllStats, String statsAccess, String message, Set<StatsFeature> features)
 {
+   /*******************************************************************************
+    ** Defensive copy.
+    *******************************************************************************/
+   public ProviderCapabilities
+   {
+      features = features == null || features.isEmpty() ? Set.of() : Collections.unmodifiableSet(EnumSet.copyOf(features));
+   }
+
+
+
+   /*******************************************************************************
+    ** Pre-feature form: a supported provider is assumed to offer every area.
+    *******************************************************************************/
+   public ProviderCapabilities(boolean supported, int version, boolean statements, boolean readAllStats, String statsAccess, String message)
+   {
+      this(supported, version, statements, readAllStats, statsAccess, message, supported ? EnumSet.allOf(StatsFeature.class) : Set.of());
+   }
+
+
+
+   /*******************************************************************************
+    ** Whether an area is available on this connection.
+    *******************************************************************************/
+   public boolean has(StatsFeature feature)
+   {
+      return (features.contains(feature));
+   }
 }

src/main/java/com/kingsrook/qbits/dbperformance/provider/SetupCheck.java

@@ -0,0 +1,31 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance.provider;
+
+
+
+
+/*******************************************************************************
+ ** One guided-setup row: the prerequisite, its observed state and the next step.
+ *******************************************************************************/
+public record SetupCheck(String check, String state, String nextStep)
+{
+}

src/main/java/com/kingsrook/qbits/dbperformance/provider/StatsFeature.java

@@ -0,0 +1,117 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance.provider;
+
+
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.Set;
+
+
+/*******************************************************************************
+ ** One area of database statistics. A provider declares which areas its vendor
+ ** can supply ({@link DbStatsProvider#features()}) and which are available on a
+ ** given connection ({@link ProviderCapabilities#features()}); presentation and
+ ** analysis degrade per area instead of per vendor.
+ *******************************************************************************/
+public enum StatsFeature
+{
+   /** Transaction, block, temp-file and deadlock counters for the database. */
+   DATABASE_COUNTERS("Database counters"),
+   /** Buffer-cache hit and read counters (cache hit ratio). */
+   CACHE_COUNTERS("Cache hit ratio"),
+   /** Database size on disk. */
+   DATABASE_SIZE("Database size"),
+   /** Configured connection limit. */
+   MAX_CONNECTIONS("Connection limit"),
+   /** Cumulative per-statement calls, time and rows. */
+   STATEMENTS("Statement statistics"),
+   /** Per-statement shared-block and temp-block I/O. */
+   STATEMENT_IO("Statement I/O"),
+   /** A server-side reset time for statement statistics. */
+   STATEMENT_RESET("Statement reset time"),
+   /** Live row estimates per table. */
+   TABLE_ROWS("Table row estimates"),
+   /** Table, index and toast sizes. */
+   TABLE_SIZES("Table sizes"),
+   /** Sequential/index scan and tuple write counters per table. */
+   TABLE_ACCESS("Table access counters"),
+   /** Dead tuples, vacuum/analyze times and freeze age. */
+   TABLE_MAINTENANCE("Table maintenance"),
+   /** Index definitions and key columns. */
+   INDEX_DEFINITIONS("Index definitions"),
+   /** Per-index scan counters. */
+   INDEX_USAGE("Index usage"),
+   /** Per-index size. */
+   INDEX_SIZES("Index sizes"),
+   /** Live sessions with state and current statement. */
+   SESSIONS("Live sessions"),
+   /** Which session blocks which. */
+   BLOCKING("Blocking"),
+   /** Wait event type and name per session. */
+   WAIT_EVENTS("Wait events"),
+   /** Transaction start time per session. */
+   TRANSACTION_AGE("Transaction age"),
+   /** Connection counts by user, application and state. */
+   CONNECTIONS("Connection counts"),
+   /** Plans as structured JSON with costs (renderable tree). */
+   EXPLAIN_JSON("Structured query plans"),
+   /** Plans as vendor text (no cost tree). */
+   EXPLAIN_TEXT("Text query plans"),
+   /** Plans for parameterized SQL without values. */
+   EXPLAIN_GENERIC("Generic plans"),
+   /** Executing the query to measure the plan (ANALYZE). */
+   EXPLAIN_ANALYZE("Explain analyze");
+
+   private final String label;
+
+
+
+   /*******************************************************************************
+    ** Constructor.
+    *******************************************************************************/
+   StatsFeature(String label)
+   {
+      this.label = label;
+   }
+
+
+
+   /*******************************************************************************
+    ** Human-readable area name.
+    *******************************************************************************/
+   public String getLabel()
+   {
+      return (label);
+   }
+
+
+
+   /*******************************************************************************
+    ** Immutable copy of a feature list.
+    *******************************************************************************/
+   public static Set<StatsFeature> of(StatsFeature... features)
+   {
+      EnumSet<StatsFeature> set = EnumSet.noneOf(StatsFeature.class);
+      Collections.addAll(set, features);
+      return (Collections.unmodifiableSet(set));
+   }
+}

src/main/java/com/kingsrook/qbits/dbperformance/provider/UnsupportedStatsProvider.java

@@ -47,7 +47,7 @@ public class UnsupportedStatsProvider implements DbStatsProvider
    @Override
    public ProviderCapabilities capabilities(Connection connection)
    {
-      return (new ProviderCapabilities(false, 0, false, false, "UNSUPPORTED", "This database vendor is not supported; PostgreSQL 13 or newer is required."));
+      return (new ProviderCapabilities(false, 0, false, false, "UNSUPPORTED", "This database vendor is not supported; PostgreSQL 13+ and H2 2.x are (see docs/PROVIDERS.md)."));
    }
 
 

src/main/java/com/kingsrook/qbits/dbperformance/widgets/DbPerfWidgetRenderer.java

@@ -29,6 +29,7 @@ import java.util.Arrays;
 import java.util.Comparator;
 import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 import java.util.Objects;
 import com.kingsrook.qbits.dbperformance.DbPerfRuntime;
@@ -36,10 +37,20 @@ import com.kingsrook.qbits.dbperformance.api.DbPerformanceData;
 import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
 import com.kingsrook.qbits.dbperformance.collect.SnapshotCollector;
 import com.kingsrook.qbits.dbperformance.provider.ConnectionCount;
+import com.kingsrook.qbits.dbperformance.provider.DbStatsProvider;
 import com.kingsrook.qbits.dbperformance.provider.DbStatsProviders;
+import com.kingsrook.qbits.dbperformance.provider.SetupCheck;
+import com.kingsrook.qbits.dbperformance.provider.StatsFeature;
 import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.AbstractWidgetRenderer;
+import com.kingsrook.qqq.backend.core.actions.tables.AggregateAction;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.Aggregate;
+import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.AggregateInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.AggregateOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.AggregateResult;
+import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.GroupBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.aggregate.QFilterOrderByAggregate;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
@@ -55,11 +66,12 @@ import com.kingsrook.qqq.backend.core.model.dashboard.widgets.QWidgetData;
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.TableData;
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.BlockLink;
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.text.TextBlockData;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.text.TextStyles;
 import com.kingsrook.qqq.backend.core.model.dashboard.widgets.blocks.text.TextValues;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
 import com.kingsrook.qqq.backend.module.rdbms.jdbc.ConnectionManager;
 import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
-import static com.kingsrook.qbits.dbperformance.api.DbPerformanceData.fields;
 import static com.kingsrook.qbits.dbperformance.api.DbPerformanceData.map;
 import static com.kingsrook.qbits.dbperformance.api.DbPerformanceData.number;
 
@@ -122,9 +134,12 @@ public class DbPerfWidgetRenderer extends AbstractWidgetRenderer
       boolean attribution = settings == null ? Boolean.TRUE.equals(runtime.getConfig().getAttributionEnabled()) : Boolean.TRUE.equals(settings.getValueBoolean("attributionEnabled"));
       List<Map<String, Object>> rows = new ArrayList<>();
       rows.add(check("Monitored backend", runtime.getConfig().getBackendName(), "Review Settings for this backend."));
-      rows.add(check("Provider", settings == null ? "Not detected yet" : settings.getValueString("provider"), "PostgreSQL 13+ is supported."));
-      rows.add(check("pg_stat_statements", access, "Preload and create pg_stat_statements; then run Collect now."));
-      rows.add(check("pg_read_all_stats", access, settings == null ? "Grant pg_read_all_stats to the application's database role." : settings.getValueString("statsAccessMessage")));
+      rows.add(check("Provider", settings == null ? "Not detected yet" : settings.getValueString("provider"), "PostgreSQL 13+ and H2 2.x are supported."));
+      DbStatsProvider provider = settings == null ? providerForBackend(runtime) : DbStatsProviders.forProviderName(settings.getValueString("provider"));
+      for(SetupCheck check : provider.setupChecks(access, settings == null ? null : settings.getValueString("statsAccessMessage")))
+      {
+         rows.add(check(check.check(), check.state(), check.nextStep()));
+      }
       rows.add(check("Last snapshot", last == null ? "Nothing collected yet" : Duration.between(last, Instant.now()).toSeconds() + " seconds ago",
          last == null ? "Run Collect now from Snapshots, or wait for the next scheduled collection." : "Collection normally runs every " + SnapshotCollector.positive(settings, "snapshotIntervalMinutes", 5) + " minutes."));
       rows.add(check("Attribution", attribution ? "On" : "Off", attribution ? "Attribution starts after the next flush." : "Enable attribution in Settings and the host configuration."));
@@ -134,6 +149,24 @@ public class DbPerfWidgetRenderer extends AbstractWidgetRenderer
 
 
 
+   /*******************************************************************************
+    ** Before the first collection the vendor comes from the backend itself;
+    ** an unreachable backend falls back to the unsupported checks.
+    *******************************************************************************/
+   private static DbStatsProvider providerForBackend(DbPerfRuntime runtime)
+   {
+      try(Connection connection = ConnectionManager.getConnection((RDBMSBackendMetaData) runtime.getInstance().getBackend(runtime.getConfig().getBackendName())))
+      {
+         return (DbStatsProviders.forConnection(connection));
+      }
+      catch(Exception e)
+      {
+         return (DbStatsProviders.forProviderName(null));
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Plain text check row, never markup.
     *******************************************************************************/
@@ -169,10 +202,11 @@ public class DbPerfWidgetRenderer extends AbstractWidgetRenderer
       List<Map<String, Object>> rows = new ArrayList<>();
       for(Map<String, Object> statement : data.statements(100, null))
       {
-         rows.add(map("Query", link((String) statement.get("queryText"), (String) statement.get("historyPath")), "Calls", statement.get("calls24h"),
-            "Mean ms", statement.get("meanMs24h"), "Total ms", statement.get("totalMs24h"), "% DB time", statement.get("shareOfDbTime24h"), "Hit ratio", statement.get("hitRatio")));
+         rows.add(map("Query", stack((String) statement.get("queryText"), (String) statement.get("historyPath"),
+               format(statement.get("calls24h")) + " calls, mean " + format(statement.get("meanMs24h")) + " ms"),
+            "Total ms (24h)", statement.get("totalMs24h"), "Share of DB time %", statement.get("shareOfDbTime24h"), "Cache hit ratio", statement.get("hitRatio")));
       }
-      TableData table = table("Top queries appear after two snapshots establish interval deltas.", rows, "Query", "Calls", "Mean ms", "Total ms", "% DB time", "Hit ratio");
+      TableData table = table("Top queries appear after two snapshots establish interval deltas.", rows, "Query", "Total ms (24h)", "Share of DB time %", "Cache hit ratio");
       table.getColumns().getFirst().setType("composite");
       return (table);
    }
@@ -210,7 +244,20 @@ public class DbPerfWidgetRenderer extends AbstractWidgetRenderer
       List<Map<String, Object>> rows = sessions.stream().filter(row -> !((List<?>) row.get("blockedBy")).isEmpty() || ((Number) row.get("blockingCount")).intValue() > 0
          || "active".equals(row.get("state")) && numeric(row.get("querySeconds")) >= longRunning
          || Objects.toString(row.get("state"), "").startsWith("idle in transaction") && numeric(row.get("xactSeconds")) >= idle).toList();
-      return (table("No long-running or blocked sessions right now", rows, "pid", "user", "application", "state", "querySeconds", "xactSeconds", "blockedBy", "blockingCount", "normalizedText"));
+      List<Map<String, Object>> cells = new ArrayList<>();
+      for(Map<String, Object> row : rows)
+      {
+         boolean blocked = !((List<?>) row.get("blockedBy")).isEmpty();
+         int     blocking = ((Number) row.get("blockingCount")).intValue();
+         cells.add(map("Session", stack("pid " + row.get("pid") + ", " + Objects.toString(row.get("user"), "?") + ", " + Objects.toString(row.get("application"), ""), null,
+               Objects.toString(row.get("normalizedText"), "")),
+            "State", Objects.toString(row.get("state"), "") + (row.get("waitEvent") == null ? "" : " (" + row.get("waitEvent") + ")"),
+            "Query / transaction s", format(row.get("querySeconds")) + " / " + format(row.get("xactSeconds")),
+            "Blocking", blocked ? "blocked by " + row.get("blockedBy") : (blocking > 0 ? "blocks " + blocking : "")));
+      }
+      TableData table = table("No long-running or blocked sessions right now", cells, "Session", "State", "Query / transaction s", "Blocking");
+      table.getColumns().getFirst().setType("composite");
+      return (table);
    }
 
 
@@ -234,13 +281,29 @@ public class DbPerfWidgetRenderer extends AbstractWidgetRenderer
       List<QRecord> snapshots = data.snapshots();
       List<MultiStatisticsData.StatisticsGroupData.Statistic> values = new ArrayList<>();
       values.add(stat("Total connections", latest == null ? null : number(latest, "connectionsTotal")));
-      values.add(stat("Maximum connections", latest == null ? null : number(latest, "maxConnections")));
+      ////////////////////////////////////////////////////////////////////////
+      // figures the provider does not keep (H2: limit, cache, temp,        //
+      // deadlocks) are stored as null and left out rather than shown as 0  //
+      ////////////////////////////////////////////////////////////////////////
+      boolean limit = latest == null || latest.getValue("maxConnections") != null;
+      boolean cache = latest == null || latest.getValue("cacheHitRatio") != null;
+      boolean counters = snapshots.isEmpty() || snapshots.stream().anyMatch(row -> row.getValue("deadlocks") != null || row.getValue("tempBytes") != null);
+      if(limit)
+      {
+         values.add(stat("Maximum connections", latest == null ? null : number(latest, "maxConnections")));
+      }
       values.add(stat("Active", latest == null ? null : number(latest, "connectionsActive")));
       values.add(stat("Idle", latest == null ? null : number(latest, "connectionsIdle")));
       values.add(stat("Idle in transaction", latest == null ? null : number(latest, "connectionsIdleInTx")));
-      values.add(stat("Cache hit %", latest == null ? null : 100 * number(latest, "cacheHitRatio")));
-      values.add(stat("Temp MB (24h)", snapshots.isEmpty() ? null : snapshots.stream().mapToDouble(row -> number(row, "tempBytes")).sum() / 1048576));
-      values.add(stat("Deadlocks (24h)", snapshots.isEmpty() ? null : snapshots.stream().mapToDouble(row -> number(row, "deadlocks")).sum()));
+      if(cache)
+      {
+         values.add(stat("Cache hit %", latest == null ? null : 100 * number(latest, "cacheHitRatio")));
+      }
+      if(counters)
+      {
+         values.add(stat("Temp MB (24h)", snapshots.isEmpty() ? null : snapshots.stream().mapToDouble(row -> number(row, "tempBytes")).sum() / 1048576));
+         values.add(stat("Deadlocks (24h)", snapshots.isEmpty() ? null : snapshots.stream().mapToDouble(row -> number(row, "deadlocks")).sum()));
+      }
       return (new MultiStatisticsData(null, List.of(new MultiStatisticsData.StatisticsGroupData().withHeader("Connection capacity")
          .withSubheader(latest == null ? "Capacity appears after the next snapshot." : "Latest snapshot; percentages and MB rounded to whole numbers.").withStatisticList(values))));
    }
@@ -265,33 +328,64 @@ public class DbPerfWidgetRenderer extends AbstractWidgetRenderer
 
 
 
+   /*******************************************************************************
+    ** Most (unit, table) groups summed for the attribution panel. Production
+    ** shows about a thousand; the cap only guards pathological unit names.
+    *******************************************************************************/
+   public static final int MAX_ATTRIBUTION_GROUPS = 5000;
+
+
+
    /*******************************************************************************
     ** Aggregate units over 24 hours and show repeated-statement patterns below them.
+    ** The sums run in the database: a day of attribution detail is hundreds of
+    ** thousands of rows (about 540 MB), and loading it into the heap on a widget
+    ** request ran the web pod out of memory (2026-10-16).
     *******************************************************************************/
    public MultiTableData attribution() throws QException
    {
-      List<QRecord> records = DbPerfStore.query("db_perf_attribution", since("windowEnd"));
+      GroupBy kindGroup = new GroupBy(QFieldType.STRING, "unitKind");
+      GroupBy nameGroup = new GroupBy(QFieldType.STRING, "unitName");
+      GroupBy tableGroup = new GroupBy(QFieldType.STRING, "tableName");
+      Aggregate statementsSum = new Aggregate("statements", AggregateOperator.SUM);
+      Aggregate totalMsSum = new Aggregate("totalMs", AggregateOperator.SUM);
+      List<AggregateResult> results = new AggregateAction().execute(new AggregateInput("db_perf_attribution")
+         .withFilter(since("windowEnd").withOrderBy(new QFilterOrderByAggregate(totalMsSum, false)))
+         .withGroupBy(kindGroup).withGroupBy(nameGroup).withGroupBy(tableGroup)
+         .withAggregate(statementsSum).withAggregate(totalMsSum)
+         .withLimit(MAX_ATTRIBUTION_GROUPS)
+         .withTransaction(QContext.getQBackendTransaction())).getResults();
       Map<String, Map<String, Object>> grouped = new LinkedHashMap<>();
       Map<String, Map<String, Double>> tableTimes = new LinkedHashMap<>();
-      double total = records.stream().mapToDouble(row -> number(row, "totalMs")).sum();
-      for(QRecord row : records)
+      double total = results.stream().mapToDouble(row -> numeric(row.getAggregateValue(totalMsSum))).sum();
+      for(AggregateResult row : results)
       {
-         String key = row.getValueString("unitKind") + "\n" + row.getValueString("unitName");
-         Map<String, Object> group = grouped.computeIfAbsent(key, ignored -> map("Kind", row.getValueString("unitKind"), "Unit", row.getValueString("unitName"), "Statements", 0.0, "Total ms", 0.0));
-         group.put("Statements", numeric(group.get("Statements")) + number(row, "statements"));
-         group.put("Total ms", numeric(group.get("Total ms")) + number(row, "totalMs"));
-         tableTimes.computeIfAbsent(key, ignored -> new LinkedHashMap<>()).merge(Objects.toString(row.getValueString("tableName"), "Unknown"), number(row, "totalMs"), Double::sum);
+         String kind = (String) row.getGroupByValue(kindGroup);
+         String name = (String) row.getGroupByValue(nameGroup);
+         String key = kind + "\n" + name;
+         Map<String, Object> group = grouped.computeIfAbsent(key, ignored -> map("Kind", kind, "Name", name, "Statements", 0.0, "Total ms", 0.0));
+         group.put("Statements", numeric(group.get("Statements")) + numeric(row.getAggregateValue(statementsSum)));
+         group.put("Total ms", numeric(group.get("Total ms")) + numeric(row.getAggregateValue(totalMsSum)));
+         tableTimes.computeIfAbsent(key, ignored -> new LinkedHashMap<>()).merge(Objects.toString(row.getGroupByValue(tableGroup), "Unknown"), numeric(row.getAggregateValue(totalMsSum)), Double::sum);
       }
       grouped.forEach((key, group) ->
       {
          group.put("Share %", total == 0 ? 0 : 100 * numeric(group.get("Total ms")) / total);
          group.put("Top table", tableTimes.get(key).entrySet().stream().max(Map.Entry.comparingByValue()).orElseThrow().getKey());
       });
-      List<Map<String, Object>> units = grouped.values().stream().sorted(Comparator.comparingDouble((Map<String, Object> row) -> numeric(row.get("Total ms"))).reversed()).toList();
+      List<Map<String, Object>> units = grouped.values().stream().sorted(Comparator.comparingDouble((Map<String, Object> row) -> numeric(row.get("Total ms"))).reversed())
+         .map(row -> map("Unit of work", stack(Objects.toString(row.get("Name"), ""), null, kindLabel(row.get("Kind")) + ", top table " + row.get("Top table")),
+            "Statements", row.get("Statements"), "Total ms (24h)", row.get("Total ms"), "Share %", row.get("Share %"))).toList();
       List<Map<String, Object>> repeats = DbPerfStore.query("db_perf_repeat_pattern", since("windowEnd").withOrderBy(new QFilterOrderBy("maxRepeats", false)).withLimit(100)).stream()
-         .map(row -> fields(row, "unitKind", "unitName", "fingerprint", "unitsAffected", "maxRepeats", "totalRepeats")).toList();
-      return (new MultiTableData(List.of(table("Attribution starts after the next flush", units, "Kind", "Unit", "Statements", "Total ms", "Share %", "Top table"),
-         table("Repeated statements appear after the next attribution flush when the repetition threshold is reached.", repeats, "unitKind", "unitName", "fingerprint", "unitsAffected", "maxRepeats", "totalRepeats"))));
+         .map(row -> map("Unit of work", stack(Objects.toString(row.getValueString("unitName"), ""), null,
+               kindLabel(row.getValueString("unitKind")) + ": " + truncate(row.getValueString("sqlText"), 160)),
+            "Most repeats in one unit", row.getValue("maxRepeats"), "Units affected", row.getValue("unitsAffected"), "Total repeats", row.getValue("totalRepeats"))).toList();
+      TableData unitTable = table("Attribution starts after the next flush", units, "Unit of work", "Statements", "Total ms (24h)", "Share %");
+      unitTable.getColumns().getFirst().setType("composite");
+      TableData repeatTable = table("Repeated statements appear after the next attribution flush when the repetition threshold is reached.", repeats,
+         "Unit of work", "Most repeats in one unit", "Units affected", "Total repeats");
+      repeatTable.getColumns().getFirst().setType("composite");
+      return (new MultiTableData(List.of(unitTable, repeatTable)));
    }
 
 
@@ -301,12 +395,29 @@ public class DbPerfWidgetRenderer extends AbstractWidgetRenderer
     *******************************************************************************/
    public MultiTableData tables(DbPerformanceData data) throws QException
    {
-      List<QRecord> scans = DbPerfStore.query("db_perf_table_stat", data.backendFilter().withOrderBy(new QFilterOrderBy("seqScanShare", false)).withLimit(100));
+      QRecord settings = data.settings();
+      DbStatsProvider provider = settings == null || settings.getValueString("provider") == null ? null : DbStatsProviders.forProviderName(settings.getValueString("provider"));
       List<QRecord> growing = DbPerfStore.query("db_perf_table_stat", data.backendFilter().withOrderBy(new QFilterOrderBy("growthBytes7d", false)).withLimit(100));
-      return (new MultiTableData(List.of(table("Table scans appear after the next table snapshot (normally hourly).", scans.stream().map(row -> fields(row, "schemaName", "tableName", "seqScan", "idxScan", "seqScanShare")).toList(),
-         "schemaName", "tableName", "seqScan", "idxScan", "seqScanShare"),
-         table("Growth appears after table history has accumulated.", growing.stream().map(row -> fields(row, "schemaName", "tableName", "totalBytes", "growthBytes7d")).toList(),
-            "schemaName", "tableName", "totalBytes", "growthBytes7d"))));
+      TableData growth = table("Growth appears after table history has accumulated.", growing.stream()
+         .map(row -> map("Table", row.getValueString("schemaName") + "." + row.getValueString("tableName"), "Size MB", mb(row.getValue("totalBytes")),
+            "Growth MB (7 days)", mb(row.getValue("growthBytes7d")))).toList(),
+         "Table", "Size MB", "Growth MB (7 days)");
+      if(provider != null && !provider.features().contains(StatsFeature.TABLE_ACCESS))
+      {
+         //////////////////////////////////////////////////////////////////
+         // vendors without scan counters (H2) list rows and size instead //
+         //////////////////////////////////////////////////////////////////
+         List<QRecord> largest = DbPerfStore.query("db_perf_table_stat", data.backendFilter().withOrderBy(new QFilterOrderBy("nLiveTup", false)).withLimit(100));
+         return (new MultiTableData(List.of(table("Tables appear after the next table snapshot (normally hourly).", largest.stream()
+            .map(row -> map("Table", row.getValueString("schemaName") + "." + row.getValueString("tableName"), "Rows (estimate)", row.getValue("nLiveTup"),
+               "Size MB", mb(row.getValue("totalBytes")))).toList(),
+            "Table", "Rows (estimate)", "Size MB"), growth)));
+      }
+      List<QRecord> scans = DbPerfStore.query("db_perf_table_stat", data.backendFilter().withOrderBy(new QFilterOrderBy("seqScanShare", false)).withLimit(100));
+      return (new MultiTableData(List.of(table("Table scans appear after the next table snapshot (normally hourly).", scans.stream()
+            .map(row -> map("Table", row.getValueString("schemaName") + "." + row.getValueString("tableName"), "Sequential scans", row.getValue("seqScan"),
+               "Index scans", row.getValue("idxScan"), "Sequential share %", row.getValue("seqScanShare"))).toList(),
+            "Table", "Sequential scans", "Index scans", "Sequential share %"), growth)));
    }
 
 
@@ -333,6 +444,79 @@ public class DbPerfWidgetRenderer extends AbstractWidgetRenderer
 
 
 
+   /*******************************************************************************
+    ** A stacked cell: the main text (a record link when a path is given) over a
+    ** smaller secondary line, so tables keep at most four columns.
+    *******************************************************************************/
+   private static CompositeWidgetData stack(String main, String path, String secondary)
+   {
+      TextBlockData first = new TextBlockData().withValues(new TextValues(truncate(main, 300)));
+      if(path != null)
+      {
+         first.withLink(new BlockLink(path));
+      }
+      CompositeWidgetData cell = new CompositeWidgetData().withLayout(CompositeWidgetData.Layout.FLEX_COLUMN).withBlock(first);
+      if(secondary != null && !secondary.isBlank())
+      {
+         cell.withBlock(new TextBlockData().withValues(new TextValues(truncate(secondary, 300))).withStyles(new TextStyles().withColor("MUTED")));
+      }
+      return (cell);
+   }
+
+
+
+   /*******************************************************************************
+    ** Plain label for a unit-of-work kind.
+    *******************************************************************************/
+   private static String kindLabel(Object kind)
+   {
+      return (switch(Objects.toString(kind, ""))
+      {
+         case "HTTP_REQUEST" -> "Request";
+         case "SCHEDULED_JOB" -> "Scheduled job";
+         case "PROCESS" -> "Process";
+         default -> "Other";
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** Text capped with an ellipsis.
+    *******************************************************************************/
+   private static String truncate(String value, int max)
+   {
+      String text = value == null ? "" : value;
+      return (text.length() <= max ? text : text.substring(0, max - 1) + "…");
+   }
+
+
+
+   /*******************************************************************************
+    ** A number for a secondary line: whole numbers without decimals.
+    *******************************************************************************/
+   private static String format(Object value)
+   {
+      if(value == null)
+      {
+         return ("0");
+      }
+      double number = ((Number) value).doubleValue();
+      return (number == Math.rint(number) ? String.valueOf((long) number) : String.format(Locale.ROOT, "%.1f", number));
+   }
+
+
+
+   /*******************************************************************************
+    ** Bytes as whole megabytes.
+    *******************************************************************************/
+   private static Long mb(Object bytes)
+   {
+      return (bytes == null ? null : Math.round(((Number) bytes).doubleValue() / 1048576));
+   }
+
+
+
    /*******************************************************************************
     ** Trailing-day filter for time-window records.
     *******************************************************************************/

src/main/resources/db/liquibase/qbit-db-performance/db_performance.changelog.sql

@@ -605,3 +605,7 @@ INSERT INTO db_perf_rule (code,label,description,enabled,severity,threshold_1,th
 SELECT 'TEMP_SPILL', 'Temporary disk spill', 'Statements that write temporary files because sorts or hashes do not fit in work_mem.', TRUE, 'WARNING', 100, 'Temporary data written per day (MB)', NULL, NULL WHERE NOT EXISTS (SELECT 1 FROM db_perf_rule WHERE code = 'TEMP_SPILL');
 INSERT INTO db_perf_rule (code,label,description,enabled,severity,threshold_1,threshold_1_label,threshold_2,threshold_2_label)
 SELECT 'DEADLOCKS', 'Deadlocks', 'Transactions that deadlocked and were cancelled by PostgreSQL. Usually two code paths that lock rows in a different order.', TRUE, 'WARNING', 1, 'Deadlocks per day', NULL, NULL WHERE NOT EXISTS (SELECT 1 FROM db_perf_rule WHERE code = 'DEADLOCKS');
+
+-- changeset qbit-db-performance:34
+-- comment: Repeated Statements: the sampling rate of each window, so repeat counts can be read at scale.
+ALTER TABLE db_perf_repeat_pattern ADD COLUMN IF NOT EXISTS sample_rate DECIMAL(5,4);

src/main/resources/help/qbit-db-performance.yaml

@@ -388,6 +388,8 @@ entries:
   summary: "Largest repetition count for one fingerprint in a single sampled unit of work."
 - key: table:db_perf_repeat_pattern;field:totalRepeats
   summary: "Total repeats reported for this repeat pattern record."
+- key: table:db_perf_repeat_pattern;field:sampleRate
+  summary: "Share of units of work that were measured in this window (1 means all)."
 - key: table:db_perf_rule;slot:help
   summary: "Editable thresholds and severity for each suggestion rule."
   content: |
@@ -517,7 +519,7 @@ entries:
 - key: table:db_perf_settings;field:lastTableSnapshotAt
   summary: "Time of the latest table and index collection pass."
 - key: table:db_perf_settings;field:statsAccess
-  summary: "Statistics capability: FULL, reduced access, missing extension, or unsupported provider."
+  summary: "Statistics capability: FULL, reduced visibility, statement statistics off, or unsupported provider."
 - key: table:db_perf_settings;field:statsAccessMessage
   summary: "The collector explains missing capabilities and the next grant or setup step."
 - key: table:db_perf_snapshot;slot:help
@@ -808,6 +810,10 @@ entries:
   summary: "Collect an immediate snapshot and force table and index statistics."
   content: |
     Run from the Snapshots table. Requires manage settings. The Result screen reports success, partial access or collection failure. The first pass establishes counter baselines.
+- key: process:dbPerfEnableStatementStatistics;slot:help
+  summary: "Turn on statement statistics where the database allows it at runtime."
+  content: |
+    Run from Settings. Requires manage settings. On H2 it runs SET QUERY_STATISTICS TRUE, which needs an H2 admin user and lasts until the database closes; add ;QUERY_STATISTICS=TRUE to the JDBC URL to keep it on. PostgreSQL cannot do this at runtime (pg_stat_statements needs shared_preload_libraries and CREATE EXTENSION), so the result explains the manual step. The Result screen shows the new statistics access.
 - key: process:dbPerfRollupAndPurge;slot:help
   summary: "Roll up completed days and remove expired details."
   content: |
@@ -815,7 +821,7 @@ entries:
 - key: process:dbPerfQueryPlan;slot:help
   summary: "Inspect the plan of one statement, with optional read-only execution."
   content: |
-    Choose PLAN (default) or ANALYZE. PLAN uses a generic plan for parameterized SQL on PostgreSQL 16+. ANALYZE requires explain analyze permission and exactly one SELECT with no modifying CTEs, INTO or row locks. Enter parameter values only for ANALYZE, one per line in placeholder order. Values are sent transiently; they and the ANALYZE plan are never stored. Every request is audited. Results include copyable plan text, cost, a SQL Workbench link and a literal-free assistant prompt. No model is called by this qbit.
+    Choose PLAN (default) or ANALYZE. PLAN uses a generic plan for parameterized SQL on PostgreSQL 16+ and H2. H2 plans are text (index choice and scan counts) without a cost tree; H2 refuses SQL naming side-effecting functions, DDL or aliases, and allows ANALYZE only for non-admin users. ANALYZE requires explain analyze permission and exactly one SELECT with no modifying CTEs, INTO or row locks. Enter parameter values only for ANALYZE, one per line in placeholder order. Values are sent transiently; they and the ANALYZE plan are never stored. Every request is audited. Results include copyable plan text, cost, a SQL Workbench link and a literal-free assistant prompt. No model is called by this qbit.
 - key: widget:dbPerfSetup;slot:label
   summary: "Check backend, statistics access, collection, attribution and scheduler setup."
 - key: widget:dbPerfDatabaseTime;slot:label

src/main/resources/openapi/qqq-v1/db-performance.yaml

@@ -1,5 +1,44 @@
 components:
   schemas:
+    BasicErrorResponseV1:
+      description: "The error body of every UI API operation (core and extensions)."
+      properties:
+        error:
+          description: "The error message (the same as message; kept for clients of\
+            \ UI API 1.0 to 1.5)."
+          type: "string"
+        code:
+          description: "A stable, machine-readable code. Well-known values: BAD_REQUEST\
+            \ (400), UNAUTHENTICATED (401),\nPERMISSION_DENIED (403), NOT_FOUND (404),\
+            \ CONFLICT (409), RATE_LIMITED (429), INTERNAL_ERROR (500),\nERROR (other).\
+            \ Extensions may add codes; treat an unknown code by the HTTP status.\
+            \ Since 1.6.0."
+          type: "string"
+        message:
+          description: "A message to show the user. Since 1.6.0."
+          type: "string"
+        fieldErrors:
+          description: "Errors about particular request fields, when known. Since\
+            \ 1.6.0."
+          items:
+            properties:
+              field:
+                description: "The field (or parameter) name."
+                type: "string"
+              message:
+                description: "The error about that field."
+                type: "string"
+              code:
+                description: "An optional machine-readable code, e.g. REQUIRED, TOO_LONG,\
+                  \ PATTERN."
+                type: "string"
+            type: "object"
+          type: "array"
+        traceId:
+          description: "Identifies this request in the server logs (also the X-QQQ-Trace-Id\
+            \ response header); quote it when reporting a problem. Since 1.6.0."
+          type: "string"
+      type: "object"
     DbPerformanceActivityV1:
       properties:
         blockingChains:
@@ -256,9 +295,42 @@ components:
       type: "object"
   securitySchemes:
     sessionUuidCookie:
+      description: "The session cookie set by POST /qqq/v1/manageSession (web clients)."
       in: "cookie"
       name: "sessionUUID"
       type: "apiKey"
+    bearerAuth:
+      bearerFormat: "JWT or session UUID"
+      description: "`Authorization: Bearer <token>`, where the token is either\n-\
+        \ an OAuth2 access token (a signed JWT) issued by the app's identity provider\
+        \ to the app's client,\n  or to its native client (`values.nativeClientId`\
+        \ in GET /qqq/v1/metaData/authentication), for\n  example from the device-authorization\
+        \ grant or auth-code + PKCE. It is verified against the\n  provider's keys\
+        \ (issuer, audience, expiry, signature) and gives the same user and permissions\n\
+        \  as signing in on the web. When it expires (401), refresh it at the provider\
+        \ and retry; or\n- a session UUID returned by POST /qqq/v1/manageSession,\
+        \ which the server keeps refreshed."
+      scheme: "bearer"
+      type: "http"
+    oauth2:
+      description: "The app's OAuth2 / OpenID Connect provider. The real endpoints\
+        \ come from the provider's discovery\ndocument: `{values.baseUrl}.well-known/openid-configuration`,\
+        \ with values from\nGET /qqq/v1/metaData/authentication. Native clients use\
+        \ `values.nativeClientId` (a public client)\nwith auth-code + PKCE (loopback\
+        \ or custom-scheme redirect URI registered at the provider) or the\ndevice-authorization\
+        \ grant (`device_authorization_endpoint`, RFC 8628), then send the access\
+        \ token\nas `Authorization: Bearer`."
+      flows:
+        authorizationCode:
+          authorizationUrl: "/authorize"
+          scopes:
+            email: "Email address"
+            offline_access: "A refresh token, to renew the access token without signing\
+              \ in again"
+            openid: "OpenID Connect sign-in"
+            profile: "Name, username and groups (permissions come from the groups)"
+          tokenUrl: "/token"
+      type: "oauth2"
 info:
   contact:
     email: "contact@kingsrook.com"
@@ -303,10 +375,37 @@ paths:
               schema:
                 $ref: "#/components/schemas/DbPerformanceOverviewV1"
           description: "Successful Response"
+        404:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Not found, or not visible to this user (code NOT_FOUND)."
+        409:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Conflict with the current state, e.g. an edit conflict or\
+            \ an invalid transition (code CONFLICT)."
+        429:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Too many requests (code RATE_LIMITED); retry later."
       security:
       - sessionUuidCookie:
         - "N/A"
+      - bearerAuth:
+        - "N/A"
+      - oauth2:
+        - "openid"
+        - "profile"
+        - "email"
       summary: "Database Performance overview"
+      tags:
+      - "db-performance"
   /qqq/v1/qbit/db-performance/activity:
     get:
       description: "Requires db_performance.view and uses the caller's session."
@@ -343,10 +442,37 @@ paths:
               schema:
                 $ref: "#/components/schemas/DbPerformanceActivityV1"
           description: "Successful Response"
+        404:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Not found, or not visible to this user (code NOT_FOUND)."
+        409:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Conflict with the current state, e.g. an edit conflict or\
+            \ an invalid transition (code CONFLICT)."
+        429:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Too many requests (code RATE_LIMITED); retry later."
       security:
       - sessionUuidCookie:
         - "N/A"
+      - bearerAuth:
+        - "N/A"
+      - oauth2:
+        - "openid"
+        - "profile"
+        - "email"
       summary: "Database Performance activity"
+      tags:
+      - "db-performance"
   /qqq/v1/qbit/db-performance/explain:
     post:
       description: "PLAN requires db_performance.explain; ANALYZE requires db_performance.explain_analyze.\
@@ -383,10 +509,37 @@ paths:
               schema:
                 $ref: "#/components/schemas/DbPerformanceExplainResultV1"
           description: "Successful Response"
+        404:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Not found, or not visible to this user (code NOT_FOUND)."
+        409:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Conflict with the current state, e.g. an edit conflict or\
+            \ an invalid transition (code CONFLICT)."
+        429:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Too many requests (code RATE_LIMITED); retry later."
       security:
       - sessionUuidCookie:
         - "N/A"
-      summary: "Explain a PostgreSQL query"
+      - bearerAuth:
+        - "N/A"
+      - oauth2:
+        - "openid"
+        - "profile"
+        - "email"
+      summary: "Explain a query (PostgreSQL JSON or H2 text plan)"
+      tags:
+      - "db-performance"
   /qqq/v1/qbit/db-performance/statements/lookup:
     get:
       description: "Requires db_performance.view and uses the caller's session."
@@ -428,7 +581,40 @@ paths:
               schema:
                 $ref: "#/components/schemas/DbPerformanceLookupV1"
           description: "Successful Response"
+        404:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Not found, or not visible to this user (code NOT_FOUND)."
+        409:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Conflict with the current state, e.g. an edit conflict or\
+            \ an invalid transition (code CONFLICT)."
+        429:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BasicErrorResponseV1"
+          description: "Too many requests (code RATE_LIMITED); retry later."
       security:
       - sessionUuidCookie:
         - "N/A"
+      - bearerAuth:
+        - "N/A"
+      - oauth2:
+        - "openid"
+        - "profile"
+        - "email"
       summary: "Database Performance lookup"
+      tags:
+      - "db-performance"
+servers:
+- description: "The QQQ server that serves this document (paths include /qqq/v1)."
+  url: "/"
+tags:
+- description: "Operations of the db-performance extension."
+  name: "db-performance"

src/test/java/com/kingsrook/qbits/dbperformance/AttributionBoundedReadTest.java

@@ -0,0 +1,239 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance;
+
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.ZoneId;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicInteger;
+import com.kingsrook.qbits.dbperformance.analyze.RuleContext;
+import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
+import com.kingsrook.qbits.dbperformance.collect.RollupService;
+import com.kingsrook.qbits.dbperformance.widgets.DbPerfWidgetRenderer;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizerInterface;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizers;
+import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.MultiTableData;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.utils.JsonUtils;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Attribution detail grows by hundreds of thousands of rows a day. On
+ ** 2026-10-16 the home widget loaded a whole day of it into the heap and ran
+ ** the kof22 web pod out of memory, and the hourly analysis filled the worker
+ ** heap the same way. These tests count every attribution detail record QQQ
+ ** materializes, so the widget, the analysis and the daily rollup cannot go
+ ** back to reading the table in one unbounded query.
+ *******************************************************************************/
+class AttributionBoundedReadTest
+{
+   private static final AtomicInteger LOADED   = new AtomicInteger();
+   private static final AtomicInteger MAX_PAGE = new AtomicInteger();
+
+   private DbPerfRuntime runtime;
+
+
+
+   /*******************************************************************************
+    ** Counts the detail records each QueryAction hands back.
+    *******************************************************************************/
+   public static class CountingCustomizer implements TableCustomizerInterface
+   {
+      /***************************************************************************
+       ** Record the page size, change nothing.
+       ***************************************************************************/
+      @Override
+      public List<QRecord> postQuery(QueryOrGetInputInterface queryInput, List<QRecord> records)
+      {
+         LOADED.addAndGet(records.size());
+         MAX_PAGE.accumulateAndGet(records.size(), Math::max);
+         return (records);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Fresh H2 instance with the counter on the detail table.
+    *******************************************************************************/
+   @BeforeEach
+   void setup() throws Exception
+   {
+      runtime = DbPerfRuntime.of(DbPerfTestSupport.instance());
+      runtime.getInstance().getTable("db_perf_attribution").withCustomizer(TableCustomizers.POST_QUERY_RECORD, new QCodeReference(CountingCustomizer.class));
+      LOADED.set(0);
+      MAX_PAGE.set(0);
+   }
+
+
+
+   /*******************************************************************************
+    ** The widget sums in the database: no detail rows reach the heap, and the
+    ** totals still match the detail.
+    *******************************************************************************/
+   @Test
+   void widgetSumsInTheDatabase() throws Exception
+   {
+      Instant now = Instant.now();
+      insert(3000, i -> row(now.minusSeconds(60), now, i));
+      LOADED.set(0);
+
+      MultiTableData attribution = new DbPerfWidgetRenderer().attribution();
+
+      assertThat(LOADED.get()).as("attribution detail rows loaded by the widget").isZero();
+      List<Map<String, Object>> units = attribution.getTableDataList().getFirst().getRows();
+      assertThat(units).hasSize(3);
+      // unit-0 holds i = 0, 3, 6 ... (1000 rows, 2 statements each), mostly against "patient"
+      assertThat(((Number) units.getFirst().get("Statements")).doubleValue() + ((Number) units.get(1).get("Statements")).doubleValue()
+         + ((Number) units.get(2).get("Statements")).doubleValue()).isEqualTo(6000.0);
+      assertThat(units).allSatisfy(unit -> assertThat(((Number) unit.get("Statements")).doubleValue()).isEqualTo(2000.0));
+      assertThat(JsonUtils.toJson(units.getFirst())).contains("top table patient");
+      assertThat(units.stream().mapToDouble(unit -> ((Number) unit.get("Share %")).doubleValue()).sum()).isCloseTo(100.0, org.assertj.core.data.Offset.offset(0.001));
+   }
+
+
+
+   /*******************************************************************************
+    ** Detail older than 24 hours is left out of the sums.
+    *******************************************************************************/
+   @Test
+   void widgetKeepsTheDayWindow() throws Exception
+   {
+      Instant now = Instant.now();
+      insert(3, i -> row(now.minusSeconds(60), now, i));
+      insert(3, i -> row(now.minusSeconds(3 * 86400), now.minusSeconds(2 * 86400), i));
+      List<Map<String, Object>> units = new DbPerfWidgetRenderer().attribution().getTableDataList().getFirst().getRows();
+      assertThat(units).hasSize(3).allSatisfy(unit -> assertThat(((Number) unit.get("Statements")).doubleValue()).isEqualTo(2.0));
+   }
+
+
+
+   /*******************************************************************************
+    ** The hourly analysis reads attribution as database sums per unit, table
+    ** and operation: no detail rows, same totals.
+    *******************************************************************************/
+   @Test
+   void analysisSumsInTheDatabase() throws Exception
+   {
+      Instant now = Instant.now();
+      insert(3000, i -> row(now.minusSeconds(60), now, i));
+      LOADED.set(0);
+      RuleContext context = new RuleContext(runtime, runtime.getConfig().getBackendName(), new QRecord(), new QRecord(), now.plusSeconds(1));
+
+      List<QRecord> rows = context.window("attribution", 1);
+
+      assertThat(LOADED.get()).as("attribution detail rows loaded by the analysis").isZero();
+      assertThat(rows).hasSize(6);
+      assertThat(rows.stream().mapToDouble(row -> RuleContext.number(row, "statements")).sum()).isEqualTo(6000.0);
+      assertThat(rows.stream().mapToDouble(row -> RuleContext.number(row, "totalMs")).sum()).isEqualTo(1500 * 10.0 + 1500 * 1.0);
+      assertThat(rows).allSatisfy(row -> assertThat(row.getValueString("operation")).isEqualTo("SELECT"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Keyset pages never exceed the page size, and every row is seen once.
+    *******************************************************************************/
+   @Test
+   void forEachPageIsBounded() throws Exception
+   {
+      Instant now = Instant.now();
+      insert(1050, i -> row(now.minusSeconds(60), now, i));
+      LOADED.set(0);
+      List<Integer> sizes = new ArrayList<>();
+      List<Object> ids = new ArrayList<>();
+      DbPerfStore.forEachPage("db_perf_attribution", new QQueryFilter(), 100, page ->
+      {
+         sizes.add(page.size());
+         page.forEach(row -> ids.add(row.getValue("id")));
+      });
+      assertThat(sizes).hasSize(11).allSatisfy(size -> assertThat(size).isLessThanOrEqualTo(100));
+      assertThat(ids).hasSize(1050).doesNotHaveDuplicates();
+      assertThat(MAX_PAGE.get()).isLessThanOrEqualTo(100);
+   }
+
+
+
+   /*******************************************************************************
+    ** The daily rollup reads the day in BATCH_SIZE pages and its sums still
+    ** cover every detail row across page boundaries.
+    *******************************************************************************/
+   @Test
+   void rollupReadsTheDayInPages() throws Exception
+   {
+      ZoneId zone = ZoneId.of(runtime.getConfig().getTimeZone());
+      LocalDate day = LocalDate.now(zone).minusDays(1);
+      Instant start = day.atStartOfDay(zone).toInstant().plusSeconds(3600);
+      int rows = DbPerfStore.BATCH_SIZE * 2 + 500;
+      insert(rows, i -> row(start, start.plusSeconds(60), i));
+      MAX_PAGE.set(0);
+      LOADED.set(0);
+
+      new RollupService(runtime).rollupDay(day);
+
+      assertThat(MAX_PAGE.get()).as("largest page of attribution detail held at once").isLessThanOrEqualTo(DbPerfStore.BATCH_SIZE);
+      assertThat(LOADED.get()).isEqualTo(rows);
+      List<QRecord> daily = DbPerfStore.query("db_perf_attribution_daily", new QQueryFilter());
+      assertThat(daily).hasSize(6);
+      assertThat(daily.stream().mapToLong(row -> row.getValueLong("statements")).sum()).isEqualTo(2L * rows);
+   }
+
+
+
+   /*******************************************************************************
+    ** Insert generated rows in batches.
+    *******************************************************************************/
+   private static void insert(int count, java.util.function.IntFunction<QRecord> factory) throws Exception
+   {
+      List<QRecord> rows = new ArrayList<>();
+      for(int i = 0; i < count; i++)
+      {
+         rows.add(factory.apply(i));
+      }
+      DbPerfStore.insert("db_perf_attribution", rows);
+   }
+
+
+
+   /*******************************************************************************
+    ** Three units; each unit spends most of its time on "patient".
+    *******************************************************************************/
+   private static QRecord row(Instant windowStart, Instant windowEnd, int i)
+   {
+      boolean patient = i % 6 < 3;
+      return (new QRecord().withValue("windowStart", windowStart).withValue("windowEnd", windowEnd).withValue("podName", "pod-" + (i % 2))
+         .withValue("unitKind", "PROCESS").withValue("unitName", "unit-" + (i % 3)).withValue("tableName", patient ? "patient" : "visit")
+         .withValue("operation", "SELECT").withValue("fingerprint", "f".repeat(64)).withValue("sqlText", "select 1")
+         .withValue("units", 1L).withValue("statements", 2L).withValue("rowsCount", 1L).withValue("errors", 0L)
+         .withValue("totalMs", patient ? BigDecimal.TEN : BigDecimal.ONE).withValue("maxMs", BigDecimal.ONE));
+   }
+}

src/test/java/com/kingsrook/qbits/dbperformance/DbPerfApiContractTest.java

@@ -56,7 +56,7 @@ class DbPerfApiContractTest
       }
       assertThat(UiApiContract.check(generated, Files.readString(path), null, 1, "mvnw -Dtest=DbPerfApiContractTest -Ddbperf.openapi.update=true test")).isEmpty();
       var model = version.generateExtensionOpenAPIModel("qqq", extension);
-      assertThat(model.getComponents().getSchemas().keySet()).allMatch(name -> name.startsWith("DbPerformance") && name.endsWith("V1"));
+      assertThat(model.getComponents().getSchemas().keySet()).allMatch(name -> (name.startsWith("DbPerformance") || name.equals("BasicErrorResponseV1")) && name.endsWith("V1"));
       assertThat(model.getPaths().keySet()).containsExactlyInAnyOrder("/qqq/v1/qbit/db-performance/overview", "/qqq/v1/qbit/db-performance/activity",
          "/qqq/v1/qbit/db-performance/explain", "/qqq/v1/qbit/db-performance/statements/lookup");
       assertThat(extension.getSemanticVersion()).isEqualTo("1.0.0");

src/test/java/com/kingsrook/qbits/dbperformance/DbPerfFixtureProvider.java

@@ -47,6 +47,7 @@ public class DbPerfFixtureProvider extends UnsupportedStatsProvider
    public Instant reset = START.minusSeconds(3600);
    public boolean limited;
    public boolean fail;
+   public Error   error;
 
 
    /*******************************************************************************
@@ -85,6 +86,10 @@ public class DbPerfFixtureProvider extends UnsupportedStatsProvider
    @Override
    public List<StatementStats> readStatements(Connection connection)
    {
+      if(error != null)
+      {
+         throw (error);
+      }
       return (List.of(new StatementStats(1, "app", true, "select * from public.accounts where id=$1", calls, BigDecimal.valueOf(calls * 10), BigDecimal.TEN, BigDecimal.valueOf(15), calls, calls * 9, calls, 0, reset, reset),
          new StatementStats(2, "app", true, "select * from public.accounts where name='private'", calls, BigDecimal.valueOf(calls * 5), BigDecimal.valueOf(5), BigDecimal.TEN, calls, calls, calls, 2, reset, reset)));
    }

src/test/java/com/kingsrook/qbits/dbperformance/DbPerfHealthTest.java

@@ -76,7 +76,7 @@ class DbPerfHealthTest
       DbPerfHealthChecks checks = checks(f, 0);
       for(String access : List.of("FULL", "NO_READ_ALL_STATS", "NO_PG_STAT_STATEMENTS", "UNSUPPORTED", "UNKNOWN"))
       {
-         DbPerfStore.update("db_perf_settings", List.of(new QRecord().withValue("id", f.settings.getValueInteger("id")).withValue("statsAccess", access)));
+         DbPerfStore.update("db_perf_settings", List.of(new QRecord().withValue("id", f.settings.getValueInteger("id")).withValue("provider", "POSTGRES").withValue("statsAccess", access)));
          var outcome = checks.check("stats_access");
          assertThat(outcome.getDetails().getValues()).containsEntry("statsAccess", access).hasSize(1);
          assertThat(outcome.getStatus()).isEqualTo(switch(access)
@@ -91,6 +91,14 @@ class DbPerfHealthTest
             assertThat(outcome.getMessage()).isEqualTo("grant pg_read_all_stats to sa");
          }
       }
+      for(String access : List.of("NO_QUERY_STATISTICS", "NOT_ADMIN"))
+      {
+         DbPerfStore.update("db_perf_settings", List.of(new QRecord().withValue("id", f.settings.getValueInteger("id")).withValue("provider", "H2").withValue("statsAccess", access)));
+         var outcome = checks.check("stats_access");
+         assertThat(outcome.getStatus()).isEqualTo(HealthStatus.DEGRADED);
+         assertThat(outcome.getDetails().getValues()).containsEntry("statsAccess", access);
+         assertThat(outcome.getMessage()).doesNotContain("pg_").contains(access.equals("NOT_ADMIN") ? "ADMIN TRUE" : "QUERY_STATISTICS=TRUE");
+      }
       for(int total : List.of(79, 80, 94, 95))
       {
          DbPerfStore.update("db_perf_snapshot", List.of(new QRecord().withValue("id", f.snapshot.getValueInteger("id")).withValue("connectionsTotal", total)));

src/test/java/com/kingsrook/qbits/dbperformance/DbPerfPresentationTest.java

@@ -33,6 +33,7 @@ import com.kingsrook.qbits.dbperformance.api.OverviewSpec;
 import com.kingsrook.qbits.dbperformance.collect.DbPerfSettingsService;
 import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
 import com.kingsrook.qbits.dbperformance.explain.ExplainRequest;
+import com.kingsrook.qbits.dbperformance.explain.ExplainResult;
 import com.kingsrook.qbits.dbperformance.explain.ExplainService;
 import com.kingsrook.qbits.dbperformance.explain.QueryPlanProcess;
 import com.kingsrook.qbits.dbperformance.normalize.SqlNormalizer;
@@ -103,7 +104,7 @@ class DbPerfPresentationTest
       assertThat(new DbPerfWidgetRenderer().liveActivity(data).getNoRowsFoundHTML()).isEqualTo("No long-running or blocked sessions right now");
       assertThat(new DbPerfWidgetRenderer().attribution().getTableDataList().getFirst().getNoRowsFoundHTML()).isEqualTo("Attribution starts after the next flush");
       assertThat(new DbPerfWidgetRenderer().connectionStatistics(data).getType()).isEqualTo("multiStatistics");
-      assertThat(new DbPerfWidgetRenderer().connectionsByApplication(runtime).getRows()).isEmpty();
+      assertThat(new DbPerfWidgetRenderer().connectionsByApplication(runtime).getRows()).isNotEmpty().allSatisfy(row -> assertThat(row).containsKeys("Application", "User", "State", "Connections"));
       QContext.setQSession(new QSession());
       for(String name : DbPerfWidgets.HOME)
       {
@@ -129,7 +130,7 @@ class DbPerfPresentationTest
       assertThat((Map<String, Integer>) overview.get("findingsBySeverity")).containsEntry("HIGH", 1);
       TableData queries = new DbPerfWidgetRenderer().topQueries(data);
       assertThat(queries.getRows()).hasSize(1);
-      assertThat((BigDecimal) queries.getRows().getFirst().get("% DB time")).isEqualByComparingTo("25");
+      assertThat((BigDecimal) queries.getRows().getFirst().get("Share of DB time %")).isEqualByComparingTo("25");
       assertThat(JsonUtils.toJson(queries)).contains("/app/dbPerformance/db_perf_statement/", "composite").doesNotContain("private-value");
       ChartData chart = new DbPerfWidgetRenderer().databaseTime(data);
       assertThat(chart.getChartData().getDatasets()).hasSize(2);
@@ -137,7 +138,7 @@ class DbPerfPresentationTest
       assertThat(new DbPerfWidgetRenderer().findings(data).getRows()).hasSize(1);
       assertThat(new DbPerfWidgetRenderer().tables(data).getTableDataList().getFirst().getRows()).hasSize(1);
       MultiTableData attribution = new DbPerfWidgetRenderer().attribution();
-      assertThat(attribution.getTableDataList().getFirst().getRows().getFirst()).containsEntry("Top table", "patient");
+      assertThat(JsonUtils.toJson(attribution.getTableDataList().getFirst().getRows().getFirst())).contains("top table patient");
       assertThat(attribution.getTableDataList().get(1).getRows()).hasSize(1);
       assertThat(JsonUtils.toJson(new DbPerfWidgetRenderer().connectionStatistics(data))).contains("Deadlocks", "Cache hit");
       JsonInput lookup = new JsonInput();
@@ -194,7 +195,7 @@ class DbPerfPresentationTest
       QContext.setQSession(new QSession().withPermissions(DbPerfPermissions.VIEW));
       TableData table = new DbPerfWidgetRenderer().liveActivity(fixtureData);
       assertThat(table.getRows()).hasSize(2);
-      assertThat(JsonUtils.toJson(table)).doesNotContain("private-value").contains("normalizedText", "blockingCount");
+      assertThat(JsonUtils.toJson(table)).doesNotContain("private-value").contains("select * from patient where name = ?", "blocks 1", "blocked by");
       QContext.setQSession(new QSession().withPermissions(DbPerfPermissions.VIEW, DbPerfPermissions.VIEW_LIVE_TEXT));
       assertThat(JsonUtils.toJson(new DbPerfWidgetRenderer().liveActivity(fixtureData))).doesNotContain("private-value");
    }
@@ -235,7 +236,9 @@ class DbPerfPresentationTest
    void explainAuditAndHandler() throws Exception
    {
       ExplainService service = new ExplainService(runtime);
-      assertThatThrownBy(() -> service.explain(new ExplainRequest(runtime.getConfig().getBackendName(), null, "select current_date", ExplainRequest.Mode.PLAN, List.of()))).hasMessageContaining("PostgreSQL");
+      ExplainResult h2 = service.explain(new ExplainRequest(runtime.getConfig().getBackendName(), null, "select current_date", ExplainRequest.Mode.PLAN, List.of()));
+      assertThat(h2.planJson()).isNull();
+      assertThat(h2.planText()).containsIgnoringCase("CURRENT_DATE");
       assertThatThrownBy(() -> service.explain(null)).hasMessageContaining("Choose PLAN");
       assertThatThrownBy(() -> service.explain(new ExplainRequest(runtime.getConfig().getBackendName(), null, null, ExplainRequest.Mode.PLAN, List.of()))).hasMessageContaining("either");
       QContext.setQSession(new QSession());

src/test/java/com/kingsrook/qbits/dbperformance/H2CollectionTest.java

@@ -0,0 +1,173 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance;
+
+
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.Statement;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.stream.Collectors;
+import com.kingsrook.qbits.dbperformance.analyze.AnalyzeService;
+import com.kingsrook.qbits.dbperformance.api.DbPerformanceData;
+import com.kingsrook.qbits.dbperformance.collect.DbPerfSettingsService;
+import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
+import com.kingsrook.qbits.dbperformance.collect.SnapshotCollector;
+import com.kingsrook.qbits.dbperformance.explain.ExplainRequest;
+import com.kingsrook.qbits.dbperformance.explain.ExplainResult;
+import com.kingsrook.qbits.dbperformance.explain.ExplainService;
+import com.kingsrook.qbits.dbperformance.processes.DbPerfEnableStatisticsStep;
+import com.kingsrook.qbits.dbperformance.widgets.DbPerfWidgetRenderer;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** The qbit end to end on an H2 backend: collection, the enable action,
+ ** feature-gated analysis, setup rows and text plans.
+ *******************************************************************************/
+class H2CollectionTest
+{
+   /*******************************************************************************
+    ** Two collections store H2 statements, tables, indexes and connections.
+    *******************************************************************************/
+   @Test
+   void collectAnalyzeAndExplain() throws Exception
+   {
+      DbPerfRuntime runtime = runtime(";QUERY_STATISTICS=TRUE;QUERY_STATISTICS_MAX_ENTRIES=1000");
+      String backend = runtime.getConfig().getBackendName();
+      workload(runtime);
+      QRecord first = new SnapshotCollector(runtime).collect(backend, true);
+      assertThat(first.getValueString("status")).as(first.getValueString("errorMessage")).isEqualTo("OK");
+      workload(runtime);
+      QRecord second = new SnapshotCollector(runtime).collect(backend, true);
+      assertThat(second.getValueString("status")).as(second.getValueString("errorMessage")).isEqualTo("OK");
+      assertThat(second.getValueInteger("intervalSeconds")).isNotNull();
+      assertThat(second.getValue("cacheHitRatio")).isNull();
+      assertThat(second.getValue("maxConnections")).isNull();
+      assertThat(second.getValueInteger("connectionsTotal")).isPositive();
+
+      QRecord settings = new DbPerfSettingsService(runtime).ensure(backend);
+      assertThat(settings.getValueString("provider")).isEqualTo("H2");
+      assertThat(settings.getValueString("statsAccess")).isEqualTo("FULL");
+
+      List<QRecord> statements = DbPerfStore.query("db_perf_statement", DbPerfStore.eq("backendName", backend));
+      assertThat(statements).anySatisfy(row ->
+      {
+         assertThat(row.getValueString("queryText")).containsIgnoringCase("h2_probe");
+         assertThat(row.getValueLong("lastCalls")).isGreaterThanOrEqualTo(6);
+      });
+      assertThat(DbPerfStore.query("db_perf_query_snapshot", new QQueryFilter())).anySatisfy(row -> assertThat(row.getValueLong("calls")).isEqualTo(3));
+      assertThat(DbPerfStore.query("db_perf_table_stat", DbPerfStore.eq("backendName", backend)))
+         .anySatisfy(row -> assertThat(row.getValueString("tableName")).isEqualToIgnoringCase("h2_probe"));
+      assertThat(DbPerfStore.query("db_perf_index_stat", DbPerfStore.eq("backendName", backend)))
+         .anySatisfy(row -> assertThat(row.getValueString("indexName")).isEqualToIgnoringCase("h2_probe_name"));
+
+      Map<String, String> results = new AnalyzeService(runtime).run(backend).stream().collect(Collectors.toMap(AnalyzeService.Result::ruleCode, r -> String.valueOf(r.error())));
+      assertThat(results).containsKeys("SLOW_QUERY", "DUPLICATE_INDEX", "IDLE_IN_TRANSACTION", "N_PLUS_ONE")
+         .doesNotContainKeys("UNUSED_INDEX", "MISSING_INDEX", "CACHE_HIT_LOW", "BLOAT", "VACUUM_STALE", "DEADLOCKS", "TEMP_SPILL", "POOL_SIZING");
+      assertThat(results.values()).containsOnly("null");
+
+      assertThat(new DbPerfWidgetRenderer().connectionsByApplication(runtime).getRows()).isNotEmpty();
+      assertThat(DbPerfStore.query("db_perf_table_stat", DbPerfStore.eq("backendName", backend))).allSatisfy(row -> assertThat(row.getValue("seqScanShare")).isNull());
+      assertThat(new DbPerfWidgetRenderer().tables(new DbPerformanceData(runtime)).getTableDataList().getFirst().getColumns()).extracting(c -> c.getHeader())
+         .containsExactly("Table", "Rows (estimate)", "Size MB");
+      assertThat(new DbPerfWidgetRenderer().connectionStatistics(new DbPerformanceData(runtime)).getStatisticsGroupData().getFirst().getStatisticList())
+         .extracting(statistic -> statistic.getLabel()).contains("Total connections", "Idle in transaction").doesNotContain("Maximum connections", "Cache hit %", "Deadlocks (24h)");
+      assertThat(new DbPerfWidgetRenderer().setup(runtime, new DbPerformanceData(runtime)).getRows()).extracting(row -> row.get("Check"))
+         .contains("H2 QUERY_STATISTICS", "H2 admin user").doesNotContain("pg_read_all_stats");
+
+      ExplainService explain = new ExplainService(runtime);
+      ExplainResult plan = explain.explain(new ExplainRequest(backend, null, "select * from h2_probe where name = ?", ExplainRequest.Mode.PLAN, List.of()));
+      assertThat(plan.mode()).isEqualTo("GENERIC");
+      assertThat(plan.planJson()).isNull();
+      assertThat(plan.planText()).containsIgnoringCase("h2_probe_name");
+      assertThat(plan.assistantPrompt()).contains("database query plan");
+      assertThatThrownBy(() -> explain.explain(new ExplainRequest(backend, null, "select * from h2_probe where name = $1", ExplainRequest.Mode.ANALYZE, List.of("secret-value"))))
+         .hasMessageContaining("ANALYZE is not available");
+      assertThatThrownBy(() -> explain.explain(new ExplainRequest(backend, null, "select file_write('x', '/tmp/p') from h2_probe", ExplainRequest.Mode.PLAN, List.of())))
+         .hasMessageContaining("FILE_WRITE");
+   }
+
+
+
+   /*******************************************************************************
+    ** Without QUERY_STATISTICS the snapshot is partial until the action runs.
+    *******************************************************************************/
+   @Test
+   void enableActionTurnsOnStatistics() throws Exception
+   {
+      DbPerfRuntime runtime = runtime("");
+      String backend = runtime.getConfig().getBackendName();
+      QRecord partial = new SnapshotCollector(runtime).collect(backend, true);
+      assertThat(partial.getValueString("status")).isEqualTo("PARTIAL");
+      assertThat(partial.getValueString("errorMessage")).contains("QUERY_STATISTICS");
+      assertThat(DbPerfStore.query("db_perf_table_stat", DbPerfStore.eq("backendName", backend))).isNotEmpty();
+
+      RunBackendStepOutput output = new RunBackendStepOutput();
+      new DbPerfEnableStatisticsStep().run(new RunBackendStepInput(), output);
+      assertThat(String.valueOf(output.getValue("processResults"))).contains("FULL");
+      assertThat(new DbPerfSettingsService(runtime).ensure(backend).getValueString("statsAccess")).isEqualTo("FULL");
+      workload(runtime);
+      assertThat(new SnapshotCollector(runtime).collect(backend, false).getValueString("status")).isEqualTo("OK");
+   }
+
+
+
+   /*******************************************************************************
+    ** QQQ runtime on a fresh H2 backend with the given URL options.
+    *******************************************************************************/
+   private static DbPerfRuntime runtime(String options) throws Exception
+   {
+      String name = "dbperfh2" + UUID.randomUUID().toString().replace("-", "");
+      RDBMSBackendMetaData backend = new RDBMSBackendMetaData().withName(name).withVendor("h2").withHostName("mem").withDatabaseName(name).withUsername("sa");
+      backend.setJdbcUrl("jdbc:h2:mem:" + name + ";CASE_INSENSITIVE_IDENTIFIERS=TRUE;DB_CLOSE_DELAY=-1;MODE=PostgreSQL" + options);
+      return (DbPerfRuntime.of(DbPerfTestSupport.instance(backend)));
+   }
+
+
+
+   /*******************************************************************************
+    ** A table with a duplicate-prone index and three identical lookups.
+    *******************************************************************************/
+   private static void workload(DbPerfRuntime runtime) throws Exception
+   {
+      RDBMSBackendMetaData backend = (RDBMSBackendMetaData) runtime.getInstance().getBackend(runtime.getConfig().getBackendName());
+      try(Connection connection = DriverManager.getConnection(backend.getJdbcUrl(), "sa", ""); Statement statement = connection.createStatement())
+      {
+         statement.execute("CREATE TABLE IF NOT EXISTS h2_probe (id INT PRIMARY KEY, name VARCHAR(40))");
+         statement.execute("CREATE INDEX IF NOT EXISTS h2_probe_name ON h2_probe (name)");
+         statement.execute("MERGE INTO h2_probe KEY (id) SELECT x, 'n' || x FROM SYSTEM_RANGE(1, 20)");
+         for(int i = 0; i < 3; i++)
+         {
+            statement.executeQuery("SELECT * FROM h2_probe WHERE name = 'n7'").close();
+         }
+      }
+   }
+}

src/test/java/com/kingsrook/qbits/dbperformance/H2StatsProviderTest.java

@@ -0,0 +1,366 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance;
+
+
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.CompletableFuture;
+import com.kingsrook.qbits.dbperformance.provider.ConnectionCount;
+import com.kingsrook.qbits.dbperformance.provider.DbStatsProviders;
+import com.kingsrook.qbits.dbperformance.provider.H2StatsProvider;
+import com.kingsrook.qbits.dbperformance.provider.IndexStats;
+import com.kingsrook.qbits.dbperformance.provider.PostgresStatsProvider;
+import com.kingsrook.qbits.dbperformance.provider.ProviderCapabilities;
+import com.kingsrook.qbits.dbperformance.provider.SessionInfo;
+import com.kingsrook.qbits.dbperformance.provider.StatementStats;
+import com.kingsrook.qbits.dbperformance.provider.StatsFeature;
+import com.kingsrook.qbits.dbperformance.provider.TableStats;
+import com.kingsrook.qbits.dbperformance.provider.UnsupportedStatsProvider;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** H2StatsProvider against real in-memory H2 databases: every read returns
+ ** rows produced by activity in the test, never fixtures.
+ *******************************************************************************/
+class H2StatsProviderTest
+{
+   private final H2StatsProvider provider = new H2StatsProvider();
+
+
+
+   /*******************************************************************************
+    ** The registry maps JDBC product names and saved names to providers.
+    *******************************************************************************/
+   @Test
+   void registryChoosesByProductName() throws Exception
+   {
+      assertThat(DbStatsProviders.forProductName("H2")).isInstanceOf(H2StatsProvider.class);
+      assertThat(DbStatsProviders.forProductName("PostgreSQL")).isInstanceOf(PostgresStatsProvider.class);
+      assertThat(DbStatsProviders.forProductName("MySQL")).isInstanceOf(UnsupportedStatsProvider.class);
+      assertThat(DbStatsProviders.forProductName(null)).isInstanceOf(UnsupportedStatsProvider.class);
+      assertThat(DbStatsProviders.forProviderName("H2")).isInstanceOf(H2StatsProvider.class);
+      assertThat(DbStatsProviders.forProviderName("POSTGRES")).isInstanceOf(PostgresStatsProvider.class);
+      assertThat(DbStatsProviders.forProviderName(null)).isInstanceOf(UnsupportedStatsProvider.class);
+      try(Connection connection = open(false, ""))
+      {
+         assertThat(DbStatsProviders.forConnection(connection)).isInstanceOf(H2StatsProvider.class);
+      }
+      assertThat(DbStatsProviders.forProductName("ExampleDB")).isInstanceOf(UnsupportedStatsProvider.class);
+      DbStatsProviders.register("ExampleDB", H2StatsProvider::new);
+      assertThat(DbStatsProviders.forProductName("exampledb")).isInstanceOf(H2StatsProvider.class);
+      assertThat(new UnsupportedStatsProvider().capabilities(null).features()).isEmpty();
+   }
+
+
+
+   /*******************************************************************************
+    ** Every read returns real rows after activity, in default and MySQL mode.
+    *******************************************************************************/
+   @ParameterizedTest
+   @ValueSource(strings = {"", ";MODE=MySQL", ";MODE=PostgreSQL;CASE_INSENSITIVE_IDENTIFIERS=TRUE"})
+   void readsReturnRealRowsAfterActivity(String mode) throws Exception
+   {
+      String url = url(true, mode);
+      try(Connection connection = DriverManager.getConnection(url, "sa", ""))
+      {
+         activity(connection);
+         ProviderCapabilities capabilities = provider.capabilities(connection);
+         assertThat(capabilities.supported()).isTrue();
+         assertThat(capabilities.statsAccess()).isEqualTo("FULL");
+         assertThat(capabilities.statements()).isTrue();
+         assertThat(capabilities.readAllStats()).isTrue();
+         assertThat(capabilities.version()).isGreaterThanOrEqualTo(2000000);
+         assertThat(capabilities.features()).contains(StatsFeature.STATEMENTS, StatsFeature.SESSIONS, StatsFeature.BLOCKING, StatsFeature.TABLE_ROWS, StatsFeature.EXPLAIN_TEXT)
+            .doesNotContain(StatsFeature.CACHE_COUNTERS, StatsFeature.DATABASE_COUNTERS, StatsFeature.INDEX_USAGE, StatsFeature.TABLE_MAINTENANCE, StatsFeature.MAX_CONNECTIONS, StatsFeature.EXPLAIN_JSON);
+         assertThat(provider.features()).containsAll(capabilities.features());
+
+         assertThat(provider.readDatabase(connection).counters()).isEmpty();
+         assertThat(provider.readDatabase(connection).maxConnections()).isZero();
+         assertThat(provider.readStatementResetInfo(connection).statsReset()).isNull();
+
+         provider.readTables(connection);
+         List<StatementStats> statements = provider.readStatements(connection);
+         StatementStats lookup = statements.stream().filter(s -> s.queryText().contains("WHERE customer_id = 3")).findFirst().orElseThrow();
+         assertThat(lookup.calls()).isEqualTo(5);
+         assertThat(lookup.rows()).isEqualTo(5 * 10);
+         assertThat(lookup.totalExecMs()).isGreaterThanOrEqualTo(lookup.maxExecMs());
+         assertThat(lookup.dbUser()).isNull();
+         assertThat(statements).noneMatch(s -> s.queryText().toUpperCase().contains("INFORMATION_SCHEMA") || s.queryText().contains("DB_PERF_PROBE")
+            || s.queryText().toUpperCase().startsWith("SET ") || s.queryText().contains("DISK_SPACE_USED") || s.queryText().equalsIgnoreCase("CALL DATABASE()"));
+         assertThat(provider.readStatements(connection)).anyMatch(s -> s.queryId() == lookup.queryId() && s.queryText().equals(lookup.queryText()));
+
+         TableStats orders = provider.readTables(connection).stream().filter(t -> t.tableName().equalsIgnoreCase("orders")).findFirst().orElseThrow();
+         assertThat(orders.counters()).containsEntry("nLiveTup", 50L).containsKeys("tableBytes", "totalBytes").doesNotContainKeys("seqScan", "nDeadTup");
+         assertThat(orders.relid()).isPositive();
+
+         List<IndexStats> indexes = provider.readIndexes(connection).stream().filter(i -> i.tableName().equalsIgnoreCase("orders")).toList();
+         assertThat(indexes).anySatisfy(i -> assertThat(i.primary() && i.unique()).isTrue());
+         assertThat(indexes).anySatisfy(i ->
+         {
+            assertThat(i.indexName()).isEqualToIgnoringCase("orders_status");
+            assertThat(i.unique()).isFalse();
+            assertThat(i.columns()).isEqualToIgnoringCase("status, created DESC");
+            assertThat(i.definition()).contains("CREATE INDEX").doesNotContain("USING CONSTRAINT");
+         });
+         assertThat(indexes).anySatisfy(i -> assertThat(i.definition()).contains("USING CONSTRAINT"));
+
+         try(Connection holder = DriverManager.getConnection(url, "sa", ""); Connection waiter = DriverManager.getConnection(url + ";LOCK_TIMEOUT=10000", "sa", ""))
+         {
+            holder.setAutoCommit(false);
+            try(Statement statement = holder.createStatement())
+            {
+               statement.executeUpdate("UPDATE orders SET status = 'HELD' WHERE id = 1");
+            }
+            CompletableFuture<Void> blocked = CompletableFuture.runAsync(() -> update(waiter));
+            List<SessionInfo> sessions = waitForBlocked(connection);
+            SessionInfo idle = sessions.stream().filter(s -> s.state().equals("idle in transaction")).findFirst().orElseThrow();
+            assertThat(idle.stateChange()).isNotNull();
+            assertThat(idle.xactSeconds()).isNotNull();
+            SessionInfo waiting = sessions.stream().filter(s -> !s.blockedBy().isEmpty()).findFirst().orElseThrow();
+            assertThat(waiting.state()).isEqualTo("active");
+            assertThat(waiting.waitEventType()).isEqualTo("Lock");
+            assertThat(waiting.blockedBy()).containsExactly(idle.pid());
+            assertThat(waiting.queryText()).contains("UPDATE orders");
+            assertThat(waiting.queryId()).isNotNull();
+            assertThat(waiting.querySeconds()).isNotNull();
+            assertThat(provider.readConnections(connection).stream().mapToInt(ConnectionCount::connectionCount).sum()).isGreaterThanOrEqualTo(3);
+            assertThat(provider.readConnections(connection)).anyMatch(c -> "idle in transaction".equals(c.state()));
+            holder.rollback();
+            blocked.get();
+         }
+
+         Map<String, String> settings = provider.readSettings(connection);
+         assertThat(settings).containsEntry("QUERY_STATISTICS", "TRUE").containsKey("info.VERSION");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Without QUERY_STATISTICS statements are unavailable until enabled.
+    *******************************************************************************/
+   @Test
+   void capabilitiesWithoutQueryStatisticsAndEnable() throws Exception
+   {
+      try(Connection connection = open(false, ""))
+      {
+         activity(connection);
+         ProviderCapabilities off = provider.capabilities(connection);
+         assertThat(off.supported()).isTrue();
+         assertThat(off.statements()).isFalse();
+         assertThat(off.statsAccess()).isEqualTo("NO_QUERY_STATISTICS");
+         assertThat(off.message()).contains("QUERY_STATISTICS=TRUE");
+         assertThat(off.has(StatsFeature.STATEMENTS)).isFalse();
+         assertThat(off.has(StatsFeature.SESSIONS)).isTrue();
+         assertThat(provider.readStatements(connection)).isEmpty();
+         assertThat(provider.readTables(connection)).isNotEmpty();
+         assertThat(provider.readSettings(connection)).containsEntry("QUERY_STATISTICS", "FALSE");
+
+         assertThat(provider.enableStatementStatistics(connection)).contains("JDBC URL");
+         activity(connection);
+         ProviderCapabilities on = provider.capabilities(connection);
+         assertThat(on.statsAccess()).isEqualTo("FULL");
+         assertThat(on.has(StatsFeature.STATEMENTS)).isTrue();
+         assertThat(provider.readStatements(connection)).anyMatch(s -> s.queryText().contains("WHERE customer_id = 3") && s.calls() == 5);
+         assertThat(provider.enableStatementStatistics(connection)).contains("already on");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** A non-admin user sees only its own session and cannot enable statistics.
+    *******************************************************************************/
+   @Test
+   void nonAdminUser() throws Exception
+   {
+      String url = url(true, "");
+      try(Connection admin = DriverManager.getConnection(url, "sa", ""))
+      {
+         try(Statement statement = admin.createStatement())
+         {
+            statement.execute("CREATE USER app PASSWORD 'secret'");
+            statement.execute("CREATE TABLE probe (id INT PRIMARY KEY)");
+            statement.execute("GRANT SELECT ON probe TO app");
+         }
+         try(Connection app = DriverManager.getConnection(url.replace(";DB_CLOSE_DELAY=-1", "").replace(";QUERY_STATISTICS=TRUE", ""), "app", "secret"))
+         {
+            ProviderCapabilities capabilities = provider.capabilities(app);
+            assertThat(capabilities.statsAccess()).isEqualTo("NOT_ADMIN");
+            assertThat(capabilities.readAllStats()).isFalse();
+            assertThat(capabilities.statements()).isTrue();
+            assertThat(capabilities.has(StatsFeature.BLOCKING)).isFalse();
+            assertThat(provider.readSessions(app)).isEmpty();
+            assertThat(provider.remedy("NOT_ADMIN", "APP")).contains("ALTER USER APP ADMIN TRUE");
+            try(Statement statement = admin.createStatement())
+            {
+               statement.execute("SET QUERY_STATISTICS FALSE");
+            }
+            assertThatThrownBy(() -> provider.enableStatementStatistics(app)).isInstanceOf(SQLException.class);
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** EXPLAIN plans without executing; ANALYZE only for a non-admin SELECT;
+    ** side-effecting functions, aliases, DDL and multiple statements refused.
+    *******************************************************************************/
+   @Test
+   void explainText() throws Exception
+   {
+      String url = url(true, ";MODE=MySQL");
+      try(Connection connection = DriverManager.getConnection(url, "sa", ""))
+      {
+         activity(connection);
+         assertThat(provider.capabilities(connection).has(StatsFeature.EXPLAIN_ANALYZE)).isFalse();
+         assertThat(provider.capabilities(connection).has(StatsFeature.EXPLAIN_TEXT)).isTrue();
+         assertThat(provider.explainText(connection, "SELECT * FROM orders WHERE status = 'NEW'", List.of(), false, 5000)).containsIgnoringCase("orders_status").doesNotContain("scanCount");
+         assertThat(provider.explainText(connection, "SELECT * FROM orders WHERE customer_id = ?1", List.of(), false, 5000)).contains("?1");
+         assertThat(connection.getAutoCommit()).isTrue();
+         assertThat(connection.isReadOnly()).isFalse();
+         assertThatThrownBy(() -> provider.explainText(connection, "SELECT * FROM orders WHERE customer_id = ?1", List.of("3"), true, 5000)).hasMessageContaining("admin");
+         assertThatThrownBy(() -> provider.explainText(connection, "SELECT FILE_WRITE('x', '/tmp/dbperf-h2-explain-probe') FROM orders", List.of(), false, 5000)).hasMessageContaining("FILE_WRITE");
+         assertThatThrownBy(() -> provider.explainText(connection, "SELECT \"file_write\"('x', '/tmp/p')", List.of(), false, 5000)).hasMessageContaining("FILE_WRITE");
+         assertThatThrownBy(() -> provider.explainText(connection, "DROP TABLE orders", List.of(), false, 5000)).hasMessageContaining("DROP");
+         assertThatThrownBy(() -> provider.explainText(connection, "SELECT 1; SELECT 2", List.of(), false, 5000)).hasMessageContaining("one statement");
+         assertThat(provider.explainText(connection, "SELECT 'drop; file_write' AS label FROM orders", List.of(), false, 5000)).containsIgnoringCase("orders");
+         try(Statement statement = connection.createStatement())
+         {
+            statement.execute("CREATE ALIAS my_side_effect FOR \"java.lang.System.nanoTime\"");
+            statement.execute("CREATE USER reader PASSWORD 'secret'");
+            statement.execute("GRANT SELECT ON orders TO reader");
+         }
+         assertThatThrownBy(() -> provider.explainText(connection, "SELECT my_side_effect() FROM orders", List.of(), false, 5000)).hasMessageContaining("MY_SIDE_EFFECT");
+         try(Connection reader = DriverManager.getConnection(url.replace(";DB_CLOSE_DELAY=-1", "").replace(";QUERY_STATISTICS=TRUE", ""), "reader", "secret"))
+         {
+            assertThat(provider.capabilities(reader).has(StatsFeature.EXPLAIN_ANALYZE)).isTrue();
+            assertThat(provider.explainText(reader, "SELECT * FROM orders WHERE customer_id = ?1", List.of("3"), true, 5000)).contains("scanCount");
+            assertThatThrownBy(() -> provider.explainText(reader, "VALUES (1)", List.of(), true, 5000)).hasMessageContaining("single SELECT");
+         }
+      }
+      assertThat(java.nio.file.Files.exists(java.nio.file.Path.of("/tmp/dbperf-h2-explain-probe"))).isFalse();
+   }
+
+
+
+   /*******************************************************************************
+    ** H2 session states use PostgreSQL's names.
+    *******************************************************************************/
+   @Test
+   void stateMapping() throws Exception
+   {
+      assertThat(provider.setupChecks("NO_QUERY_STATISTICS", "m")).extracting(c -> c.check()).containsExactly("H2 QUERY_STATISTICS", "H2 admin user");
+      assertThat(provider.remedy("FULL", "sa")).isEqualTo("Full statistics access");
+      assertThat(provider.remedy("UNSUPPORTED", "sa")).contains("H2 2.0");
+      assertThat(new PostgresStatsProvider().remedy("NO_READ_ALL_STATS", "sa")).isEqualTo("grant pg_read_all_stats to sa");
+      assertThat(new PostgresStatsProvider().setupChecks("FULL", null)).extracting(c -> c.check()).containsExactly("pg_stat_statements", "pg_read_all_stats");
+   }
+
+
+
+   /*******************************************************************************
+    ** Tables, a secondary index, a foreign key and repeated queries.
+    *******************************************************************************/
+   private static void activity(Connection connection) throws SQLException
+   {
+      try(Statement statement = connection.createStatement())
+      {
+         statement.execute("CREATE TABLE IF NOT EXISTS customer (id INT PRIMARY KEY, name VARCHAR(50))");
+         statement.execute("CREATE TABLE IF NOT EXISTS orders (id INT PRIMARY KEY, customer_id INT REFERENCES customer(id), status VARCHAR(20), created TIMESTAMP)");
+         statement.execute("CREATE INDEX IF NOT EXISTS orders_status ON orders (status, created DESC)");
+         statement.execute("MERGE INTO customer KEY (id) SELECT x, 'c' || x FROM SYSTEM_RANGE(1, 5)");
+         statement.execute("MERGE INTO orders KEY (id) SELECT x, MOD(x, 5) + 1, 'NEW', CURRENT_TIMESTAMP FROM SYSTEM_RANGE(1, 50)");
+         for(int i = 0; i < 5; i++)
+         {
+            statement.executeQuery("SELECT * FROM orders WHERE customer_id = 3").close();
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Poll until the waiter shows as blocked.
+    *******************************************************************************/
+   private List<SessionInfo> waitForBlocked(Connection connection) throws Exception
+   {
+      for(int i = 0; i < 100; i++)
+      {
+         List<SessionInfo> sessions = provider.readSessions(connection);
+         if(sessions.stream().anyMatch(s -> !s.blockedBy().isEmpty()))
+         {
+            return (sessions);
+         }
+         Thread.sleep(50);
+      }
+      throw (new AssertionError("no blocked session observed"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Blocking update for the waiter thread.
+    *******************************************************************************/
+   private static void update(Connection waiter)
+   {
+      try(Statement statement = waiter.createStatement())
+      {
+         statement.executeUpdate("UPDATE orders SET status = 'WAIT' WHERE id = 1");
+      }
+      catch(SQLException e)
+      {
+         throw (new IllegalStateException(e));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** A fresh in-memory database.
+    *******************************************************************************/
+   private static Connection open(boolean statistics, String mode) throws SQLException
+   {
+      return (DriverManager.getConnection(url(statistics, mode), "sa", ""));
+   }
+
+
+
+   /*******************************************************************************
+    ** URL of a fresh in-memory database.
+    *******************************************************************************/
+   private static String url(boolean statistics, String mode)
+   {
+      return ("jdbc:h2:mem:h2stats" + UUID.randomUUID().toString().replace("-", "") + ";DB_CLOSE_DELAY=-1" + (statistics ? ";QUERY_STATISTICS=TRUE" : "") + mode);
+   }
+}

src/test/java/com/kingsrook/qbits/dbperformance/RollupRetentionTest.java

@@ -112,6 +112,9 @@ class RollupRetentionTest
       }
       rows.add(new QRecord().withValue("windowStart", now.minusSeconds(2 * 86400)).withValue("unitName", "boundary"));
       DbPerfStore.insert("db_perf_attribution", rows);
+      DbPerfStore.insert("db_perf_repeat_pattern", List.of(
+         new QRecord().withValue("windowStart", now.minusSeconds(3 * 86400)),
+         new QRecord().withValue("windowStart", now.minusSeconds(2 * 86400))));
       DbPerfStore.insert("db_perf_attribution_daily", List.of(new QRecord().withValue("day", LocalDate.of(2026, 9, 20)).withValue("rollupKey", "old")));
       int rule = DbPerfStore.query("db_perf_rule", new QQueryFilter()).getFirst().getValueInteger("id");
       List<QRecord> findings = new ArrayList<>();
@@ -121,8 +124,9 @@ class RollupRetentionTest
       }
       DbPerfStore.insert("db_perf_finding", findings);
       RetentionService retention = new RetentionService(runtime, Clock.fixed(now, ZoneOffset.UTC));
-      assertThat(retention.purge()).isEqualTo(1008);
+      assertThat(retention.purge()).isEqualTo(1009);
       assertThat(retention.purge()).isZero();
+      assertThat(DbPerfStore.query("db_perf_repeat_pattern", new QQueryFilter())).hasSize(1);
       assertThat(DbPerfStore.query("db_perf_attribution", new QQueryFilter())).singleElement().satisfies(row -> assertThat(row.getValueString("unitName")).isEqualTo("boundary"));
       assertThat(DbPerfStore.query("db_perf_finding", new QQueryFilter())).extracting(row -> row.getValueString("status")).containsExactlyInAnyOrder("OPEN", "ACKNOWLEDGED");
    }

src/test/java/com/kingsrook/qbits/dbperformance/SnapshotCollectorTest.java

@@ -28,6 +28,7 @@ import java.util.List;
 import com.kingsrook.qbits.dbperformance.collect.DbPerfSettingsService;
 import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
 import com.kingsrook.qbits.dbperformance.collect.SnapshotCollector;
+import com.kingsrook.qbits.dbperformance.provider.UnsupportedStatsProvider;
 import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
@@ -123,6 +124,37 @@ class SnapshotCollectorTest
    }
 
 
+   /*******************************************************************************
+    ** An Error (not just an Exception) still closes the run as FAILED, and runs
+    ** left RUNNING by an earlier crash are closed once they are stale.
+    *******************************************************************************/
+   @Test
+   void errorsAndAbandonedRuns() throws Exception
+   {
+      QInstance             instance = DbPerfTestSupport.instance();
+      DbPerfRuntime         runtime  = DbPerfRuntime.of(instance);
+      DbPerfFixtureProvider provider = new DbPerfFixtureProvider();
+      runtime.asSystem(() -> DbPerfStore.insert("db_perf_snapshot", List.of(new QRecord().withValue("backendName", runtime.getConfig().getBackendName())
+         .withValue("capturedAt", DbPerfFixtureProvider.START.minusSeconds(3600)).withValue("status", "RUNNING"))));
+
+      provider.error = new StackOverflowError();
+      QRecord failed = collect(runtime, provider, 0, true);
+      assertThat(failed.getValueString("status")).isEqualTo("FAILED");
+      assertThat(failed.getValueString("errorMessage")).contains("StackOverflowError");
+      runtime.asSystem(() ->
+      {
+         List<QRecord> rows = DbPerfStore.query("db_perf_snapshot", new QQueryFilter());
+         assertThat(rows).hasSize(2).allSatisfy(row -> assertThat(row.getValueString("status")).isEqualTo("FAILED"));
+         assertThat(rows).anySatisfy(row -> assertThat(row.getValueString("errorMessage")).contains("did not finish"));
+         return (null);
+      });
+
+      provider.error = null;
+      assertThat(collect(runtime, provider, 300, true).getValueString("status")).isEqualTo("OK");
+   }
+
+
+
    /*******************************************************************************
     ** H2 remains usable and explicitly unsupported by the production selector.
     *******************************************************************************/
@@ -130,9 +162,17 @@ class SnapshotCollectorTest
    void unsupportedVendor() throws Exception
    {
       DbPerfRuntime runtime = DbPerfRuntime.of(DbPerfTestSupport.instance());
-      QRecord snapshot = new SnapshotCollector(runtime).collect(runtime.getConfig().getBackendName(), false);
+      QRecord snapshot = new SnapshotCollector(runtime, Clock.systemUTC(), new UnsupportedStatsProvider()).collect(runtime.getConfig().getBackendName(), false);
       assertThat(snapshot.getValueString("status")).isEqualTo("PARTIAL");
       assertThat(snapshot.getValueString("errorMessage")).contains("not supported");
+
+      //////////////////////////////////////////////////////////////////////
+      // the H2 test backend itself is supported, partially without      //
+      // QUERY_STATISTICS                                                 //
+      //////////////////////////////////////////////////////////////////////
+      QRecord h2 = new SnapshotCollector(runtime).collect(runtime.getConfig().getBackendName(), false);
+      assertThat(h2.getValueString("status")).isEqualTo("PARTIAL");
+      assertThat(h2.getValueString("errorMessage")).contains("QUERY_STATISTICS");
    }
 
 

src/test/java/com/kingsrook/qbits/dbperformance/SqlNormalizerTest.java

@@ -86,6 +86,14 @@ class SqlNormalizerTest
       assertThat(SqlNormalizer.mainTable("select 1")).isNull();
       assertThat(SqlNormalizer.normalize("select \"in ( ? , ? )\" from t")).isEqualTo("select \"in ( ? , ? )\" from t");
       assertThat(SqlNormalizer.normalize(null)).isEmpty();
+      ///////////////////////////////////////////////////////////////////////
+      // huge lists (production had 60 KB statements) must not overflow    //
+      ///////////////////////////////////////////////////////////////////////
+      String hugeIn = "select * from t where id in (" + "$1, ".repeat(20000) + "$1)";
+      assertThat(SqlNormalizer.normalize(hugeIn)).isEqualTo("select * from t where id in ( ? )");
+      String hugeValues = "insert into t (a, b) values " + "($1, $2), ".repeat(20000) + "($1, $2)";
+      assertThat(SqlNormalizer.normalize(hugeValues)).isEqualTo("insert into t ( a , b ) values ( ? , ? )");
+      assertThat(SqlNormalizer.normalize("select * from t where id in (1, x)")).isEqualTo("select * from t where id in ( ? , x )");
       assertThat(SqlNormalizer.normalize(" ")).isEmpty();
       assertThat(SqlNormalizer.normalize("select " + "field, ".repeat(5000))).hasSize(10000);
    }

src/test/java/com/kingsrook/qbits/dbperformance/alerts/SpikeHistoryBoundedTest.java

@@ -0,0 +1,135 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance.alerts;
+
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicInteger;
+import com.kingsrook.qbits.dbperformance.DbPerfRuntime;
+import com.kingsrook.qbits.dbperformance.DbPerfTestSupport;
+import com.kingsrook.qbits.dbperformance.analyze.RuleContext;
+import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizerInterface;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizers;
+import com.kingsrook.qqq.backend.core.model.actions.tables.QueryOrGetInputInterface;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Spike detection reads seven days of query snapshots (~230,000 rows in kof22)
+ ** on every evaluation. It must page them and keep only per-statement numbers.
+ *******************************************************************************/
+class SpikeHistoryBoundedTest
+{
+   private static final AtomicInteger MAX_PAGE = new AtomicInteger();
+   private static final AtomicInteger LOADED   = new AtomicInteger();
+
+
+
+   /*******************************************************************************
+    ** Records the largest page QQQ hands back.
+    *******************************************************************************/
+   public static class CountingCustomizer implements TableCustomizerInterface
+   {
+      /***************************************************************************
+       ** Count, change nothing.
+       ***************************************************************************/
+      @Override
+      public List<QRecord> postQuery(QueryOrGetInputInterface queryInput, List<QRecord> records)
+      {
+         LOADED.addAndGet(records.size());
+         MAX_PAGE.accumulateAndGet(records.size(), Math::max);
+         return (records);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** 2,500 samples across page boundaries: pages stay at BATCH_SIZE, invalid
+    ** snapshots and the window are honored, the current interval is found.
+    *******************************************************************************/
+   @Test
+   void historyIsPagedAndExact() throws Exception
+   {
+      DbPerfRuntime runtime = DbPerfRuntime.of(DbPerfTestSupport.instance());
+      String backend = runtime.getConfig().getBackendName();
+      runtime.getInstance().getTable("db_perf_query_snapshot").withCustomizer(TableCustomizers.POST_QUERY_RECORD, new QCodeReference(CountingCustomizer.class));
+      Instant now = Instant.parse("2026-10-16T20:00:00Z");
+
+      QRecord ok = DbPerfStore.insert("db_perf_snapshot", List.of(new QRecord().withValue("backendName", backend).withValue("capturedAt", now.minusSeconds(3600)).withValue("status", "OK"))).getFirst();
+      QRecord failed = DbPerfStore.insert("db_perf_snapshot", List.of(new QRecord().withValue("backendName", backend).withValue("capturedAt", now.minusSeconds(1800)).withValue("status", "FAILED"))).getFirst();
+      QRecord current = DbPerfStore.insert("db_perf_snapshot", List.of(new QRecord().withValue("backendName", backend).withValue("capturedAt", now).withValue("status", "OK"))).getFirst();
+
+      int one = statement(backend, 1L);
+      int two = statement(backend, 2L);
+      List<QRecord> rows = new ArrayList<>();
+      for(int i = 0; i < 2500; i++)
+      {
+         rows.add(sample(ok, i % 2 == 0 ? one : two, now.minusSeconds(3600 + i), i));
+      }
+      rows.add(sample(failed, one, now.minusSeconds(1800), 999999));
+      rows.add(sample(ok, one, now.minusSeconds(8 * 86400L), 999999));
+      rows.add(sample(current, one, now, 42));
+      DbPerfStore.insert("db_perf_query_snapshot", rows);
+      MAX_PAGE.set(0);
+      LOADED.set(0);
+
+      RuleContext ctx = new RuleContext(runtime, backend, new QRecord(), DbPerfStore.first("db_perf_settings", new com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter()), now);
+      Map<Integer, SnapshotEvaluator.StatementHistory> history = SnapshotEvaluator.history(ctx, current.getValueInteger("id"));
+
+      assertThat(MAX_PAGE.get()).as("largest page of query snapshots held at once").isLessThanOrEqualTo(DbPerfStore.BATCH_SIZE);
+      assertThat(history.get(one).sortedPrevious()).hasSize(1250).doesNotContain(999999.0);
+      assertThat(history.get(two).sortedPrevious()).hasSize(1250);
+      assertThat(history.get(one).sortedPrevious()[0]).isEqualTo(0.0);
+      assertThat(history.get(one)).extracting("current").isEqualTo(42.0);
+      assertThat(history.get(two)).extracting("current").isNull();
+   }
+
+
+
+   /*******************************************************************************
+    ** One statement identity; returns its id.
+    *******************************************************************************/
+   private static int statement(String backend, long queryId) throws Exception
+   {
+      return (DbPerfStore.insert("db_perf_statement", List.of(new QRecord().withValue("backendName", backend).withValue("queryId", queryId)
+         .withValue("queryText", "select " + queryId).withValue("fingerprint", String.valueOf(queryId).repeat(64).substring(0, 64)))).getFirst().getValueInteger("id"));
+   }
+
+
+
+   /*******************************************************************************
+    ** One query snapshot row.
+    *******************************************************************************/
+   private static QRecord sample(QRecord snapshot, int statementId, Instant at, int totalMs)
+   {
+      return (new QRecord().withValue("snapshotId", snapshot.getValueInteger("id")).withValue("statementId", statementId)
+         .withValue("capturedAt", at).withValue("totalMs", BigDecimal.valueOf(totalMs)));
+   }
+}

src/test/java/com/kingsrook/qbits/dbperformance/attribution/AttributionTest.java

@@ -0,0 +1,664 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.dbperformance.attribution;
+
+
+import java.math.BigDecimal;
+import java.sql.DriverManager;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.ZoneOffset;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+import com.kingsrook.qbits.dbperformance.DbPerfRuntime;
+import com.kingsrook.qbits.dbperformance.DbPerfTestSupport;
+import com.kingsrook.qbits.dbperformance.collect.DbPerfStore;
+import com.kingsrook.qbits.dbperformance.collect.RollupService;
+import com.kingsrook.qbits.dbperformance.metadata.DbPerfWriteGuard;
+import com.kingsrook.qbits.dbperformance.normalize.SqlNormalizer;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizers;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.instrumentation.StatementExecution;
+import com.kingsrook.qqq.backend.core.instrumentation.StatementExecutionListener;
+import com.kingsrook.qqq.backend.core.instrumentation.StatementExecutionListeners;
+import com.kingsrook.qqq.backend.core.instrumentation.StatementOperation;
+import com.kingsrook.qqq.backend.core.instrumentation.UnitOfWork;
+import com.kingsrook.qqq.backend.core.instrumentation.UnitOfWorkKind;
+import com.kingsrook.qqq.backend.core.instrumentation.UnitsOfWork;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSBackendMetaData;
+import com.kingsrook.qqq.backend.module.rdbms.model.metadata.RDBMSTableBackendDetails;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Real QQQ RDBMS hooks, persistence, bounded counters, and lifecycle contracts.
+ *******************************************************************************/
+class AttributionTest
+{
+   private DbPerfRuntime runtime;
+   private AttributionFlusher flusher;
+   private AttributionListener listener;
+   private QRecord settings;
+
+
+   /*******************************************************************************
+    ** A real business table, separate from the self-suppressed db_perf tables.
+    *******************************************************************************/
+   @BeforeEach
+   void setUp() throws Exception
+   {
+      QInstance instance = DbPerfTestSupport.instance();
+      runtime = DbPerfRuntime.of(instance);
+      RDBMSBackendMetaData backend = (RDBMSBackendMetaData) instance.getBackend(runtime.getConfig().getBackendName());
+      instance.addTable(new QTableMetaData().withName("business").withBackendName(backend.getName()).withPrimaryKeyField("id")
+         .withBackendDetails(new RDBMSTableBackendDetails().withTableName("business"))
+         .withField(new QFieldMetaData("id", QFieldType.INTEGER)).withField(new QFieldMetaData("name", QFieldType.STRING)));
+      try(var connection = DriverManager.getConnection(backend.getJdbcUrl(), backend.getUsername(), backend.getPassword()); var statement = connection.createStatement())
+      {
+         statement.execute("CREATE TABLE business (id INT PRIMARY KEY, name VARCHAR(100))");
+         statement.execute("INSERT INTO business VALUES (1, 'example')");
+      }
+      flusher = new AttributionFlusher(runtime);
+      flusher.refreshSettings();
+      listener = flusher.getListener();
+      settings = DbPerfStore.query("db_perf_settings", new QQueryFilter()).getFirst();
+      StatementExecutionListeners.register(listener);
+   }
+
+
+   /*******************************************************************************
+    ** No listener, scope, suppression or runtime may escape a test.
+    *******************************************************************************/
+   @AfterEach
+   void tearDown()
+   {
+      StatementExecutionListeners.unregister(listener);
+      flusher.close();
+      runtime.stopAttribution();
+      UnitsOfWork.reset();
+      AttributionListener.suppress(false);
+      QContext.clear();
+   }
+
+
+   /*******************************************************************************
+    ** The core hook attributes real queries and reads final HTTP route names.
+    *******************************************************************************/
+   @Test
+   void realQueriesAndFinalNames() throws Exception
+   {
+      try(var scope = UnitsOfWork.begin(UnitOfWorkKind.SCHEDULED_JOB, "job"))
+      {
+         query(2);
+      }
+      try(var scope = UnitsOfWork.begin(UnitOfWorkKind.HTTP_REQUEST, "unresolved"))
+      {
+         query(1);
+         scope.getUnitOfWork().setName("GET /things/{id}");
+      }
+      query(1);
+      flusher.flushNow();
+      List<QRecord> rows = rows("db_perf_attribution");
+      assertThat(rows).hasSize(3);
+      assertThat(rows).extracting(row -> row.getValueString("unitName")).containsExactlyInAnyOrder("job", "GET /things/{id}", "(none)");
+      QRecord job = named(rows, "job");
+      assertThat(job.getValueString("unitKind")).isEqualTo("SCHEDULED_JOB");
+      assertThat(job.getValueLong("units")).isEqualTo(1);
+      assertThat(job.getValueLong("statements")).isEqualTo(2);
+      assertThat(job.getValueLong("rowsCount")).isEqualTo(2);
+      assertThat(job.getValueString("operation")).isEqualTo("QUERY");
+      assertThat(job.getValueString("tableName")).isEqualTo("business");
+      assertThat(job.getValueString("fingerprint")).isEqualTo(SqlNormalizer.fingerprint(job.getValueString("sqlText")));
+      assertThat(named(rows, "(none)").getValueString("unitKind")).isEqualTo("OTHER");
+   }
+
+
+   /*******************************************************************************
+    ** The threshold applies to each unit, and each window uses one batch/table.
+    *******************************************************************************/
+   @Test
+   void repeatPatternsBatchesAndSelfSuppression() throws Exception
+   {
+      AtomicInteger attributionInserts = new AtomicInteger();
+      AtomicInteger repeatInserts = new AtomicInteger();
+      StatementExecutionListener observer = execution ->
+      {
+         if(execution.operation() == StatementOperation.INSERT)
+         {
+            if("db_perf_attribution".equals(execution.tableName()))
+            {
+               attributionInserts.incrementAndGet();
+            }
+            if("db_perf_repeat_pattern".equals(execution.tableName()))
+            {
+               repeatInserts.incrementAndGet();
+            }
+         }
+      };
+      StatementExecutionListeners.register(observer);
+      try
+      {
+         for(int count : List.of(12, 5))
+         {
+            try(var scope = UnitsOfWork.begin(UnitOfWorkKind.SCHEDULED_JOB, "job"))
+            {
+               query(count);
+            }
+         }
+         rows("db_perf_settings");
+         flusher.flushNow();
+         QRecord repeated = rows("db_perf_repeat_pattern").getFirst();
+         assertThat(repeated.getValueLong("unitsAffected")).isEqualTo(1);
+         assertThat(repeated.getValueInteger("maxRepeats")).isEqualTo(12);
+         assertThat(repeated.getValueLong("totalRepeats")).isEqualTo(12);
+         assertThat(repeated.getValueBigDecimal("sampleRate")).isEqualByComparingTo("1");
+         assertThat(rows("db_perf_repeat_pattern")).hasSize(1);
+         assertThat(rows("db_perf_attribution")).singleElement().satisfies(row ->
+         {
+            assertThat(row.getValueLong("units")).isEqualTo(2);
+            assertThat(row.getValueLong("statements")).isEqualTo(17);
+         });
+         flusher.flushNow();
+         assertThat(attributionInserts).hasValue(1);
+         assertThat(repeatInserts).hasValue(1);
+         assertThat(listener.drain(Instant.now()).attribution()).isEmpty();
+      }
+      finally
+      {
+         StatementExecutionListeners.unregister(observer);
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Both runtime switches and sample zero take effect through cached settings.
+    *******************************************************************************/
+   @Test
+   void disabledSamplingAndFilters() throws Exception
+   {
+      settings.withValue("attributionSampleRate", BigDecimal.ZERO);
+      refresh();
+      query(1);
+      try(var scope = UnitsOfWork.begin(UnitOfWorkKind.PROCESS, "zero"))
+      {
+         query(1);
+      }
+      assertThat(listener.drain(Instant.now()).attribution()).isEmpty();
+      settings.withValue("attributionSampleRate", BigDecimal.ONE).withValue("attributionEnabled", false);
+      refresh();
+      query(1);
+      assertThat(listener.drain(Instant.now()).attribution()).isEmpty();
+      settings.withValue("attributionEnabled", true);
+      refresh();
+      runtime.getConfig().setAttributionEnabled(false);
+      query(1);
+      runtime.getConfig().setAttributionEnabled(true);
+      listener.onStatement(new StatementExecution("wrong", "business", StatementOperation.QUERY, "select ?", 1, 1, true, null, null));
+      AttributionListener.suppress(true);
+      query(1);
+      AttributionListener.suppress(false);
+      rows("db_perf_settings");
+      assertThat(listener.drain(Instant.now()).attribution()).isEmpty();
+      query(1);
+      assertThat(listener.drain(Instant.now()).attribution()).hasSize(1);
+   }
+
+
+   /*******************************************************************************
+    ** The cap includes the overflow bucket; a unit counts only once in it.
+    *******************************************************************************/
+   @Test
+   void overflowAndRepeatBounds() throws Exception
+   {
+      settings.withValue("attributionMaxKeys", 2).withValue("nPlusOneThreshold", 2);
+      refresh();
+      try(var scope = UnitsOfWork.begin(UnitOfWorkKind.PROCESS, "many-shapes"))
+      {
+         for(int i = 0; i < 8; i++)
+         {
+            synthetic("select column_" + i + " from business", 1, true, scope.getUnitOfWork());
+         }
+      }
+      for(int i = 0; i < 8; i++)
+      {
+         try(var scope = UnitsOfWork.begin(UnitOfWorkKind.PROCESS, "job_" + i))
+         {
+            synthetic("select column_" + i + " from business", 1, true, scope.getUnitOfWork());
+            synthetic("select column_" + i + " from business", 1, true, scope.getUnitOfWork());
+         }
+      }
+      flusher.flushNow();
+      assertThat(rows("db_perf_attribution")).hasSize(2);
+      assertThat(named(rows("db_perf_attribution"), "(other)").getValueLong("units")).isEqualTo(9);
+      assertThat(rows("db_perf_attribution").stream().mapToLong(row -> row.getValueLong("statements")).sum()).isEqualTo(24);
+      assertThat(rows("db_perf_repeat_pattern")).hasSize(2);
+      assertThat(named(rows("db_perf_repeat_pattern"), "(other)").getValueString("fingerprint")).isEqualTo(SqlNormalizer.fingerprint("(other)"));
+   }
+
+
+   /*******************************************************************************
+    ** Counters, normalization, null rows, process fallback, and text bounds.
+    *******************************************************************************/
+   @Test
+   void syntheticCountersAndSqlSafety()
+   {
+      String sql = "select 'secret', 123 from business where id in (?, ?, ?)";
+      synthetic(sql, 2000000, true, null);
+      synthetic(sql, 5000000, false, null);
+      listener.onStatement(new StatementExecution(runtime.getConfig().getBackendName(), null, null, null, 10, null, true, null, "process"));
+      flusher.flushNow();
+      List<QRecord> rows = rows("db_perf_attribution");
+      QRecord row = named(rows, "(none)");
+      assertThat(row.getValueBigDecimal("totalMs")).isEqualByComparingTo("7");
+      assertThat(row.getValueBigDecimal("maxMs")).isEqualByComparingTo("5");
+      assertThat(row.getValueLong("errors")).isEqualTo(1);
+      assertThat(row.getValueLong("rowsCount")).isEqualTo(2);
+      assertThat(row.getValueString("sqlText")).doesNotContain("secret", "123");
+      assertThat(named(rows, "process").getValueString("unitKind")).isEqualTo("OTHER");
+      synthetic("select " + "identifier".repeat(600) + " from business", 1, true, null);
+      flusher.flushNow();
+      assertThat(rows("db_perf_attribution")).anySatisfy(value -> assertThat(value.getValueString("sqlText")).hasSize(4000));
+   }
+
+
+   /*******************************************************************************
+    ** An abandoned unit is merged when another unit arrives on that worker.
+    *******************************************************************************/
+   @Test
+   void defensiveUnitTransitionAndWindowBoundary() throws Exception
+   {
+      var abandoned = UnitsOfWork.begin(UnitOfWorkKind.PROCESS, "abandoned");
+      query(1);
+      UnitsOfWork.reset();
+      try(var scope = UnitsOfWork.begin(UnitOfWorkKind.HTTP_REQUEST, "initial"))
+      {
+         query(1);
+         flusher.flushNow();
+         assertThat(rows("db_perf_attribution")).singleElement().satisfies(row -> assertThat(row.getValueString("unitName")).isEqualTo("abandoned"));
+         scope.getUnitOfWork().setName("final");
+         query(1);
+      }
+      abandoned.close();
+      flusher.flushNow();
+      assertThat(named(rows("db_perf_attribution"), "final").getValueLong("statements")).isEqualTo(2);
+   }
+
+
+   /*******************************************************************************
+    ** Each sampled unit contributes all statements, including across a refresh.
+    *******************************************************************************/
+   @Test
+   void samplingIsPerUnit() throws Exception
+   {
+      settings.withValue("attributionSampleRate", new BigDecimal("0.5"));
+      refresh();
+      for(int i = 0; i < 100; i++)
+      {
+         try(var scope = UnitsOfWork.begin(UnitOfWorkKind.PROCESS, "sample_" + i))
+         {
+            for(int j = 0; j < 3; j++)
+            {
+               synthetic("select ?", 1, true, scope.getUnitOfWork());
+            }
+         }
+      }
+      var window = listener.drain(Instant.now());
+      assertThat(window.attribution().size()).isBetween(20, 80);
+      assertThat(window.attribution().values()).allSatisfy(counts -> assertThat(counts.statements.sum()).isEqualTo(3));
+   }
+
+
+   /*******************************************************************************
+    ** An in-flight unit keeps its sampling decision and original rate annotation.
+    *******************************************************************************/
+   @Test
+   void samplingRefreshDuringUnit() throws Exception
+   {
+      try(var scope = UnitsOfWork.begin(UnitOfWorkKind.PROCESS, "in-flight"))
+      {
+         query(1);
+         settings.withValue("attributionSampleRate", BigDecimal.ZERO);
+         refresh();
+         query(1);
+      }
+      query(1);
+      flusher.flushNow();
+      assertThat(rows("db_perf_attribution")).singleElement().satisfies(row ->
+      {
+         assertThat(row.getValueLong("statements")).isEqualTo(2);
+         assertThat(row.getValueBigDecimal("sampleRate")).isEqualByComparingTo("1");
+      });
+   }
+
+
+   /*******************************************************************************
+    ** Atomic drains cannot lose or double-count concurrent statement delivery.
+    *******************************************************************************/
+   @Test
+   void concurrentDrains() throws Exception
+   {
+      var pool = Executors.newFixedThreadPool(4);
+      try
+      {
+         List<java.util.concurrent.Future<?>> tasks = new ArrayList<>();
+         for(int i = 0; i < 4; i++)
+         {
+            tasks.add(pool.submit(() ->
+            {
+               for(int j = 0; j < 5000; j++)
+               {
+                  synthetic("select ?", 1, true, null);
+               }
+            }));
+         }
+         long total = 0;
+         while(tasks.stream().anyMatch(task -> !task.isDone()))
+         {
+            total += listener.drain(Instant.now()).attribution().values().stream().mapToLong(counts -> counts.statements.sum()).sum();
+            Thread.yield();
+         }
+         for(var task : tasks)
+         {
+            task.get();
+         }
+         total += listener.drain(Instant.now()).attribution().values().stream().mapToLong(counts -> counts.statements.sum()).sum();
+         assertThat(total).isEqualTo(20000);
+      }
+      finally
+      {
+         pool.shutdownNow();
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Cached hot-path overhead stays below a generous two-second budget.
+    *******************************************************************************/
+   @Test
+   void overhead()
+   {
+      StatementExecution execution = new StatementExecution(runtime.getConfig().getBackendName(), "business", StatementOperation.QUERY, "select ?", 1, 1, true, null, null);
+      listener.onStatement(execution);
+      long start = System.nanoTime();
+      for(int i = 0; i < 100000; i++)
+      {
+         listener.onStatement(execution);
+      }
+      assertThat(System.nanoTime() - start).isLessThan(TimeUnit.SECONDS.toNanos(2));
+      assertThat(listener.drain(Instant.now()).attribution().values().iterator().next().statements.sum()).isEqualTo(100001);
+   }
+
+
+   /*******************************************************************************
+    ** Launcher lifecycle registers once, flushes on stop, and respects config.
+    *******************************************************************************/
+   @Test
+   void runtimeLifecycle() throws Exception
+   {
+      flusher.close();
+      assertThat(StatementExecutionListeners.isActive()).isFalse();
+      AttributionRuntimeService service = new AttributionRuntimeService();
+      assertThat(service.getName()).isEqualTo("dbPerformanceAttribution");
+      service.stop();
+      service.start(runtime.getInstance());
+      runtime.startAttribution();
+      assertThat(StatementExecutionListeners.isActive()).isTrue();
+      query(1);
+      service.stop();
+      service.stop();
+      assertThat(StatementExecutionListeners.isActive()).isFalse();
+      assertThat(rows("db_perf_attribution")).hasSize(1);
+      runtime.getConfig().setAttributionEnabled(false);
+      service.start(runtime.getInstance());
+      assertThat(StatementExecutionListeners.isActive()).isFalse();
+      service.stop();
+   }
+
+
+   /*******************************************************************************
+    ** Real flusher rows roll up across pods, preserving max and additive totals.
+    *******************************************************************************/
+   @Test
+   void rollupMergesPods() throws Exception
+   {
+      for(int i = 1; i <= 2; i++)
+      {
+         runtime.getConfig().setPodName("pod_" + i);
+         try(var scope = UnitsOfWork.begin(UnitOfWorkKind.PROCESS, "job"))
+         {
+            synthetic("select ?", i * 1000000L, true, scope.getUnitOfWork());
+            synthetic("select ?", i * 1000000L, false, scope.getUnitOfWork());
+         }
+         flusher.flushNow();
+      }
+      new RollupService(runtime).rollupDay(LocalDate.now(ZoneOffset.UTC));
+      assertThat(rows("db_perf_attribution_daily")).singleElement().satisfies(row ->
+      {
+         assertThat(row.getValueLong("units")).isEqualTo(2);
+         assertThat(row.getValueLong("statements")).isEqualTo(4);
+         assertThat(row.getValueBigDecimal("totalMs")).isEqualByComparingTo("6");
+         assertThat(row.getValueBigDecimal("maxMs")).isEqualByComparingTo("2");
+         assertThat(row.getValueLong("rowsCount")).isEqualTo(4);
+         assertThat(row.getValueLong("errors")).isEqualTo(2);
+      });
+   }
+
+
+   /*******************************************************************************
+    ** Large windows use one QQQ insert action even when the backend pages SQL.
+    *******************************************************************************/
+   @Test
+   void largeWindowUsesOneInsertAction() throws Exception
+   {
+      CountingInsert.inputs.clear();
+      for(String table : List.of("db_perf_attribution", "db_perf_repeat_pattern"))
+      {
+         runtime.getInstance().getTable(table).getCustomizers().put(TableCustomizers.PRE_INSERT_RECORD.getRole(), new QCodeReference(CountingInsert.class));
+      }
+      settings.withValue("nPlusOneThreshold", 2);
+      refresh();
+      for(int i = 0; i < 1005; i++)
+      {
+         try(var scope = UnitsOfWork.begin(UnitOfWorkKind.PROCESS, "job_" + i))
+         {
+            synthetic("select ?", 1, true, scope.getUnitOfWork());
+            synthetic("select ?", 1, true, scope.getUnitOfWork());
+         }
+      }
+      flusher.flushNow();
+      assertThat(rows("db_perf_attribution")).hasSize(1005);
+      assertThat(rows("db_perf_repeat_pattern")).hasSize(1005);
+      assertThat(CountingInsert.inputs).extracting(InsertInput::getTableName).containsExactlyInAnyOrder("db_perf_attribution", "db_perf_repeat_pattern");
+      assertThat(CountingInsert.inputs).allSatisfy(input -> assertThat(input.getRecords()).hasSize(1005));
+   }
+
+
+   /*******************************************************************************
+    ** An insert failure drops the window and never poisons a later good window.
+    *******************************************************************************/
+   @Test
+   void failedWindowIsDropped() throws Exception
+   {
+      RDBMSTableBackendDetails details = (RDBMSTableBackendDetails) runtime.getInstance().getTable("db_perf_attribution").getBackendDetails();
+      query(1);
+      details.setTableName("missing_attribution_table");
+      flusher.flushNow();
+      details.setTableName("db_perf_attribution");
+      flusher.flushNow();
+      assertThat(rows("db_perf_attribution")).isEmpty();
+      query(1);
+      flusher.flushNow();
+      assertThat(rows("db_perf_attribution")).singleElement().satisfies(row -> assertThat(row.getValueLong("statements")).isEqualTo(1));
+   }
+
+
+   /*******************************************************************************
+    ** Cold-cache overflow remains bounded and later hits keep the right shape.
+    *******************************************************************************/
+   @Test
+   void normalizationCacheOverflow()
+   {
+      for(int i = 0; i < 5010; i++)
+      {
+         synthetic("select column_" + i + " from business", 1, true, null);
+      }
+      synthetic("select column_0 from business", 1, true, null);
+      var window = listener.drain(Instant.now());
+      assertThat(window.attribution()).hasSize(5010);
+      String fingerprint = SqlNormalizer.fingerprint(SqlNormalizer.normalize("select column_0 from business"));
+      assertThat(window.attribution().entrySet().stream().filter(entry -> entry.getKey().fingerprint().equals(fingerprint)).findFirst().orElseThrow().getValue().statements.sum()).isEqualTo(2);
+   }
+
+
+   /*******************************************************************************
+    ** The daemon executes on its own system context and honors a short interval.
+    *******************************************************************************/
+   @Test
+   void scheduledFlush() throws Exception
+   {
+      settings.withValue("attributionFlushSeconds", 1);
+      refresh();
+      flusher.start();
+      flusher.start();
+      query(1);
+      long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5);
+      while(rows("db_perf_attribution").isEmpty() && System.nanoTime() < deadline)
+      {
+         Thread.sleep(25);
+      }
+      assertThat(rows("db_perf_attribution")).hasSize(1);
+      assertThat(QContext.getQInstance()).isSameAs(runtime.getInstance());
+      flusher.close();
+      flusher.start();
+      assertThat(StatementExecutionListeners.isActive()).isFalse();
+   }
+
+
+   /*******************************************************************************
+    ** Only one runtime attributes per JVM: starting another stops the first, so
+    ** repeated server starts (tests, hot swaps) never pile up listeners.
+    *******************************************************************************/
+   @Test
+   void oneActiveRuntime() throws Exception
+   {
+      StatementExecutionListeners.unregister(listener);
+      runtime.startAttribution();
+      DbPerfRuntime other = new DbPerfRuntime(runtime.getInstance(), runtime.getConfig());
+      other.startAttribution();
+      runtime.stopAttribution();
+      assertThat(StatementExecutionListeners.isActive()).isTrue();
+      other.stopAttribution();
+      assertThat(StatementExecutionListeners.isActive()).isFalse();
+   }
+
+
+
+   /*******************************************************************************
+    ** Deliver a statement with exact counter values.
+    *******************************************************************************/
+   private void synthetic(String sql, long nanos, boolean succeeded, UnitOfWork unit)
+   {
+      listener.onStatement(new StatementExecution(runtime.getConfig().getBackendName(), "business", StatementOperation.QUERY, sql, nanos, 1, succeeded, unit, null));
+   }
+
+
+   /*******************************************************************************
+    ** Execute real RDBMS-backed QQQ queries.
+    *******************************************************************************/
+   private void query(int count) throws Exception
+   {
+      for(int i = 0; i < count; i++)
+      {
+         new QueryAction().execute(new QueryInput("business").withFilter(new QQueryFilter()));
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Persist administrator settings, then explicitly refresh the cached copy.
+    *******************************************************************************/
+   private void refresh() throws Exception
+   {
+      DbPerfStore.update("db_perf_settings", List.of(settings));
+      flusher.refreshSettings();
+   }
+
+
+   /*******************************************************************************
+    ** Read persisted evidence with a concise test failure on action errors.
+    *******************************************************************************/
+   private List<QRecord> rows(String table)
+   {
+      try
+      {
+         return (DbPerfStore.query(table, new QQueryFilter()));
+      }
+      catch(Exception e)
+      {
+         throw (new AssertionError(e));
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Find one named aggregate.
+    *******************************************************************************/
+   private static QRecord named(List<QRecord> rows, String name)
+   {
+      return (rows.stream().filter(row -> name.equals(row.getValueString("unitName"))).findFirst().orElseThrow());
+   }
+
+   /*******************************************************************************
+    ** Observe whole QQQ actions while preserving the production write guard.
+    *******************************************************************************/
+   public static class CountingInsert extends DbPerfWriteGuard
+   {
+      private static final List<InsertInput> inputs = new ArrayList<>();
+
+
+      /*******************************************************************************
+       ** Capture each action's original input before the backend pages its SQL.
+       *******************************************************************************/
+      @Override
+      public List<QRecord> preInsert(InsertInput input, List<QRecord> records, boolean preview) throws QException
+      {
+         inputs.add(input);
+         return (super.preInsert(input, records, preview));
+      }
+   }
+}