Skip to main content

​
Behavior and expectations

No. Database Traffic Control does not modify your schema or indexes, and it does not directly change how queries are planned. It focuses on whether queries are allowed to consume resources based on your configured resource budgets.
Resource budgets are configured per database branch. Each branch can have its own set of resource budgets.
Database Traffic Control blocks the query and records a violation.The blocked query returns an error to the client with SQLSTATE 53000. The error message includes [PGINSIGHTS] Traffic Control: and details about why the query was blocked (for example, which limit was exceeded). Violations are visible in the Database Traffic Control page.
In Warn mode, matching queries are not blocked or throttled; they complete normally.The client still receives a SQL notice (warning) whose text includes [PGINSIGHTS] Traffic Control: and details about which limit would have been exceeded. Resource budgets also record violations for the UI. Violations are visible in the Database Traffic Control page.

​
Resource budget matching

Yes. A query can match more than one resource budget if its attributes satisfy multiple matching criteria. For example, a query might match one resource budget based on its 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. Resource budgets are combined with AND logic, not OR.
The Database Traffic Control UI shows violations per resource budget. If a query is blocked, you can see which resource budget caused the violation. If a query matches multiple resource budgets but only one blocks it, the violation is attributed to the blocking resource budget.
The most common cause is tag placement. Tags must appear before the semicolon that ends the SQL statement. See the Query tags troubleshooting section for the correct format and other common issues.

​
Understanding and responding to high violation rates

  1. Narrow the time range in the Database Traffic Control UI to the window where the spike occurs.
  2. Identify which resource budget has the highest violation count.
  3. Determine which workload or system attribute that resource budget targets.
  4. Use Insights to see what changed (new deployment, new dashboard, larger batch job, etc.).
  5. Decide whether the workload is misbehaving or the limits are too strict:
    • If the workload is expected and healthy, consider relaxing limits slightly.
    • If the workload is unexpected or clearly problematic, work with the owning team to correct it.
Consistently high violations for a key application workload suggest a mismatch between your resource budget limits and real usage. Either:
  • The application’s normal behavior exceeds the resource budget limits, in which case you should adjust the resource budget; or
  • The application is issuing more or heavier queries than intended, in which case you should treat this as a performance issue.
  • Your queries might be poorly optimized, in which case you should inspect results in Insights for more details, or debug queries with the PlanetScale MCP Server.
  • Your database may be under-provisioned, in which case you should consider upgrading your cluster to a larger size.
In any case, do not ignore sustained high violation counts for important workloads.

​
Quickly rolling back a misconfiguration

You have several options:
  • Change the resource budget Mode from Enforce back to Warn — For new queries, this stops enforcing the resource budget while still recording violations.
  • Temporarily set the resource budget Mode to Off — Use this for emergency rollback when you need to fully disable the resource budget.
  • Loosen the resource budget’s limits — Increase capacity, burst, or concurrency to better match real traffic.
After stabilizing the system, review what went wrong before re‑enabling enforcement.

​
Configuration tips

Create a resource budget that matches only that query, then set its allowed resource usage to 0 across the board. This will block all executions of that query.
Concurrency is expressed as a percentage of Postgres worker processes. A query with a parallel execution plan uses multiple worker processes, so a single parallel query may consume more than one unit of concurrency. Keep this in mind when setting concurrency limits for workloads that run parallel queries.
Yes. The traffic_control.shm_size parameter controls how much shared memory is allocated to store resource budgets. The default is 64kB.

​
Interaction with connection pooling and clients

Database Traffic Control is concerned with the queries that reach the database, regardless of whether they come from a pool or direct connections.See Connection pooling for more information.
Database Traffic Control protects your database, but it does not replace all forms of client‑side rate limiting. You may still need application‑level controls to:
  • Protect upstream services
  • Enforce per‑user or per‑tenant limits that are not visible at the database layer
  • Set appropriate query timeouts

​
Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.