Supabase Prod Checklist

Supabase Production Deployment Checklist

Overview

Actionable 14-step checklist for taking a Supabase project to production. Covers RLS enforcement, key separation, connection pooling (Supavisor), backups/PITR, network restrictions, custom domains, auth emails, rate limits, monitoring, Edge Functions, Storage policies, indexes, and migrations. Based on Supabase's official production guide.

Prerequisites

• Supabase project on Pro plan or higher (required for PITR, network restrictions)
• Separate production project (never share dev/prod)
• @supabase/supabase-js v2+ installed
• Supabase CLI installed (npx supabase --version)
• Domain and DNS configured for custom domain
• Deployment platform ready (Vercel, Netlify, Cloudflare, etc.)

Instructions

Step 1: Enforce Row Level Security on ALL Tables

RLS is the single most critical production requirement. Without it, any client with your anon key can read/write every row.

-- Audit: find tables WITHOUT RLS enabled
-- This query MUST return zero rows before going live
SELECT schemaname, tablename, rowsecurity
FROM pg_tables
WHERE schemaname = 'public' AND rowsecurity = false;

-- Enable RLS on a table
ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;

-- Create a basic read policy (authenticated users see own rows)
CREATE POLICY "Users can view own profile"
  ON public.profiles
  FOR SELECT
  USING (auth.uid() = user_id);

-- Create an insert policy
CREATE POLICY "Users can insert own profile"
  ON public.profiles
  FOR INSERT
  WITH CHECK (auth.uid() = user_id);

-- Create an update policy
CREATE POLICY "Users can update own profile"
  ON public.profiles
  FOR UPDATE
  USING (auth.uid() = user_id)
  WITH CHECK (auth.uid() = user_id);

• RLS enabled on every public table (zero rows from audit query above)
• SELECT, INSERT, UPDATE, DELETE policies defined for each table
• Policies tested with both authenticated and anonymous roles
• No tables use USING (true) without intent (public read tables only)

Step 2: Enforce Key Separation — Anon vs Service Role

The anon key is safe for client-side code. The service_role key bypasses RLS entirely and must never leave server-side environments.

// Client-side — ONLY use anon key
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!  // Safe for browsers
);

// Server-side only — service_role key (API routes, webhooks, cron jobs)
import { createClient } from '@supabase/supabase-js';

const supabaseAdmin = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!,  // NEVER expose to client
  { auth: { autoRefreshToken: false, persistSession: false } }
);

• Anon key used in all client-side code (NEXT_PUBLIC_ prefix)
• Service role key used only in server-side code (API routes, Edge Functions)
• Service role key not in any client bundle (verify with grep -r "service_role" dist/)
• Database password changed from the auto-generated default

Step 3: Configure Connection Pooling (Supavisor)

Supabase uses Supavisor for connection pooling. Serverless functions (Vercel, Netlify, Cloudflare Workers) MUST use the pooled connection string to avoid exhausting the database connection limit.

# Direct connection (migrations, admin tasks only)
postgresql://postgres:[PASSWORD]@db.[REF].supabase.co:5432/postgres

# Pooled connection via Supavisor (application code — USE THIS)
# Port 6543 = Supavisor pooler (vs 5432 direct)
postgresql://postgres.[REF]:[PASSWORD]@aws-0-us-east-1.pooler.supabase.com:6543/postgres

// For serverless environments — use pooled connection
const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!,
  {
    db: { schema: 'public' },
    // Supavisor handles pooling at port 6543
    // No need to configure pgBouncer settings in the client
  }
);

• Application code uses pooled connection string (port 6543)
• Direct connection reserved for migrations and admin tasks only
• Connection string in deployment platform env vars (not hardcoded)
• Verified pool mode: transaction for serverless, session for long-lived connections

Step 4: Enable Database Backups

Supabase provides automatic daily backups on Pro plan. Point-in-time recovery (PITR) enables granular restores.

• Automatic daily backups enabled (Pro plan — verify in Dashboard > Database > Backups)
• Point-in-time recovery configured (Dashboard > Database > Backups > PITR)
• Tested restore procedure on a staging project (do not skip this)
• Migration files committed to version control (supabase/migrations/ directory)
• npx supabase db push tested against a fresh project to verify migrations replay cleanly

Step 5: Configure Network Restrictions

Restrict database access to known IP addresses. This prevents unauthorized direct database connections even if credentials leak.

• IP allowlist configured (Dashboard > Database > Network Restrictions)
• Only deployment platform IPs and team office IPs are allowed
• Verified that application still connects after restrictions applied
• Documented which IPs are allowed and why

Step 6: Configure Custom Domain

A custom domain replaces the default *.supabase.co URLs with your brand domain for API and auth endpoints.

• Custom domain configured (Dashboard > Settings > Custom Domains)
• DNS CNAME record added and verified
• SSL certificate provisioned and active
• Application code updated to use custom domain URL
• OAuth redirect URLs updated to use custom domain

