Database monitoring: using a connected Postgres
Connecting a Postgres database covers the role script and what Bucker will not send. Pricing and load covers what monitoring costs you and your database. This page covers what you can do once the connection is healthy: read the slowest statements, get advisor findings, propose an index, a timeout or a cancelled statement, and watch queues and caches.
Before anything shows up
Statement collection is off until an operator of the deployment enables the db_monitoring pillar. While it is off the
collector does not even open a connection to your database, a connected database stays connected, and db_queries_list
answers with a coverage block saying no statements have been collected. Queue gauges ride the same switch. A person with
egress:admin still has to enter the connection string; no agent can.
Once it is on, the collector works inside fixed limits (one statement in flight per connection, a 2 second statement timeout,
a bounded number of rows per pull), which the REST statements read publishes in its coverage.collector block. The
per-minute load cap, the back-off and the 0.5 % target described in Pricing and load are
written but not yet wired into the collector or into any answer, so db_connection_get does not return them today.
Read the statements
| Question | Tool | Scope |
|---|---|---|
| Which statements take the most database time? | db_queries_list |
db:read |
| One statement: calls, time, rows and blocks per hour and per role, and which endpoints and releases issue it | db_query_get |
db:read |
| Which databases are connected, with their sessions and breaker state? | db_connections_list, db_connection_get |
issue:read or project:read |
A statement is identified by a fingerprint with its literals removed. Bucker joins the database's own counters to the
application's spans that carry the same fingerprint, so you see the endpoint that issues a slow statement. The share of listed
database time that also appears on spans is returned as matchedDbTimeShare; a statement a scrub rule rewrote hashes
differently on the two sides and will not match. Statement text, table names and endpoints are marked untrusted for an agent.
db_query_get takes include blocks, each with its own size limit: samples, waits and blockers come from what the
collector stored; plan, schema and stats read your database live, bounded and cached. Column statistics hold row
values, so they are absent unless a person turned excerpts on for that connection.
Every answer says how complete it is: whether a database is connected, whether the collector is live, how many hours were statistics resets or evictions, and why a list is empty.
Advisor findings
Advisor rules turn the collected data into ordinary issues, with the threshold printed on each. The rules are
seq_scan_selective, function_in_filter, index_unused, index_invalid, index_redundant, bloat_suspected,
long_running, idle_in_transaction, root_blocker, generic_plan_regressed and stats_stale. Read the findings with
issues_list.
db_advisor_rules_update changes one rule's thresholds, inside published bounds, or turns it off. It is a governed change:
| What would change | Treated as | Behaviour |
|---|---|---|
| A higher bar, or the rule off | A silence | Asks a person; lasts at most 30 days, then the previous settings return unless a person keeps them |
| A lower bar, or the rule on | A tighten (the rule fires more) | Elevated |
The request carries a replay over the rule's last 200 findings: how many would still have been raised under the new setting. Moving a rule from shadow to live is never a tool call.
Indexes
db_index_preview shows the statement Bucker would compile and the evidence for it, and writes nothing. You give ids and
names (the database, the statement fingerprints, schema, table, ordered columns, optional INCLUDE columns, a method), never
SQL. Bucker matches each name exactly against your catalog and renders CREATE INDEX CONCURRENTLY with its inverse
DROP INDEX CONCURRENTLY. It refuses a partitioned parent, a view, an unknown column, a duplicate or prefix-redundant index and a
method the column types do not take. Evidence is labelled measured, estimate or not_measured, and there is no
plan with the index, because no hypothetical-index provider exists.
db_index_propose shares the compiler. After a person approves, it opens one draft pull request that adds a migration to
your repository, with the inverse recorded. Bucker never merges it and never runs the statement against your database. If the
pull request cannot be opened, the approval is spent and the delivery can be retried without asking again. It needs
db:write and the organization's setting that allows agent pull requests.
Cancel one statement
db_session_cancel_propose asks to cancel the current statement of one backend, from a root_blocker or long_running
finding. It only ever asks: no policy makes it automatic, and a person approves it in the dashboard, Slack or a push. The target
is pinned by (pid, backend_start, query_start, fingerprint) and re-read at apply time; if any of them moved, nothing is
cancelled. Idle backends, superuser and replication backends and maintenance statements are refused before anyone is asked.
Bucker sends pg_cancel_backend only, through a function you install (bucker.cancel_backend(pid, backend_start)), on a
separate apply credential a person entered. It never terminates a session, and it sends no parameters. A database where the
function is not installed answers unavailable.
Timeouts
db_timeout_propose proposes a statement_timeout for one role, with a replay of what that value would have cancelled over
the last six complete UTC days. It stores a proposal and a copyable ALTER ROLE … SET statement and nothing else. A person
runs the statement against their own database. Bucker never sets a database parameter. The replay states its limits: the
statistics say only whether some execution crossed the value since the last reset, sample counts are lower bounds, and a
sample's role is inferred from its fingerprint.
Queues and dead letters
| Question | Tool | Scope |
|---|---|---|
| Depth by state, age of the oldest ready job, throughput, failures and dead-letter depth | queue_health_get |
event:read |
| What would a redrive of a queue's dead letters move? | dlq_redrive_preview |
db:read |
| Move dead letters back to the queue they failed from | dlq_redrive_run |
queue:write |
Age counts from availability, so a job in backoff is delayed and a deliberate delay does not read as a stall. A figure no
source gives is not_measured, never zero. The dead-letter peek shows at most five failed messages as metadata and the
shape of the body; an excerpt appears only where a person turned excerpts on for the queue.
A redrive is previewed first, as its own tool, and dlq_redrive_run is refused without a preview of exactly the same plan
from the last 30 minutes. It needs approval, and moves up to the cap in batches, stopping when the number of messages
that came straight back reaches the limit fixed in the approved plan. Above 1,000 messages, or when the consumer calls a
payment provider with no idempotency evidence, it is classed critical. A queue is limited to five redrives an hour.
Afterwards the dead-letter depth is read again as the verification. Purging is not offered to any agent: it is a person's act,
under dual control, and denied until your organization writes the policy that allows it.
Caches
cache_health_get returns each cache's hit rate from the application's own spans, beside the provider's facts and the
database statements that ran on the cache's miss path. Every rate cites its basis (byBasis says how many outcomes came from
the SDK's cache.hit and how many were inferred from the trace) and compares with the previous window of the same length.
It reads at most 72 hours. It reads no key or value and changes no eviction or memory setting, and gives no sizing advice.
Scopes and the SG-059 decision
db:read, db:write and queue:write are inside the MCP connection ceiling of 41 scopes that shipped in the 2026-11-18 release. The owner
decided on 2026-11-16 to lift the SG-059 holds without a security review of the OAuth authorization server, and no such
review is recorded. Grant db:write and queue:write only to an app you would trust to ask for these changes; each one still
waits for a person's approval, and every approval is recorded.