pscale traffic-control
Manage Database Traffic Control budgets and rules for PlanetScale Postgres branches. Start with read-only inventory and Insights evidence; never create, update, delete, or enforce a budget without explicit approval.
Inventory
# List budgets and embedded rule metadata for the branch
pscale traffic-control budget list <database> <branch> --org <org> --format json
# Find budgets containing a rule for one exact Insights fingerprint
pscale traffic-control budget list <database> <branch> --org <org> \
--fingerprint <fingerprint> --format json
# Show one budget and its rules
pscale traffic-control budget show <database> <branch> <budget-id> \
--org <org> --format json
This command family is Postgres-only. Prefer JSON so IDs, nullable limits, modes, and nested rules are not truncated. An empty filtered list means no budget currently has a rule for that exact fingerprint; it does not mean the query is harmless or that no tag/keyspace rule could affect it.
Recommendation workflow
- Confirm organization, Postgres database, branch, and current application impact.
- List all budgets and inspect each relevant budget by ID.
- Gather Insights queries, full error fingerprints, tags, anomalies, and application ownership for the intended traffic slice.
- Prefer stable, bounded tags for a traffic class; use an exact fingerprint when one known query shape needs containment. Avoid unbounded values such as request IDs, user IDs, emails, UUIDs, or raw URLs.
- Propose one focused budget with exact mode, capacity, rate, burst, concurrency, warning threshold, and rules. Explain application rejection risk and rollback.
- Start in
warn for normal rollout, observe warnings/false positives, and move to enforce only after explicit approval. Use enforce immediately only for an explicitly authorized incident response.
- After any write, re-run
budget show and budget list and compare every returned field/rule.
Traffic Control is a database resource guardrail. It does not replace query tuning, application rate limits, workload isolation, or incident diagnosis. enforce can reject matching queries and change application behavior.
Budget writes
# Create in warn mode after approval; omitted numeric limits remain unlimited
pscale traffic-control budget create <database> <branch> --org <org> \
--name <name> \
--mode warn \
--capacity <0-6000> \
--rate <0-100> \
--burst <0-6000> \
--concurrency <0-100> \
--warning-threshold <0-100> \
--format json
# Update sends only flags explicitly supplied
pscale traffic-control budget update <database> <branch> <budget-id> \
--org <org> --mode warn --format json
# Delete only after inspecting rules and approving their removal
pscale traffic-control budget delete <database> <branch> <budget-id> --org <org>
--name is required on create and the default mode is warn. On create and update, omitted numeric flags are not sent; distinguish omission from an explicit zero. Before changing limits or mode, save the current JSON and verify that the application has a tested rollback path. Use --force on delete only for an already-approved non-interactive action.
Rule writes
# Exact query fingerprint
pscale traffic-control rule create <database> <branch> <budget-id> --org <org> \
--fingerprint <fingerprint> --format json
# Stable tag; source defaults to sql when omitted
pscale traffic-control rule create <database> <branch> <budget-id> --org <org> \
--tag 'key=feature,value=export,source=sql' --format json
# Delete one reviewed rule
pscale traffic-control rule delete <database> <branch> <budget-id> <rule-id> \
--org <org>
Rule create also accepts --keyspace and repeatable --tag; --kind defaults to match. Each tag must contain non-empty key and value; source defaults to sql. Confirm the complete matching scope before creation. A broad or incorrect rule can affect unrelated traffic, especially under an enforced budget. Use budget show to verify the created/deleted rule and never infer a rule ID from a truncated display.
Related Skills
- pscale-insights — gather query fingerprints, tags, errors, and anomaly evidence
- pscale-metrics — compare branch resource behavior before and after a rollout
- pscale-branch — inspect the exact Postgres branch and infrastructure target
References
See references/commands.md for the checksum-verified command help.
1---2name: pscale-traffic-control3description: Inventory and safely manage PlanetScale Postgres Database Traffic Control budgets and fingerprint, keyspace, or tag rules. Use when listing budgets, discovering budget/rule IDs, filtering budgets by query fingerprint, planning warn-mode guardrails, changing capacity/rate/burst/concurrency thresholds, or creating/deleting matching rules. Triggers on pscale traffic-control, traffic budget, traffic rule, Database Traffic Control, query budget, fingerprint budget, tag rule, capacity, burst, concurrency, warning threshold.4metadata:5 source: https://skillmd.com/skills/vince-winkintel/pscale-traffic-control6---78# pscale traffic-control910Manage Database Traffic Control budgets and rules for PlanetScale Postgres branches. Start with read-only inventory and Insights evidence; never create, update, delete, or enforce a budget without explicit approval.1112## Inventory1314```bash15# List budgets and embedded rule metadata for the branch16pscale traffic-control budget list <database> <branch> --org <org> --format json1718# Find budgets containing a rule for one exact Insights fingerprint19pscale traffic-control budget list <database> <branch> --org <org> \20 --fingerprint <fingerprint> --format json2122# Show one budget and its rules23pscale traffic-control budget show <database> <branch> <budget-id> \24 --org <org> --format json25```2627This command family is Postgres-only. Prefer JSON so IDs, nullable limits, modes, and nested rules are not truncated. An empty filtered list means no budget currently has a rule for that exact fingerprint; it does not mean the query is harmless or that no tag/keyspace rule could affect it.2829## Recommendation workflow30311. Confirm organization, Postgres database, branch, and current application impact.322. List all budgets and inspect each relevant budget by ID.333. Gather Insights queries, full error fingerprints, tags, anomalies, and application ownership for the intended traffic slice.344. Prefer stable, bounded tags for a traffic class; use an exact fingerprint when one known query shape needs containment. Avoid unbounded values such as request IDs, user IDs, emails, UUIDs, or raw URLs.355. Propose one focused budget with exact mode, capacity, rate, burst, concurrency, warning threshold, and rules. Explain application rejection risk and rollback.366. Start in `warn` for normal rollout, observe warnings/false positives, and move to `enforce` only after explicit approval. Use `enforce` immediately only for an explicitly authorized incident response.377. After any write, re-run `budget show` and `budget list` and compare every returned field/rule.3839Traffic Control is a database resource guardrail. It does not replace query tuning, application rate limits, workload isolation, or incident diagnosis. `enforce` can reject matching queries and change application behavior.4041## Budget writes4243```bash44# Create in warn mode after approval; omitted numeric limits remain unlimited45pscale traffic-control budget create <database> <branch> --org <org> \46 --name <name> \47 --mode warn \48 --capacity <0-6000> \49 --rate <0-100> \50 --burst <0-6000> \51 --concurrency <0-100> \52 --warning-threshold <0-100> \53 --format json5455# Update sends only flags explicitly supplied56pscale traffic-control budget update <database> <branch> <budget-id> \57 --org <org> --mode warn --format json5859# Delete only after inspecting rules and approving their removal60pscale traffic-control budget delete <database> <branch> <budget-id> --org <org>61```6263`--name` is required on create and the default mode is `warn`. On create and update, omitted numeric flags are not sent; distinguish omission from an explicit zero. Before changing limits or mode, save the current JSON and verify that the application has a tested rollback path. Use `--force` on delete only for an already-approved non-interactive action.6465## Rule writes6667```bash68# Exact query fingerprint69pscale traffic-control rule create <database> <branch> <budget-id> --org <org> \70 --fingerprint <fingerprint> --format json7172# Stable tag; source defaults to sql when omitted73pscale traffic-control rule create <database> <branch> <budget-id> --org <org> \74 --tag 'key=feature,value=export,source=sql' --format json7576# Delete one reviewed rule77pscale traffic-control rule delete <database> <branch> <budget-id> <rule-id> \78 --org <org>79```8081Rule create also accepts `--keyspace` and repeatable `--tag`; `--kind` defaults to `match`. Each tag must contain non-empty `key` and `value`; `source` defaults to `sql`. Confirm the complete matching scope before creation. A broad or incorrect rule can affect unrelated traffic, especially under an enforced budget. Use `budget show` to verify the created/deleted rule and never infer a rule ID from a truncated display.8283## Related Skills8485- **pscale-insights** — gather query fingerprints, tags, errors, and anomaly evidence86- **pscale-metrics** — compare branch resource behavior before and after a rollout87- **pscale-branch** — inspect the exact Postgres branch and infrastructure target8889## References9091See [references/commands.md](references/commands.md) for the checksum-verified command help.