supabase

Supabase Core Skill

Core concepts, CLI workflow, and patterns common to all Supabase projects.

Sources: Supabase Docs | Supabase CLI

Core Principle

Local-first, migrations in version control, never touch production directly.

Develop locally with the Supabase CLI, capture all changes as migrations, and deploy through CI/CD.

Supabase Stack

CLI Setup

Install & Login

# macOS
brew install supabase/tap/supabase

# npm (alternative)
npm install -g supabase

# Login
supabase login

Initialize Project

# In your project directory
supabase init

# Creates:
# supabase/
# ├── config.toml      # Local config
# ├── seed.sql         # Seed data
# └── migrations/      # SQL migrations

Link to Remote

# Get project ref from dashboard URL: https://supabase.com/dashboard/project/<ref>
supabase link --project-ref <project-id>

# Pull existing schema
supabase db pull

Start Local Stack

supabase start

# Output:
# API URL: http://localhost:54321
# GraphQL URL: http://localhost:54321/graphql/v1
# DB URL: postgresql://postgres:postgres@localhost:54322/postgres
# Studio URL: http://localhost:54323
# Anon key: eyJ...
# Service role key: eyJ...

Migration Workflow

Option 1: Dashboard + Diff (Quick Prototyping)

# 1. Make changes in local Studio (localhost:54323)
# 2. Generate migration from diff
supabase db diff -f <migration_name>

# 3. Review generated SQL
cat supabase/migrations/*_<migration_name>.sql

# 4. Reset to test
supabase db reset

Option 2: Write Migrations Directly (Recommended)

# 1. Create empty migration
supabase migration new create_users_table

# 2. Edit the migration file
# supabase/migrations/<timestamp>_create_users_table.sql

# 3. Apply locally
supabase db reset