PLANETSCALE 2026-03-23

PlanetScale — Behind the scenes: How Database Traffic Control works¶

Summary¶

Patrick Reynolds (PlanetScale, 2026-03-23) publishes the implementation deep-dive paired with the launch and patterns posts for Database Traffic Control. The article canonicalises five new mechanisms that together make pre-execution admission control viable inside Postgres: (1) hook-colocation inside the existing pginsights extension on the ExecutorRun / ProcessUtility Postgres hooks — no extra runtime overhead because the hooks were already firing for Query Insights; (2) a per-query-pattern exponential-moving-average k constant that converts Postgres's dimensionless planner cost into a wall-clock-time estimate, updated at each query completion; (3) a reverse leaky bucket where queries accumulate debt (instead of draining credits) so empty buckets can be evicted from shared memory — critical for scaling to many tag-combinations without paying memory for inactive rules; (4) a rule-set data structure mapping <key, value> pairs to rules for amortised O(1) lookup regardless of how many rules are configured; and (5) config-file push (postgresql.conf parameter reload) as the control-plane distribution channel — chosen specifically because new SQL connections fail when the server is at 100% CPU / 100% worker saturation, which is exactly when urgent Traffic Control rule edits matter. All five compose into ~1–2-second rule propagation across all replicas in microsecond-budget per-query admission decisions.

Key takeaways¶

