Go資料庫遷移實戰：用golang-migrate實現零停機Schema版本控制

Go資料庫遷移：為什麼你的專案需要版本控制

每次上線都要手動執行SQL改表？多人協作時Schema不一致導致線上故障？回滾時不知道該撤銷哪些變更？資料庫遷移（Database Migration）是解決這些問題的核心手段。2026年，golang-migrate已成為Go生態最主流的遷移工具，支援MySQL、PostgreSQL、SQLite等15+資料庫，配合CI/CD實現遷移腳本→版本追蹤→零停機變更→自動回滾的全鏈路管理。

本文將從5個核心模式出發，帶你完成遷移初始化→增量變更→零停機策略→回滾機制→CI/CD整合的全鏈路實戰。

---

核心概念

概念	說明
Migration	資料庫Schema變更的版本化單元
golang-migrate	Go資料庫遷移CLI和庫
Up Migration	向前執行Schema變更
Down Migration	回滾Schema變更
Dirty State	遷移執行失敗導致資料庫版本鎖死
Zero-Downtime	不中斷服務的Schema變更策略
Seed Data	初始化資料的遷移腳本
Idempotent	遷移腳本可重複執行不報錯

---

問題分析：資料庫遷移的5大挑戰

1. Schema漂移：多環境資料庫結構不一致，線上和開發環境差異大
2. 遷移失敗：大表ALTER TABLE鎖表導致服務中斷
3. 回滾困難：沒有Down遷移或Down遷移不可逆
4. 協作衝突：多人同時修改Schema產生合併衝突
5. CI整合：遷移腳本未納入自動化測試和部署流程

---

分步實操：5個資料庫遷移核心模式

模式1：golang-migrate安裝與專案初始化

# macOS
brew install golang-migrate

# Linux
curl -L https://github.com/golang-migrate/migrate/releases/download/v4.18.1/migrate.linux-amd64.tar.gz | tar xvz
sudo mv migrate /usr/local/bin/

# Go install
go install -tags 'postgres mysql sqlite' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

# 建立遷移檔案
migrate create -ext sql -dir db/migrations -seq init_users_table

