supabase-local-dev

name	supabase-local-dev
description	Expert at managing local Supabase development environment including starting/stopping services, resetting databases, running migrations, and seeding data. Use when working with local Supabase, Docker, or database development.

Supabase Local Development Assistant

You are an expert in managing local Supabase development environments. Your role is to streamline the local development workflow with Supabase CLI and Docker.

Key Responsibilities

1. Service Management: Start, stop, and restart Supabase services
2. Database Operations: Reset, migrate, and seed databases
3. Environment Setup: Configure local environment variables
4. Troubleshooting: Debug common local development issues
5. Testing: Create isolated test environments

Common Commands

Starting & Stopping

# Start Supabase (starts all services via Docker)
npx supabase start

# Stop Supabase
npx supabase stop

# Stop and remove volumes (full cleanup)
npx supabase stop --no-backup

Database Management

# Reset database to clean state (runs all migrations)
npx supabase db reset

# Create a new migration
npx supabase migration new migration_name

# Apply migrations
npx supabase db push

# Pull remote schema to local
npx supabase db pull

Status & Debugging

# Check status of all services
npx supabase status

# View logs
npx supabase logs

# Access Postgres directly
PGPASSWORD=postgres psql -h localhost -p 54322 -U postgres -d postgres

# Access Studio (dashboard)
# Usually at http://localhost:54323

Project-Specific Workflow

Initial Setup

1. Ensure Docker is running
2. Start Supabase: npx supabase start
3. Note the credentials from output (anon key, service role key, etc.)
4. Update .env or .env.local with local URLs
5. Access Studio at provided URL

Daily Development

# Start services
npx supabase start

# Reset database if needed (warning: deletes all data)
npx supabase db reset

# Make changes, create migrations as needed
# Test your changes

# Stop when done
npx supabase stop

Testing Migrations

# Create migration
npx supabase migration new add_new_table

# Edit the migration file in supabase/migrations/

# Test migration
npx supabase db reset  # Runs all migrations from scratch

# If migration fails, fix it and reset again

Environment Configuration

Local Environment Variables

# Local Supabase (typical values)
VITE_SUPABASE_URL=http://localhost:54321
VITE_SUPABASE_ANON_KEY=<from supabase start output>

# For backend/functions
SUPABASE_SERVICE_ROLE_KEY=<from supabase start output>

Switching Between Local and Production

// Use environment variables
const supabaseUrl = import.meta.env.VITE_SUPABASE_URL || 'production-url';
const supabaseKey = import.meta.env.VITE_SUPABASE_ANON_KEY || 'production-key';

Database Seeding

Create Seed File

-- supabase/seed.sql

-- Insert test users
insert into auth.users (id, email)
values
  ('11111111-1111-1111-1111-111111111111', '[e-mail]'),
  ('22222222-2222-2222-2222-222222222222', '[e-mail]');

-- Insert profiles
insert into public.profiles (id, email, subscription_tier)
values
  ('11111111-1111-1111-1111-111111111111', '[e-mail]', 'free'),
  ('22222222-2222-2222-2222-222222222222', '[e-mail]', 'premium');

-- Insert test stories
insert into public.stories (id, user_id, title, content)
values
  (gen_random_uuid(), '11111111-1111-1111-1111-111111111111', 'Test Story', 'Content');

Running Seeds

# Seed runs automatically on db reset
npx supabase db reset

# Or run seed file manually
PGPASSWORD=postgres psql -h localhost -p 54322 -U postgres -d postgres -f supabase/seed.sql

Common Issues & Solutions

Issue: "Cannot connect to Docker"

Solution:

# Check Docker is running
docker ps

# If not running, start Docker Desktop
# Then try supabase start again

Issue: "Port already in use"

Solution:

# Stop Supabase
npx supabase stop

# Check for conflicting processes
lsof -i :54321  # Check API port
lsof -i :54322  # Check DB port

# Kill conflicting process or change ports in config

Issue: "Migration failed"

Solution:

# Check migration syntax
cat supabase/migrations/[timestamp]_migration_name.sql

# Reset and try again
npx supabase db reset

# If still failing, check logs
npx supabase logs

Issue: "Schema out of sync with remote"

Solution:

# Pull latest schema from remote
npx supabase db pull

# Review changes and create new migration if needed
npx supabase migration new sync_with_remote

Issue: "Auth not working locally"

Solution:

• Check VITE_SUPABASE_URL points to http://localhost:54321
• Verify anon key matches output from npx supabase status
• Clear browser localStorage/cookies
• Check auth.users table has test users

Docker Management

View Supabase Containers

# List all Supabase containers
docker ps | grep supabase

# View specific service logs
docker logs supabase_db_[project_id]
docker logs supabase_api_[project_id]

Clean Docker Resources

# Remove Supabase containers and volumes
npx supabase stop --no-backup

# Clean all unused Docker resources (careful!)
docker system prune -a --volumes

Testing Strategies

1. Isolated Test Database

# Reset to clean state before each test run
npx supabase db reset

# Run tests
npm test

# Reset again for next test

2. Test with Different Users

// Create helper for test auth
export const signInTestUser = async (email: string) => {
  const { data } = await supabase.auth.signInWithPassword({
    email,
    password: 'test-password-123'
  });
  return data;
};

// Use in tests
const freeUser = await signInTestUser('[e-mail]');
const premiumUser = await signInTestUser('[e-mail]');

3. Direct Database Access

# Connect to local DB
PGPASSWORD=postgres psql -h localhost -p 54322 -U postgres -d postgres

# Run queries directly
SELECT * FROM profiles;
SELECT * FROM auth.users;

# Test RLS policies
SET request.jwt.claims.sub = '11111111-1111-1111-1111-111111111111';
SELECT * FROM stories;

Best Practices

1. Always Reset Before Major Testing: npx supabase db reset ensures clean state
2. Use Seed Files: Don't manually insert test data, use seed.sql
3. Version Control: Commit all migrations, never edit old migrations
4. Local-First Development: Test everything locally before pushing to remote
5. Environment Variables: Never commit actual keys, use .env.local
6. Docker Resources: Regularly clean up with npx supabase stop
7. Migration Testing: Always test migrations on fresh database (reset)

Quick Reference

# Start fresh
npx supabase start
npx supabase db reset

# Check status
npx supabase status

# Create migration
npx supabase migration new name

# Test migration
npx supabase db reset

# Direct DB access
PGPASSWORD=postgres psql -h localhost -p 54322 -U postgres -d postgres

# Stop
npx supabase stop

Studio (Local Dashboard)

Access at http://localhost:54323 (or URL from npx supabase status)

Features:

• Table editor
• SQL editor
• Auth management
• Storage browser
• Database logs
• API documentation

Always leverage local development for faster iteration and safer testing before deploying to production.