supabase-cli

Supabase CLI 技能

Supabase 开发的完整 CLI 命令参考。

快速参考

任务	命令
安装 CLI	npm install supabase --save-dev
登录	supabase login
初始化项目	supabase init
链接到远程项目	supabase link --project-ref <ref>
启动本地服务栈	supabase start
停止本地服务栈	supabase stop
检查状态	supabase status
创建迁移	supabase migration new <name>
推送到远程项目	supabase db push
从远程项目拉取	supabase db pull
重置本地数据库	supabase db reset
生成类型	supabase gen types typescript --local > types.ts

安装

# NPM (recommended for projects)
npm install supabase --save-dev
npx supabase [command]

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

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

前置条件：Docker（本地开发所需）

项目设置

初始化项目

supabase init

创建：

• supabase/config.toml - 配置文件
• supabase/migrations/ - 迁移文件
• supabase/seed.sql - 种子数据

链接到远程项目

supabase link --project-ref <project-ref>

从以下位置获取项目引用：Dashboard → Project Settings → General

本地开发

启动本地服务栈

supabase start

启动：

• PostgreSQL 数据库
• PostgREST API
• GoTrue Auth
• Realtime 服务
• Storage 服务
• Studio 仪表板
• Inbucket（电子邮件测试）

输出 URL：

API URL: http://localhost:54321
DB URL: postgresql://postgres:postgres@localhost:54322/postgres
Studio URL: http://localhost:54323
Inbucket URL: http://localhost:54324

停止本地服务栈

# Stop and save data
supabase stop

# Stop and delete all data
supabase stop --no-backup

检查状态

supabase status

显示 URL、API 密钥和服务状态。

数据库命令

创建迁移

supabase migration new create_users_table

创建：supabase/migrations/<timestamp>_create_users_table.sql

根据更改生成迁移

# Make changes locally, then generate migration
supabase db diff -f my_schema_changes

# Diff against specific schemas
supabase db diff -f changes --schema public,extensions

应用迁移

# Apply pending migrations locally
supabase migration up

# Push to remote
supabase db push

# Preview what would be pushed
supabase db push --dry-run

拉取远程更改

supabase db pull

根据 Dashboard 中的更改创建迁移。

重置本地数据库

supabase db reset

重新创建数据库并应用所有迁移。

列出迁移

supabase migration list

显示本地与远程迁移状态。

回滚迁移

# Rollback last n migrations
supabase migration down --count 1

# Rollback specific number
supabase migration down --count 3

合并迁移

# Combine multiple migrations into one
supabase migration squash --version 20240101000000

# Squash all migrations up to version
supabase migration squash --version <target_version>

适用于在发布前整理迁移历史。

类型生成

生成 TypeScript 类型

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

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

# From specific project
supabase gen types typescript --project-id "your-id" > database.types.ts

Edge Functions

创建函数

supabase functions new hello-world

创建：supabase/functions/hello-world/index.ts

在本地运行

# Serve all functions
supabase functions serve

# Serve specific function
supabase functions serve hello-world

# With env file and no JWT
supabase functions serve --env-file .env --no-verify-jwt

部署

# Deploy all functions
supabase functions deploy

# Deploy specific function
supabase functions deploy hello-world

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

测试函数

curl -i --request POST \
  'http://localhost:54321/functions/v1/hello-world' \
  --header 'Authorization: Bearer <ANON_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Functions"}'

密钥管理

# Set secret
supabase secrets set API_KEY=abc123

# Set multiple secrets
supabase secrets set API_KEY=abc123 DB_PASSWORD=secret

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

# List secrets
supabase secrets list

# Remove secret
supabase secrets unset API_KEY

项目管理

# List organizations
supabase orgs list

# List projects
supabase projects list

# Create project
supabase projects create <name> --org-id <id> --region <region>

# Delete project
supabase projects delete --project-ref <ref>

# Update remote config from local
supabase projects update-config

数据库检查

# Cache hit ratio
supabase inspect db cache-hit --linked

# Unused indexes
supabase inspect db unused-indexes --local

# Table bloat
supabase inspect db bloat --linked

# Long running queries
supabase inspect db long-running-queries --linked

# Active connections
supabase inspect db role-connections --linked

备份与恢复

备份

# Dump roles
supabase db dump --linked -f roles.sql --role-only

# Dump schema
supabase db dump --linked -f schema.sql

# Dump data
supabase db dump --linked -f data.sql --use-copy --data-only

恢复

psql --single-transaction \
  --file roles.sql \
  --file schema.sql \
  --command 'SET session_replication_role = replica' \
  --file data.sql \
  --dbname [CONNECTION_STRING]

常用标志

标志	描述
--debug	详细输出
--local	使用本地数据库
--linked	使用已链接的远程项目
--project-ref <ref>	指定项目
--db-url <url>	连接字符串
--dry-run	预览但不执行
-f <file>	输出到文件

参考资料

• local-development.md - 本地服务栈设置
• migrations.md - 迁移工作流
• config-toml.md - 配置选项