backend/build

MongoDB Migration 使用說明 (golang-migrate)

本目錄包含使用 golang-migrate 執行 MongoDB migration 的配置。

重要說明

golang-migrate 對 MongoDB 的文件格式要求：

根據 golang-migrate 官方文檔，MongoDB 驅動支援以下格式：

1. JSON 格式：使用 db.runCommand 的 JSON 格式
2. JavaScript 格式：.js 文件，包含 MongoDB shell 命令

當前狀況：

• 你的 migration 文件是 .txt 格式的 MongoDB shell 腳本
• golang-migrate 可能無法直接執行 .txt 文件

解決方案

方案 1：將 .txt 文件重命名為 .js（推薦）

golang-migrate 支援 .js 文件，你可以將現有的 .txt 文件重命名為 .js：

# 重命名所有 migration 文件
cd generate/database/mongo
for file in *.up.txt; do mv "$file" "${file%.txt}.js"; done
for file in *.down.txt; do mv "$file" "${file%.txt}.js"; done

方案 2：使用 JSON 格式（如果需要）

如果 .js 格式不工作，可以轉換為 JSON 格式。參考 golang-migrate MongoDB 文檔。

文件說明

• Dockerfile-migrate - 編譯帶 MongoDB 支援的 golang-migrate
• docker-compose-migrate.yml - Docker Compose 配置
• scripts/ - 輔助腳本（可選）

使用方法

使用 Docker（推薦）

執行 UP Migration

# 使用預設配置
make migrate-up

# 自定義 MongoDB 連接
make migrate-up MONGO_HOST=localhost:27017 MONGO_DB=digimon_member MONGO_USER=root MONGO_PASSWORD=example

執行 DOWN Migration

# 回滾一個版本
make migrate-down

# 自定義連接
make migrate-down MONGO_HOST=localhost:27017 MONGO_DB=digimon_member

查看版本

make migrate-version

本地執行（需要安裝 migrate）

# 安裝 migrate（帶 MongoDB 支援）
go install -tags 'mongodb' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

# UP migration
make migrate-local-up

# DOWN migration
make migrate-local-down

環境變數

變數	預設值	說明
MONGO_HOST	127.0.0.1:27017	MongoDB 主機和端口
MONGO_DB	digimon_member	資料庫名稱
MONGO_USER	root	用戶名（可選，留空則不使用認證）
MONGO_PASSWORD	example	密碼（可選）
MONGO_AUTH_DB	admin	認證資料庫

Migration 文件格式

當前格式（.txt）

db.collection.createIndex({"field": 1}, {unique: true});

golang-migrate 支援的格式

JavaScript (.js)

db.collection.createIndex({"field": 1}, {unique: true});

JSON 格式

{
  "createIndexes": "collection",
  "indexes": [
    {
      "key": {"field": 1},
      "name": "field_1",
      "unique": true
    }
  ]
}

連接字符串參數

golang-migrate 的 MongoDB 連接字符串需要包含：

• x-migrations-collection=migrations - 指定 migration 版本記錄的集合名稱

完整格式：

mongodb://user:password@host:port/database?authSource=admin&x-migrations-collection=migrations

注意事項

1. 文件格式：確保 migration 文件是 .js 或 .json 格式
2. 版本追蹤：golang-migrate 會在 MongoDB 中創建 migrations 集合來追蹤版本
3. 執行順序：文件按照文件名中的時間戳順序執行
4. 錯誤處理：如果 migration 失敗，版本不會更新，可以安全重試

故障排除

migrate 命令找不到

# 安裝 migrate
go install -tags 'mongodb' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

連接失敗

確保 MongoDB 正在運行，並且連接資訊正確：

# 測試連接
mongosh "mongodb://root:example@127.0.0.1:27017/digimon_member?authSource=admin"

文件格式錯誤

如果遇到文件格式錯誤，檢查文件是否為有效的 JavaScript 或 JSON：

# 檢查文件
node -c generate/database/mongo/2024110500000001_account.up.js

參考資料

• golang-migrate GitHub
• MongoDB Driver 文檔
• CLI 文檔