Claude-skill-registry-data managing-supabase

Supabase CLI for database management, Edge Functions, migrations, and local development. Use for managing Postgres databases, deploying serverless functions, and debugging Supabase projects.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry-data

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry-data "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/managing-supabase" ~/.claude/skills/majiayu000-claude-skill-registry-data-managing-supabase && rm -rf "$T"

manifest: data/managing-supabase/SKILL.md

source content

Supabase CLI Skill

Quick Reference
Critical: Avoiding Interactive Mode
Prerequisites
Authentication
CLI Decision Tree
Essential Commands
Local Development Ports
Common Workflows
Error Handling
Auto-Detection Triggers
Agent Integration
Quick Reference Card
Further Reading

Quick Reference

Supabase CLI enables local development, database migrations, Edge Functions deployment, and project management for Supabase projects.

Critical: Avoiding Interactive Mode

Supabase CLI can enter interactive mode which will hang Claude Code. Always use flags to bypass prompts:

Command	WRONG (Interactive)	CORRECT (Non-Interactive)
Login	`supabase login`	Use `SUPABASE_ACCESS_TOKEN` env var
Link project	`supabase link`	`supabase link --project-ref <ref>`
Create project	`supabase projects create`	`supabase projects create <name> --org-id <id> --region <region>`
Start local	`supabase start`	`supabase start` (non-interactive by default)
Deploy functions	`supabase functions deploy`	`supabase functions deploy <name> --project-ref <ref>`

Never use in Claude Code:

```
supabase login
```
without token (opens browser)
Any command without
```
--project-ref
```
when not linked
Interactive prompts for organization/region selection

Always include:

```
SUPABASE_ACCESS_TOKEN
```
environment variable for authentication
```
--project-ref
```
flag or pre-linked project
Explicit flags for all configuration options

Prerequisites

Installation Verification

supabase --version
# Expected: 2.x.x or higher

Installation Methods

# npm (requires Node.js 20+)
npm install -g supabase

# Homebrew (macOS/Linux)
brew install supabase/tap/supabase

# Scoop (Windows)
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Authentication

Environment Variables (CI/CD Required)

Variable Purpose Required For

SUPABASE_ACCESS_TOKEN

Personal access token

All remote operations

SUPABASE_DB_PASSWORD

Database password

db push

db pull

link

SUPABASE_PROJECT_ID

Project reference string

Linking without interactive prompt

Token Generation

Generate tokens at:

https://supabase.com/dashboard/account/tokens

Authentication Pattern for Claude Code

# Set from project .env file
export SUPABASE_ACCESS_TOKEN="$(grep SUPABASE_ACCESS_TOKEN .env | cut -d= -f2)"
export SUPABASE_DB_PASSWORD="$(grep SUPABASE_DB_PASSWORD .env | cut -d= -f2)"

# All commands will use these automatically
supabase projects list
supabase link --project-ref <ref>

CLI Decision Tree

What do you need to do?

Project Setup
├── Initialize local project ──────────► supabase init
├── Link to remote project ────────────► supabase link --project-ref <ref>
├── Start local stack ─────────────────► supabase start
├── Stop local stack ──────────────────► supabase stop
└── Check status ──────────────────────► supabase status

Database Operations
├── Create migration ──────────────────► supabase migration new <name>
├── Apply migrations locally ──────────► supabase db reset
├── Push migrations to remote ─────────► supabase db push
├── Pull remote schema ────────────────► supabase db pull
├── Diff local vs remote ──────────────► supabase db diff --linked
└── Lint database schema ──────────────► supabase db lint

Edge Functions
├── Create new function ───────────────► supabase functions new <name>
├── Serve locally ─────────────────────► supabase functions serve
├── Deploy function ───────────────────► supabase functions deploy <name>
├── List deployed functions ───────────► supabase functions list
└── Delete function ───────────────────► supabase functions delete <name>

Secrets Management
├── Set secret ────────────────────────► supabase secrets set NAME=value
├── Set from file ─────────────────────► supabase secrets set --env-file .env
├── List secrets ──────────────────────► supabase secrets list
└── Remove secret ─────────────────────► supabase secrets unset NAME

Type Generation
├── Generate TypeScript types ─────────► supabase gen types typescript --linked
└── Generate from local ───────────────► supabase gen types typescript --local

Debugging
├── View container logs ───────────────► supabase logs (local)
├── Check slow queries ────────────────► supabase inspect db outliers
└── View blocking queries ─────────────► supabase inspect db blocking

For complete command reference including storage, project management, and all inspection commands, see REFERENCE.md.

Essential Commands

Project Setup

Command	Description	Key Flags
`supabase init`	Initialize local project	`--workdir`
`supabase start`	Start local development stack	`-x` (exclude services)
`supabase stop`	Stop local stack	`--no-backup`
`supabase status`	Show local container status	-
`supabase link`	Link to remote project	`--project-ref <ref>` (required)

Database Commands

Command	Description	Key Flags
`supabase db reset`	Reset local database	-
`supabase db push`	Push migrations to remote	`--dry-run` , `--include-seed`
`supabase db pull`	Pull schema from remote	`--schema <name>`
`supabase db diff`	Diff schema changes	`--linked` , `--local` , `-f <name>`
`supabase db lint`	Lint for schema errors	`--linked` , `--level <warning\|error>`

