create-readonly-db-role

为 Agent 创建只读数据库角色

准备一个仅可执行 SELECT 的角色和受保护的连接。SQL、角色名、授权、拒绝列表、RLS 设置、超时和连接步骤都只是示例，请根据你的系统进行调整，不是可直接用于生产环境的配置。

访问模型

1. 仅授予 SELECT 权限。 不授予任何写入权限；使用拒绝列表排除机密信息和 PII。
2. 涵盖现有和未来的表。 授予对 public 中所有表的 SELECT 权限，并通过默认权限涵盖未来的表，然后撤销拒绝列表中表的权限。绝不授予 auth 架构的权限。新增的敏感表需要手动撤销权限。
3. 软性防护措施。 设置 default_transaction_read_only = on，并根据工作负载设置较短的 statement_timeout。

RLS： 如果该角色没有适用的策略，表可能不会返回任何行。只有在符合你的安全模型时才考虑使用 bypassrls：它会跳过行过滤，但权限授予和拒绝列表仍然有效。

工作流

1. 检查角色： select rolname from pg_roles where rolname = 'agent_reader';。使用你选定的名称；如果该角色已存在，请更新而不是重新创建。
2. 与人工负责人共同确定拒绝列表。 找出 Agent 绝不能查看的机密信息或 PII 表，例如凭据、webhook 载荷和身份表。
3. 将 SQL 保存到仓库中，例如 docs/database/create-agent-reader-role.sql。注释说明变更内容、原因，以及如何应用、验证和还原。仅在聊天中提供 SQL 并不够。
4. 由人工负责人应用。Agent 绝不能执行生产环境 DDL。 在 Supabase 中，将文件内容粘贴到 SQL 编辑器，然后从历史记录中删除该查询，因为其中包含密码。人工负责人应将密码保存在密码管理器中。
5. 配置连接，通过受保护的机密管理器或本地环境配置进行；绝不提交到仓库。Supabase 会话池通常在端口 5432 上使用 <role>.<project-ref> 作为用户名。如果缺少 psql，请安装它（macOS 上使用 Homebrew libpq）。
6. 运行下方所有验证检查。
7. 创建项目本地使用技能，说明关键表、查询模式、只读访问，以及绝不将 PII 粘贴到提交内容或文档中。

SQL 模板

-- Example only. Rename the role, timeout, and denylist for your system.

-- 1. role + soft guardrails
create role agent_reader with login password 'REPLACE_ME';
alter role agent_reader set default_transaction_read_only = on;
alter role agent_reader set statement_timeout = '10s';  -- example timeout; change as needed

-- 2. SELECT-only grants, denylist model
grant usage on schema public to agent_reader;
grant select on all tables in schema public to agent_reader;
alter default privileges for role postgres in schema public
  grant select on tables to agent_reader;   -- future tables auto-readable

-- 3. denylist: keep secrets and PII invisible (replace with your own tables)
revoke select on table public.secrets from agent_reader;
revoke select on table public.private_events from agent_reader;

-- 4. only if RLS is enabled, no policy covers this role, and bypass fits your model
alter role agent_reader bypassrls;

还原：drop owned by agent_reader; drop role agent_reader;

验证

宣布完成前，所有检查都必须通过：

# Load the connection URL from your secret manager or local environment configuration.
psql "<readonly-connection-url>" -X -c "select current_user;"                      # -> agent_reader
psql "<readonly-connection-url>" -X -c "show statement_timeout;"                   # -> matches your chosen timeout
psql "<readonly-connection-url>" -X -c "select count(*) from public.<big_table>;"  # -> real number, NOT 0
psql "<readonly-connection-url>" -X -c "delete from public.<any_table> where false;"
# -> ERROR: read-only transaction (soft guardrail)
psql "<readonly-connection-url>" -X -c "begin; set transaction read write; delete from public.<any_table> where false; rollback;"
# -> ERROR: permission denied (the hard wall)
psql "<readonly-connection-url>" -X -c "select * from public.<denylisted> limit 1;"         # -> ERROR: permission denied
psql "<readonly-connection-url>" -X -c "select * from auth.<identity_table> limit 1;"       # -> ERROR: permission denied

验证两种防护都有效：在只读防护开启时写入失败；关闭只读防护后，写入因 permission denied 而失败。如果任何检查未通过，请由人工负责人修正配置，然后重新运行所有检查。

故障排除和维护

• 所有表都没有返回行： 检查 RLS 策略；仅在适当时使用 bypassrls。
• 写入验证成功： 立即停止。让人工负责人撤销该角色的权限并修正配置，然后重新运行所有检查。
• Supabase 身份验证失败： 检查连接池用户名，通常为 <role>.<project-ref>。
• 合法查询超时： 在延长超时时间之前，先添加筛选条件或限制结果数量。
• 新增敏感表： 在拒绝列表中添加 revoke select。
• 轮换密码： 让人工负责人运行 alter role agent_reader with password '...'，并更新已保存的连接机密。
• 绝不允许 Agent 通过此角色写入。生产环境写入只能由人工执行。