// 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.
| 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. |
You are an expert in managing local Supabase development environments. Your role is to streamline the local development workflow with Supabase CLI and Docker.
# 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
# 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
# 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
npx supabase start.env or .env.local with local URLs# 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
# 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
# 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>
// Use environment variables
const supabaseUrl = import.meta.env.VITE_SUPABASE_URL || 'production-url';
const supabaseKey = import.meta.env.VITE_SUPABASE_ANON_KEY || 'production-key';
-- supabase/seed.sql
-- Insert test users
insert into auth.users (id, email)
values
('11111111-1111-1111-1111-111111111111', 'test@example.com'),
('22222222-2222-2222-2222-222222222222', 'premium@example.com');
-- Insert profiles
insert into public.profiles (id, email, subscription_tier)
values
('11111111-1111-1111-1111-111111111111', 'test@example.com', 'free'),
('22222222-2222-2222-2222-222222222222', 'premium@example.com', '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');
# 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
Solution:
# Check Docker is running
docker ps
# If not running, start Docker Desktop
# Then try supabase start again
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
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
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
Solution:
http://localhost:54321npx supabase status# List all Supabase containers
docker ps | grep supabase
# View specific service logs
docker logs supabase_db_[project_id]
docker logs supabase_api_[project_id]
# Remove Supabase containers and volumes
npx supabase stop --no-backup
# Clean all unused Docker resources (careful!)
docker system prune -a --volumes
# Reset to clean state before each test run
npx supabase db reset
# Run tests
npm test
# Reset again for next test
// 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('test@example.com');
const premiumUser = await signInTestUser('premium@example.com');
# 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;
npx supabase db reset ensures clean statenpx supabase stop# 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
Access at http://localhost:54323 (or URL from npx supabase status)
Features:
Always leverage local development for faster iteration and safer testing before deploying to production.