Step 7: Customize Auth Email Templates

Default Supabase auth emails show generic branding. Customize them so users see your domain and brand.

• Confirmation email template customized (Dashboard > Auth > Email Templates)
• Password reset email template customized
• Magic link email template customized
• Invite email template customized
• Custom SMTP configured (Dashboard > Auth > SMTP Settings) — avoids rate limits and improves deliverability
• Email confirmation enabled (Dashboard > Auth > Settings)
• OAuth redirect URLs restricted to production domains only
• Unused auth providers disabled

Step 8: Understand Rate Limits Per Tier

Supabase enforces rate limits that vary by plan. Hitting these in production causes 429 errors.

• Rate limits documented for your plan tier
• Client-side retry logic with exponential backoff for 429 responses
• Auth email rate limits understood (use custom SMTP to increase)
• Realtime connection limits planned for expected concurrent users

Step 9: Review Monitoring Dashboards

Supabase provides built-in monitoring. Review these before launch to establish baselines.

// Health check endpoint — deploy this to your application
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

export async function GET() {
  const start = Date.now();
  const { data, error } = await supabase
    .from('_health_check')  // Create a small table for this
    .select('id')
    .limit(1);

  const latency = Date.now() - start;

  return Response.json({
    status: error ? 'unhealthy' : 'healthy',
    latency_ms: latency,
    timestamp: new Date().toISOString(),
    supabase_reachable: !error,
  }, { status: error ? 503 : 200 });
}

• Dashboard > Reports reviewed (API requests, auth, storage, realtime)
• Dashboard > Logs > API checked for error patterns
• Dashboard > Database > Performance Advisor reviewed and recommendations applied
• Health check endpoint deployed and monitored (uptime service)
• Error tracking configured (Sentry, LogRocket, etc.)
• Alerts set for: error rate spikes, high latency, connection pool exhaustion

Step 10: Deploy Edge Functions with Proper Env Vars

Edge Functions run on Deno Deploy. Environment variables must be set via the Supabase CLI or Dashboard, not hardcoded.

# Set secrets for Edge Functions
npx supabase secrets set STRIPE_SECRET_KEY=sk_live_...
npx supabase secrets set RESEND_API_KEY=re_...

# List current secrets
npx supabase secrets list

# Deploy all Edge Functions
npx supabase functions deploy

# Deploy a specific function
npx supabase functions deploy process-webhook

// supabase/functions/process-webhook/index.ts
import { createClient } from '@supabase/supabase-js';

Deno.serve(async (req) => {
  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!  // Available automatically
  );

  const body = await req.json();
  // Process webhook payload...

  return new Response(JSON.stringify({ received: true }), {
    headers: { 'Content-Type': 'application/json' },
  });
});

• All Edge Functions deployed to production (npx supabase functions deploy)
• Environment secrets set via npx supabase secrets set (not hardcoded)
• SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY available automatically (no need to set)
• Edge Functions tested with npx supabase functions serve locally before deploying
• CORS headers configured for Edge Functions that receive browser requests

Step 11: Verify Storage Bucket Policies

Storage buckets need explicit policies, similar to RLS on tables. Without policies, buckets are inaccessible (default deny).

-- Check storage bucket configurations
SELECT id, name, public, file_size_limit, allowed_mime_types
FROM storage.buckets;

-- Check existing storage policies
SELECT policyname, tablename, cmd, qual
FROM pg_policies
WHERE schemaname = 'storage';

-- Example: Allow authenticated users to upload to their own folder
CREATE POLICY "Users can upload own files"
  ON storage.objects
  FOR INSERT
  WITH CHECK (
    bucket_id = 'avatars'
    AND auth.uid()::text = (storage.foldername(name))[1]
  );

-- Example: Allow public read access to a bucket
CREATE POLICY "Public read access"
  ON storage.objects
  FOR SELECT
  USING (bucket_id = 'public-assets');

• Each bucket has explicit SELECT/INSERT/UPDATE/DELETE policies
• Public buckets are intentionally public (not accidentally open)
• File size limits set per bucket (file_size_limit in bucket config)
• Allowed MIME types restricted per bucket (allowed_mime_types)
• User upload paths scoped to auth.uid() to prevent overwrites

Step 12: Add Database Indexes on Frequently Queried Columns

Missing indexes are the leading cause of slow queries after launch. Add indexes on foreign keys, filter columns, and sort columns.

-- Find missing indexes on foreign keys
SELECT
  tc.table_name, kcu.column_name,
  CASE WHEN i.indexname IS NULL THEN '** MISSING INDEX **' ELSE i.indexname END AS index_status
FROM information_schema.table_constraints tc
JOIN information_schema.key_column_usage kcu
  ON tc.constraint_name = kcu.constraint_name
