supabase

Manage Supabase: $ARGUMENTS

Project Context

• Linked project: Thoughtbox (akjccuoncxlvrrtkvtno, West US Oregon)
• Local DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
• Migrations dir: supabase/migrations/
• Config: supabase/config.toml

Commands

Parse the first word of $ARGUMENTS to determine the command:

status — Show local and hosted state

1. Run supabase status for local container health
2. Run supabase migration list to show local vs remote migration drift
3. Report: which migrations are local-only, remote-only, or synced

migrate — Create a new migration

Parse remaining arguments for the migration name.

1. Run supabase migration new <name> to create the file
2. Open the created file path for editing
3. Remind: after writing SQL, run /supabase diff to verify, then /supabase push to deploy

diff — Diff local schema against migrations

1. Run supabase db diff to show schema changes not captured in migrations
2. If changes exist, offer to create a migration capturing them
3. If clean, report "Schema in sync with migrations"

push — Push migrations to hosted project

1. Run supabase migration list to show what will be pushed
2. List the pending migrations and their filenames
3. Ask for confirmation before proceeding — this modifies the hosted database
4. Run supabase db push to apply
5. Run supabase migration list again to confirm sync

pull — Pull remote schema to local migrations

1. Run supabase db pull to generate a migration from remote schema changes
2. Show the generated migration file
3. Remind: review the SQL before committing

reset — Reset local database to migrations

1. Confirm the user wants to destroy local data
2. Run supabase db reset to drop and re-apply all migrations
3. Report success and migration count

inspect — Inspect hosted database

Parse remaining arguments for the inspection type. Default to db-stats.

Available inspections:

• db-stats — Size, cache hit rates, WAL size
• table-stats — Table sizes and row counts
• index-stats — Index usage and bloat
• outliers — Slowest queries
• locks — Active locks
• bloat — Table and index bloat estimates
• role-stats — Role information

Run: supabase inspect db <type> --linked

link — Link or re-link to hosted project

1. Run supabase link --project-ref akjccuoncxlvrrtkvtno
2. Run supabase services to verify version alignment
3. Report any version mismatches between local and remote

Gotchas (learned from experience)

Gotcha	Detail
PG version mismatch	CLI upgrades can change local PG version (e.g., 15→17). Old volumes fail with "incompatible data directory". Fix: supabase stop --no-backup, remove volume, supabase start.
--linked flag inconsistency	Some commands use --linked (e.g., inspect db), others don't support it (e.g., db execute, status). Check --help before assuming.
Migration ordering	Migrations sort lexicographically by filename. Use YYYYMMDDHHMMSS_ prefix (supabase CLI does this automatically with migration new).
RLS policies	New tables have RLS enabled by default. Forgetting policies means zero rows returned, not errors. Always add policies in the same migration that creates the table.
db push is irreversible	There is no db unpush. Test migrations locally with db reset first.
Service role vs anon key	Admin operations (user management, bypassing RLS) require the service_role key, not the anon/publishable key. Never expose service_role client-side.
Local vs hosted auth	Local auth (GoTrue) has different rate limits and email config than hosted. Test auth flows against hosted before shipping.

Candidate Slash Commands

These are composable building blocks for workflows:

Command	Purpose	Implementation
/sb-status	Quick health check	supabase status && supabase migration list
/sb-new-migration	Create + open migration	supabase migration new <name> then open file
/sb-sync-check	Drift detection	supabase migration list + diff analysis
/sb-reset-local	Clean slate local DB	supabase db reset with confirmation
/sb-push	Deploy migrations	supabase db push with pre-flight check

Candidate Hooks

These can be wired into .Codex/settings.json:

Event	Hook	Purpose
PreToolUse:Bash	Guard supabase db push	Require confirmation before pushing to hosted
PostToolUse:Write	Auto-lint on supabase/migrations/*.sql	Run supabase db lint after writing migration files
SessionStart	Migration drift check	Run supabase migration list on session start if supabase dir exists
PreToolUse:Bash	Block supabase stop --no-backup	Prevent accidental data loss without explicit intent

Workflow Compositions

New feature with schema changes

/sb-status → /sb-new-migration → [write SQL] → /sb-reset-local → [test] → /sb-push

Debug hosted schema issues

/supabase inspect db-stats → /supabase inspect outliers → /supabase inspect bloat

Sync after pulling remote changes

git pull → /sb-sync-check → /sb-reset-local (if drifted) → [verify]

Output

Always end with a one-line status summary:

Supabase: [local: running|stopped] [migrations: N local, N remote, N pending] [linked: yes|no]