Go-Datenbankmigration in der Praxis: Zero-Downtime Schema-Versionsverwaltung mit golang-migrate

Go-Datenbankmigration: Warum Ihr Projekt eine Versionsverwaltung braucht

Führen Sie bei jeder Bereitstellung manuell SQL-Änderungen durch? Verursachen Schema-Inkonsistenzen zwischen Umgebungen Produktionsausfälle? Sind Sie unsicher, welche Änderungen rückgängig gemacht werden sollen, wenn etwas schiefgeht? Datenbankmigration ist die Kernlösung für diese Probleme. Im Jahr 2026 ist golang-migrate zum beliebtesten Migrationstool im Go-Ökosystem geworden und unterstützt über 15 Datenbanken, darunter MySQL, PostgreSQL und SQLite. In Kombination mit CI/CD ermöglicht es eine vollständige Pipeline: Migrationsskripte → Versionsverfolgung → Zero-Downtime-Änderungen → automatisches Rollback.

Dieser Artikel führt durch 5 Kernmuster und deckt die gesamte Pipeline ab: Migrationsinitialisierung → inkrementelle Änderungen → Zero-Downtime-Strategie → Rollback-Mechanismus → CI/CD-Integration.

---

Kernkonzepte

Konzept	Beschreibung
Migration	Versionierte Einheit einer Datenbankschema-Änderung
golang-migrate	Go-Datenbankmigrations-CLI und -Bibliothek
Up Migration	Ausführung von Schemaänderungen vorwärts
Down Migration	Rückgängigmachen von Schemaänderungen
Dirty State	Fehlgeschlagene Migrationsausführung, die zur Datenbank-Versionssperre führt
Zero-Downtime	Schemaänderungsstrategie ohne Dienstunterbrechung
Seed Data	Migrationsskripte für Anfangsdaten
Idempotent	Migrationsskripte, die ohne Fehler erneut ausgeführt werden können

---

Problemanalyse: 5 Herausforderungen bei der Datenbankmigration

1. Schema-Drift: Inkonsistente Datenbankstrukturen zwischen Umgebungen
2. Migrationsfehler: Große Tabellen-ALTER-TABLE-Sperren verursachen Dienstunterbrechungen
3. Rollback-Schwierigkeiten: Fehlende Down-Migrationen oder irreversible Down-Migrationen
4. Kollaborationskonflikte: Mehrere Entwickler ändern gleichzeitig das Schema
5. CI-Integration: Migrationsskripte nicht in automatisierte Tests und Bereitstellungen eingebunden

---

Schritt-für-Schritt: 5 Kernmuster der Datenbankmigration

Muster 1: golang-migrate-Installation und Projektinitialisierung

# 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;

Muster 2: Go-Code-Integration und inkrementelle Änderungen

// 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
}

Muster 3: Zero-Downtime-Migrationsstrategie

-- db/migrations/000002_add_phone_column.up.sql
-- Step 1: Add nullable column (no table lock)
ALTER TABLE users ADD COLUMN phone VARCHAR(20);

-- db/migrations/000003_phone_not_null.up.sql
-- Execute after all data backfilled
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
}

Muster 4: Rollback-Mechanismus und Sicherheitsstrategie

// 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
}

Muster 5: CI/CD-Integration und Automatisierung

# .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

---

Fallstrick-Leitfaden

Fallstrick 1: Irreversible Migrationsskripte

-- ❌ Falsch: Down-Migration verliert Daten
ALTER TABLE users DROP COLUMN phone;

-- ✅ Richtig: Down-Migration erhält Daten
ALTER TABLE users ALTER COLUMN phone DROP NOT NULL;
ALTER TABLE users ALTER COLUMN phone DROP DEFAULT;

Fallstrick 2: Direktes ALTER TABLE bei großen Tabellen

-- ❌ Falsch: Hinzufügen einer NOT NULL-Spalte sperrt große Tabellen
ALTER TABLE users ADD COLUMN phone VARCHAR(20) NOT NULL DEFAULT '';

-- ✅ Richtig: Mehrstufige Zero-Downtime-Migration
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
-- Backfill-Daten in der Anwendungsschicht
ALTER TABLE users ALTER COLUMN phone SET NOT NULL;

