用 CLI 安全查询 Supabase

---
name: query-supabase-workflow
description: "先检查本地项目状态，明确 linked project，再用只读路径访问生产数据。"
---

# 查询 Supabase

## 适用目标

回答 Supabase 项目或数据库问题，不串错项目，也不绕过数据保护。

## 证据边界

- 工具状态分别标注 `docs-verified` 与真实独立执行；二者不能互换。
- 当前注册表没有记录某次工具执行具体由哪个 Agent 完成，因此不能把“兼容 Agent”称为“已测试 Agent”。
- 执行前重新核对目标账户、环境、版本与官方文档。
- 不自动执行 R2、R3 或任何标记为需要确认的步骤；必须在执行前获得明确批准。

## 推荐工具、安装与认证

- **Supabase CLI**（证据：`docs-verified`，文档检查：`2026-07-10`，未记录独立执行版本）
  - 安装：`npm install --save-dev supabase`
  - 认证：access token, database password, local development
  - 最小权限：Token 仅授权目标组织，并在远程命令前确认已关联项目。
- **PostgreSQL psql**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 18.1）
  - 安装：`brew install libpq`
  - 认证：connection URI, password file, service file, peer authentication
  - 最小权限：使用只读数据库角色、TLS，并把数据库与 schema 搜索路径限制在任务范围内。

## 输入合同

- 项目目录
- 明确的 project reference
- 只读数据库凭证
- 有限的问题范围

## 输出合同

- 本地服务状态
- 已确认的项目身份
- 有限查询结果
- 带风险说明的下一步

## 安全工作流

1. **检查本地状态** — 远程连接前先读取项目配置和本地服务状态。
   - 输入: Supabase 项目目录
   - 输出: 本地配置和服务状态
   - 风险: `read-only`
   - 命令: `supabase status --output json`
2. **确认远程目标** — 核对 project reference 和凭证范围，不暴露密钥。
   - 输入: 项目引用和受保护凭证
   - 输出: 已确认的远程目标
   - 风险: `read-only`
3. **执行有限读取** — 通过 psql 或获批 Data API 使用只读身份和明确 limit。
   - 输入: 已审查查询和目标
   - 输出: 结构化结果
   - 风险: `read-only`

## 必须先确认

- link 或 unlink 项目
- 数据库 push、迁移、reset 或函数部署
- 使用 service-role key 或修改生产数据

## 回滚

- 把本地配置修改放入版本控制
- 获批 schema 变更使用可逆迁移
- 只按项目事故流程恢复数据库备份

## 官方来源

- [Supabase CLI documentation](https://supabase.com/docs/guides/cli) — 用于核对当前命令、认证、输出和操作边界。
- [PostgreSQL psql documentation](https://www.postgresql.org/docs/current/app-psql.html) — 用于核对当前命令、认证、输出和操作边界。