Supabase CLI

与 Supabase 项目交互：执行 SQL 查询、CRUD 操作、向量相似性搜索以及表管理。

初始化配置

# 必需
export SUPABASE_URL="https://yourproject.supabase.co"
export SUPABASE_SERVICE_KEY="eyJhbGciOiJIUzI1NiIs..."

# 可选：用于管理 API
export SUPABASE_ACCESS_TOKEN="sbp_xxxxx"

常用命令速查

# 执行 SQL 查询
{baseDir}/scripts/supabase.sh query "SELECT * FROM users LIMIT 5"

# 插入数据
{baseDir}/scripts/supabase.sh insert users '{"name": "John", "email": "john@example.com"}'

# 带过滤条件的查询
{baseDir}/scripts/supabase.sh select users --eq "status:active" --limit 10

# 更新数据
{baseDir}/scripts/supabase.sh update users '{"status": "inactive"}' --eq "id:123"

# 删除数据
{baseDir}/scripts/supabase.sh delete users --eq "id:123"

# 向量相似性搜索
{baseDir}/scripts/supabase.sh vector-search documents "search query" --match-fn match_documents --limit 5

# 列出所有表
{baseDir}/scripts/supabase.sh tables

# 查看表结构
{baseDir}/scripts/supabase.sh describe users

命令参考

query —— 执行原始 SQL

{baseDir}/scripts/supabase.sh query ""

# 示例
{baseDir}/scripts/supabase.sh query "SELECT COUNT(*) FROM users"
{baseDir}/scripts/supabase.sh query "CREATE TABLE items (id serial primary key, name text)"
{baseDir}/scripts/supabase.sh query "SELECT * FROM users WHERE created_at > '2024-01-01'"

select —— 带过滤条件的表查询

{baseDir}/scripts/supabase.sh select  [选项]

选项：
  --columns     逗号分隔的列名（默认：*）
  --eq       等值过滤（可多次使用）
  --neq      不等值过滤
  --gt       大于
  --lt       小于
  --like     模式匹配（支持 % 通配符）
  --limit          限制返回结果数量
  --offset         设置结果偏移量
  --order 按指定列排序
  --desc              降序排列

# 示例
{baseDir}/scripts/supabase.sh select users --eq "status:active" --limit 10
{baseDir}/scripts/supabase.sh select posts --columns "id,title,created_at" --order created_at --desc
{baseDir}/scripts/supabase.sh select products --gt "price:100" --lt "price:500"
insert —— 插入行（单行或多行）
{baseDir}/scripts/supabase.sh insert 
 ''

# 单行插入
{baseDir}/scripts/supabase.sh insert users '{"name": "Alice", "email": "alice@test.com"}'

# 多行插入
{baseDir}/scripts/supabase.sh insert users '[{"name": "Bob"}, {"name": "Carol"}]'

update —— 更新行
{baseDir}/scripts/supabase.sh update  '' --eq 

# 示例
{baseDir}/scripts/supabase.sh update users '{"status": "inactive"}' --eq "id:123"
{baseDir}/scripts/supabase.sh update posts '{"published": true}' --eq "author_id:5"

upsert —— 插入或更新（冲突时更新）
{baseDir}/scripts/supabase.sh upsert  ''

# 示例（要求目标表存在唯一约束）
{baseDir}/scripts/supabase.sh upsert users '{"id": 1, "name": "Updated Name"}'

delete —— 删除行
{baseDir}/scripts/supabase.sh delete  --eq 

# 示例
{baseDir}/scripts/supabase.sh delete sessions --lt "expires_at:2024-01-01"

vector-search —— 基于 pgvector 的相似性搜索
{baseDir}/scripts/supabase.sh vector-search  "" [选项]

选项：
  --match-fn      RPC 函数名（默认：match_）
  --limit            返回结果数量（默认：5）
  --threshold        相似度阈值（0–1，默认：0.5）
  --embedding-model  查询嵌入所用模型（默认：使用 OpenAI）

# 示例
{baseDir}/scripts/supabase.sh vector-search documents "How to set up authentication" --limit 10

# 需要预先定义匹配函数，例如：
# CREATE FUNCTION match_documents(query_embedding vector(1536), match_threshold float, match_count int)

tables —— 列出所有表
{baseDir}/scripts/supabase.sh tables

describe —— 显示表结构（Schema）
{baseDir}/scripts/supabase.sh describe 
rpc —— 调用存储过程（Stored Procedure）
{baseDir}/scripts/supabase.sh rpc  ''

# 示例
{baseDir}/scripts/supabase.sh rpc get_user_stats '{"user_id": 123}'
向量搜索初始化配置
1. 启用 pgvector 扩展
CREATE EXTENSION IF NOT EXISTS vector;
2. 创建含 embedding 字段的表
CREATE TABLE documents (
  id bigserial PRIMARY KEY,
  content text,
  metadata jsonb,
  embedding vector(1536)
);
3. 创建相似性搜索函数
CREATE OR REPLACE FUNCTION match_documents(
  query_embedding vector(1536),
  match_threshold float DEFAULT 0.5,
  match_count int DEFAULT 5
)
RETURNS TABLE (
  id bigint,
  content text,
  metadata jsonb,
  similarity float
)
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN QUERY
  SELECT
    documents.id,
    documents.content,
    documents.metadata,
    1 - (documents.embedding <=> query_embedding) AS similarity
  FROM documents
  WHERE 1 - (documents.embedding <=> query_embedding) > match_threshold
  ORDER BY documents.embedding <=> query_embedding
  LIMIT match_count;
END;
$$;
4. 创建索引以提升性能
CREATE INDEX ON documents 
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);
环境变量



变量
是否必需
说明



SUPABASE_URL
是
项目 URL（如 https://xxx.supabase.co）


SUPABASE_SERVICE_KEY
是
Service Role 密钥（拥有完全访问权限）


SUPABASE_ANON_KEY
否
Anon 密钥（受限访问权限）


SUPABASE_ACCESS_TOKEN
否
Management API 访问令牌


OPENAI_API_KEY
否
用于生成 embedding 向量


注意事项

Service Role 密钥会绕过 RLS（Row Level Security）策略
客户端或受限场景请使用 anon key
向量搜索依赖 pgvector 扩展
默认 embedding 模型为 OpenAI text-embedding-ada-002（1536 维）