Fallstrick 3: Unbehandelter Dirty State

# ❌ Falsch: Dirty State ignorieren
migrate -path db/migrations -database "$DB_URL" up

# ✅ Richtig: Dirty State zuerst per Force beheben
migrate -path db/migrations -database "$DB_URL" force <version>
migrate -path db/migrations -database "$DB_URL" up

Fallstrick 4: Datenbankspezifische Syntax in Migrationen

-- ❌ Falsch: PostgreSQL-spezifische Syntax
ALTER TABLE users ALTER COLUMN phone SET NOT NULL;

-- ✅ Richtig: Standard-SQL oder bedingte Kompilierung verwenden
-- PostgreSQL: ALTER TABLE users ALTER COLUMN phone SET NOT NULL;
-- MySQL: ALTER TABLE users MODIFY COLUMN phone VARCHAR(20) NOT NULL;

Fallstrick 5: Migration und Code-Bereitstellung nicht synchron

# ❌ Falsch: Zuerst Code bereitstellen, dann migrieren
kubectl apply -f deployment.yaml
migrate -path db/migrations up

# ✅ Richtig: Zuerst migrieren, dann Code bereitstellen
migrate -path db/migrations up
kubectl apply -f deployment.yaml

---

Fehlerbehebung

#	Fehlermeldung	Ursache	Lösung
1	no change	Datenbank bereits auf neuester Version	Normal, kein Handlungsbedarf
2	dirty database	Migration unterbrochen	Force-Befehl verwenden, um Version zu korrigieren
3	syntax error in migration	SQL-Syntaxfehler	SQL-Syntax der Migrationsdatei prüfen
4	migration locked	Gleichzeitige Migrationsausführung	Sicherstellen, dass nur ein Migrationsprozess läuft
5	column already exists	Doppelte Migrationsausführung	Versionsnummer prüfen
6	permission denied	Unzureichende Datenbankbenutzerberechtigungen	CREATE/ALTER-Berechtigungen erteilen
7	connection refused	Datenbankverbindungsfehler	DATABASE_URL und Datenbankstatus prüfen
8	foreign key violation	Fremdschlüssel-Constraint blockiert Vorgang	Zuerst abhängige Daten bearbeiten
9	lock timeout	DDL-Sperr-Timeout bei großen Tabellen	Zero-Downtime-Strategie verwenden
10	migration file not found	Pfadfehler der Migrationsdatei	Parameter migrate -path prüfen

---

Erweiterte Optimierung

1. Migrationstests: Jede Migration mit up→down→up in CI verifizieren
2. Migration-Linter: sqlfluff oder benutzerdefinierte Tools zur Prüfung der Migrationsskriptstandards verwenden
3. Multi-Datenbank-Unterstützung: Build-Tags für verschiedene Datenbank-Migrationsdateien verwenden
4. Daten-Backfill-Überwachung: Fortschritt beim Backfill großer Tabellen mit Fortsetzungsunterstützung verfolgen
5. Blue-Green-Deployment-Integration: Migrationen mit Blue-Green-Deployment für echte Zero-Downtime-Releases koordinieren

---

Vergleich

Dimension	golang-migrate	Goose	Atlas	Liquibase
Go-nativ	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐
Multi-Datenbank	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Deklarative Migration	⭐⭐	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Versionsverfolgung	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Dirty-Fix	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
CI-Integration	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Lernkurve	Niedrig	Niedrig	Mittel	Hoch

---

Zusammenfassung: Datenbankmigration ist für Produktions-Go-Projekte unverzichtbar. golang-migrate ist die erste Wahl im Jahr 2026 mit seiner sauberen CLI, nativen Go-Integration und Multi-Datenbank-Unterstützung. Kernprinzipien: Migration vor Code-Bereitstellung, Down-Migrationen müssen umkehrbar sein, große Tabellenänderungen in Schritten, CI/CD-Automatisierungsprüfung.

---

Empfohlene Online-Tools

• JSON-Formatierer: /de/json/format
• Hash-Rechner: /de/encode/hash
• cURL zu Code: /de/dev/curl-to-code