Supabase Local

Local Supabase Management

Critical rules and patterns for working with Supabase locally.

Critical Rules

ALWAYS Use npx

# CORRECT - Always use npx
npx supabase start
npx supabase stop
npx supabase status
npx supabase migration new
npx supabase db push --local

# WRONG - Never use brew-installed supabase
supabase start  # NO!

ALWAYS Create Migrations Properly

# CORRECT - Use the CLI to generate migration files
npx supabase migration new add_user_profiles

# This creates: supabase/migrations/TIMESTAMP_add_user_profiles.sql
# Then edit that file with your SQL

ALWAYS Push Locally

# CORRECT - Apply migrations to local database
npx supabase db push --local

# WRONG - This resets your data!
npx supabase db reset  # NEVER unless explicitly asked

NEVER Use db reset

npx supabase db reset destroys all local data. Only use when:

• User explicitly requests it
• You warn them data will be lost
• They confirm

Custom Port Configuration

Every project needs unique ports to avoid conflicts when running multiple Supabase instances.

Port Range Pattern

Use a unique 5-digit prefix for each project:

Generating Unique Ports

When setting up a new project:

1. Check existing projects for used port ranges
2. Pick a new prefix (e.g., 5438X if 5436X and 5437X are used)
3. Configure all services with that prefix

See port-generator.md for a helper.

Setup Workflow

Step 1: Initialize Supabase

cd backend  # Supabase lives in backend/
npx supabase init

Step 2: Configure Ports

Edit supabase/config.toml:

[api]
port = 54361

[db]
port = 54362

[studio]
port = 54363

[inbucket]
port = 54364

[storage]
port = 54365

[auth]
port = 54366

[realtime]
port = 54367

See config-template.md for full template.

Step 3: Start Supabase

npx supabase start

Step 4: Get Credentials

npx supabase status

Copy the keys to your .env file.

Migration Workflow

Create Migration

npx supabase migration new descriptive_name

Edit Migration File

Edit supabase/migrations/TIMESTAMP_descriptive_name.sql:

-- Create table
CREATE TABLE public.profiles (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  name TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

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

-- Create policy
CREATE POLICY "Users can view own profile"
  ON public.profiles
  FOR SELECT
  USING (auth.uid() = user_id);

Apply Migration

npx supabase db push --local

Verify

# Check in Studio
open http://127.0.0.1:PORT  # Your Studio port

# Or use psql
PGPASSWORD=postgres psql -h localhost -p PORT -U postgres -d postgres

Type Generation

After schema changes, regenerate TypeScript types:

npx supabase gen types typescript --local > src/database/types.generated.ts

Database Connection Strings

Local Development (direct)

DATABASE_URL=postgresql://postgres:postgres@localhost:PORT/postgres

Docker Development

DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:PORT/postgres

Production (pooler)

DATABASE_URL=postgresql://postgres.PROJECT:PASSWORD@aws-1-region.pooler.supabase.com:5432/postgres

Direct Database Access

For ad-hoc queries, use psql:

# Single command
PGPASSWORD=postgres psql -h localhost -p PORT -U postgres -d postgres -c "SELECT * FROM profiles;"

# Interactive session
PGPASSWORD=postgres psql -h localhost -p PORT -U postgres -d postgres

Common Commands Reference

Troubleshooting

Port Already in Use

Another Supabase instance is running. Either:

• Stop it: npx supabase stop
• Use different ports in config.toml

Migration Failed

Check the SQL syntax, then:

npx supabase db push --local

If data issues, ask user if they want to reset.

Can't Connect from Docker

Use host.docker.internal instead of localhost:

DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:PORT/postgres

For templates, see config-template.md.