[{"_1":2,"_850":-5,"_851":-5},"loaderData",{"_3":4,"_22":23},"root",{"_5":6},"current",{"_7":8,"_9":10,"_21":8},"development",false,"env",{"_11":12,"_13":14,"_15":16,"_17":18,"_19":20},"COMMIT_SHA","032c64b08f7dd5f7f1f6f3923a1c6d1445f4fb68","IMAGE_CDN","https://planetscale-images.imgix.net","IMAGE_CDN_ENABLED","true","INTERNAL_API","https://api.planetscale.com","SENTRY_DSN","https://bd81903b44804e22a06bdc0c1a91b303@o499952.ingest.us.sentry.io/4504531942572032","userSignedIn","routes/blog.author.$slug",{"_24":25,"_32":33,"_840":841,"_3":849},"author",{"_26":27,"_28":29,"_30":31},"slug","joshbrown","name","Josh Brown","x","0ximjosh","blogs",[34],{"_26":35,"_36":37,"_795":796,"_797":-7,"_798":799,"_804":822,"_823":824,"_826":827,"_829":830,"_831":832,"_833":834},"patterns-for-postgres-traffic-control","body",[38,77,115,124,137,151,160,165,190,195,201,207,212,218,229,237,251,263,281,292,311,317,322,327,332,344,358,369,376,381,386,406,412,417,428,435,441,446,451,456,461,487,494,511,516,527,536,547,552,576,589,596,601,615,619,630,649,659,664,669,674,687,692,704,721,726,733,744,749,754,772,787],["SingleFetchClassInstance",39],{"_40":41,"_28":42,"_43":44,"_45":46},"$$mdtype","Tag","p","attributes",{},"children",[47,48,49,57,48,58,48,59,48,60,61,67,48,68,69,75,48,76],"Last week we introduced"," ",["SingleFetchClassInstance",50],{"_40":41,"_28":51,"_43":52,"_45":55},"a",{"_53":54},"href","/blog/introducing-database-traffic-control",[56],"Database Traffic Control","™. Traffic","Control lets you attach resource budgets to slices of your Postgres traffic,","like keeping your checkout flow running while a runaway analytics query gets","shed instead. We have already discussed ",["SingleFetchClassInstance",62],{"_40":41,"_28":51,"_43":63,"_45":65},{"_53":64},"/docs/postgres/traffic-control/examples-and-recipes",[66],"some scenarios where"," you","should use Traffic Control, along with ",["SingleFetchClassInstance",70],{"_40":41,"_28":51,"_43":71,"_45":73},{"_53":72},"/blog/graceful-degradation-in-postgres",[74],"how to define resource limits",", so now","let's dig into what Traffic Control looks like in your codebase.",["SingleFetchClassInstance",78],{"_40":41,"_28":42,"_43":79,"_45":80},{},[81],["SingleFetchClassInstance",82],{"_40":41,"_28":83,"_43":84,"_45":85},"picture",{},[86,95,101],["SingleFetchClassInstance",87],{"_40":41,"_28":88,"_43":89,"_45":94},"source",{"_90":91,"_92":93},"srcSet","https://planetscale-images.imgix.net/assets/traffic-control-dashboard-DsZVQoIr.png?auto=compress%2Cformat","media","(prefers-color-scheme: light), (prefers-color-scheme: no-preference)",[],["SingleFetchClassInstance",96],{"_40":41,"_28":88,"_43":97,"_45":100},{"_90":98,"_92":99},"https://planetscale-images.imgix.net/assets/traffic-control-dashboard-darkmode-D25zKJBn.png?auto=compress%2Cformat","(prefers-color-scheme: dark)",[],["SingleFetchClassInstance",102],{"_40":41,"_28":103,"_43":104,"_45":114},"img",{"_105":106,"_107":108,"_109":110,"_111":91,"_112":113},"alt","Traffic Control Dashboard","height",1995,"loading","lazy","src","width",3447,[],["SingleFetchClassInstance",116],{"_40":41,"_28":42,"_43":117,"_45":118},{},[119,48,120,48,121,48,122,48,123],"This post walks through some practical patterns in Go. Each pattern targets a","different failure mode, architecture, or foot gun. Most of them layer on top of","one another too, so you can adopt them individually or combine them for extra","peace of mind. Keep in mind the general concepts here are applicable to whatever","language your application is written in.",["SingleFetchClassInstance",125],{"_40":41,"_28":126,"_43":127,"_45":130},"h2",{"_128":129},"id","setup",[131],["SingleFetchClassInstance",132],{"_40":41,"_28":51,"_43":133,"_45":135},{"_53":134},"#setup",[136],"Setup",["SingleFetchClassInstance",138],{"_40":41,"_28":42,"_43":139,"_45":140},{},[141,48,142,48,143,149,48,150],"Most of the patterns here rely on custom tags attached to your queries. Traffic","Control reads these using the",["SingleFetchClassInstance",144],{"_40":41,"_28":51,"_43":145,"_45":147},{"_53":146},"https://google.github.io/sqlcommenter/",[148],"SQLCommenter"," format: a SQL comment","appended to each query with URL-encoded key=value pairs.",["SingleFetchClassInstance",152],{"_40":41,"_28":153,"_43":154,"_45":159},"CodeBlock",{"_155":156,"_157":158},"html","

SELECT * FROM orders \n  WHERE user_id = $1\n /*route='checkout',feature='new_order_flow'*/;\n

","language","sql",[],["SingleFetchClassInstance",161],{"_40":41,"_28":42,"_43":162,"_45":163},{},[164],"These tags are then available for new Traffic Control rules.",["SingleFetchClassInstance",166],{"_40":41,"_28":42,"_43":167,"_45":168},{},[169],["SingleFetchClassInstance",170],{"_40":41,"_28":83,"_43":171,"_45":172},{},[173,178,183],["SingleFetchClassInstance",174],{"_40":41,"_28":88,"_43":175,"_45":177},{"_90":176,"_92":93},"https://planetscale-images.imgix.net/assets/throttle-queries-BisrodmP.png?auto=compress%2Cformat",[],["SingleFetchClassInstance",179],{"_40":41,"_28":88,"_43":180,"_45":182},{"_90":181,"_92":99},"https://planetscale-images.imgix.net/assets/throttle-queries-darkmode-CUn0ETQq.png?auto=compress%2Cformat",[],["SingleFetchClassInstance",184],{"_40":41,"_28":103,"_43":185,"_45":189},{"_105":186,"_107":187,"_109":110,"_111":176,"_112":188},"Traffic Control rule",878,1958,[],["SingleFetchClassInstance",191],{"_40":41,"_28":42,"_43":192,"_45":193},{},[194],"Here's a minimal Go helper that appends tags in this format:",["SingleFetchClassInstance",196],{"_40":41,"_28":153,"_43":197,"_45":200},{"_155":198,"_157":199},"

import (\n    \"fmt\"\n    \"net/url\"\n    \"sort\"\n    \"strings\"\n)\n\n// appendTags appends SQLCommenter-format tags to a SQL query.\nfunc appendTags(query string, tags map[string]string) string {\n    if len(tags) == 0 {\n        return query\n    }\n    parts := make([]string, 0, len(tags))\n    for k, v := range tags {\n        parts = append(parts, fmt.Sprintf(\"%s='%s'\", k, url.QueryEscape(v)))\n    }\n    sort.Strings(parts) // deterministic order\n    return query + \" /*\" + strings.Join(parts, \",\") + \"*/\"\n}\n

","go",[],["SingleFetchClassInstance",202],{"_40":41,"_28":42,"_43":203,"_45":204},{},[205,48,206],"You'll also want a way to thread tags through your call stack without touching","every function signature. A context key works well for this:",["SingleFetchClassInstance",208],{"_40":41,"_28":153,"_43":209,"_45":211},{"_155":210,"_157":199},"

type contextKey string\n\nconst sqlTagsKey contextKey = \"sql_tags\"\n\nfunc tagsFromContext(ctx context.Context) map[string]string {\n    if tags, ok := ctx.Value(sqlTagsKey).(map[string]string); ok {\n        // return a copy so callers can't mutate shared state\n        out := make(map[string]string, len(tags))\n        for k, v := range tags {\n            out[k] = v\n        }\n        return out\n    }\n    return make(map[string]string)\n}\n\nfunc contextWithTags(ctx context.Context, tags map[string]string) context.Context {\n    return context.WithValue(ctx, sqlTagsKey, tags)\n}\n

",[],["SingleFetchClassInstance",213],{"_40":41,"_28":42,"_43":214,"_45":215},{},[216,48,217],"With these two helpers in place, the patterns below mostly just set keys and","values in context. Tagging happens automatically when the query executes.",["SingleFetchClassInstance",219],{"_40":41,"_28":126,"_43":220,"_45":222},{"_128":221},"per-service-isolation-via-roles",[223],["SingleFetchClassInstance",224],{"_40":41,"_28":51,"_43":225,"_45":227},{"_53":226},"#per-service-isolation-via-roles",[228],"Per-service isolation via Roles",["SingleFetchClassInstance",230],{"_40":41,"_28":42,"_43":231,"_45":232},{},[233,48,234,48,235,48,236],"In a microservice architecture, a single misbehaving service should not be able","to degrade every other service sharing the same database. The simplest way to","isolate a service is to create a Traffic Control rule based on a unique","connection string for the given service, or via application name.",["SingleFetchClassInstance",238],{"_40":41,"_28":42,"_43":239,"_45":240},{},[241,242,248,48,249,48,250],"A budget on ",["SingleFetchClassInstance",243],{"_40":41,"_28":244,"_43":245,"_45":246},"code",{},[247],"username='pscale_api_123abc'"," will isolate all traffic from that","role. This also helps in incident response: you can immediately cap a service's","resource share without redeploying anything.",["SingleFetchClassInstance",252],{"_40":41,"_28":42,"_43":253,"_45":254},{},[255,48,256,257,48,262],"Note that the username is the internal Postgres username of the role, not the","dashboard role name. You can also target custom roles created by ",["SingleFetchClassInstance",258],{"_40":41,"_28":244,"_43":259,"_45":260},{},[261],"CREATE ROLE","if your microservices have strict security over table permissions.",["SingleFetchClassInstance",264],{"_40":41,"_28":42,"_43":265,"_45":266},{},[267,268,273,48,274,275,280],"You can also use the ",["SingleFetchClassInstance",269],{"_40":41,"_28":244,"_43":270,"_45":271},{},[272],"application_name"," by appending it to your connection","strings such as ",["SingleFetchClassInstance",276],{"_40":41,"_28":244,"_43":277,"_45":278},{},[279],"postgresql://other@localhost/otherdb?application_name=myapp",".",["SingleFetchClassInstance",282],{"_40":41,"_28":126,"_43":283,"_45":285},{"_128":284},"route-level-tagging-in-an-http-service",[286],["SingleFetchClassInstance",287],{"_40":41,"_28":51,"_43":288,"_45":290},{"_53":289},"#route-level-tagging-in-an-http-service",[291],"Route-level tagging in an HTTP service",["SingleFetchClassInstance",293],{"_40":41,"_28":42,"_43":294,"_45":295},{},[296,48,297,298,303,48,304,305,310],"When you're running a monolith or a large API service, the problem isn't usually","the whole service, it's specific routes. The ",["SingleFetchClassInstance",299],{"_40":41,"_28":244,"_43":300,"_45":301},{},[302],"/api/export"," endpoint that","generates CSV reports should not be able to kill the ",["SingleFetchClassInstance",306],{"_40":41,"_28":244,"_43":307,"_45":308},{},[309],"/api/checkout"," flow.",["SingleFetchClassInstance",312],{"_40":41,"_28":42,"_43":313,"_45":314},{},[315,48,316],"An HTTP middleware can inject the route into context at runtime before any","handler runs:",["SingleFetchClassInstance",318],{"_40":41,"_28":153,"_43":319,"_45":321},{"_155":320,"_157":199},"

// Any route using SQLTagMiddleware will have the pattern injected into its context\n// dynamically at runtime\nfunc SQLTagMiddleware(next http.Handler) http.Handler {\n    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n        tags := tagsFromContext(r.Context())\n        route := strings.ReplaceAll(strings.ReplaceAll(r.Pattern, \"{\", \":\"), \"}\", \":\") // Removes \"{}\" characters from route\n        tags[\"route\"] = route\n        tags[\"app\"] = \"web\"\n        ctx := contextWithTags(r.Context(), tags)\n        next.ServeHTTP(w, r.WithContext(ctx))\n    })\n}\n

",[],["SingleFetchClassInstance",323],{"_40":41,"_28":42,"_43":324,"_45":325},{},[326],"Wrap your database calls to pick up the tags automatically:",["SingleFetchClassInstance",328],{"_40":41,"_28":153,"_43":329,"_45":331},{"_155":330,"_157":199},"

// QueryContext for SELECT statements\nfunc (db *DB) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) {\n    return db.sql.QueryContext(ctx, appendTags(query, tagsFromContext(ctx)), args...)\n}\n\n// ExecContext for INSERT/UPDATE statements\nfunc (db *DB) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) {\n    return db.sql.ExecContext(ctx, appendTags(query, tagsFromContext(ctx)), args...)\n}\n

",[],["SingleFetchClassInstance",333],{"_40":41,"_28":42,"_43":334,"_45":335},{},[336,48,337,338,343],"Now every query carries the route it came from. You can create a Traffic Control","budget targeting ",["SingleFetchClassInstance",339],{"_40":41,"_28":244,"_43":340,"_45":341},{},[342],"route='/api-export'"," and give it a conservative CPU limit.",["SingleFetchClassInstance",345],{"_40":41,"_28":42,"_43":346,"_45":347},{},[348,48,349,48,350,351,356,48,357],"This also makes it easy to set up broad budgets during incidents. If you","suddenly see a spike and don't know which route is responsible, the violation","graph in Traffic Control will show you exactly which ",["SingleFetchClassInstance",352],{"_40":41,"_28":244,"_43":353,"_45":354},{},[355],"route"," tag is hitting","limits.",["SingleFetchClassInstance",359],{"_40":41,"_28":126,"_43":360,"_45":362},{"_128":361},"feature-flags-and-new-deployments",[363],["SingleFetchClassInstance",364],{"_40":41,"_28":51,"_43":365,"_45":367},{"_53":366},"#feature-flags-and-new-deployments",[368],"Feature flags and new deployments",["SingleFetchClassInstance",370],{"_40":41,"_28":42,"_43":371,"_45":372},{},[373,48,374,48,375],"Shipping a new feature to production always carries risk. Maybe the new query","pattern is fine under your test load but becomes expensive at scale. Traffic","Control gives you a way to cap the blast radius before it becomes an incident.",["SingleFetchClassInstance",377],{"_40":41,"_28":42,"_43":378,"_45":379},{},[380],"The simplest version sets a tag from an environment variable at startup:",["SingleFetchClassInstance",382],{"_40":41,"_28":153,"_43":383,"_45":385},{"_155":384,"_157":199},"

var deploymentTag = os.Getenv(\"DEPLOYMENT_TAG\") // e.g. \"new_checkout_v2\" or git sha \"96e350426\"\n\nfunc tagWithDeployment(ctx context.Context) context.Context {\n    if deploymentTag == \"\" {\n        return ctx\n    }\n    tags := tagsFromContext(ctx)\n    tags[\"feature\"] = deploymentTag\n    return contextWithTags(ctx, tags)\n}\n

",[],["SingleFetchClassInstance",387],{"_40":41,"_28":42,"_43":388,"_45":389},{},[390,391,396,48,397,48,398,403,48,404,48,405],"Set ",["SingleFetchClassInstance",392],{"_40":41,"_28":244,"_43":393,"_45":394},{},[395],"DEPLOYMENT_TAG=new_checkout_v2"," when rolling out new pods and leave it","unset on the old pods. Traffic Control can then have a budget on",["SingleFetchClassInstance",399],{"_40":41,"_28":244,"_43":400,"_45":401},{},[402],"feature='new_checkout_v2'"," in Warn mode from day one, so you see exactly how","the new code behaves before it causes problems. When you're confident, either","remove the budget or switch it to Enforce as a safety net.",["SingleFetchClassInstance",407],{"_40":41,"_28":42,"_43":408,"_45":409},{},[410,48,411],"For feature flags controlled at runtime, the same approach works but driven by","your flag evaluation:",["SingleFetchClassInstance",413],{"_40":41,"_28":153,"_43":414,"_45":416},{"_155":415,"_157":199},"

func (h *OrderHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {\n    ctx := r.Context()\n    if flags.Enabled(ctx, \"new_order_flow\") {\n        tags := tagsFromContext(ctx)\n        tags[\"feature\"] = \"new_order_flow\"\n        ctx = contextWithTags(ctx, tags)\n    }\n    h.processOrder(ctx, w, r)\n}\n

",[],["SingleFetchClassInstance",418],{"_40":41,"_28":126,"_43":419,"_45":421},{"_128":420},"tier-based-limits-in-multi-tenant-apps",[422],["SingleFetchClassInstance",423],{"_40":41,"_28":51,"_43":424,"_45":426},{"_53":425},"#tier-based-limits-in-multi-tenant-apps",[427],"Tier-based limits in multi-tenant apps",["SingleFetchClassInstance",429],{"_40":41,"_28":42,"_43":430,"_45":431},{},[432,48,433,48,434],"In a SaaS application, free-tier users should not be able to degrade the","experience for enterprise customers. Traffic Control lets you enforce this at","the database level rather than just at the application layer.",["SingleFetchClassInstance",436],{"_40":41,"_28":42,"_43":437,"_45":438},{},[439,48,440],"Inject the user's subscription tier into the SQL tags early in your request","handling — ideally right after you've resolved the authenticated user:",["SingleFetchClassInstance",442],{"_40":41,"_28":153,"_43":443,"_45":445},{"_155":444,"_157":199},"

type Tier string\n\nconst (\n    TierFree       Tier = \"FREE\"\n    TierPro        Tier = \"PRO\"\n    TierEnterprise Tier = \"ENTERPRISE\"\n)\n\nfunc WithUserTier(ctx context.Context, tier Tier) context.Context {\n    tags := tagsFromContext(ctx)\n    tags[\"tier\"] = string(tier)\n    return contextWithTags(ctx, tags)\n}\n

",[],["SingleFetchClassInstance",447],{"_40":41,"_28":42,"_43":448,"_45":449},{},[450],"In your authentication middleware:",["SingleFetchClassInstance",452],{"_40":41,"_28":153,"_43":453,"_45":455},{"_155":454,"_157":199},"

func AuthMiddleware(users *UserService, next http.Handler) http.Handler {\n    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n        user, err := users.Authenticate(r)\n        if err != nil {\n            http.Error(w, \"unauthorized\", http.StatusUnauthorized)\n            return\n        }\n        ctx := WithUserTier(r.Context(), user.Tier)\n        next.ServeHTTP(w, r.WithContext(ctx))\n    })\n}\n

",[],["SingleFetchClassInstance",457],{"_40":41,"_28":42,"_43":458,"_45":459},{},[460],"With this in place, create two Traffic Control budgets:",["SingleFetchClassInstance",462],{"_40":41,"_28":463,"_43":464,"_45":465},"ul",{},[466,477],["SingleFetchClassInstance",467],{"_40":41,"_28":468,"_43":469,"_45":470},"li",{},[471,476],["SingleFetchClassInstance",472],{"_40":41,"_28":244,"_43":473,"_45":474},{},[475],"tier='free'"," — conservative limits on server share and max concurrent queries",["SingleFetchClassInstance",478],{"_40":41,"_28":468,"_43":479,"_45":480},{},[481,486],["SingleFetchClassInstance",482],{"_40":41,"_28":244,"_43":483,"_45":484},{},[485],"tier='pro'"," — moderate limits",["SingleFetchClassInstance",488],{"_40":41,"_28":42,"_43":489,"_45":490},{},[491,48,492,48,493],"Leave enterprise traffic unbudgeted or give it a high budget as a ceiling. When","a free-tier user runs an expensive dashboard or triggers a slow query, the","budget sheds that traffic before it touches enterprise workloads.",["SingleFetchClassInstance",495],{"_40":41,"_28":42,"_43":496,"_45":497},{},[498,48,499,504,48,505,509,48,510],"You can combine this with the route tag from Pattern 2. A budget matching",["SingleFetchClassInstance",500],{"_40":41,"_28":244,"_43":501,"_45":502},{},[503],"tier='free' AND route='api-export'"," can be stricter than a budget on",["SingleFetchClassInstance",506],{"_40":41,"_28":244,"_43":507,"_45":508},{},[475]," alone. Enterprise export requests get more headroom than free-tier","export requests.",["SingleFetchClassInstance",512],{"_40":41,"_28":513,"_43":514,"_45":515},"hr",{},[],["SingleFetchClassInstance",517],{"_40":41,"_28":126,"_43":518,"_45":520},{"_128":519},"background-jobs-and-scripts",[521],["SingleFetchClassInstance",522],{"_40":41,"_28":51,"_43":523,"_45":525},{"_53":524},"#background-jobs-and-scripts",[526],"Background jobs and scripts",["SingleFetchClassInstance",528],{"_40":41,"_28":42,"_43":529,"_45":530},{},[531,48,532,48,533,48,534,48,535],"Background jobs are a common cause of database incidents. A migration script, a","nightly sync, or a one-off data backfill can all accidentally saturate your","database if they run faster than expected. Traffic Control is a clean way to","give these jobs a resource ceiling without having to tune query-level timeouts","throughout your codebase.",["SingleFetchClassInstance",537],{"_40":41,"_28":42,"_43":538,"_45":539},{},[540,48,541,542,546],"For long-running background workers, use a dedicated connection pool with a","distinct ",["SingleFetchClassInstance",543],{"_40":41,"_28":244,"_43":544,"_45":545},{},[272],":",["SingleFetchClassInstance",548],{"_40":41,"_28":153,"_43":549,"_45":551},{"_155":550,"_157":199},"

func newJobDB(dsn string) (*sql.DB, error) {\n    jobDSN, err := url.Parse(dsn) // your connection string\n    if err != nil {\n        return nil, err\n    }\n    q := jobDSN.Query()\n    // This sets the application name in code instead of in the connection string env variable.\n    q.Set(\"application_name\", \"background-jobs\")\n    jobDSN.RawQuery = q.Encode()\n\n    db, err := sql.Open(\"pgx\", jobDSN.String()) // connects to Postgres\n    if err != nil {\n        return nil, err\n    }\n    db.SetMaxOpenConns(4) // Jobs don't need high concurrency\n    return db, nil\n}\n

",[],["SingleFetchClassInstance",553],{"_40":41,"_28":42,"_43":554,"_45":555},{},[556,561,562,566,48,567,572,48,573,48,574,48,575],["SingleFetchClassInstance",557],{"_40":41,"_28":244,"_43":558,"_45":559},{},[560],"newJobDB"," takes the DSN of your database and sets ",["SingleFetchClassInstance",563],{"_40":41,"_28":244,"_43":564,"_45":565},{},[272]," to",["SingleFetchClassInstance",568],{"_40":41,"_28":244,"_43":569,"_45":570},{},[571],"background-jobs"," before connecting. Once connected we set the max connections","to 4 to make sure our background job isn't taking up more workers than it","should, and finally we return it so that the calling function can now query the","database.",["SingleFetchClassInstance",577],{"_40":41,"_28":42,"_43":578,"_45":579},{},[580,581,585,48,586,48,587,48,588],"Setting ",["SingleFetchClassInstance",582],{"_40":41,"_28":244,"_43":583,"_45":584},{},[272]," on the connection string level in code ensures that","it is always set for this service, no matter the query or connection string","given. You can pair this with SQL comments as described above for even more","fine-grained control and insights into your queries.",["SingleFetchClassInstance",590],{"_40":41,"_28":42,"_43":591,"_45":592},{},[593,48,594,48,595],"For one-off scripts and migrations we can do something similar. Here we encode","the script's identity directly in the connection string so it shows up clearly","in Traffic Control and Insights:",["SingleFetchClassInstance",597],{"_40":41,"_28":153,"_43":598,"_45":600},{"_155":599,"_157":199},"

// Returns a database instance with the `application_name` set to `script-[scriptName]`\n// for use in scripts\nfunc scriptDB(dsn, scriptName string) (*sql.DB, error) {\n    u, _ := url.Parse(dsn)\n    q := u.Query()\n    q.Set(\"application_name\", \"script-\"+scriptName) // e.g. \"script-backfill-order-totals\"\n    u.RawQuery = q.Encode()\n    return sql.Open(\"pgx\", u.String())\n}\n

",[],["SingleFetchClassInstance",602],{"_40":41,"_28":42,"_43":603,"_45":604},{},[605,606,611,48,612,48,613,48,614],"Create a Traffic Control budget for ",["SingleFetchClassInstance",607],{"_40":41,"_28":244,"_43":608,"_45":609},{},[610],"application_name='background-jobs'"," in Warn","mode before you run this job next. Observe how much of the database's resources","your background work typically consumes. Then switch to Enforce to cap it at a","level where it can't crowd out interactive traffic even if a job goes sideways.",["SingleFetchClassInstance",616],{"_40":41,"_28":513,"_43":617,"_45":618},{},[],["SingleFetchClassInstance",620],{"_40":41,"_28":126,"_43":621,"_45":623},{"_128":622},"handling-blocked-queries",[624],["SingleFetchClassInstance",625],{"_40":41,"_28":51,"_43":626,"_45":628},{"_53":627},"#handling-blocked-queries",[629],"Handling blocked queries",["SingleFetchClassInstance",631],{"_40":41,"_28":42,"_43":632,"_45":633},{},[634,48,635,636,641,48,642,647,48,648],"When Traffic Control is in Enforce mode and a query exceeds its budget, Postgres","returns SQLSTATE ",["SingleFetchClassInstance",637],{"_40":41,"_28":244,"_43":638,"_45":639},{},[640],"53000"," with an error message prefixed with",["SingleFetchClassInstance",643],{"_40":41,"_28":244,"_43":644,"_45":645},{},[646],"[PGINSIGHTS] Traffic Control:",". Your application needs to handle this without","crashing.",["SingleFetchClassInstance",650],{"_40":41,"_28":42,"_43":651,"_45":652},{},[653,654,546],"With ",["SingleFetchClassInstance",655],{"_40":41,"_28":244,"_43":656,"_45":657},{},[658],"pgx/v5",["SingleFetchClassInstance",660],{"_40":41,"_28":153,"_43":661,"_45":663},{"_155":662,"_157":199},"

import (\n    \"errors\"\n    \"github.com/jackc/pgx/v5/pgconn\"\n)\n\nconst sqlstateTrafficControl = \"53000\"\n\nfunc isTrafficControlError(err error) bool {\n    var pgErr *pgconn.PgError\n    return errors.As(err, &pgErr) && pgErr.Code == sqlstateTrafficControl\n}\n

",[],["SingleFetchClassInstance",665],{"_40":41,"_28":42,"_43":666,"_45":667},{},[668],"The right response depends on the query's role in your application:",["SingleFetchClassInstance",670],{"_40":41,"_28":153,"_43":671,"_45":673},{"_155":672,"_157":199},"

func (s *OrderService) GetUserOrders(ctx context.Context, userID int64) ([]Order, error) {\n    rows, err := s.db.QueryContext(ctx, `SELECT id, total FROM orders WHERE user_id = $1`, userID)\n    if err != nil {\n        if isTrafficControlError(err) {\n            // Return a degraded response rather than a 500\n            return nil, ErrServiceUnavailable\n        }\n        return nil, err\n    }\n    defer rows.Close()\n    // ...\n}\n

",[],["SingleFetchClassInstance",675],{"_40":41,"_28":42,"_43":676,"_45":677},{},[678,48,679,684,48,685,48,686],"For non-critical workloads like analytics or reporting, returning a",["SingleFetchClassInstance",680],{"_40":41,"_28":244,"_43":681,"_45":682},{},[683],"503 Service Unavailable"," or a cached result is most likely the right behavior.","That's exactly the controlled failure mode Traffic Control is designed to","create. For more critical paths, you may want a short retry with backoff:",["SingleFetchClassInstance",688],{"_40":41,"_28":153,"_43":689,"_45":691},{"_155":690,"_157":199},"

func queryWithBackoff(ctx context.Context, db *sql.DB, query string, args ...any) (*sql.Rows, error) {\n    const maxRetries = 3\n    backoff := 100 * time.Millisecond\n\n    for attempt := range maxRetries {\n        rows, err := db.QueryContext(ctx, query, args...)\n        if err == nil {\n            return rows, nil\n        }\n        if !isTrafficControlError(err) || attempt == maxRetries-1 {\n            return nil, err\n        }\n        select {\n        case <-time.After(backoff):\n            backoff *= 2\n        case <-ctx.Done():\n            return nil, ctx.Err()\n        }\n    }\n    return nil, errors.New(\"overloaded\")\n}\n

",[],["SingleFetchClassInstance",693],{"_40":41,"_28":694,"_43":695,"_45":697},"h3",{"_128":696},"observing-warn-mode-notices",[698],["SingleFetchClassInstance",699],{"_40":41,"_28":51,"_43":700,"_45":702},{"_53":701},"#observing-warn-mode-notices",[703],"Observing warn-mode notices",["SingleFetchClassInstance",705],{"_40":41,"_28":42,"_43":706,"_45":707},{},[708,48,709,48,710,714,715,719,48,720],"Before switching a budget to Enforce, you'll run it in Warn mode. In Warn mode,","queries succeed but the driver receives a Postgres notice containing",["SingleFetchClassInstance",711],{"_40":41,"_28":244,"_43":712,"_45":713},{},[646],". With ",["SingleFetchClassInstance",716],{"_40":41,"_28":244,"_43":717,"_45":718},{},[658]," you can log these notices to","build an accurate picture of what would be blocked:",["SingleFetchClassInstance",722],{"_40":41,"_28":153,"_43":723,"_45":725},{"_155":724,"_157":199},"

import \"github.com/jackc/pgx/v5\"\n\nconfig, err := pgx.ParseConfig(dsn)\nif err != nil {\n    log.Fatal(err)\n}\n\nconfig.OnNotice = func(c *pgconn.PgConn, notice *pgconn.Notice) {\n    if strings.Contains(notice.Message, \"[PGINSIGHTS] Traffic Control:\") {\n        log.Printf(\"traffic control warning: %s\", notice.Message)\n        // Increment a metric, write to a structured log, etc.\n    }\n}\n

",[],["SingleFetchClassInstance",727],{"_40":41,"_28":42,"_43":728,"_45":729},{},[730,48,731,48,732],"Collect these logs for a few hours of representative traffic before switching to","Enforce. The pattern of which rules fire and how often tells you whether your","limits need adjustment.",["SingleFetchClassInstance",734],{"_40":41,"_28":126,"_43":735,"_45":737},{"_128":736},"putting-it-together",[738],["SingleFetchClassInstance",739],{"_40":41,"_28":51,"_43":740,"_45":742},{"_53":741},"#putting-it-together",[743],"Putting it together",["SingleFetchClassInstance",745],{"_40":41,"_28":42,"_43":746,"_45":747},{},[748],"These patterns compose. A real application might layer several of them:",["SingleFetchClassInstance",750],{"_40":41,"_28":153,"_43":751,"_45":753},{"_155":752,"_157":199},"

func (s *Server) setupMiddleware() http.Handler {\n    mux := http.NewServeMux()\n    // register routes...\n\n    var handler http.Handler = mux\n    handler = SQLTagMiddleware(handler)   // Pattern 2: route tags\n    handler = AuthMiddleware(s.users, handler) // Pattern 4: tier tags\n    return handler\n}\n\n// At startup, the job worker uses Pattern 5: Background jobs\njobDB, _ := newJobDB(dsn)\n\n// New features use Pattern 3:\n// DEPLOYMENT_TAG=new_checkout_v2 set in the deployment manifest\n

",[],["SingleFetchClassInstance",755],{"_40":41,"_28":42,"_43":756,"_45":757},{},[758,48,759,763,48,764,769,48,770,48,771],"Traffic Control sees all of this as a combination of tags. A budget on",["SingleFetchClassInstance",760],{"_40":41,"_28":244,"_43":761,"_45":762},{},[475]," covers all free-tier traffic regardless of route. A budget on",["SingleFetchClassInstance",765],{"_40":41,"_28":244,"_43":766,"_45":767},{},[768],"route='api-export' AND tier='free'"," covers a specific combination. Multiple","matching budgets all apply simultaneously and queries must satisfy every budget","they match. You can build layered policies without complicated rule logic.",["SingleFetchClassInstance",773],{"_40":41,"_28":42,"_43":774,"_45":775},{},[776,48,777,48,778,48,779,785,48,786],"Start in Warn mode, observe which budgets would fire during normal load, tighten","the limits until only pathological cases trigger violations, then switch to","Enforce. The",["SingleFetchClassInstance",780],{"_40":41,"_28":51,"_43":781,"_45":783},{"_53":782},"/docs/postgres/traffic-control/getting-started",[784],"getting started guide"," walks","through this rollout process in detail.",["SingleFetchClassInstance",788],{"_40":41,"_28":42,"_43":789,"_45":790},{},[791,48,792,48,793,48,794],"The difference between a database outage and a degraded experience often comes","down to whether you've decided in advance which traffic to shed. Traffic Control","makes that decision explicit and configurable instead of leaving it to whichever","query happens to win a resource race.","body_text","Last week we introducedDatabase Traffic Control™. TrafficControl lets you attach resource budgets to slices of your Postgres traffic,like keeping your checkout flow running while a runaway analytics query getsshed instead. We have already discussed some scenarios where youshould use Traffic Control, along with how to define resource limits, so nowlet's dig into what Traffic Control looks like in your codebase.\n\nThis post walks through some practical patterns in Go. Each pattern targets adifferent failure mode, architecture, or foot gun. Most of them layer on top ofone another too, so you can adopt them individually or combine them for extrapeace of mind. Keep in mind the general concepts here are applicable to whateverlanguage your application is written in.\nSetup\nMost of the patterns here rely on custom tags attached to your queries. TrafficControl reads these using theSQLCommenter format: a SQL commentappended to each query with URL-encoded key=value pairs.SELECT * FROM orders \n WHERE user_id = $1\n /*route='checkout',feature='new_order_flow'*/;\n\nThese tags are then available for new Traffic Control rules.\n\nHere's a minimal Go helper that appends tags in this format:import (\n \"fmt\"\n \"net/url\"\n \"sort\"\n \"strings\"\n)\n\n// appendTags appends SQLCommenter-format tags to a SQL query.\nfunc appendTags(query string, tags map[string]string) string {\n if len(tags) == 0 {\n return query\n }\n parts := make([]string, 0, len(tags))\n for k, v := range tags {\n parts = append(parts, fmt.Sprintf(\"%s='%s'\", k, url.QueryEscape(v)))\n }\n sort.Strings(parts) // deterministic order\n return query + \" /*\" + strings.Join(parts, \",\") + \"*/\"\n}\n\nYou'll also want a way to thread tags through your call stack without touchingevery function signature. A context key works well for this:type contextKey string\n\nconst sqlTagsKey contextKey = \"sql_tags\"\n\nfunc tagsFromContext(ctx context.Context) map[string]string {\n if tags, ok := ctx.Value(sqlTagsKey).(map[string]string); ok {\n // return a copy so callers can't mutate shared state\n out := make(map[string]string, len(tags))\n for k, v := range tags {\n out[k] = v\n }\n return out\n }\n return make(map[string]string)\n}\n\nfunc contextWithTags(ctx context.Context, tags map[string]string) context.Context {\n return context.WithValue(ctx, sqlTagsKey, tags)\n}\n\nWith these two helpers in place, the patterns below mostly just set keys andvalues in context. Tagging happens automatically when the query executes.\nPer-service isolation via Roles\nIn a microservice architecture, a single misbehaving service should not be ableto degrade every other service sharing the same database. The simplest way toisolate a service is to create a Traffic Control rule based on a uniqueconnection string for the given service, or via application name.\nA budget on username='pscale_api_123abc' will isolate all traffic from thatrole. This also helps in incident response: you can immediately cap a service'sresource share without redeploying anything.\nNote that the username is the internal Postgres username of the role, not thedashboard role name. You can also target custom roles created by CREATE ROLEif your microservices have strict security over table permissions.\nYou can also use the application_name by appending it to your connectionstrings such as postgresql://other@localhost/otherdb?application_name=myapp.\nRoute-level tagging in an HTTP service\nWhen you're running a monolith or a large API service, the problem isn't usuallythe whole service, it's specific routes. The /api/export endpoint thatgenerates CSV reports should not be able to kill the /api/checkout flow.\nAn HTTP middleware can inject the route into context at runtime before anyhandler runs:// Any route using SQLTagMiddleware will have the pattern injected into its context\n// dynamically at runtime\nfunc SQLTagMiddleware(next http.Handler) http.Handler {\n return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n tags := tagsFromContext(r.Context())\n route := strings.ReplaceAll(strings.ReplaceAll(r.Pattern, \"{\", \":\"), \"}\", \":\") // Removes \"{}\" characters from route\n tags[\"route\"] = route\n tags[\"app\"] = \"web\"\n ctx := contextWithTags(r.Context(), tags)\n next.ServeHTTP(w, r.WithContext(ctx))\n })\n}\n\nWrap your database calls to pick up the tags automatically:// QueryContext for SELECT statements\nfunc (db *DB) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) {\n return db.sql.QueryContext(ctx, appendTags(query, tagsFromContext(ctx)), args...)\n}\n\n// ExecContext for INSERT/UPDATE statements\nfunc (db *DB) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) {\n return db.sql.ExecContext(ctx, appendTags(query, tagsFromContext(ctx)), args...)\n}\n\nNow every query carries the route it came from. You can create a Traffic Controlbudget targeting route='/api-export' and give it a conservative CPU limit.\nThis also makes it easy to set up broad budgets during incidents. If yousuddenly see a spike and don't know which route is responsible, the violationgraph in Traffic Control will show you exactly which route tag is hittinglimits.\nFeature flags and new deployments\nShipping a new feature to production always carries risk. Maybe the new querypattern is fine under your test load but becomes expensive at scale. TrafficControl gives you a way to cap the blast radius before it becomes an incident.\nThe simplest version sets a tag from an environment variable at startup:var deploymentTag = os.Getenv(\"DEPLOYMENT_TAG\") // e.g. \"new_checkout_v2\" or git sha \"96e350426\"\n\nfunc tagWithDeployment(ctx context.Context) context.Context {\n if deploymentTag == \"\" {\n return ctx\n }\n tags := tagsFromContext(ctx)\n tags[\"feature\"] = deploymentTag\n return contextWithTags(ctx, tags)\n}\n\nSet DEPLOYMENT_TAG=new_checkout_v2 when rolling out new pods and leave itunset on the old pods. Traffic Control can then have a budget onfeature='new_checkout_v2' in Warn mode from day one, so you see exactly howthe new code behaves before it causes problems. When you're confident, eitherremove the budget or switch it to Enforce as a safety net.\nFor feature flags controlled at runtime, the same approach works but driven byyour flag evaluation:func (h *OrderHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {\n ctx := r.Context()\n if flags.Enabled(ctx, \"new_order_flow\") {\n tags := tagsFromContext(ctx)\n tags[\"feature\"] = \"new_order_flow\"\n ctx = contextWithTags(ctx, tags)\n }\n h.processOrder(ctx, w, r)\n}\n\nTier-based limits in multi-tenant apps\nIn a SaaS application, free-tier users should not be able to degrade theexperience for enterprise customers. Traffic Control lets you enforce this atthe database level rather than just at the application layer.\nInject the user's subscription tier into the SQL tags early in your requesthandling — ideally right after you've resolved the authenticated user:type Tier string\n\nconst (\n TierFree Tier = \"FREE\"\n TierPro Tier = \"PRO\"\n TierEnterprise Tier = \"ENTERPRISE\"\n)\n\nfunc WithUserTier(ctx context.Context, tier Tier) context.Context {\n tags := tagsFromContext(ctx)\n tags[\"tier\"] = string(tier)\n return contextWithTags(ctx, tags)\n}\n\nIn your authentication middleware:func AuthMiddleware(users *UserService, next http.Handler) http.Handler {\n return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n user, err := users.Authenticate(r)\n if err != nil {\n http.Error(w, \"unauthorized\", http.StatusUnauthorized)\n return\n }\n ctx := WithUserTier(r.Context(), user.Tier)\n next.ServeHTTP(w, r.WithContext(ctx))\n })\n}\n\nWith this in place, create two Traffic Control budgets:\ntier='free' — conservative limits on server share and max concurrent queries\ntier='pro' — moderate limits\nLeave enterprise traffic unbudgeted or give it a high budget as a ceiling. Whena free-tier user runs an expensive dashboard or triggers a slow query, thebudget sheds that traffic before it touches enterprise workloads.\nYou can combine this with the route tag from Pattern 2. A budget matchingtier='free' AND route='api-export' can be stricter than a budget ontier='free' alone. Enterprise export requests get more headroom than free-tierexport requests.\nBackground jobs and scripts\nBackground jobs are a common cause of database incidents. A migration script, anightly sync, or a one-off data backfill can all accidentally saturate yourdatabase if they run faster than expected. Traffic Control is a clean way togive these jobs a resource ceiling without having to tune query-level timeoutsthroughout your codebase.\nFor long-running background workers, use a dedicated connection pool with adistinct application_name:func newJobDB(dsn string) (*sql.DB, error) {\n jobDSN, err := url.Parse(dsn) // your connection string\n if err != nil {\n return nil, err\n }\n q := jobDSN.Query()\n // This sets the application name in code instead of in the connection string env variable.\n q.Set(\"application_name\", \"background-jobs\")\n jobDSN.RawQuery = q.Encode()\n\n db, err := sql.Open(\"pgx\", jobDSN.String()) // connects to Postgres\n if err != nil {\n return nil, err\n }\n db.SetMaxOpenConns(4) // Jobs don't need high concurrency\n return db, nil\n}\n\nnewJobDB takes the DSN of your database and sets application_name tobackground-jobs before connecting. Once connected we set the max connectionsto 4 to make sure our background job isn't taking up more workers than itshould, and finally we return it so that the calling function can now query thedatabase.\nSetting application_name on the connection string level in code ensures thatit is always set for this service, no matter the query or connection stringgiven. You can pair this with SQL comments as described above for even morefine-grained control and insights into your queries.\nFor one-off scripts and migrations we can do something similar. Here we encodethe script's identity directly in the connection string so it shows up clearlyin Traffic Control and Insights:// Returns a database instance with the `application_name` set to `script-[scriptName]`\n// for use in scripts\nfunc scriptDB(dsn, scriptName string) (*sql.DB, error) {\n u, _ := url.Parse(dsn)\n q := u.Query()\n q.Set(\"application_name\", \"script-\"+scriptName) // e.g. \"script-backfill-order-totals\"\n u.RawQuery = q.Encode()\n return sql.Open(\"pgx\", u.String())\n}\n\nCreate a Traffic Control budget for application_name='background-jobs' in Warnmode before you run this job next. Observe how much of the database's resourcesyour background work typically consumes. Then switch to Enforce to cap it at alevel where it can't crowd out interactive traffic even if a job goes sideways.\nHandling blocked queries\nWhen Traffic Control is in Enforce mode and a query exceeds its budget, Postgresreturns SQLSTATE 53000 with an error message prefixed with[PGINSIGHTS] Traffic Control:. Your application needs to handle this withoutcrashing.\nWith pgx/v5:import (\n \"errors\"\n \"github.com/jackc/pgx/v5/pgconn\"\n)\n\nconst sqlstateTrafficControl = \"53000\"\n\nfunc isTrafficControlError(err error) bool {\n var pgErr *pgconn.PgError\n return errors.As(err, &pgErr) && pgErr.Code == sqlstateTrafficControl\n}\n\nThe right response depends on the query's role in your application:func (s *OrderService) GetUserOrders(ctx context.Context, userID int64) ([]Order, error) {\n rows, err := s.db.QueryContext(ctx, `SELECT id, total FROM orders WHERE user_id = $1`, userID)\n if err != nil {\n if isTrafficControlError(err) {\n // Return a degraded response rather than a 500\n return nil, ErrServiceUnavailable\n }\n return nil, err\n }\n defer rows.Close()\n // ...\n}\n\nFor non-critical workloads like analytics or reporting, returning a503 Service Unavailable or a cached result is most likely the right behavior.That's exactly the controlled failure mode Traffic Control is designed tocreate. For more critical paths, you may want a short retry with backoff:func queryWithBackoff(ctx context.Context, db *sql.DB, query string, args ...any) (*sql.Rows, error) {\n const maxRetries = 3\n backoff := 100 * time.Millisecond\n\n for attempt := range maxRetries {\n rows, err := db.QueryContext(ctx, query, args...)\n if err == nil {\n return rows, nil\n }\n if !isTrafficControlError(err) || attempt == maxRetries-1 {\n return nil, err\n }\n select {\n case <-time.After(backoff):\n backoff *= 2\n case <-ctx.Done():\n return nil, ctx.Err()\n }\n }\n return nil, errors.New(\"overloaded\")\n}\n\nObserving warn-mode notices\nBefore switching a budget to Enforce, you'll run it in Warn mode. In Warn mode,queries succeed but the driver receives a Postgres notice containing[PGINSIGHTS] Traffic Control:. With pgx/v5 you can log these notices tobuild an accurate picture of what would be blocked:import \"github.com/jackc/pgx/v5\"\n\nconfig, err := pgx.ParseConfig(dsn)\nif err != nil {\n log.Fatal(err)\n}\n\nconfig.OnNotice = func(c *pgconn.PgConn, notice *pgconn.Notice) {\n if strings.Contains(notice.Message, \"[PGINSIGHTS] Traffic Control:\") {\n log.Printf(\"traffic control warning: %s\", notice.Message)\n // Increment a metric, write to a structured log, etc.\n }\n}\n\nCollect these logs for a few hours of representative traffic before switching toEnforce. The pattern of which rules fire and how often tells you whether yourlimits need adjustment.\nPutting it together\nThese patterns compose. A real application might layer several of them:func (s *Server) setupMiddleware() http.Handler {\n mux := http.NewServeMux()\n // register routes...\n\n var handler http.Handler = mux\n handler = SQLTagMiddleware(handler) // Pattern 2: route tags\n handler = AuthMiddleware(s.users, handler) // Pattern 4: tier tags\n return handler\n}\n\n// At startup, the job worker uses Pattern 5: Background jobs\njobDB, _ := newJobDB(dsn)\n\n// New features use Pattern 3:\n// DEPLOYMENT_TAG=new_checkout_v2 set in the deployment manifest\n\nTraffic Control sees all of this as a combination of tags. A budget ontier='free' covers all free-tier traffic regardless of route. A budget onroute='api-export' AND tier='free' covers a specific combination. Multiplematching budgets all apply simultaneously and queries must satisfy every budgetthey match. You can build layered policies without complicated rule logic.\nStart in Warn mode, observe which budgets would fire during normal load, tightenthe limits until only pathological cases trigger violations, then switch toEnforce. Thegetting started guide walksthrough this rollout process in detail.\nThe difference between a database outage and a degraded experience often comesdown to whether you've decided in advance which traffic to shed. Traffic Controlmakes that decision explicit and configurable instead of leaving it to whicheverquery happens to win a resource race.","aside","toc",[800,805,807,809,811,813,815,820],{"_45":801,"_128":129,"_802":803,"_804":136},[],"level",2,"title",{"_45":806,"_128":221,"_802":803,"_804":228},[],{"_45":808,"_128":284,"_802":803,"_804":291},[],{"_45":810,"_128":361,"_802":803,"_804":368},[],{"_45":812,"_128":420,"_802":803,"_804":427},[],{"_45":814,"_128":519,"_802":803,"_804":526},[],{"_45":816,"_128":622,"_802":803,"_804":629},[817],{"_45":818,"_128":696,"_802":819,"_804":703},[],3,{"_45":821,"_128":736,"_802":803,"_804":743},[],"Patterns for Postgres Traffic Control","authors",[825],{"_26":27,"_28":29,"_30":31},"categories",[828],"engineering","excerpt","Practical patterns for leveraging Database traffic Control","createdAt","2026-04-02","meta",{"_835":836,"_837":830,"_838":839,"_804":822},"canonical","https://planetscale.com/blog/patterns-for-postgres-traffic-control","description","image","/assets/patterns-for-postgres-traffic-control-social-CJkJTKOD.png","pagination",{"_842":843,"_844":8,"_845":8,"_846":843,"_847":848},"page",1,"hasPrev","hasNext","totalPages","url","https://planetscale.com/blog/author/joshbrown","https://planetscale.com","actionData","errors"]

Posts by Josh Brown

Patterns for Postgres Traffic Control