> ## 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 或託管 Supabase 專案，然後執行資料庫遷移。

## 什麼是遷移

全新的資料庫是空的——沒有存放使用者、工作區或記錄的表。遷移是一份儲存好的、有序的資料庫變更：一個寫著“建立這張表、加上那列”的檔案。套件附帶現成的遷移；`db:migrate` 命令把所有未應用的遷移應用到 `DATABASE_URL` 指定的資料庫。

執行它不是可選步驟——正是它把空蕩蕩的 Postgres 變成你應用的資料庫。登入、工作區、賬單記錄和已存資料都住在那些表裡。

這就是為什麼在遷移之前登入會讓賬戶壞掉：應用把新使用者寫進一張還不存在的表，留下半個賬戶。永遠先遷移——下面的安裝步驟正是在第一次真實登入前完成這件事。


## 安裝與配置

在執行任何步驟之前，請閱讀[開始之前](https://supastack.dev/zh-tw/docs/web/before-you-start.md) 和[終端基礎知識](https://supastack.dev/zh-tw/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-tw/docs/web/setup-payments.md)》。


## 下一篇

[資料庫與遷移](https://supastack.dev/zh-tw/docs/web/database.md)