173 lines
4.3 KiB
Markdown
173 lines
4.3 KiB
Markdown
# 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)
|