Hooks are the extensibility substrate. "Much of what Postgres extensions can do, they do using hooks. A hook is a function that runs before, after, or instead of existing Postgres functionality … there are 55 hooks available to anyone writing Postgres extensions." Canonical wiki framing of Postgres hook as first-class extensibility primitive; named mainline examples in the post are ExecutorRun / ProcessUtility for query interception, plus a planner hook. (Source: sources/2026-04-21-planetscale-behind-the-scenes-how-database-traffic-control-works.)
Traffic Control bolted onto pginsights to avoid a second hook pass. "It turns out Traffic Control needed the same hook points and much of the same information that pginsights already had. So rather than duplicate all that code and impose the extra runtime overhead of another extension, we taught pginsights how to block queries." Canonical wiki instance of patterns/hook-colocation-for-zero-overhead: when the same hook trigger points + measurements are needed, extend the existing extension rather than load a second one. The original plan had Traffic Control as a separate new extension; scoping revealed pg_strict was the static-analysis-flavoured split, and the cumulative-cost-flavoured split merged into pginsights.
Four-check admission sequence at ExecutorRun. *"If there are any Traffic Control rules configured, then at the beginning of each query execution, the extension does four things:
It identifies all of the rules that match the tags and other metadata of the query. Each rule identifies a budget; multiple rules can map to the same budget.
It checks to see if any of the applicable budgets has reached its concurrency limit.
It checks if the query's estimated cost is higher than any applicable budget's per-query limit.
It checks to see if every applicable budget has enough available capacity for the query to begin execution."* Steps 1+2 are trivial; 3+4 require knowing query cost before the query runs — the next takeaway.
Blocking before execution is strictly better than statement_timeout or cgroups. "Blocking a query just before it begins execution means the server spends no resources on the query, beyond the cost of the planner and the decision to block it. That's an improvement over schedulers like Linux cgroups, which let every task begin and simply starve them of resources if higher priority tasks exist in the system. It's also an improvement over the Postgres statement_timeout setting, which allows any overly expensive query to consume resources until it times out. Traffic Control blocks expensive, low priority queries before they begin." Canonical framing: the spent-then-reclaimed family (cgroups / statement_timeout / query-killer) all pay the cost of starting the query. Admission control pays only the planner cost.
Plan cost × k is the pre-execution estimator. "A SQL query planner takes a parsed SQL statement and selects what it hopes is the most efficient series of steps to execute that query … The cost is measured in dimensionless units … We assume that there is an unknown constant k that we can multiply the plan cost by, to get the actual wall-clock time it will take to execute that query. But that constant is different for each query pattern and for each host. The constant may also change over time as the workload mix on the server changes and as tables grow and change. So it's not exactly a constant!" Canonical wiki framing of concepts/plan-cost-to-wallclock-constant-k: k is a per-query-pattern per-host time-varying calibration factor, stored as a ratio of two exponential moving averages (observed CPU time, observed plan cost) updated on every query completion. Pattern: patterns/plan-cost-times-k-estimator.
Per-pattern EMA is the data structure under k. "Traffic Control implements a hash table on each host, mapping query patterns to two averages: CPU time and planner cost estimates. Both are exponential moving averages, heavily weighting recent queries. Every time a query completes, we update both of those averages. The magical not-quite-constant k is the ratio of the two." Two EMAs per (host × query pattern) — feeds both the per-query and cumulative budget checks.
Reverse leaky bucket for memory-efficient cumulative budgets. "Each budget is modeled as a reverse leaky bucket. Here's how that works. Each query that executes accumulates debt in the bucket. Any query that would cause the bucket to overflow with debt is blocked. Debt drains out over time, until the bucket is empty. The bucket has two important parameters: its size and its drain rate. The size dictates the burst limit … The drain rate dictates the server share … Traditionally, leaky buckets work the other way: they start out full, they fill (but never overflow) with credits at a configured rate, traffic consumes credits, and if a bucket is ever empty, traffic gets blocked. We inverted the model for a simple reason: an empty bucket doesn't need to be stored. Over time, we may need to store many buckets for changing rules and changing query metadata. We can drop buckets with a zero debt level, meaning that we only need to store recently active buckets, instead of every possible bucket." Canonical framing of concepts/reverse-leaky-bucket: the inversion is motivated entirely by the evictability property. Classical leaky buckets require storage-per-rate-limited-entity even when idle; reverse leaky buckets can be evicted the moment their debt hits zero.
Lazy update, lazy eviction. "There is no periodic task that drains debt from all buckets. Instead, each bucket is updated only when read. There is also no periodic task to evict buckets with a debt level of zero. Instead, adding a new bucket to the table evicts any that have already emptied, or whichever bucket is expected to become empty soonest." Canonical new concepts/lazy-leaky-bucket-update: amortise the maintenance cost into query arrival; avoid a dedicated sweeper thread. Shared-memory footprint is tunable.
Rule sets deliver O(1) rule matching for any rule count. "One important goal for Traffic Control is that it can efficiently decide when not to block a query … the budget here is measured in microseconds. But we also want developers and database administrators to be able to configure as many rules as it takes to manage traffic to their application. So it's crucial that we can evaluate many rules quickly. Enter rule sets: a data structure that allows evaluating n rules in O(1) time. Each rule has the form <key, value>, and it matches any query that has that same value for that same key … A rule set maps each <key, value> pair to a rule. Now, when a query comes in with metadata like username=postgres, app=commerce, controller=api, the rule set can quickly identify the rule for each of those pairs. Hence, for this query, there are just three lookups in the rule set, regardless of how many rules are configured." Canonical new concepts/rule-set-o1-rule-matching: the number of lookups equals the number of metadata fields on the query, not the number of rules configured on the system.
Three exceptions to O(1) rule matching. "There are three exceptions to the O(1) target for identifying rules: (1) Rules for the remote_address key check for a match for each mask length. So if you have rules for ten different mask lengths, the rule set has to do as many as ten lookups to find the rule with the longest matching prefix. (2) Any conjunction rule — that is, a rule with multiple <key, value> pairs ANDed together — may be identified as a candidate for queries that match any one of the <key, value> pairs in the rule. So if you have conjunction rules with overlapping <key, value> pairs, the rule set may identify several or all of them as candidates for each query. (3) It is possible to add multiple rules for the exact same <key, value> pair. If you do that, any query with that exact <key, value> pair will get checked against all of those rules." Operator-visible cost semantics: CIDR-masked remote_address rules cost O(mask-length-count); conjunction rules cost O(matching- <k,v>-count); duplicate-key rules cost O(duplicates).
Rule-set builds twice: identify candidates, then intersect. "Note that a rule set only identifies rules to consider. Each rule's budget is only checked if all its conditions match the query. A rule set is all about checking as few rules as possible. So, the sequence is: the rule set identifies a list of rules, that list is narrowed down to just the rules that actually match, and then the budgets for all the matching rules get checked to see if the query can proceed." Three-phase dispatch: lookup → filter → budget- check. O(1) is an upper bound on phase 1 only.
1–2-second rule propagation via postgresql.conf push. "Traffic Control is meant to be used both proactively and during incident response. For incident response, it's important that rules take effect quickly. And they do! Rules created or modified in the UI generally take effect at all database replicas in just 1–2 seconds. How? Rules and budgets are stored as objects in the PlanetScale app. Any change to Traffic Control rules made in the UI or the API gets stored as rows in the planetscale database. Then it's serialized as JSON in the traffic_control.rules and traffic_control. budgets parameters for Postgres. Some Postgres parameters require restarting the server, but those two don't. So they cut the line and get sent immediately to postgresql.conf files on each database replica. Postgres reads the new config, and each worker process parses it into a rule set as soon as it completes whatever query it's executing. The rule set is in place before the next query begins." Canonical new concepts/postgresql-conf-as-control-plane: config-file push is the distribution channel.
Config-file push beats SQL-channel push under overload. "One big advantage of using Postgres configuration files, rather than sending configuration over SQL connections, is robustness on a busy server. You may want new Traffic Control rules most urgently when Postgres is using 100% of its available CPU, 100% of its worker processes, or both. Changing config files is possible even when opening a new SQL connection and issuing statements wouldn't be." Operational reliability framing: the emergency-use case is when SQL channel itself is unavailable. Control-plane signal propagates out-of-band.

