For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/modules/database.md (or send Accept: text/markdown).

数据库模块

每条记录流经的 Drizzle 模式与持久化助手。

询问本指南

安装与配置

在执行任何步骤之前，请阅读开始之前和终端基础知识。这些说明假设您在 VS Code 中打开了完整的 supastack monorepo；它的根 package.json 标记存储库根。在 pnpm 命令中，工作区包是应用程序或共享代码文件夹；在产品中，工作空间是团队的数据容器和安全边界。 corepack pnpm --filter ... 从 monorepo 选择一个包，同时从其根运行命令。如果您仅打开同步的移动或桌面文件夹，则它不包含 Web 后端、Docker 设置或根脚本：从此 monorepo 或可访问的托管服务器运行后端，并使用平台文件夹自己的脚本。环境变量是存储在本地 .env 文件或托管仪表板中的命名设置；更改后重新启动相关应用程序，并将服务器机密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。

1.安装并启动Docker Desktop。

2. 将 .env.example 复制到迁移工具根目录中的 .env，将 Next.js 复制到 apps/web/.env.local（PowerShell：Copy-Item .env.example .env；Copy-Item .env.example apps/web/.env.local. macOS/Linux/Git Bash：cp .env.example .env；cp .env.example apps/web/.env.local）。保持两个文件中的 DATABASE_URL 相同；该示例已与本地 Docker 数据库匹配。

3. 从存储库根目录运行 docker compose up -d postgres 和 docker compose ps；等到 postgres 报告健康。

4. 从根运行 corepack pnpm --filter @supastack/db db:migrate 以应用套件中已附带的迁移。仅在编辑 packages/db/src/schema.ts 后，运行 db:generate，检查生成的 SQL，然后运行 db:migrate。预期：本地 Postgres 容器运行正常，并且 Web 应用程序使用其迁移的数据库。切勿将首次运行指向生产环境。

在服务端环境中为目标 Postgres 数据库配置 DATABASE_URL。集成验收使用独立的一次性数据库。绝不要把测试迁移指向生产数据库。

数据库 workspace 导出模式定义与持久化助手。引入表或列之前，先阅读 packages/db/src/schema.ts 与迁移目录。

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

# Only after changing packages/db/src/schema.ts:
corepack pnpm --filter @supastack/db db:generate
corepack pnpm --filter @supastack/db db:migrate

要复制的命令

按照注释查看命令在哪个文件夹中运行。如果标记了两个终端，请打开两个终端窗口，并在使用第二个命令时保持第一个命令运行。

# Choose one copy method for your terminal:
# PowerShell:
Copy-Item .env.example .env
Copy-Item .env.example apps/web/.env.local

# macOS/Linux/Git Bash alternative:
# cp .env.example .env
# cp .env.example apps/web/.env.local

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

实现流程

修改模式后生成迁移，检查生成的 SQL，并与模式变更一起提交。新增必填列之前，先规划既有记录如何取值。

每条用户记录都带 workspaceId，并把这个边界带进读写。AI 记账使用不可变的模型-价格历史，而不是重写已被用量记录引用的价格。

验证与排障

如果 Docker 表示无法连接到其引擎，请启动 Docker Desktop 并等待其完成加载。如果 postgres 运行状况不佳，请从根目录运行 docker compose log postgres 并在迁移之前修复该错误。如果Web显示DATABASE_URL缺失，请检查apps/web/.env.local；如果 db:migrate 无法连接，请检查 root .env。如果更改数据库，请更新这两个文件。重试之前读取第一个失败的迁移语句；切勿在生产中重复此操作。

在隔离数据库上应用迁移并在其上运行数据库门槛测试。缺少凭证应产生明确的跳过门槛，而不是“持久化已通过”的断言。迁移失败时，先看是哪条语句失败以及当前模式，再重试。