Supabase Multi-Environment Setup

Overview

Production Supabase deployments require a separate project per environment — each with its

own URL, API keys, database, and RLS policies. This skill configures a three-tier

architecture (local dev, staging, production) with safe migration promotion via

supabase db push, environment-aware createClient initialization, database branching

for preview deployments, and CI/CD that prevents accidental cross-environment operations.

When to use: setting up a new project with multiple environments, migrating from a

single-project setup, adding staging to an existing dev/prod split, or configuring preview

environments with database branching.

Prerequisites

• Three separate Supabase projects created at supabase.com/dashboard (dev, staging, production)
• Supabase CLI installed: npm install -g supabase or npx supabase --version
• @supabase/supabase-js v2+ installed in your project
• Node.js 18+ with a framework that supports .env files (Next.js, Nuxt, SvelteKit, etc.)
• A secret management solution for CI (GitHub Actions Secrets, Vercel env vars, etc.)

Instructions

The workflow is three steps. Each step below gives the shape and the one command that

matters; the full implementation walkthrough carries the

complete env files, TypeScript client factory, RLS policies, CI/CD workflow, and seed data

verbatim.

Step 1: Environment Files and Project Layout

Keep one Supabase CLI project with shared migrations and one .env.* file per

environment. Each file points at a different Supabase project; only .env.local is safe to

commit.

supabase/migrations/   # shared schema — every env applies the same migrations
.env.local             # supabase start defaults (safe to commit)
.env.staging           # staging project creds  (gitignored)
.env.production        # production project creds (gitignored — NEVER commit)

The CLI links one project at a time. Before any db push or functions deploy,

re-link to the target:

npx supabase link --project-ref <target-ref>

See the implementation walkthrough (Step 1)

for full .env.* contents, the .gitignore block, and the local-port reference.

Step 2: Environment-Aware Client and Safeguards

Detect the active environment once, then build browser (anon key, respects RLS) and server

(service-role key, bypasses RLS) clients from it. Gate every destructive helper behind a

production guard so seeds and resets can never fire against prod:

export function requireNonProduction(operation: string): void {
  if (isProduction()) {
    throw new Error(`[BLOCKED] "${operation}" is not allowed in production.`);
  }
}

The implementation walkthrough (Step 2)

has the full lib/env.ts detection, the createBrowserClient / createServerClient

factory, the seedTestData / resetDatabase guards, and environment-scoped RLS policies.

Step 3: Migration Promotion and Database Branching

Promote schema changes strictly local → staging → production. db reset applies

everything plus seed.sql locally; db push applies only new migrations to a linked

remote:

npx supabase db reset                              # local: all migrations + seed
npx supabase link --project-ref <staging-ref> && npx supabase db push   # then staging
npx supabase link --project-ref <prod-ref>    && npx supabase db push   # then production

For preview deployments, supabase branches create (Pro plan) gives each feature its own

isolated database, URL, and keys. Full migration workflow, branching commands, the

GitHub Actions deploy workflow (with a production approval gate), and seed data live in the

implementation walkthrough (Step 3).

Output

Completing this skill produces:

• Three isolated Supabase projects — each with its own URL, API keys, database, and storage
• Environment-specific .env files — .env.local, .env.staging, .env.production with correct credentials
• Environment-aware createClient — browser and server clients auto-configured from env vars with x-environment header tracking
• Production safeguards — requireNonProduction() blocks destructive operations outside local/staging
• Migration promotion pipeline — supabase db push promotes schema changes local → staging → production
• Database branching — preview environments get isolated database branches (Pro plan)
• CI/CD workflows — GitHub Actions deploys migrations and Edge Functions per environment with approval gates for production
• Generated TypeScript types — database.types.ts generated from local or linked project schema

Error Handling

Examples

Three worked examples live in references/examples.md. The fastest

path — a full three-env bootstrap from supabase init to a production db push — is:

npx supabase init && npx supabase start        # local, copy keys to .env.local
npx supabase migration new create_users        # author schema, then:
npx supabase db reset                           # verify locally
npx supabase link --project-ref "<staging-ref>" && npx supabase db push
npx supabase link --project-ref "<prod-ref>"    && npx supabase db push

Examples 2 and 3 (full file) show a Next.js middleware that

stamps and gates on x-supabase-env, and an admin handler that calls requireNonProduction

before a destructive RPC.

Resources

• Managing Environments — Supabase Docs
• Database Migrations — Supabase Docs
• Database Branching — Supabase Docs
• Supabase CLI Reference
• createClient — @supabase/supabase-js
• GitHub Actions with Supabase
• 12-Factor App — Config
• Full implementation walkthrough · Examples

Next Steps

• For authentication patterns across environments, see supabase-auth-storage-realtime-core
• For RLS policy testing and validation, see supabase-policy-guardrails
• For local development workflow optimization, see supabase-local-dev-loop
• For monitoring and observability across environments, see supabase-observability