mcpField
S
supabase

supabase

github.com/jawwadfirdousi数据与数据库1546 次安装15 周前更新
代码仓库

关于 supabase

此技能通过管理 API 在 Supabase 项目中执行 SQL，并提供环境选择与安全指导，适用于查询、架构变更、策略、存储元数据和迁移。

主要功能

  1. 01管理命名连接环境
  2. 02执行 SQL 字符串和文件
  3. 03使用项目管理 API 权限
  4. 04以 JSON 查看查询结果
  5. 05遵循破坏性变更安全措施
  6. 06参考 SQL 示例手册

适用场景

  1. 01查询指定环境中的数据
  2. 02修改数据库架构或策略
  3. 03从文件执行迁移
  4. 04检查存储元数据或数据库架构

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jawwadfirdousi/agent-skills --skill supabase

安装后在 Claude Code 中输入/supabase确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.gitignore
environments.example.json
references/
sql-cookbook.md
scripts/
supabase.sh

详细介绍

Supabase

通过管理 API 对 Supabase 项目运行 SQL：查询数据、修改架构（DDL）、管理策略（RLS）、存储元数据和迁移。SQL 以管理 API 权限运行，因此应将其视为管理员级数据库访问。

所有操作都通过一个脚本 scripts/supabase.sh 完成，该脚本有三个命令：

  • env — 管理连接环境（存储在 environments.json 中）
  • sql — 运行 SQL 字符串
  • sql-file — 运行文件中的 SQL

环境

每个环境都是 environments.json 中的一个命名条目（已加入 gitignore，权限为 chmod 600），其中包含 url 和可选的 access_token。使用 env 子命令管理环境：

# List configured envs (tokens masked)
scripts/supabase.sh env list

# Add an env (--url required; --access-token and --description optional)
scripts/supabase.sh env add dev  --url https://<dev-ref>.supabase.co  --access-token sbp_...
scripts/supabase.sh env add prod --url https://<prod-ref>.supabase.co --description "Production"

# Update one or more fields on an existing env
scripts/supabase.sh env update dev --url https://<new-ref>.supabase.co --access-token sbp_...

# Inspect one env: human (default), json, or shell export
scripts/supabase.sh env get dev
scripts/supabase.sh env get dev --format json
scripts/supabase.sh env get dev --format export

# Remove an env (refused if it is the only one)
scripts/supabase.sh env remove prod

# Verify at least one env is configured (non-zero exit otherwise)
scripts/supabase.sh env check

脚本强制执行以下规则：

  • env add 需要 --url；环境名称必须唯一。
  • 如果只剩一个环境，env remove 将拒绝删除。
  • 访问令牌是机密信息。如果环境中未存储令牌，则使用 shell 中的 SUPABASE_ACCESS_TOKEN。
  • 脚本会从技能根目录读取 environments.json；如果该文件已存在于 ~/.config/claude/supabase-environments.json，则从该处读取。

如果脚本报告 no environments configured 或 SUPABASE_URL not set，则表示用户尚未完成设置：运行 env add 创建第一个环境，或引导用户查看自述文件。

选择环境

使用 --env <name> 为每条命令指定环境。解析顺序如下：

1) --env <name> set            -> use that env from environments.json
2) SUPABASE_URL + TOKEN exported -> use those exported values
3) exactly one env configured  -> use it (--env optional)
4) multiple envs, none named   -> error: pass --env <name>

当用户指定环境（“在 prod 中”“在 dev 上”）时，传入 --env <name>。如果存在多个环境，而用户未指定其中一个，则在运行前询问要使用哪个环境。

运行 SQL

# Run a SQL string
scripts/supabase.sh sql --env dev "SELECT * FROM users LIMIT 5"
scripts/supabase.sh sql --env prod "SELECT count(*) FROM users"
scripts/supabase.sh sql --env dev "INSERT INTO users (name, email) VALUES ('Alice', '[email protected]')"

# Run SQL from a file (prefer for long or multi-statement SQL)
scripts/supabase.sh sql-file --env dev ./migrations/001_init.sql
  • 为 SQL 加上引号。转义内部的双引号（例如策略名称：\"items_read_own\"）。
  • sql 会将整个字符串作为一条查询发送，因此多个以 ; 分隔的语句会一起运行。
  • 包含 $ 的 SQL —— 美元引用的函数／触发器主体（$$ … $$）或位置参数（$1）—— 必须通过 sql-file 运行。在双引号括起的 sql 参数中，shell 会展开 $$（替换为其 PID）和 $1，导致语句被破坏。文件内容会原样发送，因此 sql-file 是安全的。
读取输出

输出是原始管理 API JSON，并通过 jq 处理：

  • 查询成功时，会以 JSON 形式返回结果（SELECT 返回行对象数组）。
  • 查询被拒绝时，会返回包含 message 字段的对象，例如 {"message": "syntax error at or near ..."}。可通过检查是否只有一个 message 键来判断失败——即使 SQL 被拒绝，HTTP 调用通常仍会成功（退出码也通常如此）。

安全

这些命令以管理 API（管理员）权限运行，因此错误语句可能会删除数据或破坏线上项目。运行前：

  • 对破坏性语句向用户确认 — DROP、TRUNCATE，以及任何不带 WHERE 子句的 DELETE／UPDATE — 尤其是针对生产环境时。
  • 确认写入的目标环境。 如果配置了多个环境，且请求涉及写入或 DDL，则在运行前确认要使用哪个环境（--env <name>）；不要让写入操作回退到自动选择的环境。
  • 先进行只读探索。 在修改数据和架构前，优先使用 SELECT ... LIMIT 检查数据和架构。
  • 确保迁移具有原子性。 将多步修改用 BEGIN; ... COMMIT; 包裹（通过 sql-file），以便中途失败时回滚。请注意，CREATE INDEX CONCURRENTLY 不能在事务中运行，应作为独立语句运行。
  • 确保迁移可以重复运行。 优先使用 CREATE TABLE IF NOT EXISTS、CREATE OR REPLACE、ADD COLUMN IF NOT EXISTS 和 DROP ... IF EXISTS。

SQL 参考

有关涵盖 DDL、索引、枚举类型、视图、函数／RPC、触发器、RLS、数据模式（upsert、JSONB）、pgvector 相似度搜索、存储和架构自省的现成示例，请参阅 references/sql-cookbook.md。

评论

支持 Markdown