Datenbank-Migrationen

Datenbank-Migrationsmuster

Sichere, umkehrbare Datenbankschema-Änderungen für Produktionssysteme.

Wann aktivieren

• Erstellen oder Ändern von Datenbanktabellen
• Hinzufügen/Entfernen von Spalten oder Indizes
• Ausführen von Datenmigrationen (Backfill, Transformation)
• Planung von Schemaänderungen ohne Ausfallzeit
• Einrichten von Migrationstools für ein neues Projekt

Kernprinzipien

1. Jede Änderung ist eine Migration – niemals Produktionsdatenbanken manuell ändern
2. Migrationen sind in der Produktion vorwärtsgerichtet – Rollbacks erfolgen durch neue Vorwärtsmigrationen
3. Schema- und Datenmigrationen sind getrennt – niemals DDL und DML in einer Migration mischen
4. Migrationen gegen produktionsnahe Daten testen – eine Migration, die mit 100 Zeilen funktioniert, kann bei 10 Millionen blockieren
5. Migrationen sind nach der Bereitstellung unveränderlich – niemals eine Migration bearbeiten, die in der Produktion ausgeführt wurde

Sicherheitscheckliste für Migrationen

Vor dem Anwenden einer Migration:

• Migration hat sowohl UP als auch DOWN (oder ist explizit als irreversibel gekennzeichnet)
• Keine vollständigen Tabellensperren bei großen Tabellen (nebenläufige Operationen verwenden)
• Neue Spalten haben Standardwerte oder sind nullable (niemals NOT NULL ohne Standardwert hinzufügen)
• Indizes nebenläufig erstellen (nicht inline mit CREATE TABLE für bestehende Tabellen)
• Daten-Backfill ist eine separate Migration von der Schemaänderung
• Gegen eine Kopie der Produktionsdaten getestet
• Rollback-Plan dokumentiert

PostgreSQL-Muster

Sichere Spalten hinzufügen

-- GUT: Nullable-Spalte, keine Sperre
ALTER TABLE users ADD COLUMN avatar_url TEXT;

-- GUT: Spalte mit Standardwert (Postgres 11+ ist sofort, kein Neuschreiben)
ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true;

-- SCHLECHT: NOT NULL ohne Standardwert bei bestehender Tabelle (erfordert vollständiges Neuschreiben)
ALTER TABLE users ADD COLUMN role TEXT NOT NULL;
-- Dies sperrt die Tabelle und schreibt jede Zeile neu

Hinzufügen eines Index ohne Ausfallzeit

-- SCHLECHT: Blockiert Schreibvorgänge bei großen Tabellen
CREATE INDEX idx_users_email ON users (email);

-- GUT: Nicht blockierend, erlaubt nebenläufige Schreibvorgänge
CREATE INDEX CONCURRENTLY idx_users_email ON users (email);

-- Hinweis: CONCURRENTLY kann nicht innerhalb eines Transaktionsblocks ausgeführt werden
-- Die meisten Migrationstools benötigen dafür eine spezielle Behandlung

Umbenennen einer Spalte (Ausfallzeit-frei)

Niemals direkt in der Produktion umbenennen. Verwenden Sie das Expand-Contract-Muster:

-- Schritt 1: Neue Spalte hinzufügen (Migration 001)
ALTER TABLE users ADD COLUMN display_name TEXT;

-- Schritt 2: Daten backfillen (Migration 002, Datenmigration)
UPDATE users SET display_name = username WHERE display_name IS NULL;

-- Schritt 3: Anwendungscode aktualisieren, um beide Spalten zu lesen/schreiben
-- Anwendungsänderungen bereitstellen

-- Schritt 4: Schreiben in alte Spalte beenden, löschen (Migration 003)
ALTER TABLE users DROP COLUMN username;

Sicheres Entfernen einer Spalte

-- Schritt 1: Alle Anwendungsverweise auf die Spalte entfernen
-- Schritt 2: Anwendung ohne den Spaltenverweis bereitstellen
-- Schritt 3: Spalte in der nächsten Migration löschen
ALTER TABLE orders DROP COLUMN legacy_status;

-- Für Django: SeparateDatabaseAndState verwenden, um die Spalte aus dem Modell zu entfernen
-- ohne DROP COLUMN zu generieren (dann in der nächsten Migration löschen)

Große Datenmigrationen

-- SCHLECHT: Aktualisiert alle Zeilen in einer Transaktion (sperrt Tabelle)
UPDATE users SET normalized_email = LOWER(email);

-- GUT: Batch-Update mit Fortschritt
DO $$
DECLARE
  batch_size INT := 10000;
  rows_updated INT;
