192 lines
94 KiB
HTML
192 lines
94 KiB
HTML
<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><meta name="theme-color" content="#111111"/><meta name="user-signed-in" content="false"/><title>Behind the scenes: How Database Traffic Control works — PlanetScale</title><meta name="description" content="Learn how Traffic Control enforces real-time limits on Postgres queries."/><meta name="robots"/><meta property="og:url" content="https://planetscale.com/blog/behind-the-scenes-how-traffic-control-works"/><meta property="og:type" content="website"/><meta property="og:title" content="Behind the scenes: How Database Traffic Control works — PlanetScale"/><meta property="og:image" content="https://planetscale.com/assets/behind-the-scenes-how-traffic-control-works-social-MNXbuFQ_.png"/><meta property="og:description" content="Learn how Traffic Control enforces real-time limits on Postgres queries."/><meta property="twitter:card" content="summary_large_image"/><meta property="twitter:site" content="@PlanetScale"/><meta property="twitter:creator" content="@PlanetScale"/><meta property="twitter:url" content="https://planetscale.com/blog/behind-the-scenes-how-traffic-control-works"/><meta property="twitter:title" content="Behind the scenes: How Database Traffic Control works — PlanetScale"/><meta property="twitter:description" content="Learn how Traffic Control enforces real-time limits on Postgres queries."/><meta property="twitter:image" content="https://planetscale.com/assets/behind-the-scenes-how-traffic-control-works-social-MNXbuFQ_.png"/><link rel="canonical" href="https://planetscale.com/blog/behind-the-scenes-how-traffic-control-works"/><link rel="preconnect" href="https://planetscale-images.imgix.net"/><link nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ=" rel="icon" href="/favicon.ico" type="image/x-icon" sizes="16x16"/><link nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ=" rel="icon" href="/icon.png" type="image/png" sizes="32x32"/><link nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ=" rel="apple-touch-icon" href="/apple-touch-icon.png" type="image/png" sizes="32x32"/><link nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ=" rel="manifest" href="/manifest.webmanifest"/><link rel="modulepreload" href="/assets/entry.client-3vubyXrk.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/jsx-runtime-DwfQwkRq.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/components-_bNmAApg.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/_.well-known_.mcp.server-card_.json_-Sx7XeH3e.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/index-mKTXLmHu.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/errorBoundaries-DhW4jVYt.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/root-DbOv4-98.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/lib-Dg89tQ22.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/analytics.client-DM6E8o1h.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/SiteHeader-C2U5gvDH.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/current-9yDxj94E.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/clsx-eT0YPcGk.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/bugs-38ilEoW0.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/keyboard-D-uXZORL.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/use-tab-direction-dKm-S3Ck.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/blog-pXH7ptHJ.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/blog._slug-Ch_92qsH.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/ContentImage-Dh6VEOUl.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/BlogCategoryLink-DmQyn0gp.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/Details-BSB_b6hI.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/Skittle-CDFOPRjH.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/SiteFooter-B2Gq9u2j.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/Vimeo-00PQJDli.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/YouTube-CMfaljVr.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/date-CJTFH3uT.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/use-inert-others-BMJ6-xOX.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/description-Cf6FZmDe.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/use-is-mounted-uQsUZyP9.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="modulepreload" href="/assets/types-DvonrUFF.js" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ="/><link rel="stylesheet" href="/assets/styles-ns8XBZ1D.css"/><script nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ=">window.ENV = {"IMAGE_CDN":"https://planetscale-images.imgix.net","IMAGE_CDN_ENABLED":"true","INTERNAL_API":"https://api.planetscale.com","RELEASE":"117b8aaf-965c-42bc-b013-5f72770de4d9","SENTRY_DSN":"https://bd81903b44804e22a06bdc0c1a91b303@o499952.ingest.us.sentry.io/4504531942572032"}</script></head><body class="flex min-h-screen flex-col"><div class="bg-neki px-3 py-1 text-center font-medium text-gray-900 dark:font-semibold"><span>Neki, sharded Postgres, is now available.</span> <span class="whitespace-nowrap"><a href="https://auth.planetscale.com/sign-up" class="whitespace-nowrap bg-gray-900 px-sm font-semibold text-white">Get started</a></span></div><header class="relative mb-6 mt-4 bg-primary"><div class="flex flex-col gap-y-3 px-3 sm:px-5 container max-w-7xl"><div class="grid w-full grid-cols-[auto_1fr] grid-rows-1 items-center lg:items-start lg:gap-3"><a aria-label="Go to homepage" class="col-start-1 col-end-2 h-4 w-4 rounded-full text-primary lg:hidden" href="/" data-discover="true"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="none" viewBox="0 0 40 40"><path fill="currentColor" d="M0 20C0 8.954 8.954 0 20 0c8.121 0 15.112 4.84 18.245 11.794l-26.45 26.45a20 20 0 0 1-3.225-1.83L24.984 20H20L5.858 34.142A19.94 19.94 0 0 1 0 20M39.999 20.007 20.006 40c11.04-.004 19.99-8.953 19.993-19.993"></path></svg></a><div class="group col-start-2 col-end-3 row-start-1 flex shrink-0 items-center justify-end gap-1.5 lg:gap-3"><div class="flex flex-row gap-2 lg:flex-col lg:gap-1 xl:flex-row"><div class="flex items-center justify-end gap-1 lg:h-4"><a href="https://auth.planetscale.com/sign-in" class="font-semibold text-primary hover:text-orange">Sign in</a></div><div class="flex items-center justify-end gap-0.5 lg:h-4"><form class="btn-sm hidden sm:inline-flex" action="/api/demo-sessions" method="post"><button type="submit" class="btn btn-outline btn-sm hidden sm:inline-flex">View sandbox</button></form><a class="btn btn-sm" href="/contact" data-discover="true">Get in touch</a></div></div></div><div class="col-start-1 col-end-2 flex items-center gap-x-3 lg:row-start-1 lg:h-4"><a aria-label="Go to homepage" class="col-start-1 col-end-2 hidden h-4 w-4 rounded-full text-primary lg:block" href="/" data-discover="true"><svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="none" viewBox="0 0 40 40"><path fill="currentColor" d="M0 20C0 8.954 8.954 0 20 0c8.121 0 15.112 4.84 18.245 11.794l-26.45 26.45a20 20 0 0 1-3.225-1.83L24.984 20H20L5.858 34.142A19.94 19.94 0 0 1 0 20M39.999 20.007 20.006 40c11.04-.004 19.99-8.953 19.993-19.993"></path></svg></a><nav aria-label="Main" data-orientation="horizontal" class="hidden items-center lg:flex"><ul class="flex flex-wrap gap-x-1 md:flex-nowrap"><li><div data-headlessui-state=""><button class="font-semibold text-primary hover:text-contrast focus-visible:ring-0 ui-open:text-orange" type="button" aria-expanded="false" data-headlessui-state="">Platform<span class="ml-sm inline-block ui-open:rotate-180">▾</span></button></div><span hidden="" style="position:fixed;top:1px;left:1px;width:1px;height:0;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;border-width:0;display:none"></span></li><li class="text-decoration" role="presentation">|</li><li><div data-headlessui-state=""><button class="font-semibold text-primary hover:text-contrast focus-visible:ring-0 ui-open:text-orange" type="button" aria-expanded="false" data-headlessui-state="">Resources<span class="ml-sm inline-block ui-open:rotate-180">▾</span></button></div><span hidden="" style="position:fixed;top:1px;left:1px;width:1px;height:0;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;border-width:0;display:none"></span></li><li class="text-decoration" role="presentation">|</li><li><a class="font-semibold text-primary hover:text-contrast" href="/docs">Documentation</a></li><li class="text-decoration" role="presentation">|</li><li><a class="font-semibold text-primary hover:text-contrast" href="/pricing" data-discover="true">Pricing</a></li><li class="text-decoration" role="presentation">|</li><li><a class="font-semibold text-primary hover:text-contrast" href="/migrate" data-discover="true">Migrate</a></li></ul></nav></div></div><details class="lg:hidden"><summary>Navigation</summary><nav class="dashed-box mt-1 p-3"><ul class="flex flex-wrap gap-x-1 md:flex-nowrap"><li><div data-headlessui-state=""><button class="font-semibold text-primary hover:text-contrast focus-visible:ring-0 ui-open:text-orange" type="button" aria-expanded="false" data-headlessui-state="">Platform<span class="ml-sm inline-block ui-open:rotate-180">▾</span></button></div><span hidden="" style="position:fixed;top:1px;left:1px;width:1px;height:0;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;border-width:0;display:none"></span></li><li class="text-decoration" role="presentation">|</li><li><div data-headlessui-state=""><button class="font-semibold text-primary hover:text-contrast focus-visible:ring-0 ui-open:text-orange" type="button" aria-expanded="false" data-headlessui-state="">Resources<span class="ml-sm inline-block ui-open:rotate-180">▾</span></button></div><span hidden="" style="position:fixed;top:1px;left:1px;width:1px;height:0;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;border-width:0;display:none"></span></li><li class="text-decoration" role="presentation">|</li><li><a class="font-semibold text-primary hover:text-contrast" href="/docs">Documentation</a></li><li class="text-decoration" role="presentation">|</li><li><a class="font-semibold text-primary hover:text-contrast" href="/pricing" data-discover="true">Pricing</a></li><li class="text-decoration" role="presentation">|</li><li><a class="font-semibold text-primary hover:text-contrast" href="/migrate" data-discover="true">Migrate</a></li></ul></nav></details></div></header><main class="container mb-6 flex max-w-7xl flex-1 flex-col px-3 sm:px-5 lg:px-12"><section class=""><p class="block"><a class="pr-sm text-primary hover:text-contrast" href="/blog" data-discover="true">Blog</a><span class="px-sm text-decoration">|</span><a class="px-sm text-blue hover:bg-blue-100 dark:hover:bg-blue-900" href="/blog/category/engineering" data-discover="true">Engineering</a><span class="px-sm text-decoration">|</span><a class="px-sm text-postgres hover:bg-gray-100 dark:hover:bg-gray-800" href="/blog/category/postgres" data-discover="true">PostgreSQL</a></p><div class="flex lg:flex-row-reverse lg:gap-x-6"><div class="lg:sticky lg:top-2 lg:self-start"><button class="absolute right-0 bg-gray-100 px-sm md:block lg:hidden dark:bg-gray-800 -mt-9 hidden"><span class="inline">Table of contents «</span><span class="hidden">Close »</span></button><aside class="tree-nav w-full shrink-0 space-y-3 lg:w-36 hidden lg:block"><div><h4 class="text-secondary">Table of contents</h4><ul><li><a class="font-semibold text-primary hover:text-blue" href="/blog/behind-the-scenes-how-traffic-control-works#background" data-discover="true">Background</a></li><li><a class="font-semibold text-primary hover:text-blue" href="/blog/behind-the-scenes-how-traffic-control-works#insights-hooks-and-blocking-queries" data-discover="true">Insights, hooks, and blocking queries</a></li><li><a class="font-semibold text-primary hover:text-blue" href="/blog/behind-the-scenes-how-traffic-control-works#cost-prediction" data-discover="true">Cost prediction</a></li><li><a class="font-semibold text-primary hover:text-blue" href="/blog/behind-the-scenes-how-traffic-control-works#leaky-buckets" data-discover="true">Leaky buckets</a></li><li><a class="font-semibold text-primary hover:text-blue" href="/blog/behind-the-scenes-how-traffic-control-works#rule-sets" data-discover="true">Rule sets</a></li><li><a class="font-semibold text-primary hover:text-blue" href="/blog/behind-the-scenes-how-traffic-control-works#applying-new-rules" data-discover="true">Applying new rules</a></li><li><a class="font-semibold text-primary hover:text-blue" href="/blog/behind-the-scenes-how-traffic-control-works#wrap-up" data-discover="true">Wrap up</a></li></ul><div class="mb-3 mt-6 border bg-blue-50 p-3 font-semibold text-contrast dark:bg-blue-900"><p>PlanetScale, the fastest cloud Postgres, from $5/month.</p><p><a href="https://app.planetscale.com/new">Start now</a></p></div><p>Get the <a href="/blog/feed.atom">RSS feed</a></p></div></aside></div><article class="min-w-0 flex-grow"><h1>Behind the scenes: How Database Traffic Control works</h1><p class="text-secondary"><a class="text-contrast no-underline" href="/blog/author/piki" data-discover="true">Patrick Reynolds</a> |<!-- --> <time dateTime="2026-03-23T16:00:00.000Z">March 23, 2026</time></p><div class="blog-post-body"><p>Today, we released Database Traffic Control®, a feature for mitigating and preventing database overload due to unexpectedly expensive SQL queries. For an overview, read the <a href="/blog/introducing-database-traffic-control">blog post introducing the feature</a>, and to get started using it, read the <a href="/docs/postgres/traffic-control/">reference documentation</a>. This post is a deep dive into how the feature works.</p><h2 id="background"><a href="#background">Background</a></h2><p>If you already know how Postgres and Postgres extensions work internally, you can skip this section.</p><p>A single Postgres server is made up of many running processes. Each client connection to Postgres gets its own dedicated worker <a href="/blog/processes-and-threads">process</a>, and all SQL queries from that client connection run, one at a time, in that worker process. When a client sends a SQL query, the worker process parses it, plans it, executes it, and sends any results back to the client. <a href="/blog/what-is-a-query-planner">Planning</a> is a key step, in which Postgres takes a parsed query and turns it into a step-by-step execution plan that specifies the indexes to use, the order to load rows from multiple tables, and the operators that will be used to filter, aggregate, and join those rows. Most queries can be run using several different plans, so it's the planner's job to estimate the cost of the possible plans and pick the cheapest one.</p><p>Every part of how Postgres handles queries can be modified by extensions. Extensions can add new functions, new data types, new storage systems, and new authentication methods, among other things. (They can also <a href="https://www.vldb.org/pvldb/vol18/p1962-kim.pdf">add new failure modes</a>, but that's a topic for another day.) Extensions can also passively observe and report on traffic, like PlanetScale's own <a href="/docs/postgres/extensions/pginsights"><code>pginsights</code></a> extension that powers <a href="/docs/postgres/monitoring/query-insights">Query Insights</a>.</p><p>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. Want to observe or replace the planner? There's a hook for that. Want to examine queries as they execute? There are three hooks for that. As of this writing, there are <a href="https://github.com/search?q=repo%3Apostgres%2Fpostgres%20%2F%5E%5CS.*%5Cw_hook%20%3D%20NULL%2F&type=code">55 hooks</a> available to anyone writing Postgres extensions.</p><p>PlanetScale's <code>pginsights</code> extension installs hooks for the <code>ExecutorRun</code> and <code>ProcessUtility</code> functions, among others, to run timers and measure resource consumption while SQL statements execute. Since each hook wraps the original Postgres functionality, that means <code>pginsights</code> sees each query just before it executes and again just after it completes. Any time that has elapsed and any resources the worker process has consumed are directly attributable to that query. The extension does some aggregation, sends aggregate data periodically to a data pipeline, and returns control to Postgres to accept the next query.</p><h2 id="insights-hooks-and-blocking-queries"><a href="#insights-hooks-and-blocking-queries">Insights, hooks, and blocking queries</a></h2><p>When we first started planning for Traffic Control, we knew we would use a Postgres extension with a hook on <code>ExecutorRun</code> to decide whether or not each statement would be allowed to run. Initially, we wrote a new extension for this. We soon realized that there are two ways to choose which queries to block: based on static analysis of the individual query, or based on cumulative measurements of resource usage over time. We split the extension along those lines. Blocking based on static analysis got merged into the project that became <a href="/changelog/postgres-extension-pg-strict"><code>pg_strict</code></a>. Blocking based on cumulative resource usage became Traffic Control.</p><p>It turns out Traffic Control needed the same hook points and much of the same information that <code>pginsights</code> already had. So rather than duplicate all that code and impose the extra runtime overhead of another extension, we taught <code>pginsights</code> how to block queries.</p><p><button type="button" aria-haspopup="dialog" aria-expanded="false" aria-label="Enlarge image: How Traffic Control decides whether or not to block a query" class="focus-visible-ring group relative block w-fit max-w-[min(100%,800px)] cursor-zoom-in text-left [&_picture]:contents"><picture class="block"><source media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" srcSet="https://planetscale-images.imgix.net/assets/traffic-control-checks-Dww9PUBq.png?auto=compress%2Cformat"/><source media="(prefers-color-scheme: dark)" srcSet="https://planetscale-images.imgix.net/assets/traffic-control-checks-darkmode-RO3pOuCZ.png?auto=compress%2Cformat"/><img alt="How Traffic Control decides whether or not to block a query" src="https://planetscale-images.imgix.net/assets/traffic-control-checks-Dww9PUBq.png?auto=compress%2Cformat" width="2960" height="2864" loading="lazy" class="w-auto max-w-full"/></picture><span aria-hidden="true" class="pointer-events-none absolute right-1 top-1 z-10 flex h-5 w-5 items-center justify-center border border-white/25 bg-black/70 text-white backdrop-blur-sm transition-colors transition-opacity group-hover:bg-black/90 group-hover:opacity-100 group-focus-visible:opacity-100 motion-reduce:transition-none [@media(hover:hover)_and_(pointer:fine)]:opacity-0"><svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M10 2h4v4M6 14H2v-4M14 2l-4.5 4.5M2 14l4.5-4.5"></path></svg></span></button><span hidden="" style="position:fixed;top:1px;left:1px;width:1px;height:0;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;border-width:0;display:none"></span></p><p>If there are any Traffic Control rules configured, then at the beginning of each query execution, the extension does four things:</p><ol><li>It identifies all of the rules that match the <a href="/docs/postgres/traffic-control/concepts#rules">tags and other metadata</a> of the query. Each rule identifies a budget; multiple rules can map to the same budget.</li><li>It checks to see if any of the applicable budgets has reached its concurrency limit.</li><li>It checks if the query's estimated cost is higher than any applicable budget's per-query limit.</li><li>It checks to see if every applicable budget has enough available capacity for the query to begin execution. In the <a href="/docs/postgres/traffic-control/concepts#resource-budget-limits">documentation</a>, these parameters are described as the burst limit and the server share. As we'll see <a href="#leaky-buckets">below</a>, those parameters combine over time to describe the behavior of a leaky-bucket rate limiter.</li></ol><p>If any budget fails any of these checks, then the query is warned or blocked, based on how the budget is configured.</p><p>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 <a href="https://www.man7.org/linux/man-pages/man7/cgroups.7.html">Linux cgroups</a>, 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 <a href="https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-STATEMENT-TIMEOUT">Postgres <code>statement_timeout</code> setting</a>, which allows any overly expensive query to consume resources until it times out. Traffic Control blocks expensive, low priority queries before they begin.</p><h2 id="cost-prediction"><a href="#cost-prediction">Cost prediction</a></h2><p>I glossed over something important in the last section: cost. The concurrency check is easy, because it just counts worker processes already assigned to the queries associated with a Traffic Control budget. But the other two checks — per-query cost and cumulative cost — require us to know what resources the query will consume before it even begins execution. How do we do that? We trust, but also don't trust, the planner.</p><p>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. To evaluate all the possible plans, the planner has to estimate the cost of each one. When you run <code>EXPLAIN</code> on a SQL statement, Postgres's planner shows the cost of each step in the chosen plan, as well as the overall total cost. The cost is <a href="https://www.postgresql.org/docs/current/runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS">measured in dimensionless units and is based on configurable weights</a> assigned to each step the plan will take. There are a lot of variables that go into the plan cost, most of which you can ignore for the purposes of understanding Traffic Control. Just remember these two things: plan costs are roughly linear (a plan with double the cost should take something like double the time and resources to execute), and the relationship between plan costs and real-world resources is heavily dependent on what query you're running, what server you run it on, and what else is happening on that server at the moment.</p><p>Traffic Control compensates for those dependencies. We assume that there is an unknown constant <code>k</code> 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 <a href="/blog/query-performance-analysis-with-insights">query pattern</a> 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!</p><p>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 <code>k</code> is the ratio of the two.</p><p>Each time a query comes in, Traffic Control multiplies the planner's estimated cost by <code>k</code> to guess how much CPU and/or wall-clock time the query will take. Based on that estimate, Traffic Control decides if the query can be allowed to begin. If it does, then at the end of query execution, Traffic Control updates the two averages for that query pattern so the <code>k</code> value will be more recent and more precise for the next query that arrives.</p><h2 id="leaky-buckets"><a href="#leaky-buckets">Leaky buckets</a></h2><p>Two of the checks that Traffic Control performs for each query are easy: if the query's estimated cost is too high, block it. If too many queries in the same budget are already running, block it. But the final check — is there enough capacity in the budget to proceed — is harder. It's important, though! Many executions of a moderately expensive query can be even more damaging than a single very expensive query, and managing a budget over time is the best way to block queries that are only expensive in aggregate. Traffic Control considers the cumulative cost of queries in each configured budget.</p><p><button type="button" aria-haspopup="dialog" aria-expanded="false" aria-label="Enlarge image: Reverse leaky bucket" class="focus-visible-ring group relative block w-fit max-w-[min(100%,800px)] cursor-zoom-in text-left [&_picture]:contents"><picture class="block"><source media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" srcSet="https://planetscale-images.imgix.net/assets/traffic-control-leaky-bucket-DiqkqEyT.png?auto=compress%2Cformat"/><source media="(prefers-color-scheme: dark)" srcSet="https://planetscale-images.imgix.net/assets/traffic-control-leaky-bucket-darkmode-YEz2CO8P.png?auto=compress%2Cformat"/><img alt="Reverse leaky bucket" src="https://planetscale-images.imgix.net/assets/traffic-control-leaky-bucket-DiqkqEyT.png?auto=compress%2Cformat" width="2412" height="1636" loading="lazy" class="w-auto max-w-full"/></picture><span aria-hidden="true" class="pointer-events-none absolute right-1 top-1 z-10 flex h-5 w-5 items-center justify-center border border-white/25 bg-black/70 text-white backdrop-blur-sm transition-colors transition-opacity group-hover:bg-black/90 group-hover:opacity-100 group-focus-visible:opacity-100 motion-reduce:transition-none [@media(hover:hover)_and_(pointer:fine)]:opacity-0"><svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M10 2h4v4M6 14H2v-4M14 2l-4.5 4.5M2 14l4.5-4.5"></path></svg></span></button><span hidden="" style="position:fixed;top:1px;left:1px;width:1px;height:0;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;border-width:0;display:none"></span></p><p>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 <a href="/docs/postgres/traffic-control/concepts#resource-budget-limits">two important parameters</a>: its size and its drain rate. The size dictates the <strong>burst limit</strong>, or what total resources queries under a given budget can use in a short amount of time. The drain rate dictates the <strong>server share</strong>, or what fraction of overall resources queries under a given budget can use in the long term.</p><p>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. We store as many buckets as will fit in a configurable amount of shared memory, and we evict them implicitly when their debt falls to zero.</p><p>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.</p><h2 id="rule-sets"><a href="#rule-sets">Rule sets</a></h2><p>One important goal for Traffic Control is that it can efficiently decide when not to block a query. After all, Traffic Control has to make that decision before each query is even allowed to begin execution. So 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 <code>n</code> rules in <code>O(1)</code> time.</p><p><button type="button" aria-haspopup="dialog" aria-expanded="false" aria-label="Enlarge image: RuleSet data structure" class="focus-visible-ring group relative block w-fit max-w-[min(100%,800px)] cursor-zoom-in text-left [&_picture]:contents"><picture class="block"><source media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" srcSet="https://planetscale-images.imgix.net/assets/traffic-control-rule-set-D8I0PDRX.png?auto=compress%2Cformat"/><source media="(prefers-color-scheme: dark)" srcSet="https://planetscale-images.imgix.net/assets/traffic-control-rule-set-darkmode-lxM-eKyc.png?auto=compress%2Cformat"/><img alt="RuleSet data structure" src="https://planetscale-images.imgix.net/assets/traffic-control-rule-set-D8I0PDRX.png?auto=compress%2Cformat" width="5308" height="1272" loading="lazy" class="w-auto max-w-full"/></picture><span aria-hidden="true" class="pointer-events-none absolute right-1 top-1 z-10 flex h-5 w-5 items-center justify-center border border-white/25 bg-black/70 text-white backdrop-blur-sm transition-colors transition-opacity group-hover:bg-black/90 group-hover:opacity-100 group-focus-visible:opacity-100 motion-reduce:transition-none [@media(hover:hover)_and_(pointer:fine)]:opacity-0"><svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M10 2h4v4M6 14H2v-4M14 2l-4.5 4.5M2 14l4.5-4.5"></path></svg></span></button><span hidden="" style="position:fixed;top:1px;left:1px;width:1px;height:0;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;border-width:0;display:none"></span></p><p>Each rule has the form <code><key, value></code>, and it matches any query that has that same value for that same key. It's complicated a bit by the fact that <code>value</code> can be an IP address with a CIDR mask.</p><p>A rule set maps each <code><key, value></code> pair to a rule. Now, when a query comes in with metadata like <code>username=postgres, app=commerce, controller=api</code>, 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.</p><p>Note that a rule set only <em>identifies rules to consider</em>. 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.</p><p>There are three exceptions to the <code>O(1)</code> target for identifying rules:</p><ol><li>Rules for the <code>remote_address</code> 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.</li><li>Any conjunction rule — that is, a rule with multiple <code><key, value></code> pairs ANDed together — may be identified as a candidate for queries that match any one of the <code><key, value></code> pairs in the rule. So if you have conjunction rules with overlapping <code><key, value></code> pairs, the rule set may identify several or all of them as candidates for each query.</li><li>It is possible to add multiple rules for the exact same <code><key, value></code> pair. If you do that, any query with that exact <code><key, value></code> pair will get checked against all of those rules.</li></ol><h2 id="applying-new-rules"><a href="#applying-new-rules">Applying new rules</a></h2><p>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?</p><p>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 <code>planetscale</code> database. Then it's serialized as JSON in the <code>traffic_control.rules</code> and <code>traffic_control.budgets</code> 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 <code>postgresql.conf</code> 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.</p><p>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.</p><h2 id="wrap-up"><a href="#wrap-up">Wrap up</a></h2><p>Traffic Control uses the hooks and the performance measurements that Query Insights already implemented, then bolts on a system for sorting query traffic into budgets and warning or blocking queries that exceed those budgets. Each query can be warned or blocked if it's individually too expensive, if too many other queries are already running under the same budget, or if recent and concurrent queries under the same budget have consumed too many resources in the aggregate. Traffic Control implements a dynamic model per query pattern that leverages the existing Postgres planner to estimate the real-world cost of a query before it begins to execute. Leaky buckets impose limits on both traffic bursts and the long-term average fraction of server resources assigned to any individual budget.</p><p>Taken as a whole, these elements implement Traffic Control, which gives developers and database administrators powerful new tools to identify, prioritize, and limit SQL traffic.</p></div></article></div></section></main><footer class="mb-6 mt-10 px-3 sm:px-5 container max-w-7xl"><nav class="grid grid-cols-1 text-left sm:grid-cols-2 lg:grid-cols-5 lg:mx-7"><div class="dashed-box dashed-box-x-t sm:dashed-box-l-t lg:dashed-box-y-l p-3"><h2 class="font-semibold">Company</h2><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/about" data-discover="true">About</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/brand" data-discover="true">Brand</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/blog" data-discover="true">Blog</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/changelog" data-discover="true">Changelog</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/careers" data-discover="true">Careers</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/events" data-discover="true">Events</a></div><div class="dashed-box dashed-box-x-t lg:dashed-box-y-l p-3"><h2 class="font-semibold">Product</h2><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/case-studies" data-discover="true">Case studies</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/enterprise" data-discover="true">Enterprise</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/pricing" data-discover="true">Pricing</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/benchmarks" data-discover="true">Benchmarks</a></div><div class="dashed-box dashed-box-x-t sm:dashed-box-l-t lg:dashed-box-y-l p-3"><h2 class="font-semibold">Resources</h2><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/docs">Documentation</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/migrate" data-discover="true">Migrate</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="https://support.planetscale.com/hc/en-us" rel="nofollow noopener noreferrer" target="_blank">Support</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="https://planetscalestatus.com" rel="nofollow noopener noreferrer" target="_blank">Status</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="https://trust.planetscale.com" rel="nofollow noopener noreferrer" target="_blank">Trust Center</a></div><div class="dashed-box dashed-box-x-t lg:dashed-box-y-l p-3"><h2 class="font-semibold">Courses</h2><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/learn/courses/mysql-for-developers" data-discover="true">MySQL for Developers</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/learn/courses/database-scaling" data-discover="true">Database Scaling</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/learn/courses/vitess" data-discover="true">Learn Vitess</a></div><div class="dashed-box p-3 sm:col-span-2 lg:col-span-1"><h2 class="font-semibold text-primary hover:text-contrast">Open source</h2><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="/vitess" data-discover="true">Vitess</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="https://vitess.io/slack" rel="nofollow noopener noreferrer" target="_blank">Vitess community</a><a class="block pl-1ch -indent-1ch text-primary hover:text-contrast" href="https://github.com/planetscale" rel="me nofollow noopener noreferrer" target="_blank">GitHub</a></div></nav><div class="dashed-box dashed-box-x-b p-3 lg:mx-7"><p class="mb-3 md:mb-0"><a class="text-primary" rel="nofollow" href="/legal/privacy" data-discover="true">Privacy</a><span class="text-decoration" role="presentation"> <!-- -->|<!-- --> </span><a class="text-primary" rel="nofollow" href="/legal/siteterms" data-discover="true">Terms</a><span class="text-decoration" role="presentation"> <!-- -->|<!-- --> </span><a class="text-primary" rel="nofollow" href="/legal/cookies" data-discover="true">Cookies</a><span class="text-decoration" role="presentation"> <!-- -->|<!-- --> </span><a class="text-primary" rel="nofollow" href="/legal/patents" data-discover="true">Patents</a><span class="text-decoration" role="presentation"> <!-- -->|<!-- --> </span><a class="text-primary" rel="nofollow" href="/legal/privacy#privacy-rights-and-choices" data-discover="true">Do Not Share My Personal Information</a></p><p class="text-secondary">© <!-- -->2026<!-- --> PlanetScale, Inc. All rights reserved.</p></div><p class="mb-0 mt-3 break-normal lg:mx-7"><a class="text-primary" href="https://github.com/planetscale" rel="me nofollow noopener noreferrer" target="_blank">GitHub</a><span class="text-decoration" role="presentation"> <!-- -->|<!-- --> </span><a aria-label="X (formerly Twitter)" class="text-primary" href="https://twitter.com/planetscale" rel="me nofollow noopener noreferrer" target="_blank">X</a><span class="text-decoration" role="presentation"> <!-- -->|<!-- --> </span><a aria-label="LinkedIn" class="text-primary" href="https://www.linkedin.com/company/planetscale" target="_blank" rel="noreferrer">LinkedIn</a><span class="text-decoration" role="presentation"> <!-- -->|<!-- --> </span><a class="text-primary" href="https://www.youtube.com/planetscale" rel="me nofollow noopener noreferrer" target="_blank">YouTube</a><span class="text-decoration" role="presentation"> <!-- -->|<!-- --> </span><a aria-label="Discord" class="text-primary" href="https://pscale.link/community" rel="nofollow noopener noreferrer" target="_blank">Discord</a><span class="text-decoration" role="presentation"> <!-- -->|<!-- --> </span><a class="text-primary" href="https://www.facebook.com/planetscaledata" rel="me nofollow noopener noreferrer" target="_blank">Facebook</a></p></footer><script nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ=">((storageKey2, restoreKey) => {
|
|
if (!window.history.state || !window.history.state.key) {
|
|
let key2 = Math.random().toString(32).slice(2);
|
|
window.history.replaceState({ key: key2 }, "");
|
|
}
|
|
try {
|
|
let storedY = JSON.parse(sessionStorage.getItem(storageKey2) || "{}")[restoreKey || window.history.state.key];
|
|
if (typeof storedY === "number") window.scrollTo(0, storedY);
|
|
} catch (error2) {
|
|
console.error(error2);
|
|
sessionStorage.removeItem(storageKey2);
|
|
}
|
|
})("react-router-scroll-positions", null)</script><script nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ=">window.__reactRouterContext = {"basename":"/","future":{"unstable_enableNodeReadableStream":false,"unstable_optimizeDeps":true},"routeDiscovery":{"mode":"lazy","manifestPath":"/__manifest"},"ssr":true,"isSpaMode":false};window.__reactRouterContext.stream = new ReadableStream({start(controller){window.__reactRouterContext.streamController = controller;}}).pipeThrough(new TextEncoderStream());</script><script nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ=" type="module" async="">;
|
|
import * as route0 from "/assets/root-DbOv4-98.js";
|
|
import * as route1 from "/assets/blog-pXH7ptHJ.js";
|
|
import * as route2 from "/assets/blog._slug-Ch_92qsH.js";
|
|
window.__reactRouterManifest = {
|
|
"entry": {
|
|
"module": "/assets/entry.client-3vubyXrk.js",
|
|
"imports": [
|
|
"/assets/jsx-runtime-DwfQwkRq.js",
|
|
"/assets/components-_bNmAApg.js",
|
|
"/assets/_.well-known_.mcp.server-card_.json_-Sx7XeH3e.js",
|
|
"/assets/index-mKTXLmHu.js",
|
|
"/assets/errorBoundaries-DhW4jVYt.js"
|
|
],
|
|
"css": []
|
|
},
|
|
"routes": {
|
|
"root": {
|
|
"id": "root",
|
|
"path": "",
|
|
"hasAction": false,
|
|
"hasLoader": true,
|
|
"hasClientAction": false,
|
|
"hasClientLoader": false,
|
|
"hasClientMiddleware": false,
|
|
"hasDefaultExport": true,
|
|
"hasErrorBoundary": true,
|
|
"module": "/assets/root-DbOv4-98.js",
|
|
"imports": [
|
|
"/assets/jsx-runtime-DwfQwkRq.js",
|
|
"/assets/components-_bNmAApg.js",
|
|
"/assets/_.well-known_.mcp.server-card_.json_-Sx7XeH3e.js",
|
|
"/assets/index-mKTXLmHu.js",
|
|
"/assets/errorBoundaries-DhW4jVYt.js",
|
|
"/assets/lib-Dg89tQ22.js",
|
|
"/assets/analytics.client-DM6E8o1h.js",
|
|
"/assets/SiteHeader-C2U5gvDH.js",
|
|
"/assets/current-9yDxj94E.js",
|
|
"/assets/clsx-eT0YPcGk.js",
|
|
"/assets/bugs-38ilEoW0.js",
|
|
"/assets/keyboard-D-uXZORL.js",
|
|
"/assets/use-tab-direction-dKm-S3Ck.js"
|
|
],
|
|
"css": []
|
|
},
|
|
"routes/blog": {
|
|
"id": "routes/blog",
|
|
"parentId": "root",
|
|
"path": "blog",
|
|
"hasAction": false,
|
|
"hasLoader": false,
|
|
"hasClientAction": false,
|
|
"hasClientLoader": false,
|
|
"hasClientMiddleware": false,
|
|
"hasDefaultExport": false,
|
|
"hasErrorBoundary": false,
|
|
"module": "/assets/blog-pXH7ptHJ.js",
|
|
"imports": [
|
|
"/assets/_.well-known_.mcp.server-card_.json_-Sx7XeH3e.js"
|
|
],
|
|
"css": []
|
|
},
|
|
"routes/blog.$slug": {
|
|
"id": "routes/blog.$slug",
|
|
"parentId": "routes/blog",
|
|
"path": ":slug",
|
|
"hasAction": false,
|
|
"hasLoader": true,
|
|
"hasClientAction": false,
|
|
"hasClientLoader": false,
|
|
"hasClientMiddleware": false,
|
|
"hasDefaultExport": true,
|
|
"hasErrorBoundary": false,
|
|
"module": "/assets/blog._slug-Ch_92qsH.js",
|
|
"imports": [
|
|
"/assets/components-_bNmAApg.js",
|
|
"/assets/lib-Dg89tQ22.js",
|
|
"/assets/jsx-runtime-DwfQwkRq.js",
|
|
"/assets/ContentImage-Dh6VEOUl.js",
|
|
"/assets/clsx-eT0YPcGk.js",
|
|
"/assets/BlogCategoryLink-DmQyn0gp.js",
|
|
"/assets/_.well-known_.mcp.server-card_.json_-Sx7XeH3e.js",
|
|
"/assets/Details-BSB_b6hI.js",
|
|
"/assets/Skittle-CDFOPRjH.js",
|
|
"/assets/SiteFooter-B2Gq9u2j.js",
|
|
"/assets/SiteHeader-C2U5gvDH.js",
|
|
"/assets/Vimeo-00PQJDli.js",
|
|
"/assets/YouTube-CMfaljVr.js",
|
|
"/assets/date-CJTFH3uT.js",
|
|
"/assets/errorBoundaries-DhW4jVYt.js",
|
|
"/assets/keyboard-D-uXZORL.js",
|
|
"/assets/use-tab-direction-dKm-S3Ck.js",
|
|
"/assets/index-mKTXLmHu.js",
|
|
"/assets/use-inert-others-BMJ6-xOX.js",
|
|
"/assets/description-Cf6FZmDe.js",
|
|
"/assets/use-is-mounted-uQsUZyP9.js",
|
|
"/assets/types-DvonrUFF.js",
|
|
"/assets/current-9yDxj94E.js",
|
|
"/assets/analytics.client-DM6E8o1h.js",
|
|
"/assets/bugs-38ilEoW0.js"
|
|
],
|
|
"css": []
|
|
},
|
|
"routes/_index": {
|
|
"id": "routes/_index",
|
|
"parentId": "root",
|
|
"index": true,
|
|
"hasAction": false,
|
|
"hasLoader": true,
|
|
"hasClientAction": false,
|
|
"hasClientLoader": false,
|
|
"hasClientMiddleware": false,
|
|
"hasDefaultExport": true,
|
|
"hasErrorBoundary": false,
|
|
"module": "/assets/_index-BfA6EnlR.js",
|
|
"imports": [
|
|
"/assets/components-_bNmAApg.js",
|
|
"/assets/lib-Dg89tQ22.js",
|
|
"/assets/jsx-runtime-DwfQwkRq.js",
|
|
"/assets/Logo-Gm9TLYAs.js",
|
|
"/assets/SiteFooter-B2Gq9u2j.js",
|
|
"/assets/SiteHeader-C2U5gvDH.js",
|
|
"/assets/_.well-known_.mcp.server-card_.json_-Sx7XeH3e.js",
|
|
"/assets/bugs-38ilEoW0.js",
|
|
"/assets/keyboard-D-uXZORL.js",
|
|
"/assets/use-is-mounted-uQsUZyP9.js",
|
|
"/assets/use-tab-direction-dKm-S3Ck.js",
|
|
"/assets/errorBoundaries-DhW4jVYt.js",
|
|
"/assets/clsx-eT0YPcGk.js",
|
|
"/assets/current-9yDxj94E.js",
|
|
"/assets/analytics.client-DM6E8o1h.js",
|
|
"/assets/index-mKTXLmHu.js"
|
|
],
|
|
"css": []
|
|
},
|
|
"routes/blog._index": {
|
|
"id": "routes/blog._index",
|
|
"parentId": "routes/blog",
|
|
"index": true,
|
|
"hasAction": false,
|
|
"hasLoader": true,
|
|
"hasClientAction": false,
|
|
"hasClientLoader": false,
|
|
"hasClientMiddleware": false,
|
|
"hasDefaultExport": true,
|
|
"hasErrorBoundary": false,
|
|
"module": "/assets/blog._index-DcvTTuDd.js",
|
|
"imports": [
|
|
"/assets/components-_bNmAApg.js",
|
|
"/assets/jsx-runtime-DwfQwkRq.js",
|
|
"/assets/social-Cd2AtOZM.js",
|
|
"/assets/BlogCategoryLink-DmQyn0gp.js",
|
|
"/assets/BlogPostLink-DC1SPKBJ.js",
|
|
"/assets/BlogCategoryNav-CB7TJ3IB.js",
|
|
"/assets/Paginator-xlPA_JNt.js",
|
|
"/assets/SiteFooter-B2Gq9u2j.js",
|
|
"/assets/SiteHeader-C2U5gvDH.js",
|
|
"/assets/date-CJTFH3uT.js",
|
|
"/assets/_.well-known_.mcp.server-card_.json_-Sx7XeH3e.js",
|
|
"/assets/lib-Dg89tQ22.js",
|
|
"/assets/errorBoundaries-DhW4jVYt.js",
|
|
"/assets/clsx-eT0YPcGk.js",
|
|
"/assets/types-DvonrUFF.js",
|
|
"/assets/enumerator-2YLGh-nT.js",
|
|
"/assets/current-9yDxj94E.js",
|
|
"/assets/analytics.client-DM6E8o1h.js",
|
|
"/assets/bugs-38ilEoW0.js",
|
|
"/assets/keyboard-D-uXZORL.js",
|
|
"/assets/use-tab-direction-dKm-S3Ck.js",
|
|
"/assets/index-mKTXLmHu.js"
|
|
],
|
|
"css": []
|
|
}
|
|
},
|
|
"url": "/assets/manifest-e17deb94.js",
|
|
"version": "e17deb94"
|
|
};
|
|
window.__reactRouterRouteModules = {"root":route0,"routes/blog":route1,"routes/blog.$slug":route2};
|
|
|
|
import("/assets/entry.client-3vubyXrk.js");</script><script type="application/ld+json" nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ=">{"@context":"https://schema.org","@type":"Organization","name":"PlanetScale, Inc.","url":"https://planetscale.com","sameAs":["https://twitter.com/PlanetScale","https://www.facebook.com/planetscaledata/","https://www.instagram.com/planetscale/"],"address":{"@type":"PostalAddress","streetAddress":"WeWork c/o PlanetScale, 535 Mission Street, 14th Floor","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94105","addressCountry":"US"}}</script><!--$--><script nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ=">window.__reactRouterContext.streamController.enqueue("[{\"_1\":2,\"_3\":-5,\"_4\":-5},\"loaderData\",{\"_5\":6,\"_7\":8},\"actionData\",\"errors\",\"root\",{\"_711\":712},\"routes/blog.$slug\",{\"_9\":10,\"_5\":11},\"blog\",{\"_12\":13,\"_14\":15,\"_16\":-7,\"_17\":18,\"_19\":20,\"_21\":22,\"_23\":24,\"_25\":26,\"_27\":28,\"_29\":30,\"_31\":32},\"https://planetscale.com\",\"body\",[76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117],\"body_text\",\"Today, we released Database Traffic Control®, a feature for mitigating and preventing database overload due to unexpectedly expensive SQL queries. For an overview, read the blog post introducing the feature, and to get started using it, read the reference documentation. This post is a deep dive into how the feature works.\\nBackground\\nIf you already know how Postgres and Postgres extensions work internally, you can skip this section.\\nA single Postgres server is made up of many running processes. Each client connection to Postgres gets its own dedicated worker process, and all SQL queries from that client connection run, one at a time, in that worker process. When a client sends a SQL query, the worker process parses it, plans it, executes it, and sends any results back to the client. Planning is a key step, in which Postgres takes a parsed query and turns it into a step-by-step execution plan that specifies the indexes to use, the order to load rows from multiple tables, and the operators that will be used to filter, aggregate, and join those rows. Most queries can be run using several different plans, so it's the planner's job to estimate the cost of the possible plans and pick the cheapest one.\\nEvery part of how Postgres handles queries can be modified by extensions. Extensions can add new functions, new data types, new storage systems, and new authentication methods, among other things. (They can also add new failure modes, but that's a topic for another day.) Extensions can also passively observe and report on traffic, like PlanetScale's own pginsights extension that powers Query Insights.\\nMuch 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. Want to observe or replace the planner? There's a hook for that. Want to examine queries as they execute? There are three hooks for that. As of this writing, there are 55 hooks available to anyone writing Postgres extensions.\\nPlanetScale's pginsights extension installs hooks for the ExecutorRun and ProcessUtility functions, among others, to run timers and measure resource consumption while SQL statements execute. Since each hook wraps the original Postgres functionality, that means pginsights sees each query just before it executes and again just after it completes. Any time that has elapsed and any resources the worker process has consumed are directly attributable to that query. The extension does some aggregation, sends aggregate data periodically to a data pipeline, and returns control to Postgres to accept the next query.\\nInsights, hooks, and blocking queries\\nWhen we first started planning for Traffic Control, we knew we would use a Postgres extension with a hook on ExecutorRun to decide whether or not each statement would be allowed to run. Initially, we wrote a new extension for this. We soon realized that there are two ways to choose which queries to block: based on static analysis of the individual query, or based on cumulative measurements of resource usage over time. We split the extension along those lines. Blocking based on static analysis got merged into the project that became pg_strict. Blocking based on cumulative resource usage became Traffic Control.\\nIt 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.\\n\\nIf there are any Traffic Control rules configured, then at the beginning of each query execution, the extension does four things:\\nIt 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.\\nIt checks to see if any of the applicable budgets has reached its concurrency limit.\\nIt checks if the query's estimated cost is higher than any applicable budget's per-query limit.\\nIt checks to see if every applicable budget has enough available capacity for the query to begin execution. In the documentation, these parameters are described as the burst limit and the server share. As we'll see below, those parameters combine over time to describe the behavior of a leaky-bucket rate limiter.\\nIf any budget fails any of these checks, then the query is warned or blocked, based on how the budget is configured.\\nBlocking 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.\\nCost prediction\\nI glossed over something important in the last section: cost. The concurrency check is easy, because it just counts worker processes already assigned to the queries associated with a Traffic Control budget. But the other two checks — per-query cost and cumulative cost — require us to know what resources the query will consume before it even begins execution. How do we do that? We trust, but also don't trust, the planner.\\nA SQL query planner takes a parsed SQL statement and selects what it hopes is the most efficient series of steps to execute that query. To evaluate all the possible plans, the planner has to estimate the cost of each one. When you run EXPLAIN on a SQL statement, Postgres's planner shows the cost of each step in the chosen plan, as well as the overall total cost. The cost is measured in dimensionless units and is based on configurable weights assigned to each step the plan will take. There are a lot of variables that go into the plan cost, most of which you can ignore for the purposes of understanding Traffic Control. Just remember these two things: plan costs are roughly linear (a plan with double the cost should take something like double the time and resources to execute), and the relationship between plan costs and real-world resources is heavily dependent on what query you're running, what server you run it on, and what else is happening on that server at the moment.\\nTraffic Control compensates for those dependencies. 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!\\nTraffic 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.\\nEach time a query comes in, Traffic Control multiplies the planner's estimated cost by k to guess how much CPU and/or wall-clock time the query will take. Based on that estimate, Traffic Control decides if the query can be allowed to begin. If it does, then at the end of query execution, Traffic Control updates the two averages for that query pattern so the k value will be more recent and more precise for the next query that arrives.\\nLeaky buckets\\nTwo of the checks that Traffic Control performs for each query are easy: if the query's estimated cost is too high, block it. If too many queries in the same budget are already running, block it. But the final check — is there enough capacity in the budget to proceed — is harder. It's important, though! Many executions of a moderately expensive query can be even more damaging than a single very expensive query, and managing a budget over time is the best way to block queries that are only expensive in aggregate. Traffic Control considers the cumulative cost of queries in each configured budget.\\n\\nEach 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, or what total resources queries under a given budget can use in a short amount of time. The drain rate dictates the server share, or what fraction of overall resources queries under a given budget can use in the long term.\\nTraditionally, 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. We store as many buckets as will fit in a configurable amount of shared memory, and we evict them implicitly when their debt falls to zero.\\nThere 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.\\nRule sets\\nOne important goal for Traffic Control is that it can efficiently decide when not to block a query. After all, Traffic Control has to make that decision before each query is even allowed to begin execution. So 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.\\n\\nEach rule has the form \u003ckey, value\u003e, and it matches any query that has that same value for that same key. It's complicated a bit by the fact that value can be an IP address with a CIDR mask.\\nA rule set maps each \u003ckey, value\u003e 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.\\nNote 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.\\nThere are three exceptions to the O(1) target for identifying rules:\\nRules 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.\\nAny conjunction rule — that is, a rule with multiple \u003ckey, value\u003e pairs ANDed together — may be identified as a candidate for queries that match any one of the \u003ckey, value\u003e pairs in the rule. So if you have conjunction rules with overlapping \u003ckey, value\u003e pairs, the rule set may identify several or all of them as candidates for each query.\\nIt is possible to add multiple rules for the exact same \u003ckey, value\u003e pair. If you do that, any query with that exact \u003ckey, value\u003e pair will get checked against all of those rules.\\nApplying new rules\\nTraffic 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?\\nRules 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.\\nOne 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.\\nWrap up\\nTraffic Control uses the hooks and the performance measurements that Query Insights already implemented, then bolts on a system for sorting query traffic into budgets and warning or blocking queries that exceed those budgets. Each query can be warned or blocked if it's individually too expensive, if too many other queries are already running under the same budget, or if recent and concurrent queries under the same budget have consumed too many resources in the aggregate. Traffic Control implements a dynamic model per query pattern that leverages the existing Postgres planner to estimate the real-world cost of a query before it begins to execute. Leaky buckets impose limits on both traffic bursts and the long-term average fraction of server resources assigned to any individual budget.\\nTaken as a whole, these elements implement Traffic Control, which gives developers and database administrators powerful new tools to identify, prioritize, and limit SQL traffic.\",\"aside\",\"toc\",[44,45,46,47,48,49,50],\"title\",\"Behind the scenes: How Database Traffic Control works\",\"authors\",[40],\"categories\",[38,39],\"excerpt\",\"Learn how Traffic Control enforces real-time limits on Postgres queries.\",\"createdAt\",\"2026-03-23T16:00:00.000Z\",\"slug\",\"behind-the-scenes-how-traffic-control-works\",\"meta\",{\"_33\":34,\"_35\":26,\"_36\":37,\"_19\":20},\"canonical\",\"https://planetscale.com/blog/behind-the-scenes-how-traffic-control-works\",\"description\",\"image\",\"/assets/behind-the-scenes-how-traffic-control-works-social-MNXbuFQ_.png\",\"engineering\",\"postgres\",{\"_29\":41,\"_42\":43},\"piki\",\"name\",\"Patrick Reynolds\",{\"_51\":73,\"_53\":74,\"_55\":56,\"_19\":75},{\"_51\":70,\"_53\":71,\"_55\":56,\"_19\":72},{\"_51\":67,\"_53\":68,\"_55\":56,\"_19\":69},{\"_51\":64,\"_53\":65,\"_55\":56,\"_19\":66},{\"_51\":61,\"_53\":62,\"_55\":56,\"_19\":63},{\"_51\":58,\"_53\":59,\"_55\":56,\"_19\":60},{\"_51\":52,\"_53\":54,\"_55\":56,\"_19\":57},\"children\",[],\"id\",\"wrap-up\",\"level\",2,\"Wrap up\",[],\"applying-new-rules\",\"Applying new rules\",[],\"rule-sets\",\"Rule sets\",[],\"leaky-buckets\",\"Leaky buckets\",[],\"cost-prediction\",\"Cost prediction\",[],\"insights-hooks-and-blocking-queries\",\"Insights, hooks, and blocking queries\",[],\"background\",\"Background\",[\"SingleFetchClassInstance\",693],[\"SingleFetchClassInstance\",685],[\"SingleFetchClassInstance\",681],[\"SingleFetchClassInstance\",663],[\"SingleFetchClassInstance\",635],[\"SingleFetchClassInstance\",624],[\"SingleFetchClassInstance\",600],[\"SingleFetchClassInstance\",592],[\"SingleFetchClassInstance\",571],[\"SingleFetchClassInstance\",556],[\"SingleFetchClassInstance\",541],[\"SingleFetchClassInstance\",537],[\"SingleFetchClassInstance\",495],[\"SingleFetchClassInstance\",491],[\"SingleFetchClassInstance\",467],[\"SingleFetchClassInstance\",459],[\"SingleFetchClassInstance\",455],[\"SingleFetchClassInstance\",438],[\"SingleFetchClassInstance\",422],[\"SingleFetchClassInstance\",413],[\"SingleFetchClassInstance\",398],[\"SingleFetchClassInstance\",390],[\"SingleFetchClassInstance\",386],[\"SingleFetchClassInstance\",371],[\"SingleFetchClassInstance\",347],[\"SingleFetchClassInstance\",343],[\"SingleFetchClassInstance\",339],[\"SingleFetchClassInstance\",331],[\"SingleFetchClassInstance\",316],[\"SingleFetchClassInstance\",289],[\"SingleFetchClassInstance\",274],[\"SingleFetchClassInstance\",259],[\"SingleFetchClassInstance\",248],[\"SingleFetchClassInstance\",238],[\"SingleFetchClassInstance\",186],[\"SingleFetchClassInstance\",178],[\"SingleFetchClassInstance\",174],[\"SingleFetchClassInstance\",145],[\"SingleFetchClassInstance\",141],[\"SingleFetchClassInstance\",130],[\"SingleFetchClassInstance\",126],[\"SingleFetchClassInstance\",118],{\"_119\":120,\"_42\":121,\"_122\":123,\"_51\":124},\"$$mdtype\",\"Tag\",\"p\",\"attributes\",{},[125],\"Taken as a whole, these elements implement Traffic Control, which gives developers and database administrators powerful new tools to identify, prioritize, and limit SQL traffic.\",{\"_119\":120,\"_42\":121,\"_122\":127,\"_51\":128},{},[129],\"Traffic Control uses the hooks and the performance measurements that Query Insights already implemented, then bolts on a system for sorting query traffic into budgets and warning or blocking queries that exceed those budgets. Each query can be warned or blocked if it's individually too expensive, if too many other queries are already running under the same budget, or if recent and concurrent queries under the same budget have consumed too many resources in the aggregate. Traffic Control implements a dynamic model per query pattern that leverages the existing Postgres planner to estimate the real-world cost of a query before it begins to execute. Leaky buckets impose limits on both traffic bursts and the long-term average fraction of server resources assigned to any individual budget.\",{\"_119\":120,\"_42\":131,\"_122\":132,\"_51\":133},\"h2\",{\"_53\":54},[134],[\"SingleFetchClassInstance\",135],{\"_119\":120,\"_42\":136,\"_122\":137,\"_51\":138},\"a\",{\"_139\":140},[57],\"href\",\"#wrap-up\",{\"_119\":120,\"_42\":121,\"_122\":142,\"_51\":143},{},[144],\"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.\",{\"_119\":120,\"_42\":121,\"_122\":146,\"_51\":147},{},[148,149,150,151,152,153,154,155,156],\"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 \",[\"SingleFetchClassInstance\",170],\" database. Then it's serialized as JSON in the \",[\"SingleFetchClassInstance\",166],\" and \",[\"SingleFetchClassInstance\",162],\" 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 \",[\"SingleFetchClassInstance\",157],\" 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.\",{\"_119\":120,\"_42\":158,\"_122\":159,\"_51\":160},\"code\",{},[161],\"postgresql.conf\",{\"_119\":120,\"_42\":158,\"_122\":163,\"_51\":164},{},[165],\"traffic_control.budgets\",{\"_119\":120,\"_42\":158,\"_122\":167,\"_51\":168},{},[169],\"traffic_control.rules\",{\"_119\":120,\"_42\":158,\"_122\":171,\"_51\":172},{},[173],\"planetscale\",{\"_119\":120,\"_42\":121,\"_122\":175,\"_51\":176},{},[177],\"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?\",{\"_119\":120,\"_42\":131,\"_122\":179,\"_51\":180},{\"_53\":59},[181],[\"SingleFetchClassInstance\",182],{\"_119\":120,\"_42\":136,\"_122\":183,\"_51\":184},{\"_139\":185},[60],\"#applying-new-rules\",{\"_119\":120,\"_42\":187,\"_122\":188,\"_51\":189},\"ol\",{},[190,191,192],[\"SingleFetchClassInstance\",228],[\"SingleFetchClassInstance\",209],[\"SingleFetchClassInstance\",193],{\"_119\":120,\"_42\":194,\"_122\":195,\"_51\":196},\"li\",{},[197,198,199,200,201],\"It is possible to add multiple rules for the exact same \",[\"SingleFetchClassInstance\",206],\" pair. If you do that, any query with that exact \",[\"SingleFetchClassInstance\",202],\" pair will get checked against all of those rules.\",{\"_119\":120,\"_42\":158,\"_122\":203,\"_51\":204},{},[205],\"\u003ckey, value\u003e\",{\"_119\":120,\"_42\":158,\"_122\":207,\"_51\":208},{},[205],{\"_119\":120,\"_42\":194,\"_122\":210,\"_51\":211},{},[212,213,214,215,216,217,218],\"Any conjunction rule — that is, a rule with multiple \",[\"SingleFetchClassInstance\",225],\" pairs ANDed together — may be identified as a candidate for queries that match any one of the \",[\"SingleFetchClassInstance\",222],\" pairs in the rule. So if you have conjunction rules with overlapping \",[\"SingleFetchClassInstance\",219],\" pairs, the rule set may identify several or all of them as candidates for each query.\",{\"_119\":120,\"_42\":158,\"_122\":220,\"_51\":221},{},[205],{\"_119\":120,\"_42\":158,\"_122\":223,\"_51\":224},{},[205],{\"_119\":120,\"_42\":158,\"_122\":226,\"_51\":227},{},[205],{\"_119\":120,\"_42\":194,\"_122\":229,\"_51\":230},{},[231,232,233],\"Rules for the \",[\"SingleFetchClassInstance\",234],\" 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.\",{\"_119\":120,\"_42\":158,\"_122\":235,\"_51\":236},{},[237],\"remote_address\",{\"_119\":120,\"_42\":121,\"_122\":239,\"_51\":240},{},[241,242,243],\"There are three exceptions to the \",[\"SingleFetchClassInstance\",244],\" target for identifying rules:\",{\"_119\":120,\"_42\":158,\"_122\":245,\"_51\":246},{},[247],\"O(1)\",{\"_119\":120,\"_42\":121,\"_122\":249,\"_51\":250},{},[251,252,253],\"Note that a rule set only \",[\"SingleFetchClassInstance\",254],\". 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.\",{\"_119\":120,\"_42\":255,\"_122\":256,\"_51\":257},\"em\",{},[258],\"identifies rules to consider\",{\"_119\":120,\"_42\":121,\"_122\":260,\"_51\":261},{},[262,263,264,265,266],\"A rule set maps each \",[\"SingleFetchClassInstance\",271],\" pair to a rule. Now, when a query comes in with metadata like \",[\"SingleFetchClassInstance\",267],\", 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.\",{\"_119\":120,\"_42\":158,\"_122\":268,\"_51\":269},{},[270],\"username=postgres, app=commerce, controller=api\",{\"_119\":120,\"_42\":158,\"_122\":272,\"_51\":273},{},[205],{\"_119\":120,\"_42\":121,\"_122\":275,\"_51\":276},{},[277,278,279,280,281],\"Each rule has the form \",[\"SingleFetchClassInstance\",286],\", and it matches any query that has that same value for that same key. It's complicated a bit by the fact that \",[\"SingleFetchClassInstance\",282],\" can be an IP address with a CIDR mask.\",{\"_119\":120,\"_42\":158,\"_122\":283,\"_51\":284},{},[285],\"value\",{\"_119\":120,\"_42\":158,\"_122\":287,\"_51\":288},{},[205],{\"_119\":120,\"_42\":121,\"_122\":290,\"_51\":291},{},[292],[\"SingleFetchClassInstance\",293],{\"_119\":120,\"_42\":294,\"_122\":295,\"_51\":296},\"ContentImage\",{\"_297\":298,\"_299\":300,\"_301\":302,\"_303\":304,\"_305\":306,\"_307\":308},[],\"alt\",\"RuleSet data structure\",\"height\",1272,\"loading\",\"lazy\",\"src\",\"https://planetscale-images.imgix.net/assets/traffic-control-rule-set-D8I0PDRX.png?auto=compress%2Cformat\",\"srcs\",[309,310],\"width\",5308,{\"_311\":304,\"_313\":315},{\"_311\":312,\"_313\":314},\"srcSet\",\"https://planetscale-images.imgix.net/assets/traffic-control-rule-set-darkmode-lxM-eKyc.png?auto=compress%2Cformat\",\"media\",\"(prefers-color-scheme: dark)\",\"(prefers-color-scheme: light), (prefers-color-scheme: no-preference)\",{\"_119\":120,\"_42\":121,\"_122\":317,\"_51\":318},{},[319,320,321,322,323],\"One important goal for Traffic Control is that it can efficiently decide when not to block a query. After all, Traffic Control has to make that decision before each query is even allowed to begin execution. So 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 \",[\"SingleFetchClassInstance\",327],\" rules in \",[\"SingleFetchClassInstance\",324],\" time.\",{\"_119\":120,\"_42\":158,\"_122\":325,\"_51\":326},{},[247],{\"_119\":120,\"_42\":158,\"_122\":328,\"_51\":329},{},[330],\"n\",{\"_119\":120,\"_42\":131,\"_122\":332,\"_51\":333},{\"_53\":62},[334],[\"SingleFetchClassInstance\",335],{\"_119\":120,\"_42\":136,\"_122\":336,\"_51\":337},{\"_139\":338},[63],\"#rule-sets\",{\"_119\":120,\"_42\":121,\"_122\":340,\"_51\":341},{},[342],\"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.\",{\"_119\":120,\"_42\":121,\"_122\":344,\"_51\":345},{},[346],\"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. We store as many buckets as will fit in a configurable amount of shared memory, and we evict them implicitly when their debt falls to zero.\",{\"_119\":120,\"_42\":121,\"_122\":348,\"_51\":349},{},[350,351,352,353,354,355,356],\"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 \",[\"SingleFetchClassInstance\",366],\": its size and its drain rate. The size dictates the \",[\"SingleFetchClassInstance\",362],\", or what total resources queries under a given budget can use in a short amount of time. The drain rate dictates the \",[\"SingleFetchClassInstance\",357],\", or what fraction of overall resources queries under a given budget can use in the long term.\",{\"_119\":120,\"_42\":358,\"_122\":359,\"_51\":360},\"strong\",{},[361],\"server share\",{\"_119\":120,\"_42\":358,\"_122\":363,\"_51\":364},{},[365],\"burst limit\",{\"_119\":120,\"_42\":136,\"_122\":367,\"_51\":368},{\"_139\":370},[369],\"two important parameters\",\"/docs/postgres/traffic-control/concepts#resource-budget-limits\",{\"_119\":120,\"_42\":121,\"_122\":372,\"_51\":373},{},[374],[\"SingleFetchClassInstance\",375],{\"_119\":120,\"_42\":294,\"_122\":376,\"_51\":377},{\"_297\":378,\"_299\":379,\"_301\":302,\"_303\":380,\"_305\":381,\"_307\":382},[],\"Reverse leaky bucket\",1636,\"https://planetscale-images.imgix.net/assets/traffic-control-leaky-bucket-DiqkqEyT.png?auto=compress%2Cformat\",[383,384],2412,{\"_311\":380,\"_313\":315},{\"_311\":385,\"_313\":314},\"https://planetscale-images.imgix.net/assets/traffic-control-leaky-bucket-darkmode-YEz2CO8P.png?auto=compress%2Cformat\",{\"_119\":120,\"_42\":121,\"_122\":387,\"_51\":388},{},[389],\"Two of the checks that Traffic Control performs for each query are easy: if the query's estimated cost is too high, block it. If too many queries in the same budget are already running, block it. But the final check — is there enough capacity in the budget to proceed — is harder. It's important, though! Many executions of a moderately expensive query can be even more damaging than a single very expensive query, and managing a budget over time is the best way to block queries that are only expensive in aggregate. Traffic Control considers the cumulative cost of queries in each configured budget.\",{\"_119\":120,\"_42\":131,\"_122\":391,\"_51\":392},{\"_53\":65},[393],[\"SingleFetchClassInstance\",394],{\"_119\":120,\"_42\":136,\"_122\":395,\"_51\":396},{\"_139\":397},[66],\"#leaky-buckets\",{\"_119\":120,\"_42\":121,\"_122\":399,\"_51\":400},{},[401,402,403,404,405],\"Each time a query comes in, Traffic Control multiplies the planner's estimated cost by \",[\"SingleFetchClassInstance\",410],\" to guess how much CPU and/or wall-clock time the query will take. Based on that estimate, Traffic Control decides if the query can be allowed to begin. If it does, then at the end of query execution, Traffic Control updates the two averages for that query pattern so the \",[\"SingleFetchClassInstance\",406],\" value will be more recent and more precise for the next query that arrives.\",{\"_119\":120,\"_42\":158,\"_122\":407,\"_51\":408},{},[409],\"k\",{\"_119\":120,\"_42\":158,\"_122\":411,\"_51\":412},{},[409],{\"_119\":120,\"_42\":121,\"_122\":414,\"_51\":415},{},[416,417,418],\"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 \",[\"SingleFetchClassInstance\",419],\" is the ratio of the two.\",{\"_119\":120,\"_42\":158,\"_122\":420,\"_51\":421},{},[409],{\"_119\":120,\"_42\":121,\"_122\":423,\"_51\":424},{},[425,426,427,428,429],\"Traffic Control compensates for those dependencies. We assume that there is an unknown constant \",[\"SingleFetchClassInstance\",435],\" 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 \",[\"SingleFetchClassInstance\",430],\" 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!\",{\"_119\":120,\"_42\":136,\"_122\":431,\"_51\":432},{\"_139\":434},[433],\"query pattern\",\"/blog/query-performance-analysis-with-insights\",{\"_119\":120,\"_42\":158,\"_122\":436,\"_51\":437},{},[409],{\"_119\":120,\"_42\":121,\"_122\":439,\"_51\":440},{},[441,442,443,444,445],\"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. To evaluate all the possible plans, the planner has to estimate the cost of each one. When you run \",[\"SingleFetchClassInstance\",451],\" on a SQL statement, Postgres's planner shows the cost of each step in the chosen plan, as well as the overall total cost. The cost is \",[\"SingleFetchClassInstance\",446],\" assigned to each step the plan will take. There are a lot of variables that go into the plan cost, most of which you can ignore for the purposes of understanding Traffic Control. Just remember these two things: plan costs are roughly linear (a plan with double the cost should take something like double the time and resources to execute), and the relationship between plan costs and real-world resources is heavily dependent on what query you're running, what server you run it on, and what else is happening on that server at the moment.\",{\"_119\":120,\"_42\":136,\"_122\":447,\"_51\":448},{\"_139\":450},[449],\"measured in dimensionless units and is based on configurable weights\",\"https://www.postgresql.org/docs/current/runtime-config-query.html#RUNTIME-CONFIG-QUERY-CONSTANTS\",{\"_119\":120,\"_42\":158,\"_122\":452,\"_51\":453},{},[454],\"EXPLAIN\",{\"_119\":120,\"_42\":121,\"_122\":456,\"_51\":457},{},[458],\"I glossed over something important in the last section: cost. The concurrency check is easy, because it just counts worker processes already assigned to the queries associated with a Traffic Control budget. But the other two checks — per-query cost and cumulative cost — require us to know what resources the query will consume before it even begins execution. How do we do that? We trust, but also don't trust, the planner.\",{\"_119\":120,\"_42\":131,\"_122\":460,\"_51\":461},{\"_53\":68},[462],[\"SingleFetchClassInstance\",463],{\"_119\":120,\"_42\":136,\"_122\":464,\"_51\":465},{\"_139\":466},[69],\"#cost-prediction\",{\"_119\":120,\"_42\":121,\"_122\":468,\"_51\":469},{},[470,471,472,473,474],\"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 \",[\"SingleFetchClassInstance\",486],\", 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 \",[\"SingleFetchClassInstance\",475],\", which allows any overly expensive query to consume resources until it times out. Traffic Control blocks expensive, low priority queries before they begin.\",{\"_119\":120,\"_42\":136,\"_122\":476,\"_51\":477},{\"_139\":485},[478,479,480],\"Postgres \",[\"SingleFetchClassInstance\",481],\" setting\",{\"_119\":120,\"_42\":158,\"_122\":482,\"_51\":483},{},[484],\"statement_timeout\",\"https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-STATEMENT-TIMEOUT\",{\"_119\":120,\"_42\":136,\"_122\":487,\"_51\":488},{\"_139\":490},[489],\"Linux cgroups\",\"https://www.man7.org/linux/man-pages/man7/cgroups.7.html\",{\"_119\":120,\"_42\":121,\"_122\":492,\"_51\":493},{},[494],\"If any budget fails any of these checks, then the query is warned or blocked, based on how the budget is configured.\",{\"_119\":120,\"_42\":187,\"_122\":496,\"_51\":497},{},[498,499,500,501],[\"SingleFetchClassInstance\",526],[\"SingleFetchClassInstance\",522],[\"SingleFetchClassInstance\",518],[\"SingleFetchClassInstance\",502],{\"_119\":120,\"_42\":194,\"_122\":503,\"_51\":504},{},[505,506,507,508,509],\"It checks to see if every applicable budget has enough available capacity for the query to begin execution. In the \",[\"SingleFetchClassInstance\",514],\", these parameters are described as the burst limit and the server share. As we'll see \",[\"SingleFetchClassInstance\",510],\", those parameters combine over time to describe the behavior of a leaky-bucket rate limiter.\",{\"_119\":120,\"_42\":136,\"_122\":511,\"_51\":512},{\"_139\":397},[513],\"below\",{\"_119\":120,\"_42\":136,\"_122\":515,\"_51\":516},{\"_139\":370},[517],\"documentation\",{\"_119\":120,\"_42\":194,\"_122\":519,\"_51\":520},{},[521],\"It checks if the query's estimated cost is higher than any applicable budget's per-query limit.\",{\"_119\":120,\"_42\":194,\"_122\":523,\"_51\":524},{},[525],\"It checks to see if any of the applicable budgets has reached its concurrency limit.\",{\"_119\":120,\"_42\":194,\"_122\":527,\"_51\":528},{},[529,530,531],\"It identifies all of the rules that match the \",[\"SingleFetchClassInstance\",532],\" of the query. Each rule identifies a budget; multiple rules can map to the same budget.\",{\"_119\":120,\"_42\":136,\"_122\":533,\"_51\":534},{\"_139\":536},[535],\"tags and other metadata\",\"/docs/postgres/traffic-control/concepts#rules\",{\"_119\":120,\"_42\":121,\"_122\":538,\"_51\":539},{},[540],\"If there are any Traffic Control rules configured, then at the beginning of each query execution, the extension does four things:\",{\"_119\":120,\"_42\":121,\"_122\":542,\"_51\":543},{},[544],[\"SingleFetchClassInstance\",545],{\"_119\":120,\"_42\":294,\"_122\":546,\"_51\":547},{\"_297\":548,\"_299\":549,\"_301\":302,\"_303\":550,\"_305\":551,\"_307\":552},[],\"How Traffic Control decides whether or not to block a query\",2864,\"https://planetscale-images.imgix.net/assets/traffic-control-checks-Dww9PUBq.png?auto=compress%2Cformat\",[553,554],2960,{\"_311\":550,\"_313\":315},{\"_311\":555,\"_313\":314},\"https://planetscale-images.imgix.net/assets/traffic-control-checks-darkmode-RO3pOuCZ.png?auto=compress%2Cformat\",{\"_119\":120,\"_42\":121,\"_122\":557,\"_51\":558},{},[559,560,561,562,563],\"It turns out Traffic Control needed the same hook points and much of the same information that \",[\"SingleFetchClassInstance\",568],\" already had. So rather than duplicate all that code and impose the extra runtime overhead of another extension, we taught \",[\"SingleFetchClassInstance\",564],\" how to block queries.\",{\"_119\":120,\"_42\":158,\"_122\":565,\"_51\":566},{},[567],\"pginsights\",{\"_119\":120,\"_42\":158,\"_122\":569,\"_51\":570},{},[567],{\"_119\":120,\"_42\":121,\"_122\":572,\"_51\":573},{},[574,575,576,577,578],\"When we first started planning for Traffic Control, we knew we would use a Postgres extension with a hook on \",[\"SingleFetchClassInstance\",588],\" to decide whether or not each statement would be allowed to run. Initially, we wrote a new extension for this. We soon realized that there are two ways to choose which queries to block: based on static analysis of the individual query, or based on cumulative measurements of resource usage over time. We split the extension along those lines. Blocking based on static analysis got merged into the project that became \",[\"SingleFetchClassInstance\",579],\". Blocking based on cumulative resource usage became Traffic Control.\",{\"_119\":120,\"_42\":136,\"_122\":580,\"_51\":581},{\"_139\":587},[582],[\"SingleFetchClassInstance\",583],{\"_119\":120,\"_42\":158,\"_122\":584,\"_51\":585},{},[586],\"pg_strict\",\"/changelog/postgres-extension-pg-strict\",{\"_119\":120,\"_42\":158,\"_122\":589,\"_51\":590},{},[591],\"ExecutorRun\",{\"_119\":120,\"_42\":131,\"_122\":593,\"_51\":594},{\"_53\":71},[595],[\"SingleFetchClassInstance\",596],{\"_119\":120,\"_42\":136,\"_122\":597,\"_51\":598},{\"_139\":599},[72],\"#insights-hooks-and-blocking-queries\",{\"_119\":120,\"_42\":121,\"_122\":601,\"_51\":602},{},[603,604,605,606,152,607,608,609,610],\"PlanetScale's \",[\"SingleFetchClassInstance\",621],\" extension installs hooks for the \",[\"SingleFetchClassInstance\",618],[\"SingleFetchClassInstance\",614],\" functions, among others, to run timers and measure resource consumption while SQL statements execute. Since each hook wraps the original Postgres functionality, that means \",[\"SingleFetchClassInstance\",611],\" sees each query just before it executes and again just after it completes. Any time that has elapsed and any resources the worker process has consumed are directly attributable to that query. The extension does some aggregation, sends aggregate data periodically to a data pipeline, and returns control to Postgres to accept the next query.\",{\"_119\":120,\"_42\":158,\"_122\":612,\"_51\":613},{},[567],{\"_119\":120,\"_42\":158,\"_122\":615,\"_51\":616},{},[617],\"ProcessUtility\",{\"_119\":120,\"_42\":158,\"_122\":619,\"_51\":620},{},[591],{\"_119\":120,\"_42\":158,\"_122\":622,\"_51\":623},{},[567],{\"_119\":120,\"_42\":121,\"_122\":625,\"_51\":626},{},[627,628,629],\"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. Want to observe or replace the planner? There's a hook for that. Want to examine queries as they execute? There are three hooks for that. As of this writing, there are \",[\"SingleFetchClassInstance\",630],\" available to anyone writing Postgres extensions.\",{\"_119\":120,\"_42\":136,\"_122\":631,\"_51\":632},{\"_139\":634},[633],\"55 hooks\",\"https://github.com/search?q=repo%3Apostgres%2Fpostgres%20%2F%5E%5CS.*%5Cw_hook%20%3D%20NULL%2F\u0026type=code\",{\"_119\":120,\"_42\":121,\"_122\":636,\"_51\":637},{},[638,639,640,641,642,643,644],\"Every part of how Postgres handles queries can be modified by extensions. Extensions can add new functions, new data types, new storage systems, and new authentication methods, among other things. (They can also \",[\"SingleFetchClassInstance\",658],\", but that's a topic for another day.) Extensions can also passively observe and report on traffic, like PlanetScale's own \",[\"SingleFetchClassInstance\",650],\" extension that powers \",[\"SingleFetchClassInstance\",645],\".\",{\"_119\":120,\"_42\":136,\"_122\":646,\"_51\":647},{\"_139\":649},[648],\"Query Insights\",\"/docs/postgres/monitoring/query-insights\",{\"_119\":120,\"_42\":136,\"_122\":651,\"_51\":652},{\"_139\":657},[653],[\"SingleFetchClassInstance\",654],{\"_119\":120,\"_42\":158,\"_122\":655,\"_51\":656},{},[567],\"/docs/postgres/extensions/pginsights\",{\"_119\":120,\"_42\":136,\"_122\":659,\"_51\":660},{\"_139\":662},[661],\"add new failure modes\",\"https://www.vldb.org/pvldb/vol18/p1962-kim.pdf\",{\"_119\":120,\"_42\":121,\"_122\":664,\"_51\":665},{},[666,667,668,669,670],\"A single Postgres server is made up of many running processes. Each client connection to Postgres gets its own dedicated worker \",[\"SingleFetchClassInstance\",676],\", and all SQL queries from that client connection run, one at a time, in that worker process. When a client sends a SQL query, the worker process parses it, plans it, executes it, and sends any results back to the client. \",[\"SingleFetchClassInstance\",671],\" is a key step, in which Postgres takes a parsed query and turns it into a step-by-step execution plan that specifies the indexes to use, the order to load rows from multiple tables, and the operators that will be used to filter, aggregate, and join those rows. Most queries can be run using several different plans, so it's the planner's job to estimate the cost of the possible plans and pick the cheapest one.\",{\"_119\":120,\"_42\":136,\"_122\":672,\"_51\":673},{\"_139\":675},[674],\"Planning\",\"/blog/what-is-a-query-planner\",{\"_119\":120,\"_42\":136,\"_122\":677,\"_51\":678},{\"_139\":680},[679],\"process\",\"/blog/processes-and-threads\",{\"_119\":120,\"_42\":121,\"_122\":682,\"_51\":683},{},[684],\"If you already know how Postgres and Postgres extensions work internally, you can skip this section.\",{\"_119\":120,\"_42\":131,\"_122\":686,\"_51\":687},{\"_53\":74},[688],[\"SingleFetchClassInstance\",689],{\"_119\":120,\"_42\":136,\"_122\":690,\"_51\":691},{\"_139\":692},[75],\"#background\",{\"_119\":120,\"_42\":121,\"_122\":694,\"_51\":695},{},[696,697,698,699,700],\"Today, we released Database Traffic Control®, a feature for mitigating and preventing database overload due to unexpectedly expensive SQL queries. For an overview, read the \",[\"SingleFetchClassInstance\",706],\", and to get started using it, read the \",[\"SingleFetchClassInstance\",701],\". This post is a deep dive into how the feature works.\",{\"_119\":120,\"_42\":136,\"_122\":702,\"_51\":703},{\"_139\":705},[704],\"reference documentation\",\"/docs/postgres/traffic-control/\",{\"_119\":120,\"_42\":136,\"_122\":707,\"_51\":708},{\"_139\":710},[709],\"blog post introducing the feature\",\"/blog/introducing-database-traffic-control\",\"current\",{\"_713\":714,\"_715\":716,\"_717\":714},\"development\",false,\"env\",{\"_718\":719,\"_720\":721,\"_722\":723,\"_724\":725,\"_726\":727},\"userSignedIn\",\"IMAGE_CDN\",\"https://planetscale-images.imgix.net\",\"IMAGE_CDN_ENABLED\",\"true\",\"INTERNAL_API\",\"https://api.planetscale.com\",\"RELEASE\",\"117b8aaf-965c-42bc-b013-5f72770de4d9\",\"SENTRY_DSN\",\"https://bd81903b44804e22a06bdc0c1a91b303@o499952.ingest.us.sentry.io/4504531942572032\"]\n");</script><!--$--><script nonce="QWt7XcXX9UFsmf1SIq42nVEng5bahvor3XP1WU/3kEQ=">window.__reactRouterContext.streamController.close();</script><!--/$--><!--/$--></body></html> |