LEFT JOIN pg_indexes i
  ON i.tablename = tc.table_name
  AND i.indexdef LIKE '%' || kcu.column_name || '%'
WHERE tc.constraint_type = 'FOREIGN KEY'
  AND tc.table_schema = 'public';

-- Find slow queries (requires pg_stat_statements extension)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

SELECT query, calls, mean_exec_time::numeric(10,2) AS avg_ms,
       total_exec_time::numeric(10,2) AS total_ms
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;

-- Check table bloat (dead tuples from updates/deletes)
SELECT relname, n_live_tup, n_dead_tup,
       round(n_dead_tup::numeric / greatest(n_live_tup, 1) * 100, 1) AS dead_pct
FROM pg_stat_user_tables
WHERE n_dead_tup > 1000
ORDER BY n_dead_tup DESC;

-- Create indexes on commonly filtered columns
CREATE INDEX idx_profiles_user_id ON public.profiles(user_id);
CREATE INDEX idx_orders_created_at ON public.orders(created_at DESC);
CREATE INDEX idx_posts_status ON public.posts(status) WHERE status = 'published';  -- Partial index

-- Set query timeout for the authenticated role
ALTER ROLE authenticated SET statement_timeout = '10s';

• Indexes on all foreign key columns
• Indexes on columns used in WHERE, ORDER BY, and JOIN clauses
• pg_stat_statements enabled for ongoing query monitoring
• Performance Advisor reviewed (Dashboard > Database > Performance)
• statement_timeout set for authenticated role to prevent runaway queries
• Table bloat checked — VACUUM if dead tuple percentage > 10%

Step 13: Apply Migrations with npx supabase db push

All schema changes must go through migration files, never manual Dashboard edits in production.

# Generate a migration from local changes
npx supabase db diff --use-migra -f add_indexes

# Apply migrations to production (linked project)
npx supabase db push

# Verify migration history
npx supabase migration list

# If a migration fails, create a rollback
npx supabase migration new rollback_bad_change

• All schema changes in supabase/migrations/ directory (version controlled)
• npx supabase db push tested against a fresh project
• Migration history matches between local and remote (npx supabase migration list)
• Rollback migration prepared for risky schema changes
• No manual schema edits in production Dashboard

Step 14: Pre-Launch Final Verification

# Verify RLS status one final time
npx supabase inspect db table-sizes --linked

# Check that the project is linked to production
npx supabase status

# Verify connection string works
npx supabase db ping --linked

• CORS settings match production domain (Dashboard > API > CORS)
• Environment variables set correctly in deployment platform
• Realtime enabled only on tables that need it (reduces connection usage)
• Webhook endpoints registered and tested
• Load test completed on staging (see supabase-load-scale)
• SSL enforcement enabled (Dashboard > Database > Settings > SSL)
• DNS and custom domain verified end-to-end

Output

• All 14 checklist sections verified with zero unchecked items
• RLS enforced on every public table with tested policies
• Key separation verified (anon client-side, service_role server-side only)
• Connection pooling via Supavisor (port 6543) for all application code
• Backups, PITR, monitoring, Edge Functions, Storage policies, indexes all verified
• Migrations applied cleanly via npx supabase db push

Error Handling

Examples

Client Setup (Next.js)

// lib/supabase/client.ts — browser (anon key)
import { createClient } from '@supabase/supabase-js';
export const supabase = createClient<Database>(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

// lib/supabase/server.ts — server only (service role)
export const supabaseAdmin = createClient<Database>(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!,
  { auth: { autoRefreshToken: false, persistSession: false } }
);

RLS Policy Pattern

ALTER TABLE public.posts ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Public read published" ON public.posts
  FOR SELECT USING (status = 'published');
CREATE POLICY "Authors manage own" ON public.posts
  FOR ALL USING (auth.uid() = author_id)
  WITH CHECK (auth.uid() = author_id);

Rollback

npx supabase migration new rollback_bad_change  # Create reversal SQL
npx supabase db push                             # Apply rollback
# For data: Dashboard > Database > Backups > PITR
# For app: vercel rollback / netlify deploy --prod

For complete examples including health checks, storage policies, and Edge Functions, see examples.md.

Resources

• Going to Production — Official production checklist
• Maturity Model — Project lifecycle stages
• Shared Responsibility Model — What Supabase manages vs. what you manage
• Performance Advisor — Built-in query analysis
• Connection Pooling — Supavisor configuration
• RLS Guide — Policy patterns and examples
• Edge Functions — Serverless Deno functions
• Storage — File storage with policies
• @supabase/supabase-js Reference — Client SDK docs

Next Steps

• For SDK version upgrades, see supabase-upgrade-migration
• For load testing before launch, see supabase-load-scale
• For monitoring in production, see supabase-monitoring
• For Edge Function patterns, see supabase-edge-functions