Supabase Local Development — Run Supabase Locally with the CLI
In this tutorial, you will learn about Supabase Local Development. We cover key concepts, practical examples, and best practices to help you master this topic.
Supabase local development uses Docker to run the entire Supabase stack locally -- PostgreSQL, authentication, storage, realtime, and edge functions -- enabling offline development and testing.
What You'll Learn
By the end of this lesson you will start a local Supabase stack with Docker, apply migrations, use the local dashboard, manage local authentication, and sync schema changes to your remote project.
Why It Matters
Local development eliminates the need for a constant internet connection, speeds up development iterations, and prevents accidental changes to production data during testing.
Real-World Use
DodaZIP developers run Supabase locally for daily work. They make schema changes, write queries, and test RLS policies against a local database before pushing migrations to the shared staging environment.
flowchart LR
A[Developer Machine] -->|Docker| B[Local Supabase Stack]
B --> C[(Local PostgreSQL)]
B --> D[Local Auth Service]
B --> E[Local Storage]
B --> F[Local Realtime]
G[Supabase Cloud] -->|Sync| A
style B fill:#3ecf8e,color:#fff
Starting the Local Stack
Initialize and start Supabase locally.
# Install Supabase CLI
npm install supabase --save-dev
# Initialize Supabase project
supabase init
# Start the local Supabase stack
supabase start
# Output example:
# Started supabase local development setup.
# API URL: http://localhost:54321
# DB URL: postgresql://postgres:postgres@localhost:54322/postgres
# Studio URL: http://localhost:54323
# Inbucket URL: http://localhost:54324
# JWT secret: super-secret-jwt-token
# anon key: eyJhbGciOiJIUzI1NiIs...
# service_role key: eyJhbGciOiJIUzI1NiIs...
# local_stack.py
# Verify local Supabase stack
def check_local_stack():
services = [
("API (Kong)", "http://localhost:54321", "Gateway and API routing"),
("Database (PostgreSQL)", "localhost:54322", "Postgres with all extensions"),
("Studio (Dashboard)", "http://localhost:54323", "Local Supabase Dashboard"),
("Inbucket (Email)", "http://localhost:54324", "Local email testing"),
]
print("Local Supabase Stack:")
for service, url, desc in services:
print(f" {service:20s} | {url:35s} | {desc}")
check_local_stack()
Using the Local Studio
Access the local Supabase dashboard.
# Open local Studio in browser
open http://localhost:54323
# The local Studio provides:
# - Table Editor for managing schemas
# - SQL Editor for running queries
# - Authentication settings
# - Storage bucket management
# - Edge Functions management
# studio_features.py
# Local Studio features
def local_studio_features():
features = [
"Table Editor -- Create and modify tables visually",
"SQL Editor -- Run SQL queries against local database",
"Auth Settings -- Configure local authentication providers",
"Storage -- Manage local storage buckets",
"Edge Functions -- Test functions locally",
"API Docs -- View auto-generated API documentation",
"Realtime -- Test and monitor subscriptions",
]
print("Local Studio Features:")
for feature in features:
print(f" {feature}")
local_studio_features()
Applying Local Migrations
Manage schema changes locally.
# Create a migration
supabase migration new add_profiles_table
# Edit the migration file and apply it
supabase migration up
# Reset the local database
supabase db reset
# Diff local DB against remote
supabase db diff --linked
# local_migrations.py
# Local migration workflow
def local_migration_workflow():
print("Local Migration Workflow:")
print()
print("1. Create migration: supabase migration new <name>")
print("2. Write SQL in the generated file")
print("3. Apply locally: supabase migration up")
print("4. Test with queries in the local Studio")
print("5. If something breaks: supabase db reset")
print("6. Push to remote: supabase db push")
print()
print("Tip: Use supabase db reset to start fresh")
print(" when migrations get out of sync.")
local_migration_workflow()
Syncing with Remote
Link your local project to a remote Supabase project.
# Link to remote project
supabase link --project-ref <your-project-ref>
# Pull remote schema changes locally
supabase db pull
# Push local migrations to remote
supabase db push
# Check for differences
supabase db remote changes
# sync_remote.py
# Local-to-remote sync workflow
def sync_workflow():
print("Remote Sync Workflow:")
print()
print("Initial setup:")
print(" 1. supabase link --project-ref <ref>")
print(" 2. supabase db pull (get remote schema)")
print()
print("Daily workflow:")
print(" 1. supabase db pull (if others changed schema)")
print(" 2. Make local changes")
print(" 3. supabase migration up")
print(" 4. Test locally")
print(" 5. supabase db push (deploy to remote)")
print()
print("Conflict resolution:")
print(" - supabase db diff to see differences")
print(" - Manual SQL to reconcile divergent schemas")
sync_workflow()
Common Mistakes
Not starting the stack before working: The local stack must be running before you can use the Studio, run queries, or apply migrations.
Forgetting to stop the stack: The Docker containers continue running. Use
supabase stopto free resources when not working.Outdated local Docker images: Run
supabase startperiodically to pull updated images with bug fixes and new features.Using production credentials locally: Always use the local credentials (localhost:54321) for local development. Never point your local app at the production database.
Pushing untested migrations: Always test migrations locally before pushing to remote. A bad Migration can lock or crash the shared database.
Practice Questions
What command starts the local Supabase stack?
supabase start, which launches Docker containers for all services.How do you access the local Supabase Studio? Open http://localhost:54323 in a browser.
How do you link a local project to a remote Supabase project? Run
supabase link --project-ref <ref>.What command resets the local database?
supabase db reset, which drops and recreates the database from migrations.Challenge: Set up a complete local development workflow: initialize Supabase, create a migration, apply it locally, test in the Studio, link to a remote project, and push the migration.
FAQ
Mini Project
Set up a complete local development environment: initialize Supabase, create a migration for a task management schema, seed the database with sample data, and verify everything works in the local Studio.
def local_dev_setup():
print("Local Development Environment Setup:")
print()
print("Step 1: supabase init")
print("Step 2: supabase start")
print("Step 3: supabase migration new task_schema")
print("Step 4: Write migration SQL")
print("Step 5: Create seed.sql with sample data")
print("Step 6: supabase db reset")
print("Step 7: Verify in Studio at http://localhost:54323")
print("Step 8: supabase link --project-ref <ref>")
print()
print("Environment ready for development!")
local_dev_setup()
What's Next
Next: Supabase Project for the capstone project.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro