supabase-cost-tuning — Claude Code skill: install and use
The supabase-cost-tuning skill audits Supabase spending and points to waste in the database, storage, connections, and Edge Functions.
MIT 1 installs ★ 2,935 updated 2026-11-01
npx skills add jeremylongshore/tons-of-skills-marketplace --skill supabase-cost-tuning -a claude-codeWhat supabase-cost-tuning does
The skill uses a three-step review of a Supabase project. It starts with database size, table growth, unused indexes, dead tuples, connection counts, storage usage, and current billing. SQL queries cover the database; a service-role client handles bucket audits and cleanup scripts.
It then targets the largest findings: archive old rows, run VACUUM ANALYZE, compress images before upload, remove orphaned files, and reduce bandwidth with explicit columns, head: true counts, and .range() pagination. The final step examines direct, session, and transaction pooling, plus caching and dynamic imports in Edge Functions.
Before using it, prepare Dashboard and SQL Editor access, install @supabase/supabase-js, and provide a service role key for storage audits and admin scripts. Migrations may need direct or session semantics, so routing every workflow through transaction pooling can break the setup.
What it helps with
- audit which tables and indexes drive database usage
- find dead tuples and plan
VACUUM ANALYZEwork - remove Supabase Storage files that have no linked record
- cut bandwidth with column selection and pagination
- right-size connection pooling before increasing compute
Example prompts for the agent
- Audit this Supabase project and identify the main cost drivers.
- Review the database, Storage, and connections, then suggest changes in order.
- Check whether pooling, archival, and orphan cleanup can reduce compute usage.
How to install supabase-cost-tuning
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill supabase-cost-tuning -a claude-code2Manually: put the files in place
~/.claude/skills/supabase-cost-tuning/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/supabase-cost-tuning/
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill supabase-cost-tuning -a codex2Manually: put the files in place
.agents/skills/supabase-cost-tuning/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill supabase-cost-tuning -a cursor2Manually: put the files in place
.cursor/skills/supabase-cost-tuning/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install jeremylongshore/tons-of-skills-marketplace skills/.curated/supabase-cost-tuning2Manually: put the files in place
.github/skills/supabase-cost-tuning/SKILL.md1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill supabase-cost-tuning -a gemini-cli2Platform CLI
gemini skills install https://github.com/jeremylongshore/tons-of-skills-marketplace --path skills/.curated/supabase-cost-tuningManually: put the files in place
.devin/skills/supabase-cost-tuning/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill supabase-cost-tuning -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about supabase-cost-tuning
How do I install supabase-cost-tuning in Claude Code?
Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill supabase-cost-tuning -a claude-code. The skill file will be available at ~/.claude/skills/supabase-cost-tuning/SKILL.md.
What does supabase-cost-tuning do?
It audits Supabase usage and billing, then reviews database waste, Storage files, connection pooling, bandwidth, compute sizing, and Edge Function resource use.
What does supabase-cost-tuning need to work?
You need Supabase Dashboard and SQL Editor access, @supabase/supabase-js, and a service role key for storage audits and administrative scripts.
Source text
SKILL.md · MIT
--- name: supabase-cost-tuning description: 'Optimize Supabase costs through plan selection, database tuning, storage cleanup, connection pooling, and Edge Function optimization. Use when analyzing Supabase billing, reducing costs, right-sizing compute, or implementing usage tracking and budget alerts. Trigger with phrases like "supabase cost", "supabase billing", "reduce supabase costs", "supabase pricing", "supabase expensive", "supabase budget". ' allowed-tools: Read, Write, Edit, Grep, Bash(supabase:*) version: 1.55.0 license: MIT author: Jeremy Longshore <[email protected]> tags: - saas - supabase - cost-optimization compatibility: Designed for Claude Code --- # Supabase Cost Tuning ## Overview Reduce Supabase spend by auditing usage against plan limits, eliminating database and storage waste, and right-sizing compute resources. The three biggest levers: database optimization (vacuum, index cleanup, archival), storage lifecycle management (compress before upload, orphan cleanup), and connection pooling to reduce compute add-on requirements. Work the three steps below in order — audit first to find where the money goes, then optimize the biggest offenders, then right-size compute. Each step keeps a representative snippet inline; the full query and script sets live in `references/` so this file stays scannable. ## Prerequisites - Supabase project with Dashboard access (Settings > Billing) - `@supabase/supabase-js` installed: `npm install @supabase/supabase-js` - Service role key for admin operations (storage audit, cleanup scripts) - SQL editor access (Dashboard > SQL Editor or `psql` connection) ## Pricing Reference Reviewed 2026-10-22: use [current pricing](https://supabase.com/pricing) and the project's actual billing dashboard rather than a universal hard-coded plan table. Compute is billed hourly; paid organizations receive $10 of compute credits per month, shared across projects, not a free compute instance for every project. The [compute usage reference](https://supabase.com/docs/guides/platform/manage-your-usage/compute) lists Small at $0.0206/hour (about $15 for 730 hours), Medium at $0.0822/hour (about $60), and Large at $0.1517/hour (about $111), before plan fees, credits and other usage. These dated estimates are not a billing quote or fixed monthly cap. Read replicas have their own compute and usage costs, not a universal $25/month price. Model the selected size, active hours, disk, egress, region and current plan allowances before changing topology. Pooling can reduce connection overhead but does not guarantee that a smaller compute size will satisfy the workload. ## Instructions ### Step 1: Audit current usage and identify cost drivers Find where the database budget is going before changing anything. Run the audit queries in the SQL Editor to surface the biggest tables, unused indexes, dead-tuple bloat, and connection count. Start with total size: ```sql select pg_size_pretty(pg_database_size(current_database())) as total_db_size; ``` Then audit storage per bucket with a service-role client, and read current spend under **Dashboard > Settings > Billing**. See [full audit queries and storage script](references/audit-queries.md) for the complete SQL set (table sizes, zero-scan indexes, dead-tuple ratio, connection count) and the per-bucket usage script. ### Step 2: Optimize database, storage, and bandwidth Attack the biggest offenders from Step 1. Archive old rows before deleting, then VACUUM ANALYZE to make dead-tuple space reusable and refresh planner stats; ordinary VACUUM does not generally shrink the on-disk allocation: ```sql vacuum (verbose, analyze) public.events; ``` For storage, compress images client-side before upload and schedule an orphan-cleanup job. For bandwidth, replace `select('*')` with explicit column lists, use `head: true` count queries for totals, and paginate with `.range()`. See [full optimization code](references/optimization.md) for the archival + VACUUM SQL, the compress/clean-orphans scripts, and the bandwidth-reduction patterns. ### Step 3: Right-size compute and distinguish invocation cost from latency Prefer pooling and code fixes over a compute upgrade. Choose the appropriate direct or Supavisor session/transaction connection mode for the client. Migrations may require direct/session semantics; do not send every workflow to transaction pooling: ```typescript // Copy the actual direct/session/transaction connection string from Dashboard. // Do not derive the pooler hostname by changing only the port. // Transaction pooling constraints (including prepared statements) need review. ``` Smaller imports and warm-instance caching can improve latency/resource use, but do not themselves reduce hosted Edge Function invocation charges. Current [invocation billing](https://supabase.com/docs/guides/platform/manage-your-usage/edge-function-invocations) is based on invocation count (excluding preflight OPTIONS), with package rounding for billable overage. Avoid unnecessary invocations and retry storms within the application's correctness requirements; do not skip required work to reduce counts. Treat historical optimization examples as resource/latency patterns, not evidence of invocation savings. Use actual billing usage rather than a custom event table as invoice authority. ## Output After completing all three steps, the project has: - Database size audit with table-level breakdown and dead tuple analysis - Candidate unused indexes reviewed against representative workloads before any approved drop - Approved archival and vacuum outcomes measured without promising physical disk shrinkage - Storage orphans cleaned and upload compression implemented - Bandwidth reduced through column selection and pagination - Connection pooling configured to avoid unnecessary compute upgrades - Edge Function cold starts minimized with dynamic imports and caching - Usage monitoring table and daily summary view for spend visibility ## Error Handling | Issue | Cause | Solution | | ------------------------------------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Database approaching 500 MB (Free) or 8 GB (Pro) | Data growth without archival | Archive old records, VACUUM, drop unused indexes | | Storage costs climbing monthly | Orphaned uploads accumulating | Schedule cleanup job for files not linked to records | | Unexpected bandwidth spike | `select('*')` on large tables | Use specific column lists; add `.range()` pagination | | Edge Function billing spike | Excess invocations or retry loops | Inspect invocation counts and correctness-preserving admission/retry budgets; import size is a latency concern | | Connection limit errors | Too many direct connections | Switch to pooler URL (port 6543); reduce client pool size | | Spend cap reached | A capped usage surface reached its allowance | Review the current spend-cap coverage and response; it does not cap every charge | | VACUUM not reclaiming space | Long-running transactions holding locks | Check `pg_stat_activity` for idle-in-transaction; terminate stale sessions | ## Examples **Quick cost check** — inspect actual billing usage and an authorized database-size query; bucket count is not stored bytes. **Cost estimation** — supply reviewed quantities, units, current rates, eligible credits and source/date to an explicitly scoped calculator. No universal Pro-tier total is supplied. The [explicit-input examples](references/examples.md) validate arithmetic without embedding provider rates. Reconcile every included allowance, package/tier rounding, compute hour, credit and excluded charge against the current billing surface before using an estimate for a decision. ## Resources - [Supabase Pricing](https://supabase.com/pricing) — plan comparison and calculator - [Compute Add-ons](https://supabase.com/docs/guides/platform/compute-add-ons) — instance sizing guide - [Spend Cap](https://supabase.com/docs/guides/platform/spend-cap) — prevent unexpected overage charges - [Database Disk Usage](https://supabase.com/docs/guides/platform/database-size) — monitoring and management - [Connection Pooling (Supavisor)](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pooler) — reduce connection overhead - [Edge Functions Best Practices](https://supabase.com/docs/guides/functions/best-practices) — cold start and performance tips - [supabase-js Reference](https://supabase.com/docs/reference/javascript/introduction) — `createClient` and SDK patterns ## Next Steps For architecture patterns, see `supabase-reference-architecture`. For performance tuning beyond cost, see `supabase-performance-tuning`.
© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace