mcpField
R
read-prod-database

read-prod-database

github.com/davidondrej数据与数据库4.2k43 次安装今天更新
代码仓库

关于 read-prod-database

用于以只读方式查询 DeepAPI 生产环境 Supabase Postgres 数据库的技能。它指导 Agent 选择查询范围、探索数据库结构并开展分析，同时保护内部使用数据和用户信息。

主要功能

  1. 01只读访问生产数据库
  2. 02客户范围与全部工作区查询模式
  3. 03数据库结构探索与查询示例
  4. 04拒绝列表与超时处理指引
  5. 05PII 处理和写入防护规则

适用场景

  1. 01分析客户使用情况与留存
  2. 02检查 API 请求和服务成本
  3. 03核实生产环境迁移版本

安装

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

$npx skills add https://github.com/davidondrej/skills --skill read-prod-database

安装后在 Claude Code 中输入/read-prod-database确认已加载。

详细介绍

读取生产数据库（只读）

通过授权方式只读访问生产环境的 DeepAPI Supabase Postgres（ADR 0093）。此角色无法执行写入操作——切勿尝试写入。

快速开始

# env var lives in David's ~/.zshrc. NEVER `source ~/.zshrc` (breaks agent shells).
URL=${DEEPAPI_READONLY_DB_URL:-$(rg -o 'DEEPAPI_READONLY_DB_URL="([^"]+)"' -r '$1' ~/.zshrc)}

psql "$URL" -X -c "select count(*) from public.workspaces;"

状态检查：select current_user; 必须返回 agents_readonly。如果环境变量完全缺失，请停止并询问用户。

默认排除 David 和团队（ADR 0175）

每次运行使用情况／客户／PMF 查询时，都必须选择以下两种模式之一。每次都要有意识地选择：

  1. 仅客户（默认） — 排除 David、@davidondrej.com 团队以及 dogfood／测试工作区。
  2. 所有工作区 — 包含内部使用情况。仅在用户明确要求，或检查运行负载／总支出时使用。

如果工作区 ID 位于 src/config/internal-workspaces.ts 中（从中复制当前 UUID 列表），或者任何 dashboard_workspace_members 电子邮件地址属于 @davidondrej.com，则该工作区为内部工作区。将此条件添加到任何限定工作区范围的查询中：

-- customer-only scope: replace <uuids> with the list from src/config/internal-workspaces.ts
where sr.workspace_id <> all (array['<uuid-1>','<uuid-2>']::uuid[])
  and not exists (
    select 1 from public.dashboard_workspace_members m
    where m.workspace_id = sr.workspace_id
      and split_part(m.email, '@', 2) = 'davidondrej.com')

务必告知用户每个数字采用的范围——将结果标记为“仅客户（已排除 David 和团队）”或“所有工作区（包含内部工作区）”。切勿提供未标注或范围混杂的数字。

可查看和不可查看的内容

  • 可对所有当前及未来的 public 表执行 SELECT（拒绝列表模式），并读取所有行（该角色具有 bypassrls）。
  • 始终在拒绝列表中，访问时会返回 permission denied：api_keys、email_webhook_events 和整个 auth 架构。这是有意设置的——不要申请访问权限，也不要绕过限制（例如，联接 service_requests.api_key_id，而不是 api_keys）。
  • 防护措施：每个会话均为只读，查询超过 10s 后会被终止。

先发现架构，再查询

psql "$URL" -X -c '\dt public.*'                    # list tables
psql "$URL" -X -c '\d public.service_requests'      # columns of one table

仓库中的架构事实来源：src/db/migrations/*.sql。

主要表：workspaces（租户）、service_requests（每次 API 调用：状态、成本、提供方）、service_usage_events（使用情况汇总）、credit_accounts / credit_ledger_entries（资金、不可变账本）、credit_reservations（预留款）、rate_limit_counters、waitlist_signups、schema_migrations（已运行的迁移）。

实用模式：

# recent requests for one workspace (route = endpoint, e.g. /v1/research/deep)
psql "$URL" -X -c "select id, route, status, created_at from public.service_requests where workspace_id = '<id>' order by created_at desc limit 20;"

# weekly returning workspaces (retention, ADR 0069) — PMF metric: apply the customer-only scope filter above
psql "$URL" -X -c "select date_trunc('week', created_at) w, count(distinct workspace_id) from public.service_requests group by 1 order by 1 desc limit 8;"

# did migration NNNN run on prod?
psql "$URL" -X -c "select version from public.schema_migrations order by version;"

故障模式

  • permission denied for table ... → 表在拒绝列表中（符合预期，见上文）。
  • canceling statement due to statement timeout → 查询负载过重；添加筛选条件／限制，切勿循环重试同一查询。
  • 结果为空且出乎意料 → 使用 select current_user 再次检查，并通过 \dt 确认表存在；不要假定数据缺失。
  • 连接被拒绝／身份验证失败 → URL 或密码已更改；请询问用户（密码通过 alter role agents_readonly with password 轮换）。

硬性规则

  • 只读。不得执行 INSERT/UPDATE/DELETE/DDL，不得使用 set default_transaction_read_only = off，也不得通过其他方式绕过写入限制。生产环境写入由用户执行（迁移 + schema_migrations 记录）。
  • 查询结果包含真实用户数据（电子邮件、姓名、使用情况）。可在聊天中用于分析，但绝不能将个人身份信息（PII）或批量数据转储粘贴到提交、PR、文档或代码中。
  • 设置、维护和轮换详情：docs/external/supabase-readonly-agent-db-access.md。角色 SQL：docs/database/create-agents-readonly-role.sql。

评论

支持 Markdown