> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 数据库与迁移

准备 Postgres，并用已提交的迁移演进 Drizzle 模式。

## 安装与配置

在执行任何步骤之前，请阅读[开始之前](https://supastack.dev/zh/docs/web/before-you-start.md) 和[终端基础知识](https://supastack.dev/zh/docs/web/terminal-basics.md)。这些说明假设您在 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

# Optional Compose / Supabase settings in .env:
# POSTGRES_PASSWORD=supastack
# SUPABASE_ACCESS_TOKEN=
# DATABASE_POOLER=transaction
```


## 要复制的命令

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

```
# 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。如果更改数据库，请更新这两个文件。重试之前读取第一个失败的迁移语句；切勿在生产中重复此操作。

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


如果你想继续完成设置，可以阅读《[设置支付](https://supastack.dev/zh/docs/web/setup-payments.md)》。


## 下一篇

[数据库模块](https://supastack.dev/zh/docs/modules/database.md)