数据库
数据库配置
从开发数据库开始，查看数据，再为上线准备独立生产库。
Web 使用连接池驱动的 PostgreSQL。先使用 Docker 或托管开发库，再为生产准备独立数据库。
开始前准备
在仓库根目录安装依赖。首次设置使用全新开发数据库。已有自定义数据库时，先阅读 更新已有项目，再执行迁移。
开发 PostgreSQL
使用本地 Docker Postgres：
pnpm muse:init --yes --app web --docker
pnpm db:seed使用 Neon 等托管开发库时，创建数据库，复制完整连接串（含服务商要求的 TLS 参数），再运行：
pnpm muse:init --yes --app web --database-url "postgres://USER:PASSWORD@HOST:5432/DATABASE"
pnpm db:seed两条路径选一条即可。初始化会在 apps/web/.env.local 写入 DATABASE_URL 并执行初始迁移。已经完成快速开始，只查看数据的话不需要再初始化。
检查迁移状态，打开数据库浏览器：
pnpm db:status
pnpm db:studio打开终端给出的 Studio URL。可以查看 seed 用户，不要手工修改认证记录。Node 使用连接池，DATABASE_POOL_MAX 默认为 5，必要时根据宿主连接额度调整。
确认结果
- 初始化与对应 seed 命令完成，没有数据库错误。
- 开发用户可以登录，保存的账号修改刷新后仍存在。
- Node
pnpm db:status显示预期迁移状态，Studio 指向你的开发库。
常见问题
| 问题 | 处理方式 |
|---|---|
| 连接被拒绝 | 检查 Postgres 地址/端口，以及 Docker 或数据库服务是否运行 |
| 认证或 TLS 错误 | 复制完整服务商连接串，正确转义密码中的保留字符 |
| 连接数过多 | 检查数据库额度与 Node 连接池上限 |
| 已有生产数据 | 先备份并设计增量迁移，不重放新安装基线 |
开始新增业务表时
Schema 位于 packages/db/src/schema.ts。生成对应 数据库迁移。共享查询在 packages/db/src/queries/，首个参数为 db，应用包装层绑定 driver。组件不直接访问数据库。