supabase-local-dev
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.
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-22
Download the latest version (v1.0.0) from this page.
SKILL.md
---
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```typescript
// 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
```sql
-- 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');
```
### Running Seeds
```bash
# 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**:
```bash
# Check Docker is running
docker ps
# If not running, start Docker Desktop
# Then try supabase start again
```
### Issue: "Port already in use"
**Solution**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```typescript
// 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');
```
### 3. Direct Database Access
```bash
# 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
```bash
# 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.