数据库角色与凭据变更

当前能力

I15 已在独立的 PostgreSQL 17 密码认证实例中验收应用角色、环境连接权限与密码变更，再用真实本地 Worker 完成注册、上传、任务、扣费和私有下载。验收使用两个一次性数据库，不修改正常预览的角色、密码、授权或 0012 迁移；真实 Neon / Hyperdrive 连接池仍待指定环境验收。

三种角色分开安排

身份	用途	权限与配置
数据库迁移所有者	建表、增量迁移、备份和独立恢复	CLI 的管理连接；本教程授权脚本要求实际 current_user 是目标数据库、公共模式及其中表 / 序列的所有者
数据库应用角色	API 经 Hyperdrive 日常读写	每个站、每个环境独立登录账号；只授予公共模式的业务读写与序列使用
网站用户 / 管理员	登录、查看自己的文件、站内管理	数据库 user.role 和接口鉴权；与数据库登录账号分开

应用角色是服务端凭据，能读写公共模式的业务表。文件与任务的用户隔离由原接口鉴权实现，本脚本不提供数据库逐用户行隔离，也不会把网站普通用户提升为管理员。

1. 在指定环境授予应用权限

先审查并应用该环境需要的增量迁移，再执行 db/scripts/grant-app-role.sql。脚本不会创建数据库或应用迁移，正常启动、发布与生成新站也不会自动执行它。

从仓库根目录运行，连接字段替换为自己已确认的环境；管理密码放在权限为 600 的私有 PGPASSFILE 中。按实际服务配置 TLS，避免沿用上一环境的连接字段：

export PGHOST='自己的数据库主机'
export PGPORT='5432'
export PGDATABASE='自己的测试数据库'
export PGUSER='实际迁移所有者'
export PGPASSFILE='/自己的私有目录/数据库密码文件'
psql --no-psqlrc --no-password \
  --set role=app_staging \
  --file db/scripts/grant-app-role.sql

首次创建时 psql 会请求新应用密码并确认，不把密码写进命令参数或 SQL 文本。不要使用旧写法 -v password=...，脚本会拒绝。已有角色重复授权不会修改密码；密码变更在下节单独处理。这一方式依据 PostgreSQL 的 \password 说明，核对日期为 2026-10-11。

脚本先检查实际所有者和已有角色，拒绝继承其他所有者权限后代运行、已拥有对象的账号、特权属性、角色成员关系、额外直接授权及不合规默认授权。公共表 / 序列分属不同所有者也会拒绝，避免 PostgreSQL 仅警告而跳过授权。直接函数授权也需另行审查，不能作为普通应用角色自动接入。

创建角色、密码设置、当前授权与默认授权都在同一事务中；中途失败回滚。本地受控验收已在最后的默认授权处制造失败，确认新角色未留下，原授权不变。脚本不会偷偷撤销已有角色的其他直接权限；需要额外权限的角色应由操作者单独处理。

2. 核对实际权限

操作	本地实际结果
公共业务表查询、插入、更新、删除	允许；真实账号、文件、任务与积分流程通过
同一迁移所有者之后新增的公共表与序列	默认授权生效，插入及 nextval 可用
建表、建模式、临时表、修改或删除表	拒绝
TRUNCATE、序列 setval	拒绝；清理数据应走原业务入口
读取 drizzle.__drizzle_migrations	拒绝；迁移核查使用管理连接
另一环境的应用账号连接已加固的目标库	拒绝

脚本撤销所选数据库对 PUBLIC 的连接 / 临时表权限，以及所选库公共模式的公开建表权限，再授予指定账号连接与业务权限。测试库和正式库需分别执行；不自动调整其他库、其他账号或自定义公开授权。全局对象所有权和数据库直接授权会检查，但其他数据库内部的模式、函数与表授权不在本次检查范围。不要据此声称整个集群已完全隔离。

授权返回成功后，仍要用应用账号新建连接并走完整业务流程，确认认证、默认权限和环境绑定。恢复归档不带原所有者与授权，重新安排权限后执行同样的检查，见备份与恢复。

3. 更换密码与处理旧连接

用已确认环境的所有者连接执行：

psql --no-psqlrc --no-password --command '\password app_staging'

交互输入新密码后，更新所选环境缓存和无缓存两个 Hyperdrive 的源凭据。部署使用 Terraform 管理这两项资源，实际变更需遵循该环境的资源管理流程，不能只改电脑的 DATABASE_URL。

本地实测：旧密码的新连接被拒绝，新密码的新连接可用，修改密码不会断开已经建立的连接。撤销 CONNECT 同样只影响新连接。验收记录同一连接的后端编号，在修改密码及撤销连接权限后仍能查询；只有明确终止该自有测试连接后才断开。真实环境需先安排业务暂停、在途任务和连接更新，再决定是否终止旧连接；本教程不提供跨环境批量终止操作。

Cloudflare 也明确说明，更新 Hyperdrive 配置不会自动清除缓存或关闭原连接池；新连接采用新配置，立即替换已有连接需另行重启连接池。也可创建新配置并切换 Worker，但模板的资源管理与回滚安排需一起核对。官方凭据变更说明，核对日期为 2026-10-11；这不是本项目已完成云端连接池验收的证明。

更换后检查原用户登录、原私有结果下载、任务重复提交、积分账本及队列消费。本地在更新 Worker 凭据后验证了原结果可下载，同一任务仍原编号、一次尝试、17 积分，无再次扣费。数据库密码变更不自动撤销网站登录会话；认证密钥轮换是另一项维护。

本地复验

准备 initdb、pg_ctl、psql 并加入 PATH，从仓库根目录运行：

bun db:validate-app-role

命令自建仅回环监听、SCRAM 密码认证的 PostgreSQL 实例，应用两份完整迁移，验证权限、错误密码、环境连接隔离、额外授权拒绝、事务回滚及真实 Worker 流程。随后更改自有角色密码、处理自有连接、重启隔离 Worker，核对原下载和扣费去重，再停止并清理自己的实例与目录。它不读取管理连接去修改正常预览或远程角色，也不向真实供应商发送请求。日志只报告阶段和结论；私有本地诊断会隐藏生成的密码与密码校验值。