Supabase Deploy Integration
Overview
Deploy and manage Supabase projects in production with confidence. This skill covers the full deployment lifecycle: pushing database migrations, deploying Edge Functions, managing secrets, executing zero-downtime rollouts with blue/green database branching, rolling back failed migrations, and verifying deployment health. All commands use the Supabase CLI with --project-ref for explicit project targeting.
SDK: @supabase/supabase-js — supabase.com/docs
Prerequisites
- Supabase CLI installed (
npm install -g supabase or npx supabase)
- Supabase project linked (
npx supabase link --project-ref <your-ref>)
- Database migrations in
supabase/migrations/ directory
- Edge Functions in
supabase/functions/ directory (if deploying functions)
SUPABASE_ACCESS_TOKEN set for CI/non-interactive environments
Instructions
Step 1 — Push Database Migrations and Deploy Edge Functions
Apply pending database migrations to your production project, then deploy Edge Functions with their required secrets.
Database migrations:
npx supabase db push --project-ref $PROJECT_REF
npx supabase db push --project-ref $PROJECT_REF --dry-run
npx supabase migration list --project-ref $PROJECT_REF
Each migration file in supabase/migrations/ is applied in timestamp order. The CLI tracks which migrations have already been applied and only runs new ones.
Edge Functions deployment:
npx supabase functions deploy process-webhook --project-ref $PROJECT_REF
npx supabase functions deploy --project-ref $PROJECT_REF
Secrets management — set environment variables for Edge Functions:
npx supabase secrets set STRIPE_KEY=sk_live_xxx --project-ref $PROJECT_REF
npx supabase secrets set WEBHOOK_SECRET=whsec_xxx --project-ref $PROJECT_REF
npx supabase secrets set API_KEY=value1 SIGNING_KEY=value2 --project-ref $PROJECT_REF
npx supabase secrets list --project-ref $PROJECT_REF
npx supabase secrets unset OLD_KEY --project-ref $PROJECT_REF
Step 2 — Zero-Downtime Deployments and Blue/Green Branching
Use Supabase database branching to test migrations against a production-like environment before cutting over.
Blue/green deployment via database branching:
npx supabase branches create staging-v2 --project-ref $PROJECT_REF
npx supabase db push --project-ref $BRANCH_REF
npx supabase db push --project-ref $PROJECT_REF
npx supabase branches delete staging-v2 --project-ref $PROJECT_REF
Rolling deployment pattern for zero downtime:
- Deploy backward-compatible migration first (additive schema changes only)
- Deploy application code that works with both old and new schema
- Run data backfill if needed
- Deploy cleanup migration (drop old columns/tables) after all instances updated
ALTER TABLE orders ADD COLUMN status_v2 text;
UPDATE orders SET status_v2 = status WHERE status_v2 IS NULL;
ALTER TABLE orders DROP COLUMN status;
ALTER TABLE orders RENAME COLUMN status_v2 TO status;
Step 3 — Rollback, Health Checks, and Monitoring
When a migration fails or causes issues, roll it back. Then verify deployment health.
Rollback a failed migration:
npx supabase migration repair --status reverted <migration_version> --project-ref $PROJECT_REF
npx supabase migration repair --status reverted 20260322120000 --project-ref $PROJECT_REF
npx supabase migration new rollback_order_status
ALTER TABLE orders DROP COLUMN IF EXISTS status_v2;
npx supabase db push --project-ref $PROJECT_REF
Post-deploy health check:
import { createClient } from '@supabase/supabase-js'
async function healthCheck() {
const supabase = createClient(
process.env.SUPABASE_URL!,
process.env.SUPABASE_ANON_KEY!
)
const checks = {
database: false,
auth: false,
storage: false,
functions: false,
}
const dbStart = Date.now()
const { error: dbErr } = await supabase.from('_health').select('count').limit(1)
checks.database = !dbErr || dbErr.code === 'PGRST116'
const dbLatency = Date.now() - dbStart
const { error: authErr } = await supabase.auth.getSession()
checks.auth = !authErr
const { : storageErr } = supabase..()
checks. = !storageErr
{
{ : fnErr } = supabase..()
checks. = !fnErr
} {
checks. =
}
allHealthy = .(checks).()
.({
: allHealthy ? : ,
checks,
: dbLatency,
: ().(),
})
allHealthy
}
Monitoring via Supabase Dashboard:
- Navigate to Dashboard > Reports for database performance metrics
- Check Dashboard > Logs > Postgres for slow queries and errors
- Review Dashboard > Logs > Edge Functions for function invocation logs
- Set up Dashboard > Database > Webhooks for change notifications
- Monitor Dashboard > Settings > Infrastructure for resource utilization
Output
After completing these steps, you will have:
- All pending database migrations applied to production via
supabase db push
- Edge Functions deployed to Supabase's global edge network
- Secrets configured for Edge Functions without exposing values in code
- A zero-downtime deployment strategy using database branching or rolling migrations
- Rollback capability for any failed migration via
migration repair --status reverted
- Health check endpoint verifying database, auth, storage, and function connectivity
- Monitoring configured through the Supabase Dashboard Reports
Error Handling
| Error | Cause | Solution |
|---|
migration already applied | Re-running a migration that succeeded | Check npx supabase migration list — skip if already applied |
permission denied for schema | Migration modifies a protected schema | Use ALTER DEFAULT PRIVILEGES or run via dashboard SQL editor |
functions deploy: not linked | Project not linked locally | Run npx supabase link --project-ref $PROJECT_REF first |
secret already exists | Setting a secret that exists | supabase secrets set overwrites by default — this is safe |
branch limit reached | Too many active branches | Delete unused branches with supabase branches delete |
migration repair has no effect | Wrong version number | Run supabase migration list to find the exact version string |
connection refused on db push | IP not allowlisted | Add your IP in Dashboard > Settings > Database > Network Bans |
| Edge Function 500 after deploy | Missing secret or import error | Check supabase functions logs <name> for stack trace |
Examples
CI/CD pipeline — GitHub Actions:
name: Deploy to Supabase
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: supabase/setup-cli@v1
with:
version: latest
- name: Link project
run: npx supabase link --project-ref ${{ secrets.SUPABASE_PROJECT_REF }}
env:
SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
- name: Push migrations
run: npx supabase db push --project-ref ${{ secrets.SUPABASE_PROJECT_REF }}
env:
SUPABASE_ACCESS_TOKEN:
Quick rollback script:
#!/bin/bash
set -euo pipefail
REF="${1:?Usage: rollback.sh <project-ref>}"
LAST=$(npx supabase migration list --project-ref "$REF" 2>/dev/null | tail -1 | awk '{print $1}')
echo "Reverting migration: $LAST"
npx supabase migration repair --status reverted "$LAST" --project-ref "$REF"
echo "Migration $LAST marked as reverted. Write and push a compensating migration next."
Resources
Next Steps
- For schema design from requirements, see
supabase-schema-from-requirements
- For RLS policy configuration, see
supabase-policy-guardrails
- For webhook and event handling, see
supabase-webhooks-events
- For production readiness checklist, see
supabase-prod-checklist
- For multi-environment setup, see
supabase-multi-env-setup
