---
url: /docs/deployment/production-database.md
---
# 生产数据库

## 连接分工

可使用 Neon PostgreSQL。应用运行通过 Hyperdrive 使用业务角色，数据库迁移通过管理连接。不同站点和环境保持独立数据与凭据，生产不使用本机演示数据库。

使用直接数据库主机连接 Hyperdrive，不叠加 Neon 的事务连接池。现有 Terraform 配置会拒绝带 `-pooler` 的主机及不支持的连接串格式。

## 准备步骤

1. 创建生产数据库及独立业务角色，保留管理连接用于迁移。
2. 审查并执行初始迁移，授予业务角色必要权限。
3. 为实时和缓存查询分别创建 Hyperdrive，配置正确源连接。
4. 将两个资源 ID 写入接口生产配置，再设置应用秘密。
5. 在预发布先验证连接、权限与迁移兼容性。

`db/scripts/grant-app-role.sql` 已在独立本地密码认证实例验收，由实际数据库 / 公共对象所有者运行；不由部署自动执行。新密码交互输入，已有账号重复授权不会改密码，旧参数传密码方式被拒绝。权限边界、事务回滚与复验见[数据库角色与凭据](../agentbuff-stack/database-roles)；真实 Neon 权限仍需在自己的环境验证。

## 缓存和连接额度

权限、会话、账单、积分和写后读使用实时连接。缓存连接只用于能接受短期旧结果的读取。两个 Hyperdrive 分别占用连接预算，要把它们的总量纳入源数据库限制。

缓存时间和连接上限以 `infra/` 当前配置与账户限制为准，不能仅因使用免费套餐就假设不会产生费用或限制。

数据库改密码不会自动断开已有连接。更新所选环境两个 Hyperdrive 的源凭据后，也需核对旧连接池的处理和原业务恢复；不能只改本机连接或据此宣称旧连接已撤销，具体步骤见上述角色教程。

## 备份与恢复

发布前确认数据库备份和恢复能力；在隔离环境验证恢复，而不是只确认有一个备份按钮。回滚 Worker 不会撤销数据库迁移，破坏性改动需要单独恢复或补救方案。

## 排查

连接失败核对主机、数据库、角色、SSL 和网络；权限错误核对表及序列授权；缺表检查目标库的迁移记录；只在生产出现旧权限结果时检查是否误用了查询缓存。