---
url: /docs/database.md
---
# 数据库概览

## 当前模型

数据库使用 PostgreSQL 和 Drizzle，开发可使用独立本地库，目标部署可使用 Neon。模型集中在 `db/schema/`，从 `db/schema/index.ts` 和 `@repo/db` 导出。

账号、会话、组织及订阅由 Better Auth 插件使用；工具记录和积分由业务接口维护。类型 `Database` 屏蔽底层驱动差异，不在业务代码依赖驱动私有连接对象。

## 连接与权限

完整本地预览用 `DATABASE_URL` 直连；线上接口用 Hyperdrive。认证、权限、订阅和积分走实时连接，只有可接受旧结果的读取才使用缓存连接。

应用连接使用日常业务角色，迁移使用有建表权限的管理角色。角色授权脚本位于 `db/scripts/grant-app-role.sql`，由实际数据库 / 公共对象所有者在指定库执行；新密码交互输入，已有账号不自动轮换。权限、连接池与实际复验见[数据库角色与凭据](../agentbuff-stack/database-roles)。

## 常用命令

```sh
bun db:generate
bun db:check
bun db:typecheck
bun db:studio
```

生成迁移和检查不会替你完成线上发布。`db:migrate` 应用于明确选择的数据库；`db:push` 直接调整结构，仅适合已确认的可丢弃本地库。

## 环境选择

`db/drizzle.config.ts` 只接受开发、预发布和生产。预发布与生产必须存在各自 `.env.<环境>.local`，并由该文件明确提供 `DATABASE_URL`，不能回退到开发库或沿用 shell 中旧地址。

测试使用进程内 PGlite，不使用真实开发或生产连接；`ENVIRONMENT=test` 不作为数据库迁移目标。

完整归档、校验和独立空库恢复使用新增 `bun db:backup` / `bun db:restore`，详见[数据库备份与恢复](../agentbuff-stack/backup-restore)。原导出命令默认只导出结构，不作为完整备份。

继续阅读 [数据模型](./schema.md)、[数据库迁移](./migrations.md) 和 [查询写法](./queries.md)。