# Database monitoring: using a connected Postgres

[Connecting a Postgres database](./database-connections.md) covers the role script and what Bucker will not send. [Pricing and
load](./database-monitoring-pricing.md) 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](./database-monitoring-pricing.md) 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.

## Related

- [Connecting a Postgres database](./database-connections.md)
- [Database monitoring: what it costs, and what it costs your database](./database-monitoring-pricing.md)
- [Database scope: what Bucker will not do](./database-scope.md)
- [SQL comments and privacy](./sql-comments-privacy.md)
- [MCP setup](./mcp-setup.md)
