Database

The panel is served over Agroal instead of HikariCP and looks the same. Pool metrics require quarkus.datasource.jdbc.metrics.enabled=true; with metrics disabled the configuration still renders but the live snapshot is marked unavailable. Pool library reads Agroal. Settings Agroal does not expose (validation timeout, keepalive interval, read-only flag) render as "—"; a maximum lifetime of 0 means no limit.

• Database advisor checks physical schema structure from metadata and vendor catalogs.
• SQL Trace shows statements this JVM recently issued.
• PostgreSQL reads PostgreSQL's own cumulative pg_stat_* and pg_catalog views, which include work from every client of the database.

The panel runs one read-only transaction per datasource, pinning statement_timeout to 5 seconds, lock_timeout to 2 seconds, and the read budget to 15 seconds. Every statistics query runs in its own savepoint, so one error does not abort the others.

BootUI refuses a connection already in manual-commit mode (for example spring.datasource.hikari.auto-commit=false) before issuing SQL, and never commits or rolls back that connection.

List sections are capped per datasource. These keys and defaults are the same on all three stacks:

bootui.postgresql.max-sessions=100
bootui.postgresql.max-statements=100
bootui.postgresql.max-indexes=500
bootui.postgresql.max-tables=200
bootui.postgresql.max-vacuum-tables=200
bootui.postgresql.max-replicas=10
bootui.postgresql.max-settings=40

Values must be positive integers below 2147483647; zero does not mean unlimited, and invalid values are rejected. Restart after changing a limit. See the property reference.

truncated means a row cap was reached; exhausting the time budget produces an explicit section reason and keeps the rows already read. A top-100 statement ranking is an expected cap and shows one informational note, not a warning. The API, MCP, and CLI report PARTIAL with truncated=true and list capped sections in limitations.

The change baseline is never written to disk, and a section that could not be read keeps its earlier value. The Notable settings list excludes statement_timeout, lock_timeout, and idle_in_transaction_session_timeout, because BootUI overrides them for its own read.

Values follow the global exposure policy. Session and statement text is redacted, masked, and truncated: under MASKED or METADATA_ONLY, string literals and dollar-quoted bodies are replaced, and session and replica client addresses are masked under METADATA_ONLY. Error messages from failed reads are redacted the same way.

Without pg_monitor, PostgreSQL silently restricts its views:

BootUI probes pg_read_all_stats membership and marks the affected sections partially read. Statement ranking also requires the pg_stat_statements extension. On a standby, the replica list and primary-relative lag are not read (replication.replicasAvailable=false). A datasource that declares no readable URL keeps the panel available whenever the PostgreSQL driver is on the classpath; a non-PostgreSQL datasource is then skipped with a diagnostic.

The autovacuum "due" estimate uses the settings the server would apply to each relation, including per-table reloptions. It models only the dead-tuple trigger and reads pg_stat_user_tables, which the section states.

The Spring MVC sample has a docker-postgresql profile that preloads pg_stat_statements. Run bootui-spring-sample-app/run-local-postgresql.sh for a lightweight PostgreSQL-and-Redis stack.

The Spring MVC sample has a docker-mysql profile that enables statement instrumentation and provisions the diagnostic grants. Run bootui-spring-sample-app/run-local-mysql.sh for a lightweight MySQL-and-Redis stack.

Over MCP and the CLI, the explicit read answers with a summary and the cached report returns the rows. Neither operation accepts SQL, a schema selector, or a server address; collection uses the application's existing datasources and credentials.

Global bootui.read-only or bootui.panels.mysql.read-only blocks the explicit read because it initiates external work; cached reads remain allowed. Disabling bootui.panels.mysql.enabled blocks both. An overlapping read is refused, not queued.

Reports are NOT_READ, READ, PARTIAL, ERROR, or DISABLED. READ means applicable sections completed within their scope, not that the database is healthy. A section is AVAILABLE, SKIPPED, or FAILED, with a reason when evidence is incomplete. The cache holds sanitized data; changing the exposure policy invalidates it and requires a new explicit read.

• Server evidence can include other applications; do not add server counters from multiple pools on one instance.
• Selected schema sections are skipped when no schema is selected; BootUI never enumerates every database.
• Default-schema-associated sessions and digests are not an inventory of every statement touching that schema.
• Unknown values are null, not zero. Large counters, byte sizes, and identifiers are exact decimal strings in JSON; do not coerce them through a JavaScript Number.
• The first read has no invented rates. Comparisons need a compatible datasource, server identity, and counter provenance; a restart or server change invalidates the baseline. Nothing is persisted to disk.
• Statement ranking has normalized digests only, never raw SQL. Index handler statistics are not query counts, and "no recorded reads" is not advice to drop an index. Table estimates can be cached; BootUI never runs COUNT(*). Replication evidence has no end-to-end lag.

The execution bounds are a 15-second cooperative total read budget, a 5-second server SELECT limit (MAX_EXECUTION_TIME, or SET STATEMENT max_statement_time on MariaDB), a 2-second metadata-lock wait limit, and 400 characters of displayed statement text. The borrowed connection also gets a JDBC network timeout of at most 7 seconds. BootUI uses neither Statement.setQueryTimeout nor Statement.cancel, avoiding Connector/J's auxiliary KILL QUERY connections. These are not hard end-to-end deadlines; connection-acquisition waits are controlled by the application pool.

If performance_schema.global_status is unreadable, BootUI falls back to SHOW GLOBAL STATUS filtered to 17 fixed safe names.

