用途：通过 Supabase 管理 API 对项目执行 SQL，覆盖数据查询、DDL 表结构变更、RLS 策略、存储元数据与迁移。SQL 以管理 API 权限运行，等同管理员级数据库访问。
主要能力：全部操作经 scripts/supabase.sh 完成，含三个命令：env（管理连接环境，存于 environments.json）、sql（执行 SQL 字符串）、sql-file（执行文件中的 SQL）。环境为 environments.json 中的命名条目，含 url 与可选 access_token，支持 env list/add/update/get/remove/check。env add 必须提供 --url 且名称唯一；env remove 拒绝删除最后一个环境；未存 token 时使用 shell 的 SUPABASE_ACCESS_TOKEN。
使用方式：用 --env <name> 选择环境，解析顺序为 --env 指定、导出的 SUPABASE_URL 与 TOKEN、仅一个环境时自动使用、多环境未指定则报错。示例：scripts/supabase.sh sql --env dev "SELECT * FROM users LIMIT 5"；长或多语句 SQL 用 scripts/supabase.sh sql-file --env dev ./migrations/001_init.sql。含 $ 的 SQL（如 $$ 函数体、$1 参数）必须走 sql-file，否则 shell 会展开 $$ 与 $1 破坏语句。输出为管理 API 原始 JSON 经 jq 处理，失败时返回含 message 字段的对象，需检查该键判断失败。
适用场景：查询记录、应用 schema 变更、管理策略、处理存储元数据与迁移。
限制与安全：命令具管理权限，错误语句可能删数据或破坏线上项目。执行 DROP、TRUNCATE 及无 WHERE 的 DELETE/UPDATE 前需与用户确认，尤其生产环境；写入或 DDL 前确认目标环境，勿让写入回退到自动选择的环境；先只读探查；迁移用 BEGIN; ... COMMIT; 保证原子性，CREATE INDEX CONCURRENTLY 不能放在事务内；迁移应可重复运行。更多示例见 references/sql-cookbook.md。