-- db/migrations/000001_init_users_table.up.sql
CREATE TABLE IF NOT EXISTS users (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(255) NOT NULL UNIQUE,
    email VARCHAR(255) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_username ON users(username);

-- db/migrations/000001_init_users_table.down.sql
DROP INDEX IF EXISTS idx_users_username;
DROP INDEX IF EXISTS idx_users_email;
DROP TABLE IF EXISTS users;

模式2：Go程式碼整合與增量變更

// internal/database/migrate.go
package database

import (
	"fmt"
	"log"

	"github.com/golang-migrate/migrate/v4"
	_ "github.com/golang-migrate/migrate/v4/database/postgres"
	_ "github.com/golang-migrate/migrate/v4/source/file"
)

type Migrator struct {
	migrate *migrate.Migrate
}

func NewMigrator(databaseURL string) (*Migrator, error) {
	m, err := migrate.New(
		"file://db/migrations",
		databaseURL,
	)
	if err != nil {
		return nil, fmt.Errorf("failed to create migrator: %w", err)
	}
	return &Migrator{migrate: m}, nil
}

func (m *Migrator) Up() error {
	if err := m.migrate.Up(); err != nil && err != migrate.ErrNoChange {
		return fmt.Errorf("migration up failed: %w", err)
	}
	log.Println("Migrations applied successfully")
	return nil
}

func (m *Migrator) Down() error {
	if err := m.migrate.Steps(-1); err != nil && err != migrate.ErrNoChange {
		return fmt.Errorf("migration down failed: %w", err)
	}
	log.Println("Migration rolled back successfully")
	return nil
}

func (m *Migrator) Version() (uint, bool, error) {
	return m.migrate.Version()
}

func (m *Migrator) Force(version int) error {
	if err := m.migrate.Force(version); err != nil {
		return fmt.Errorf("force version failed: %w", err)
	}
	log.Printf("Forced migration version to %d", version)
	return nil
}

模式3：零停機遷移策略

-- db/migrations/000002_add_phone_column.up.sql
-- 第一步：新增可空列（不鎖表）
ALTER TABLE users ADD COLUMN phone VARCHAR(20);

-- db/migrations/000003_phone_not_null.up.sql
-- 確保所有資料已回填後執行
ALTER TABLE users ALTER COLUMN phone SET NOT NULL;
ALTER TABLE users ALTER COLUMN phone SET DEFAULT '';

// internal/database/backfill.go
package database

import (
	"context"
	"database/sql"
	"fmt"
	"log"
	"time"
)

type BackfillConfig struct {
	BatchSize    int
	DelayBetween time.Duration
	DryRun       bool
}

func BackfillPhoneNumbers(ctx context.Context, db *sql.DB, config BackfillConfig) error {
	if config.BatchSize <= 0 {
		config.BatchSize = 1000
	}
	if config.DelayBetween == 0 {
		config.DelayBetween = 100 * time.Millisecond
	}

	var totalUpdated int64

	for {
		var updated int64
		err := db.QueryRowContext(ctx, `
			WITH batch AS (
				SELECT id FROM users
				WHERE phone IS NULL
				LIMIT $1
			)
			UPDATE users SET phone = ''
			WHERE id IN (SELECT id FROM batch)
			RETURNING 1
		`, config.BatchSize).Scan(&updated)

		if err != nil {
			return fmt.Errorf("backfill batch failed: %w", err)
		}

		if updated == 0 {
			break
		}

		totalUpdated += updated
		log.Printf("Backfilled %d rows (total: %d)", updated, totalUpdated)

		if config.DryRun {
			log.Println("Dry run mode, stopping after first batch")
			break
		}

		select {
		case <-ctx.Done():
			return ctx.Err()
		case <-time.After(config.DelayBetween):
		}
	}

	log.Printf("Backfill complete. Total rows updated: %d", totalUpdated)
	return nil
}

模式4：回滾機制與安全策略

// internal/database/safe_migrate.go
package database

import (
	"fmt"
	"log"

	"github.com/golang-migrate/migrate/v4"
)

type SafeMigrator struct {
	migrate *migrate.Migrate
	dryRun  bool
}

func NewSafeMigrator(databaseURL string, dryRun bool) (*SafeMigrator, error) {
	m, err := migrate.New("file://db/migrations", databaseURL)
	if err != nil {
		return nil, fmt.Errorf("failed to create migrator: %w", err)
	}
	return &SafeMigrator{migrate: m, dryRun: dryRun}, nil
}

func (sm *SafeMigrator) SafeUp() error {
	currentVersion, dirty, err := sm.migrate.Version()
	if err != nil && err != migrate.ErrNilVersion {
		return fmt.Errorf("failed to get current version: %w", err)
	}

	if dirty {
		return fmt.Errorf("database is in dirty state at version %d, run force first", currentVersion)
	}

	if sm.dryRun {
		log.Printf("[DRY RUN] Would apply migrations from version %d", currentVersion)
		return nil
	}

	if err := sm.migrate.Up(); err != nil && err != migrate.ErrNoChange {
		return fmt.Errorf("migration up failed: %w", err)
	}

	newVersion, _, _ := sm.migrate.Version()
	log.Printf("Migrated from version %d to %d", currentVersion, newVersion)
	return nil
}

func (sm *SafeMigrator) SafeDown(steps int) error {
	currentVersion, dirty, err := sm.migrate.Version()
	if err != nil {
		return fmt.Errorf("failed to get current version: %w", err)
	}

	if dirty {
		return fmt.Errorf("database is in dirty state at version %d", currentVersion)
	}

	if currentVersion == 0 {
		log.Println("Already at version 0, nothing to rollback")
		return nil
	}

	if sm.dryRun {
		log.Printf("[DRY RUN] Would rollback %d step(s) from version %d", steps, currentVersion)
		return nil
	}

	if err := sm.migrate.Steps(-steps); err != nil && err != migrate.ErrNoChange {
		return fmt.Errorf("migration down failed: %w", err)
	}

	newVersion, _, _ := sm.migrate.Version()
	log.Printf("Rolled back from version %d to %d", currentVersion, newVersion)
	return nil
}

模式5：CI/CD整合與自動化

# .github/workflows/migrate.yml
name: Database Migration

on:
  push:
    paths:
      - 'db/migrations/**'
      - 'internal/database/**'

jobs:
  migrate-dry-run:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_DB: test_db
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-go@v5
        with:
          go-version: '1.24'

      - name: Install migrate
        run: go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

      - name: Run migrations
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test_db?sslmode=disable
        run: |
          migrate -path db/migrations -database "$DATABASE_URL" up

      - name: Verify rollback
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test_db?sslmode=disable
        run: |
          migrate -path db/migrations -database "$DATABASE_URL" down 1
          migrate -path db/migrations -database "$DATABASE_URL" up

---

避坑指南

坑1：遷移腳本不可逆

-- ❌ 錯誤：Down遷移遺失資料
ALTER TABLE users DROP COLUMN phone;

-- ✅ 正確：保留資料的Down遷移
ALTER TABLE users ALTER COLUMN phone DROP NOT NULL;
ALTER TABLE users ALTER COLUMN phone DROP DEFAULT;

坑2：大表直接ALTER TABLE

-- ❌ 錯誤：大表直接加NOT NULL列會鎖表
ALTER TABLE users ADD COLUMN phone VARCHAR(20) NOT NULL DEFAULT '';

-- ✅ 正確：分步執行零停機遷移
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
-- 應用層回填資料
ALTER TABLE users ALTER COLUMN phone SET NOT NULL;

坑3：Dirty State未處理

# ❌ 錯誤：忽略dirty狀態繼續遷移
migrate -path db/migrations -database "$DB_URL" up

# ✅ 正確：先force修復dirty狀態
migrate -path db/migrations -database "$DB_URL" force <version>
migrate -path db/migrations -database "$DB_URL" up

坑4：遷移腳本中使用資料庫特有語法

-- ❌ 錯誤：PostgreSQL特有語法，無法遷移到MySQL
ALTER TABLE users ALTER COLUMN phone SET NOT NULL;

-- ✅ 正確：使用標準SQL或條件編譯
-- PostgreSQL: ALTER TABLE users ALTER COLUMN phone SET NOT NULL;
-- MySQL: ALTER TABLE users MODIFY COLUMN phone VARCHAR(20) NOT NULL;

坑5：遷移和程式碼部署不同步

# ❌ 錯誤：先部署程式碼再遷移
kubectl apply -f deployment.yaml
migrate -path db/migrations up

# ✅ 正確：先遷移再部署程式碼
migrate -path db/migrations up
kubectl apply -f deployment.yaml

---

報錯排查

序號	報錯資訊	原因	解決方法
1	no change	資料庫已是最新版本	正常提示，無需處理
2	dirty database	遷移執行中斷	使用force命令修復版本號
3	syntax error in migration	SQL語法錯誤	檢查遷移檔案SQL語法
4	migration locked	並發遷移執行	確保同一時間只有一個遷移程序
5	column already exists	重複執行遷移	檢查版本號是否正確
6	permission denied	資料庫使用者許可權不足	授予CREATE/ALTER許可權
7	connection refused	資料庫連線失敗	檢查DATABASE_URL和資料庫狀態
8	foreign key violation	外鍵約束阻止操作	先處理關聯資料再執行遷移
9	lock timeout	大表DDL鎖超時	使用零停機策略分步執行
10	migration file not found	遷移檔案路徑錯誤	檢查migrate -path引數

---

進階最佳化

1. 遷移測試：在CI中對每個遷移做up→down→up驗證，確保雙向可執行
2. 遷移Linter：使用sqlfluff或自訂工具檢查遷移腳本規範性
3. 多資料庫支援：透過建構標籤（build tags）區分不同資料庫的遷移檔案
4. 資料回填監控：回填大表時記錄進度，支援斷點續傳
5. 藍綠部署整合：遷移與藍綠部署配合，實現真正的零停機發佈

---

對比分析

維度	golang-migrate	Goose	Atlas	Liquibase
Go原生	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐
多資料庫	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
宣告式遷移	⭐⭐	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
版本追蹤	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Dirty修復	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
CI整合	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
學習曲線	低	低	中	高

---

總結：資料庫遷移是生產級Go專案的必備能力。golang-migrate以其簡潔的CLI、Go原生整合、多資料庫支援成為2026年的首選。核心原則：遷移先於程式碼部署、Down遷移必須可逆、大表變更分步執行、CI/CD自動驗證。

---

線上工具推薦

• JSON格式化：/zh-TW/json/format
• Hash計算：/zh-TW/encode/hash
• cURL轉程式碼：/zh-TW/dev/curl-to-code