BEGIN
  LOOP
    UPDATE users
    SET normalized_email = LOWER(email)
    WHERE id IN (
      SELECT id FROM users
      WHERE normalized_email IS NULL
      LIMIT batch_size
      FOR UPDATE SKIP LOCKED
    );
    GET DIAGNOSTICS rows_updated = ROW_COUNT;
    RAISE NOTICE 'Updated % rows', rows_updated;
    EXIT WHEN rows_updated = 0;
    COMMIT;
  END LOOP;
END $$;

Prisma (TypeScript/Node.js)

Arbeitsablauf

# Migration aus Schemaänderungen erstellen
npx prisma migrate dev --name add_user_avatar

# Ausstehende Migrationen in der Produktion anwenden
npx prisma migrate deploy

# Datenbank zurücksetzen (nur Entwicklung)
npx prisma migrate reset

# Client nach Schemaänderungen generieren
npx prisma generate

Schema-Beispiel

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  avatarUrl String?  @map("avatar_url")
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")
  orders    Order[]

  @@map("users")
  @@index([email])
}

Benutzerdefinierte SQL-Migration

Für Operationen, die Prisma nicht ausdrücken kann (nebenläufige Indizes, Daten-Backfills):

# Leere Migration erstellen, dann SQL manuell bearbeiten
npx prisma migrate dev --create-only --name add_email_index

-- migrations/20240115_add_email_index/migration.sql
-- Prisma kann CONCURRENTLY nicht generieren, also schreiben wir es manuell
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email ON users (email);

Drizzle (TypeScript/Node.js)

Arbeitsablauf

# Migration aus Schemaänderungen generieren
npx drizzle-kit generate

# Migrationen anwenden
npx drizzle-kit migrate

# Schema direkt pushen (nur Entwicklung, keine Migrationsdatei)
npx drizzle-kit push

Schema-Beispiel

import { pgTable, text, timestamp, uuid, boolean } from "drizzle-orm/pg-core";