Systems named¶

systems/planetscale-traffic-control — canonical product this post is explaining the internals of.
systems/planetscale-insights — pginsights extension that hosts Traffic Control.
systems/postgresql — the substrate; ExecutorRun, ProcessUtility, planner hook, postgresql.conf all named.
systems/planetscale-for-postgres — the product surface.
systems/planetscale — the parent database platform.
pg_strict — named as the static-analysis sibling that split off from the original single-extension Traffic Control plan. Referenced via changelog URL; not a wiki system page yet.

Concepts extracted¶

concepts/postgres-hook — NEW — the 55-hook extensibility surface; post names ExecutorRun, ProcessUtility, planner hook as the Traffic Control insertion points.
concepts/reverse-leaky-bucket — NEW — debt-accumulating leaky bucket; chosen for the memory-eviction property (empty buckets are droppable, unlike classical credit-bucket rate limiters which require per-entity state regardless).
concepts/plan-cost-to-wallclock-constant-k — NEW — per-(query-pattern × host) EMA ratio that translates Postgres planner's dimensionless cost estimate into a wall-clock-time estimate for pre-execution admission decisions.
concepts/lazy-leaky-bucket-update — NEW — no periodic drain task, no periodic eviction task; both happen on bucket read / new-bucket insertion.
concepts/rule-set-o1-rule-matching — NEW — <key, value>-indexed rule lookup giving O(1) candidate identification independent of rule count.
concepts/postgresql-conf-as-control-plane — NEW — config-file push (non-restart-required parameters) as the control-plane distribution channel, chosen for robustness under connection saturation.
concepts/query-planner — existing page; post names it explicitly as the source of the dimensionless plan-cost number that Traffic Control multiplies by k.

Patterns extracted¶

patterns/hook-colocation-for-zero-overhead — NEW — when a new feature needs the same hooks / measurements an existing extension already has, merge into the existing extension instead of loading a second one. Avoids double hook- chain invocation cost + double measurement cost.
patterns/plan-cost-times-k-estimator — NEW — use the database's own query planner as a free pre-execution cost oracle, then calibrate its dimensionless output into wall- clock via a per-(pattern × host) EMA ratio updated on query completion.
patterns/postgres-extension-over-fork — existing; this post is another canonical instance of the pattern (the entire Traffic Control mechanism ships as an extension without touching Postgres core).
patterns/workload-class-resource-budget — existing; this post is the implementation-level companion to graceful-degradation and patterns posts.
Config-file push over runtime SQL for control-plane distribution — noted but not yet promoted to a standalone pattern page (single source; graduate after a second independent instance).

Operational numbers¶

55 hooks available to Postgres extension authors as of post publication (sourced to a /^\S.*\w_hook = NULL/ regex search over postgres/postgres).
1–2 seconds end-to-end rule-propagation latency from UI edit → every replica enforcing the new rule.
Microsecond budget for per-query admission-decision cost (stated as the reason rule-set O(1) matching is important).
Two Postgres parameters carry the JSON-serialised rules and budgets: traffic_control.rules, traffic_control.budgets. Both reloadable without restart.
Four checks per query at ExecutorRun: rule match → concurrency → per-query cost → cumulative cost.

Caveats¶

No numbers on k calibration accuracy. The post argues k varies per-pattern and over time, and that an EMA is the response, but doesn't publish the EMA smoothing coefficient, typical k variance within a pattern, or the fraction of mis-admitted-too-expensive queries that break through the budget.
Bucket-eviction eviction criterion under-specified. "Adding a new bucket to the table evicts any that have already emptied, or whichever bucket is expected to become empty soonest" — the expected-to-empty-soonest heuristic isn't spelt out (linear prediction off drain rate?). Worth revisiting if we get a second source describing the eviction algorithm.
remote_address CIDR matching cost = O(mask-length-count) is the worst published exception to O(1) rule matching. In practice a rule set with rules at 10 different mask lengths could cost 10 lookups per query, per the post. Not typically a problem but worth noting as a scaling dimension.
Post doesn't name the planner hook. Says "hook on ExecutorRun" and "hook on ProcessUtility" explicitly. Mentions a planner hook in the list of extensible hooks but doesn't say Traffic Control uses it. Claims of Traffic Control using the planner hook should be checked against source before citing.
pg_strict linked as a changelog entry, not as a wiki system. Can be promoted to a system page if it gets a second-source mention; for now, link-in-source-only.