backend/build/README.md

# MongoDB Migration 使用說明 (golang-migrate)

本目錄包含使用 [golang-migrate](https://github.com/golang-migrate/migrate) 執行 MongoDB migration 的配置。

## 重要說明

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

根據 [golang-migrate 官方文檔](https://github.com/golang-migrate/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`：

```bash
# 重命名所有 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 文檔](https://pkg.go.dev/github.com/golang-migrate/migrate/v4/database/mongodb)。

## 文件說明

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

## 使用方法

### 使用 Docker（推薦）

#### 執行 UP Migration

```bash
# 使用預設配置
make migrate-up

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

#### 執行 DOWN Migration

```bash
# 回滾一個版本
make migrate-down

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

#### 查看版本

```bash
make migrate-version
```

### 本地執行（需要安裝 migrate）

```bash
# 安裝 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）

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

### golang-migrate 支援的格式

#### JavaScript (.js)
```javascript
db.collection.createIndex({"field": 1}, {unique: true});
```

#### JSON 格式
```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 命令找不到

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

### 連接失敗

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

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

### 文件格式錯誤

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

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

## 參考資料

- [golang-migrate GitHub](https://github.com/golang-migrate/migrate)
- [MongoDB Driver 文檔](https://pkg.go.dev/github.com/golang-migrate/migrate/v4/database/mongodb)
- [CLI 文檔](https://github.com/golang-migrate/migrate/tree/master/cmd/migrate)