Skip to content

budgets.mdx

Latest commit

 

History

History
65 lines (50 loc) · 2.8 KB

budgets.mdx

File metadata and controls

65 lines (50 loc) · 2.8 KB
Raw
title Query Budgets
icon Gauge
description Cap queries per window and rows per result for an agent credential. Runaway loops and full-table scans hit a ceiling instead of your database.

A budget caps how much an agent can run. You set queries per window, a maximum number of rows per result, and a statement timeout. When an agent loops or asks for too much, the budget stops it at the wire instead of letting it hammer your database.

Set a budget

pgbeam policies create --name analytics \
  --budget-queries-per-day 5000 \
  --max-rows 1000 \
  --statement-timeout-ms 10000

In the dashboard, set the budget on the policy profile under Budgets.

What you can cap

Limit Effect
Queries per window Cap statements per hour or per day. The next query past the cap is blocked with an error until the window resets.
Max rows Truncate any result to at most this many rows.
Write row cap Hard cap on rows a single write (INSERT/UPDATE/DELETE) may affect. Set with --max-affected-rows.
Statement timeout Cancel a statement that runs longer than this.

What the agent sees

A query past the cap comes back as a Postgres error (SQLSTATE 53400):

ERROR:  PgBeam agent day query budget exhausted; resets at 2026-06-15T00:00:00Z; ask your operator to raise the limit

The message names the window and the exact reset time, so an agent can back off rather than retry blindly. A per-day egress (bytes) budget produces a similar message when exceeded.

Write row cap

--max-affected-rows bounds how many rows a single write may affect, separate from --max-rows (which truncates read results). A write whose affected-row count would exceed the cap runs inside a transaction, is checked, and is rolled back so nothing persists, then blocked. It applies to INSERT, UPDATE, and DELETE and is enforced independently of human approval. 0 means unlimited.

Budget counters are kept per data plane and per region, like the rate limiter. An agent connects to one region in practice, so the window it sees is consistent. The control plane aggregates usage across regions and can trip the [kill-switch](/docs/kill-switch) if an organization-level ceiling is breached.

Related