2026-07-10 12:54:45 +00:00
|
|
|
|
# Database migrations（golang-migrate + MongoDB）
|
|
|
|
|
|
|
|
|
|
|
|
**第一性原理：** index／seed 用 **檔案** 宣告，交給 `migrate`；沒有 Go seeder／init 程式。
|
|
|
|
|
|
|
|
|
|
|
|
工具：[golang-migrate](https://github.com/golang-migrate/migrate)
|
|
|
|
|
|
Mongo driver 讀的是 **JSON**（`db.runCommand` 陣列），不是 shell `.js`。
|
|
|
|
|
|
|
|
|
|
|
|
## 目錄
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
generate/database/mongo/
|
|
|
|
|
|
000001_members_indexes.up.json
|
|
|
|
|
|
000001_members_indexes.down.json
|
|
|
|
|
|
000002_jobs_indexes.up.json
|
|
|
|
|
|
...
|
|
|
|
|
|
000003_seed_admin.up.json # 可選種子
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
命名：`{version}_{name}.up.json` / `.down.json`
|
|
|
|
|
|
|
|
|
|
|
|
## 指令
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 安裝 CLI（一次）
|
|
|
|
|
|
go install -tags 'mongodb' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
|
|
|
|
|
|
|
|
|
|
|
|
# 連線字串要含 database 名
|
|
|
|
|
|
export MONGO_URL='mongodb://127.0.0.1:27017/haixun'
|
|
|
|
|
|
|
|
|
|
|
|
# 套用全部
|
|
|
|
|
|
migrate -path generate/database/mongo -database "$MONGO_URL" up
|
|
|
|
|
|
|
|
|
|
|
|
# 回滾一步
|
|
|
|
|
|
migrate -path generate/database/mongo -database "$MONGO_URL" down 1
|
|
|
|
|
|
|
|
|
|
|
|
# 看版本
|
|
|
|
|
|
migrate -path generate/database/mongo -database "$MONGO_URL" version
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Makefile：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
make migrate-up
|
|
|
|
|
|
make migrate-down
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 何時寫什麼
|
|
|
|
|
|
|
|
|
|
|
|
| 類型 | 放哪 | 範例 |
|
|
|
|
|
|
|------|------|------|
|
|
|
|
|
|
| Index / collection 約束 | `*.up.json` createIndexes | members.uid unique |
|
2026-07-15 15:23:59 +00:00
|
|
|
|
| 種子資料 | 不放 migration | 使用 `cmd/seeder` 與 runtime secret |
|
2026-07-10 12:54:45 +00:00
|
|
|
|
| 業務邏輯、密碼 runtime 產生 | **不要**寫進 migration | 用 API / 測試 helper |
|
|
|
|
|
|
|
2026-07-15 15:23:59 +00:00
|
|
|
|
Migration 不建立任何預設帳號。首次管理員必須透過 `make seeder`，並由環境提供強密碼。
|
2026-07-10 12:54:45 +00:00
|
|
|
|
|
|
|
|
|
|
## 與 gateway
|
|
|
|
|
|
|
|
|
|
|
|
先 `make migrate-up`，再 `go run . -f etc/gateway.yaml`（需 Mongo + Redis）。
|
|
|
|
|
|
## 不要
|
|
|
|
|
|
|
2026-07-15 15:23:59 +00:00
|
|
|
|
- 在 migration 寫死帳號或密碼
|
2026-07-10 12:54:45 +00:00
|
|
|
|
- 手寫 migration runner
|
|
|
|
|
|
- 把 stand-alone 電商 `.txt` 當 migrate 來源（格式不同；要用 JSON runCommand）
|
