为每个 Agent 创建自动过期的数据库角色

让 Agent 连接数据库最快的方式，是把 owner 密码交给它。但这也是最难收回的方式：所有 Agent 共用一个凭证，无法单独吊销其中一个，数据库也无法告诉您哪条语句是哪个 Agent 执行的。

更好的默认做法是为每个 Agent 创建一个专属数据库角色，按任务需要授权，并在任务预计结束时自动过期。本指南介绍如何通过 Lymeno API 实现这一点。

为任务创建角色

curl -X POST https://console.lymeno.com/v1/databases/$DATABASE_ID/roles \
  -H "Authorization: Bearer $LYMENO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "agent_report_0412",
    "inheritedRoles": ["pg_read_all_data"],
    "validUntil": "2026-10-04T00:00:00Z"
  }'

请求包含三个字段：

• username：3–63 个字符，以小写字母开头，只能包含小写字母、数字和下划线。PostgreSQL 或 Lymeno 的保留名称（例如 postgres、admin 以及以 pg_ 开头的名称）会被拒绝。
• inheritedRoles：角色获得的权限，至少一项。
• validUntil：可选的过期时间，采用 ISO 8601 格式，必须晚于当前时间。省略时角色不会过期。

响应包含角色信息、创建该角色的操作 ID 以及密码。密码只在这一次响应中返回，请先将其保存到 Agent 能读取的位置（例如 Agent 的密钥存储），再进行其他操作。

只授予任务所需的权限

inheritedRoles 只接受以下取值：

角色	允许的操作
owner	拥有 public schema，可创建和修改表
pg_read_all_data	读取所有表、视图和序列
pg_write_all_data	在所有表中插入、更新和删除数据
pg_read_all_stats	读取所有统计视图
pg_monitor	读取监控相关的视图和函数
pg_signal_backend	取消其他角色的查询、结束其会话
pg_maintain	执行 VACUUM、ANALYZE、REINDEX 等维护命令

除 owner 外，其余均为 PostgreSQL 内置角色，含义与官方定义一致。生成报表的 Agent 只需要 pg_read_all_data；执行迁移的 Agent 需要 owner；只负责发现慢查询的 Agent 只需要 pg_monitor。

按需数据库目前支持 owner、pg_monitor 和 pg_signal_backend，其他取值会返回 validation_failed，原因为 role_not_supported。

让访问权限自动结束

validUntil 对应 PostgreSQL 的 VALID UNTIL。到期后，PostgreSQL 将拒绝该角色的新登录，即使没有人记得清理，访问也会按时结束。

有两点需要注意：

• 过期只影响新连接。已经建立的会话会继续运行，直到断开。如果 Agent 持有长期存在的连接池，请在任务结束时关闭它。
• 过期的角色仍然存在。不再需要时，请调用 DELETE /v1/databases/:id/roles/:roleId 将其删除。每个数据库最多可以有 20 个角色。

搭配限定权限的 API 令牌

数据库角色决定 Agent 在 PostgreSQL 内能做什么，API 令牌决定它在 Lymeno 中能做什么。两者应遵循同样的原则：

• 为每个 Agent 或自动化流程单独创建令牌，而不是所有用途共用一个。
• 只需读取状态的令牌授予只读的 member 角色，只有需要执行变更的令牌才授予 admin。
• 为令牌设置 30、90 或 365 天的有效期。
• API 令牌无法创建或吊销其他令牌，因此泄露的令牌无法签发新令牌。

使用令牌执行的每项变更都会以该令牌的名称记入审计日志。当每个 Agent 都有自己的令牌和角色时，审计日志与数据库自身的日志相互印证：哪个 Agent 在什么时间做了什么，一目了然。