Resource budgets
A resource budget is the primary Database Traffic Control™ configuration mechanism. It defines how much database resource a specific slice of traffic is allowed to consume.
A resource budget:
- Applies to traffic that matches one or more rules, which can be a specific query, a system attribute, or a combination of SQLCommenter tags.
- Defines limits on resource consumption (capacity, rate, burst, concurrency)
- Handles responses in a mode (Enforce, Warn, Off)
- Is scoped to a specific database branch
Resource budget limits
When a query to the database arrives, Database Traffic Control first checks whether it matches any resource budget rules. If a match is found, the cost of executing the query is estimated, and the limits in that resource budget determine whether the query is allowed, warned, or blocked.
Each resource budget has four optional, configurable limits:
- Server share - The max percentage of overall system resources available to queries managed by this budget.
- Burst limit - Burst limit is the maximum short-term CPU burst your server can use above its steady share, measured in whole-server seconds and refilled gradually over time.
- Per-query limit - The maximum resources any individual query can use, as a percentage of server resources in the first second.
- Maximum concurrent queries - Percentage of available worker processes this policy can use
How resource budgets are estimated
Database Traffic Control estimates the cost of the query based on the recent behavior of similar queries. If the estimated cost exceeds the resource budget limits, the decision to block is enforced or a warning is issued, depending on the mode setting.
- There is insufficient capacity to handle the query:
fill_level + estimated_cost > capacity
- The query is too expensive on its own:
estimated_cost > burst
These estimates are not precise, real-time measurements. Database Traffic Control uses recent query behavior to make fast decisions about whether to allow, warn, or block a query before it runs. Each unique query pattern learns its own cost model over time, so estimates improve as the system observes more executions of the same query shape.
Under normal usage, queries flow through without noticeable impact. When a workload exceeds its configured limits, and the mode is set to Enforce, queries are blocked to keep other workloads healthy.
Modes: Enforce, Warn, Off
Each resource budget has a mode that controls how strictly it is applied.
- Enforce
- Limits are active
- Queries that exceed limits are blocked
- Violation counts are recorded and visible in the UI
- Best choice for stabilizing workloads
- Blocked queries return with the code
53000 and a message from [PGINSIGHTS] Traffic Control: and, the ID of the resource budget that blocked the query and the limit that was exceeded
- Warn
- Limits are evaluated, but not enforced
- Queries always continue
- Violation counts are recorded and visible in the UI
- Best choice for initial rollout or tuning
- Query response contains a message indicating the query would have been blocked by Database Traffic Control, and which limit was exceeded
- Off
- The resource budget does not participate in matching
- No violations are recorded
It is best practice to roll out a new resource budget in stages:
- Create a resource budget in Warn mode
- Observe violation patterns and adjust limits
- Switch to Enforce once you are confident in the configuration
Response messages
Resource budgets in Warn or Enforce mode attach a message to the SQL response when a limit would be or was exceeded.
Messages use the prefix [PGINSIGHTS] Traffic Control:, followed by the ID of the resource budget that blocked the query and the limit that was exceeded.
- Enforce — The query is blocked. The client receives a SQL error with SQLSTATE
53000 and a message that includes [PGINSIGHTS] Traffic Control: and the reason. Treat this as a failed statement and use retry or fallback logic as needed.
- Warn — The query still runs and returns a normal result. The client also receives a SQL notice (warning) whose text includes
[PGINSIGHTS] Traffic Control: and the reason. Log or surface these notices for observability while tuning limits before enforcement.
Applications can detect Traffic Control specifically by SQLSTATE 53000 on blocked queries, by matching this prefix in error or notice text, or both.
Rules
Resource budgets apply to specific traffic based on matching against a rule. Rules can be individual queries, system attributes, or tags.
System attributes and tags are matched on key-value pairs. System attributes are created automatically when using Postgres, while tags must be added to your queries.
You can combine rules with AND logic so that multiple rules must match, or OR logic so that any one of the rules must match, for the resource budget to apply.
System attribute rules
System attribute rules match key-value pairs that Postgres automatically provides for each connection. You can write rules that match against any of the following:
| Attribute | Description |
|---|
username | The database role or user executing the query |
remote_address | The client IP address of the connection |
application_name | The application name set by the connecting client |
- Limit analytics queries by having them connect as a dedicated database user, like
analytics_user and matching username = analytics_user
- Isolate traffic from a known internal service that connects from a fixed IP range by matching
remote_address
- Target a specific service without creating separate database users by matching
application_name
Tag-based rules
Tag rules match against key-value pairs that your application attaches to queries using the SQLCommenter format. A tag rule targets one or many queries that share the same tag.
To create a tag-based rule, recently executed queries must have included the tag.
Usage examples include:
- Feature flags or code paths, such as
feature='beta_checkout'
- Application tags, such as
app='web'
- Route-level targeting, such as
route='api-export'
For details on the tag format, how to add tags to your queries, and framework support, see Query tags.
Query-based rules
Target a specific query by using the query itself as the rule.
You can create query-based rules by finding the query in the Insights page and clicking Create resource budget.
This is recommended only for temporary cases where you need to test or limit the resources allocated to a specific query. Such as an emergency situation. Prefer system attribute or tag-based rules.
Matching multiple rules
Resource budget rules may contain several attributes combined with AND or OR logic.
A query may also match more than one resource budget. For example, a query might match one resource budget based on its system attribute username and another based on an application tag.
When a query matches multiple resource budgets, it must satisfy all of them. If any matching resource budget would block the query, the query is blocked. Multiple resource budgets are combined with AND logic, not OR.
Need help?
Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.
