supabase-rate-limits
Provides strategies to handle Supabase rate limits, connection pooling, and retry logic to prevent API throttling.
Install
mkdir -p .claude/skills/supabase-rate-limits && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/5400" && unzip -o skill.zip -d .claude/skills/supabase-rate-limits && rm skill.zipInstalls to .claude/skills/supabase-rate-limits
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Manage Supabase rate limits and quotas across all plan tiers. Use when hitting 429 errors, configuring connection pooling, optimizing API throughput, or understanding tier-specific quotas for Auth, Storage, Realtime, and Edge Functions. Trigger with "supabase rate limit", "supabase 429", "supabase throttle", "supabase quota", "supabase connection pool", "supabase too many requests".Key capabilities
- →Understand Supabase rate limits across all API surfaces and plan tiers
- →Configure connection pooling using Supavisor for different workloads
- →Implement exponential-backoff retry logic for 429 errors
- →Paginate large queries to reduce payload size and avoid timeouts
- →Batch multiple write operations into a single upsert request
- →Monitor API usage through the Supabase dashboard
How it works
This skill details Supabase rate limits per tier and API surface, then provides patterns for connection pooling with Supavisor, exponential-backoff retries for 429 errors, pagination for large reads, and batch upserts for multiple writes.
Inputs & outputs
When to use supabase-rate-limits
- →Handling 429 errors
- →Optimizing API performance
- →Implementing retry logic
About this skill
Supabase Rate Limits
Overview
Supabase limits differ across PostgREST, Auth, Storage, Realtime, and Edge Functions. Use the current surface-specific documentation and project configuration rather than a universal requests-per-minute or requests-per-day table. Review pooling, bounded retries, pagination, and monitoring for the actual workload.
Prerequisites
- Active Supabase project (any tier)
@supabase/supabase-jsv2+ installed- Project URL and anon/service-role key available
- Node.js 22+ for current SDK releases, or another supported SDK runtime
Instructions
Step 1 — Know your tier limits
Record the relevant endpoint, project configuration, plan, observation date, and current provider documentation. Auth, Storage, Realtime, Edge Functions, and database connections have different controls; a plan name alone does not establish one universal API request budget. See rate-limit-tiers.md for the per-surface review.
Step 2 — Pool connections with Supavisor
Supavisor is Supabase's built-in connection pooler (replaced PgBouncer). Pick the mode by workload:
| Use case | Mode | Port |
|---|---|---|
| Serverless / Edge Functions | Transaction | 6543 |
| Next.js API routes | Transaction | 6543 |
| Long-running workers | Session | 5432 |
| Realtime subscriptions | Direct (no pooler) | 5432 |
| Prisma / Drizzle ORM | Transaction + ?pgbouncer=true | 6543 |
Transaction mode (port 6543) returns a connection to the pool after each transaction — the right default for serverless. Session mode (port 5432) holds a dedicated connection for LISTEN/NOTIFY and prepared statements. Full client setup and connection-string formats are in implementation.md.
Step 3 — Retry, paginate, and batch
Wrap queries in an exponential-backoff retry that recognizes 429s and pool exhaustion:
// Retryable when the error is a rate limit, "too many requests",
// code 429, or PGRST000 (connection pool exhausted). Delay doubles
// per attempt with jitter, capped at maxDelayMs, honoring Retry-After.
const users = await withRetry(() =>
supabase.from('users').select('id, email, created_at').eq('active', true)
)
Then cut request volume two ways: paginate large reads with .range(from, to) so responses stay small and avoid timeouts, and combine compatible writes using bounded batch upsert requests (choose chunk sizes for the actual payload and API behavior). The full withRetry, fetchPaginated, and batch/chunk helpers — plus dashboard monitoring steps — are in implementation.md.
Output
After applying this skill you will have:
- Dated, per-surface limit evidence and project-specific operating budgets
- Connection pooling configured via Supavisor (port 6543 transaction mode for serverless)
- Retry wrapper with exponential backoff handling 429 errors
- Paginated queries using
.range(0, 99)to reduce payload size - Batch upsert pattern reducing N requests to 1
- Dashboard monitoring configured for API usage alerts
Error Handling
| Error | Cause | Solution |
|---|---|---|
429 Too Many Requests | Endpoint-specific rate control or workload saturation | Apply withRetry backoff; reduce concurrency; upgrade tier |
PGRST000: could not connect | Connection pool exhausted | Switch to Supavisor transaction mode (port 6543); reduce concurrent queries |
Auth over_request_rate_limit | Too many signups/logins from one IP | Add CAPTCHA; configure custom auth rate limits in Dashboard |
Storage 413 Payload Too Large | File exceeds tier limit | Use TUS resumable upload; check tier file size limit |
Realtime too_many_connections | Concurrent connection limit reached | Unsubscribe unused channels; review the current project connection allowance |
Edge Function BOOT_ERROR | Cold start timeout or memory exceeded | Reduce bundle size; avoid large imports at top level |
pgbouncer=true errors with Prisma | Missing connection string parameter | Append ?pgbouncer=true to pooler connection string on port 6543 |
Use response headers only where the endpoint documents them; honor Retry-After when supplied. Endpoint-specific error handling is in errors.md.
Examples
- Serverless Edge Function with a batch-inserting, rate-limit-safe client — see examples.md
- Connection-string selection per runtime (serverless vs long-running vs direct) — see examples.md
- Queue-based throttling and client-side header monitoring — see examples.md
Resources
- Supabase Platform Limits & Quotas
- Supavisor Connection Pooling
- Edge Functions Limits
- Storage Limits
- @supabase/supabase-js Reference
Next Steps
For securing your Supabase project with RLS policies and API key management, see supabase-security-basics. For optimizing database queries and indexing, see supabase-performance-tuning.
When not to use it
- →When the Supabase project is not active
- →When @supabase/supabase-js v2+ is not installed
Prerequisites
Limitations
- →Rate limits vary by plan tier and API surface
- →Connection pool exhaustion can occur without proper Supavisor configuration
- →Auth rate limits may require CAPTCHA or custom configurations
How it compares
This workflow provides specific Supabase-centric strategies for managing rate limits and optimizing API usage, unlike general rate-limiting approaches.
Compared to similar skills
supabase-rate-limits side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| supabase-rate-limits (this skill) | 1 | 4mo | Review | Intermediate |
| sql-optimization-patterns | 64 | 6mo | No flags | Advanced |
| springboot-patterns | 11 | 8mo | No flags | Intermediate |
| backend-development | 17 | 7mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by jeremylongshore
View all by jeremylongshore →You might also like
sql-optimization-patterns
wshobson
Master SQL query optimization, indexing strategies, and EXPLAIN analysis to dramatically improve database performance and eliminate slow queries. Use when debugging slow queries, designing database schemas, or optimizing application performance.
springboot-patterns
affaan-m
Spring Boot 架构模式、REST API 设计、分层服务、数据访问、缓存、异步处理和日志记录。适用于 Java Spring Boot 后端工作。
backend-development
skillcreatorai
Backend API design, database architecture, microservices patterns, and test-driven development. Use for designing APIs, database schemas, or backend system architecture.
supabase-postgres-best-practices
davila7
Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
supabase-performance-tuning
jeremylongshore
Optimize Supabase API performance with caching, batching, and connection pooling. Use when experiencing slow API responses, implementing caching strategies, or optimizing request throughput for Supabase integrations. Trigger with phrases like "supabase performance", "optimize supabase", "supabase latency", "supabase caching", "supabase slow", "supabase batch".
analyzing-query-performance
jeremylongshore
Execute use when you need to work with query optimization. This skill provides query performance analysis with comprehensive guidance and automation. Trigger with phrases like "optimize queries", "analyze performance", or "improve query speed".