Skip to content
bucker

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.