The seven startup row caps, identical across the three JDBC adapters, are:

bootui.mysql.max-sessions=100
bootui.mysql.max-statements=100
bootui.mysql.max-indexes=500
bootui.mysql.max-tables=200
bootui.mysql.max-lock-waits=100
bootui.mysql.max-replication-channels=10
bootui.mysql.max-settings=40

Each applies per datasource. Values must be positive integers below 2147483647; invalid values fail startup, and zero is not unlimited. Restart after changing a cap. See the property reference.

truncated=true means a BootUI row cap omitted results, not a failed query. The UI shows row caps as neutral Limited labels; permission problems, timeouts, and unavailable instrumentation remain warnings or errors.

Collection sets transaction_read_only=1, starts START TRANSACTION READ ONLY, and verifies the server setting; it avoids Connection.setReadOnly. Manual-commit connections are refused before any SQL. Afterward, BootUI rolls back only its own transaction and restores the auto-commit, session settings, and network timeout. If restoration and abort both fail, the handle is quarantined and further collection is disabled until the pool and BootUI restart.

No application rows, LOCK_DATA key values, QUERY_SAMPLE_TEXT, PROCESSLIST_INFO, or TRX_QUERY are selected. Only normalized digest text is exposed, after masking, credential redaction, the exposure policy, and length bounds; metadata-only mode withholds statement text and sensitive addresses. Raw JDBC URLs, arbitrary server errors, replication secrets, and variable dumps are excluded in every mode. There are no kill controls, SQL console, query plans, DDL, or controls to change server configuration.

Sidebar discovery reads local declarations only, never a database; the explicit read verifies the connected server and reports unsupported targets. Routing datasources describe the actual connected server. On Quarkus, use quarkus-jdbc-mysql and a JDBC datasource; a reactive client alone does not qualify.

Use the application's existing account and grant only the visibility the operator approves. There is no single pg_monitor equivalent, and BootUI never enables instruments or resets statistics. Do not grant SUPER or all of performance_schema.* just to make the panel complete.

Uninstrumented or unknown objects keep their catalog metadata, but affected activity counters are withheld and explained per section, never shown as zero. An empty metadata-lock list with disabled instrumentation cannot establish absence.

BootUI wraps each DataSource bean with a JDK dynamic proxy and records the SQL text, statement type, category (SELECT, INSERT, UPDATE, DELETE, DDL, OTHER), duration, affected rows, batch size, connection, executing thread and its kind (WORKER, VIRTUAL_THREAD, EVENT_LOOP, REACTOR_SCHEDULER, OTHER), the call site when enabled, and any failure. On Spring MVC and Quarkus, each statement also records the request phase it ran in: FILTERS, HANDLER, or RESPONSE (where lazy loading surfaces). Spring WebFlux records no phase.

A Spring DataSource wrapper is never replaced; when it owns the only reference to a pool (for example LazyConnectionDataSourceProxy), the pool inside is traced in place. Wrapping fails open: a DataSource that cannot be proxied is left untouched. On the JVM the proxy also advertises the vendor interfaces of the original bean, such as Oracle UCP's PoolDataSource, so by-type injection keeps working.

Grouping uses the framework's route template (GET /api/sample/orders/{id}) when available, otherwise matches the path against the application's declared route mappings, and falls back to a masked path (identifier-looking segments become {value}, query string discarded). Matching a declaration is strict, and ambiguous declarations produce no template, because masking alone cannot tell /api/users/alice from a fixed route segment.

Capture comes from two feeders: an @Alternative Agroal DataSource wrapping the default pool for manual JDBC, and a @PersistenceUnitExtension Hibernate StatementInspector for ORM SQL of the default persistence unit (named units are not traced), because Hibernate resolves its pool from Agroal's own registry.

The inspector observes preparation only. Those rows stay visible with a report warning, but their compatibility fields (durationMicros: 0, success: true) do not establish an execution or outcome, so they are excluded from statistics, rankings, N+1 badges, and confirmed event-loop blocking. Both feeders are wired in dev and test only, and the inspector never captures bound parameter values.

On Spring MVC and WebFlux, BootUI contributes a TransactionExecutionListener (Spring Framework 6.1+) through Spring Boot's transaction-manager customization. It composes with your own listeners; managers that do not implement the configurable listener SPI stay unobserved. On WebFlux this covers blocking managers used on a Reactor boundedElastic worker and a ReactiveTransactionManager such as R2DBC's, recorded without a thread-bound parent or isolation (WebFlux support). SQL and connection counts describe JDBC work on the begin thread, so zero counts do not prove that no database work occurred.

Each transaction records the boundary name (typically ClassName.methodName), a best-effort propagation (NEW or PARTICIPATING), the isolation level, the outcome (COMMITTED, ROLLED_BACK, or UNKNOWN), timestamps and duration, the enclosing transaction id, the thread, and the trace id. Each entry is correlated by thread and time window to SQL Trace executions, showing how many statements and connections it touched.

When the opt-in MCP Server is enabled on Spring MVC or WebFlux, get_transactions exposes the same bounded report.

Only the first resolved EntityManagerFactory is inspected, so a multi-persistence-unit application sees one unit. There is no per-entity or per-query drill-down beyond what Statistics exposes. bootui.monitoring.exclude-self does not apply, because these are process-global counters.

When module-aware Flyway migrations are active, the panel shows the root and module-specific history tables separately. Those entries are read-only in BootUI. This is Spring-specific and not reported on Quarkus.