export const users = pgTable("users", {
  id: uuid("id").primaryKey().defaultRandom(),
  email: text("email").notNull().unique(),
  name: text("name"),
  isActive: boolean("is_active").notNull().default(true),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

Kysely (TypeScript/Node.js)

Arbeitsablauf (kysely-ctl)

# Konfigurationsdatei initialisieren (kysely.config.ts)
kysely init

# Neue Migrationsdatei erstellen
kysely migrate make add_user_avatar

# Alle ausstehenden Migrationen anwenden
kysely migrate latest

# Letzte Migration rückgängig machen
kysely migrate down

# Migrationsstatus anzeigen
kysely migrate list

Migrationsdatei

// migrations/2024_01_15_001_create_user_profile.ts
import { type Kysely, sql } from 'kysely'

// WICHTIG: Immer Kysely<any> verwenden, nicht die typisierte DB-Schnittstelle.
// Migrationen sind zum Zeitpunkt der Entstehung eingefroren und dürfen nicht
// von aktuellen Schematypen abhängen.
export async function up(db: Kysely<any>): Promise<void> {
  await db.schema
    .createTable('user_profile')
    .addColumn('id', 'serial', (col) => col.primaryKey())
    .addColumn('email', 'varchar(255)', (col) => col.notNull().unique())
    .addColumn('avatar_url', 'text')
    .addColumn('created_at', 'timestamp', (col) =>
      col.defaultTo(sql`now()`).notNull()
    )
    .execute()

  await db.schema
    .createIndex('idx_user_profile_avatar')
    .on('user_profile')
    .column('avatar_url')
    .execute()
}

export async function down(db: Kysely<any>): Promise<void> {
  await db.schema.dropTable('user_profile').execute()
}

Programmatischer Migrator

import { Migrator, FileMigrationProvider } from 'kysely'
import { promises as fs } from 'fs'
import * as path from 'path'
// Nur ESM — CJS kann __dirname direkt verwenden
import { fileURLToPath } from 'url'
const migrationFolder = path.join(
  path.dirname(fileURLToPath(import.meta.url)),
  './migrations',
)

// `db` ist Ihre Kysely<any>-Datenbankinstanz
const migrator = new Migrator({
  db,
  provider: new FileMigrationProvider({
    fs,
    path,
    migrationFolder,
  }),
  // WARNUNG: Nur in der Entwicklung aktivieren. Deaktiviert die Zeitstempel-Sortierung
  // – Validierung, die zu Schema-Drift zwischen Umgebungen führen kann.
  // allowUnorderedMigrations: true,
})

const { error, results } = await migrator.migrateToLatest()

results?.forEach((it) => {
  if (it.status === 'Success') {
    console.log(`migration "${it.migrationName}" executed successfully`)
  } else if (it.status === 'Error') {
    console.error(`failed to execute migration "${it.migrationName}"`)
  }
})

if (error) {
  console.error('migration failed', error)
  process.exit(1)
}

Django (Python)

Arbeitsablauf

# Migration aus Modelländerungen generieren
python manage.py makemigrations

# Migrationen anwenden
python manage.py migrate

# Migrationsstatus anzeigen
python manage.py showmigrations

# Leere Migration für benutzerdefiniertes SQL generieren
python manage.py makemigrations --empty app_name -n description

Datenmigration

from django.db import migrations

def backfill_display_names(apps, schema_editor):
    User = apps.get_model("accounts", "User")
    batch_size = 5000
    users = User.objects.filter(display_name="")
    while users.exists():
        batch = list(users[:batch_size])
        for user in batch:
            user.display_name = user.username
        User.objects.bulk_update(batch, ["display_name"], batch_size=batch_size)

def reverse_backfill(apps, schema_editor):
    pass  # Datenmigration, kein Reverse nötig

class Migration(migrations.Migration):
    dependencies = [("accounts", "0015_add_display_name")]

    operations = [
        migrations.RunPython(backfill_display_names, reverse_backfill),
    ]

SeparateDatabaseAndState

Eine Spalte aus dem Django-Modell entfernen, ohne sie sofort aus der Datenbank zu löschen:

class Migration(migrations.Migration):
    operations = [
        migrations.SeparateDatabaseAndState(
            state_operations=[
                migrations.RemoveField(model_name="user", name="legacy_field"),
            ],
            database_operations=[],  # Die DB noch nicht anfassen
        ),
    ]

golang-migrate (Go)

Arbeitsablauf

# Migrationspaar erstellen
migrate create -ext sql -dir migrations -seq add_user_avatar

# Alle ausstehenden Migrationen anwenden
migrate -path migrations -database "$DATABASE_URL" up

# Letzte Migration rückgängig machen
migrate -path migrations -database "$DATABASE_URL" down 1

# Version erzwingen (fehlerhaften Zustand beheben)
migrate -path migrations -database "$DATABASE_URL" force VERSION

Migrationsdateien

-- migrations/000003_add_user_avatar.up.sql
ALTER TABLE users ADD COLUMN avatar_url TEXT;
CREATE INDEX CONCURRENTLY idx_users_avatar ON users (avatar_url) WHERE avatar_url IS NOT NULL;

-- migrations/000003_add_user_avatar.down.sql
DROP INDEX IF EXISTS idx_users_avatar;
ALTER TABLE users DROP COLUMN IF EXISTS avatar_url;

Ausfallzeit-freie Migrationsstrategie

Für kritische Produktionsänderungen folgen Sie dem Expand-Contract-Muster:

Phase 1: EXPAND
  - Neue Spalte/Tabelle hinzufügen (nullable oder mit Standardwert)
  - Bereitstellen: App schreibt in BEIDE alt und neu
  - Vorhandene Daten backfillen

Phase 2: MIGRATE
  - Bereitstellen: App liest aus NEU, schreibt in BEIDE
  - Datenkonsistenz prüfen

Phase 3: CONTRACT
  - Bereitstellen: App verwendet nur NEU
  - Alte Spalte/Tabelle in separater Migration löschen

Zeitplanbeispiel

Tag 1: Migration fügt neue_Status-Spalte hinzu (nullable)
Tag 1: Bereitstellung App v2 – schreibt in status und neue_status
Tag 2: Backfill-Migration für vorhandene Zeilen ausführen
Tag 3: Bereitstellung App v3 – liest nur aus neue_status
Tag 7: Migration löscht alte status-Spalte

Anti-Patterns

Anti-Pattern	Warum es fehlschlägt	Besserer Ansatz
Manuelles SQL in der Produktion	Keine Audit-Trail, nicht wiederholbar	Immer Migrationsdateien verwenden
Bereitgestellte Migrationen bearbeiten	Verursacht Drift zwischen Umgebungen	Stattdessen neue Migration erstellen
NOT NULL ohne Standardwert	Sperrt Tabelle, schreibt alle Zeilen neu	Nullable hinzufügen, backfillen, dann Einschränkung hinzufügen
Inline-Index bei großer Tabelle	Blockiert Schreibvorgänge während der Erstellung	CREATE INDEX CONCURRENTLY
Schema + Daten in einer Migration	Schwer rückgängig zu machen, lange Transaktionen	Separate Migrationen
Spalte vor dem Entfernen des Codes löschen	Anwendungsfehler durch fehlende Spalte	Zuerst Code entfernen, Spalte im nächsten Deployment löschen