Migration Commands

Command Description Key Flags

supabase migration new

Create new migration

<name>

(required)

supabase migration list

List migration history

--db-url <url>

supabase migration up

Apply pending migrations

--local

--linked

Edge Functions Commands

Command	Description	Key Flags
`supabase functions new`	Create new function	`<name>` (required)
`supabase functions serve`	Serve locally	`--env-file <path>`
`supabase functions deploy`	Deploy function(s)	`--no-verify-jwt` , `--project-ref`
`supabase functions delete`	Delete function	`<name>` (required)

Secrets Commands

Command Description Key Flags

supabase secrets set

Set secret(s)

NAME=value

--env-file <path>

supabase secrets list

List secrets

--project-ref

supabase secrets unset

Remove secret(s)

<NAME>

For type generation, database inspection, storage, and project management commands, see REFERENCE.md.

Local Development Ports

Service	Port	URL
API Gateway	54321	`http://localhost:54321`
Database	54322	`postgresql://postgres:postgres@localhost:54322/postgres`
Studio	54323	`http://localhost:54323`
Inbucket (Email)	54324	`http://localhost:54324`

Common Workflows

1. Initialize New Project

# Create local project structure
supabase init

# Link to existing remote project
export SUPABASE_ACCESS_TOKEN="your-token"
supabase link --project-ref <project-ref>

# Start local development
supabase start

2. Create and Apply Migrations

# Create new migration
supabase migration new add_users_table

# Edit migration file at supabase/migrations/<timestamp>_add_users_table.sql

# Apply locally
supabase db reset

# Push to remote
supabase db push

3. Pull Remote Schema Changes

# Link project first
supabase link --project-ref <ref>

# Pull all schema changes
supabase db pull

# Or create migration from remote changes
supabase db pull --schema public

4. Deploy Edge Functions

# Create new function
supabase functions new hello-world

# Edit supabase/functions/hello-world/index.ts

# Test locally
supabase functions serve

# Deploy to production
supabase functions deploy hello-world

# Deploy without JWT verification (for webhooks)
supabase functions deploy hello-world --no-verify-jwt

5. Manage Secrets

# Set individual secret
supabase secrets set STRIPE_KEY=sk_test_xxx

# Set from .env file
supabase secrets set --env-file .env.production

# List current secrets
supabase secrets list

# Remove secret
supabase secrets unset STRIPE_KEY

6. Generate TypeScript Types

# From remote database
supabase gen types typescript --linked > src/types/database.ts

# From local database
supabase gen types typescript --local > src/types/database.ts

7. Debug Database Performance

# Find slow queries
supabase inspect db outliers

# Check for blocking queries
supabase inspect db blocking

# Check cache hit ratios
supabase inspect db cache-hit

For advanced workflows including CI/CD integration and migration strategies, see REFERENCE.md.

Error Handling

Common Errors and Solutions

Error	Cause	Solution
`Error: You need to be logged in`	Missing access token	Set `SUPABASE_ACCESS_TOKEN` env var
`Error: Project ref is required`	No project linked	Use `--project-ref` or run `supabase link`
`Error: Cannot connect to Docker`	Docker not running	Start Docker Desktop
`Error: Port 54321 already in use`	Previous instance running	Run `supabase stop` first
`Error: Migration failed`	SQL syntax error	Check migration file syntax

Docker Issues

# Check if Docker is running
docker info

# Clean up Supabase containers
supabase stop --no-backup
docker system prune -f

# Restart with fresh state
supabase start

Migration Conflicts

# View migration status
supabase migration list

# Repair migration history
supabase migration repair --status reverted <version>

# Squash migrations if needed
supabase migration squash --version <timestamp>

For complete troubleshooting guide including permission issues and advanced debugging, see REFERENCE.md.

Auto-Detection Triggers

This skill auto-loads when Supabase context is detected:

File-based triggers:

```
supabase/config.toml
```
in project
```
supabase/
```
directory present
```
SUPABASE_ACCESS_TOKEN
```
in
```
.env
```
file

Context-based triggers:

User mentions "Supabase"
User runs supabase CLI commands
Database migration discussions
Edge Functions deployment

Agent Integration

Compatible Agents

Agent	Use Case
`deployment-orchestrator`	Automated deployments, CI/CD
`infrastructure-developer`	Database provisioning
`deep-debugger`	Query analysis, performance debugging
`backend-developer`	Database schema, Edge Functions
`postgresql-specialist`	Advanced database operations

Handoff Patterns

To Deep-Debugger: Slow query investigation, migration failures, Edge Function runtime errors

From Deep-Debugger: Schema problems requiring migrations, environment variable changes

Quick Reference Card

# Authentication (NEVER use supabase login in Claude Code)
export SUPABASE_ACCESS_TOKEN="xxx"

# Project setup
supabase init
supabase link --project-ref <ref>
supabase start
supabase stop

# Database
supabase migration new <name>
supabase db reset
supabase db push
supabase db pull
supabase db diff --linked

# Edge Functions
supabase functions new <name>
supabase functions serve
supabase functions deploy <name>

# Secrets
supabase secrets set KEY=value
supabase secrets list
supabase secrets unset KEY

# Types
supabase gen types typescript --linked > types.ts

# Debugging
supabase inspect db outliers
supabase inspect db blocking