Migrationen: Sperre auf eigener Verbindung, Wiederanlauf nach Abbruch (#100)

GET_LOCK/RELEASE_LOCK liefen über den Pool und damit ggf. auf verschiedenen
Sitzungen; die Sperre schützte DDL nicht zuverlässig und wurde evtl. nie
freigegeben. Jetzt nutzt der gesamte Lauf eine Verbindung.

Fortschritt je Migration in schema_migrations_dirty: nach einem Abbruch
verweigern weitere Läufe die Arbeit, bis mit --resume ab der
fehlgeschlagenen Anweisung fortgesetzt wird (Prüfsumme muss gleich sein).
Tests: parallele Läufe, Sperre nach Fehler frei, Abbruch + Resume.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Claude (KI) 2026-10-06 11:15:06 +02:00
parent ce71058b4d
commit 8ee2eecde8
3 changed files with 119 additions and 22 deletions

View file

@ -2,47 +2,98 @@ import { createHash } from 'node:crypto';
import { readdirSync, readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { join, dirname } from 'node:path';
import type { PoolConnection } from 'mysql2/promise';
import '../core/config.js';
import { pool } from '../core/db.js';
const dir = join(dirname(fileURLToPath(import.meta.url)), '../../../../migrations');
const defaultDir = join(dirname(fileURLToPath(import.meta.url)), '../../../../migrations');
const sha256 = (s: string) => createHash('sha256').update(s).digest('hex');
export const splitStatements = (content: string) => content.replace(/^\s*--.*$/gm, '').split(/;\s*\n/).map((s) => s.trim()).filter(Boolean);
export async function migrate(): Promise<void> {
await pool.query('CREATE TABLE IF NOT EXISTS schema_migrations (name VARCHAR(200) PRIMARY KEY, checksum CHAR(64) NULL, applied_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3))');
await pool.query('ALTER TABLE schema_migrations ADD COLUMN IF NOT EXISTS checksum CHAR(64) NULL'); // bestehende Installationen ohne die Spalte nachziehen
// Sperre gegen gleichzeitige Migrationsläufe (z. B. zwei parallele Deploys) – sonst könnten beide dieselbe neue
// Migration anwenden oder sich beim Anlegen der Zeile in schema_migrations in die Quere kommen.
const [[lockRow]] = await pool.query('SELECT GET_LOCK(?, 10) AS got', ['kc_migrate']) as any;
if (Number(lockRow?.got) !== 1) throw new Error('Migrations-Sperre konnte nicht erlangt werden (läuft bereits eine andere Migration? Zeitüberschreitung nach 10s)');
export interface MigrateOptions {
/** Verzeichnis mit *.sql (Tests). */
dir?: string;
/** Eine abgebrochene Migration nach Prüfung ab der ersten nicht angewendeten Anweisung fortsetzen. */
resume?: boolean;
/** Wartezeit auf die Sperre in Sekunden. */
lockTimeoutSec?: number;
}
/**
* Wendet neue Migrationen an. Alles läuft über EINE Verbindung: GET_LOCK ist in MariaDB an die Sitzung gebunden –
* über den Pool könnten Sperre, DDL und RELEASE_LOCK auf verschiedenen Verbindungen landen (Sperre schützt dann nichts
* bzw. wird nie freigegeben).
*
* DDL ist in MariaDB nicht transaktional. Deshalb wird je Migration der Fortschritt (angewendete Anweisungen) in
* schema_migrations_dirty mitgeschrieben. Bricht eine Migration ab, verweigern weitere Läufe die Arbeit, bis jemand
* den Zustand geprüft hat: `pnpm migrate --resume` setzt bei der fehlgeschlagenen Anweisung fort (die davor sind
* bereits angewendet und werden nicht wiederholt). Siehe docs/betrieb-backup-restore.md, Abschnitt Migrationen.
*/
export async function migrate(opts: MigrateOptions = {}): Promise<string[]> {
const dir = opts.dir ?? defaultDir;
const done: string[] = [];
const c: PoolConnection = await pool.getConnection();
let locked = false;
try {
const rows = (await pool.query('SELECT name, checksum FROM schema_migrations') as any)[0] as { name: string; checksum: string | null }[];
await c.query('CREATE TABLE IF NOT EXISTS schema_migrations (name VARCHAR(200) PRIMARY KEY, checksum CHAR(64) NULL, applied_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3))');
await c.query('ALTER TABLE schema_migrations ADD COLUMN IF NOT EXISTS checksum CHAR(64) NULL'); // bestehende Installationen ohne die Spalte nachziehen
await c.query('CREATE TABLE IF NOT EXISTS schema_migrations_dirty (name VARCHAR(200) PRIMARY KEY, checksum CHAR(64) NOT NULL, statements_done INT NOT NULL, statements_total INT NOT NULL, error TEXT NULL, updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3))');
// Sperre gegen gleichzeitige Migrationsläufe (z. B. zwei parallele Deploys).
const [[lockRow]] = await c.query('SELECT GET_LOCK(?, ?) AS got', ['kc_migrate', opts.lockTimeoutSec ?? 10]) as any;
if (Number(lockRow?.got) !== 1) throw new Error('Migrations-Sperre konnte nicht erlangt werden (läuft bereits eine andere Migration? Zeitüberschreitung)');
locked = true;
const dirty = ((await c.query('SELECT * FROM schema_migrations_dirty') as any)[0]) as { name: string; checksum: string; statements_done: number; statements_total: number; error: string | null }[];
if (dirty.length > 0 && !opts.resume) {
const d = dirty[0]!;
throw new Error(`Migration ${d.name} ist unvollständig: ${d.statements_done} von ${d.statements_total} Anweisungen angewendet` +
(d.error ? `, Fehler: ${d.error}` : ' (Abbruch)') + '. Zustand der Datenbank prüfen, Ursache beheben, dann mit "pnpm migrate --resume" fortsetzen.');
}
const resumeAt = new Map(dirty.map((d) => [d.name, d]));
const rows = (await c.query('SELECT name, checksum FROM schema_migrations') as any)[0] as { name: string; checksum: string | null }[];
const applied = new Map(rows.map((r) => [r.name, r.checksum]));
for (const f of readdirSync(dir).filter((n) => n.endsWith('.sql')).sort()) {
const content = readFileSync(join(dir, f), 'utf8');
const sum = sha256(content);
if (applied.has(f)) {
const stored = applied.get(f);
// Bereits angewendete Migrationen dürfen nachträglich nicht mehr verändert werden (sonst driften Umgebungen
// unbemerkt auseinander, je nachdem wann sie migriert haben). Alte Zeilen ohne Prüfsumme werden einmalig nachgetragen.
if (stored == null) await pool.query('UPDATE schema_migrations SET checksum = ? WHERE name = ?', [sum, f]);
// Bereits angewendete Migrationen dürfen nachträglich nicht mehr verändert werden. Alte Zeilen ohne Prüfsumme werden einmalig nachgetragen.
if (stored == null) await c.query('UPDATE schema_migrations SET checksum = ? WHERE name = ?', [sum, f]);
else if (stored !== sum) throw new Error(`Migration ${f} wurde bereits angewendet, ihr Inhalt hat sich seitdem aber geändert (Prüfsumme weicht ab). Bitte die Datei nicht nachträglich bearbeiten, sondern eine neue Migration anlegen.`);
continue;
}
const c = await pool.getConnection();
try {
// DDL ist in MariaDB nicht transaktional; jede Migration einzeln, bei Fehler Abbruch.
const stmts = content.replace(/^\s*--.*$/gm, '').split(/;\s*\n/).map((s) => s.trim()).filter(Boolean);
for (const st of stmts) await c.query(st);
await c.query('INSERT INTO schema_migrations (name, checksum) VALUES (?, ?)', [f, sum]);
console.log('migriert:', f);
} finally { c.release(); }
const stmts = splitStatements(content);
let start = 0;
const prev = resumeAt.get(f);
if (prev) {
if (prev.checksum !== sum) throw new Error(`Migration ${f} wurde seit dem Abbruch verändert – Fortsetzen ist nicht sicher. Ursprüngliche Datei wiederherstellen oder den Zustand von Hand bereinigen.`);
start = prev.statements_done;
console.log(`setze ${f} bei Anweisung ${start + 1} von ${stmts.length} fort`);
} else {
await c.query('INSERT INTO schema_migrations_dirty (name, checksum, statements_done, statements_total) VALUES (?, ?, 0, ?)', [f, sum, stmts.length]);
}
for (let i = start; i < stmts.length; i++) {
try {
await c.query(stmts[i]!);
} catch (e) {
await c.query('UPDATE schema_migrations_dirty SET error = ? WHERE name = ?', [String((e as Error).message).slice(0, 2000), f]).catch(() => undefined);
throw new Error(`Migration ${f}, Anweisung ${i + 1} von ${stmts.length} fehlgeschlagen: ${(e as Error).message}`);
}
await c.query('UPDATE schema_migrations_dirty SET statements_done = ?, error = NULL WHERE name = ?', [i + 1, f]);
}
await c.query('INSERT INTO schema_migrations (name, checksum) VALUES (?, ?)', [f, sum]);
await c.query('DELETE FROM schema_migrations_dirty WHERE name = ?', [f]);
done.push(f);
console.log('migriert:', f);
}
return done;
} finally {
await pool.query('SELECT RELEASE_LOCK(?)', ['kc_migrate']).catch(() => undefined);
if (locked) await c.query('SELECT RELEASE_LOCK(?)', ['kc_migrate']).catch(() => undefined);
c.release();
}
}
if (import.meta.url === `file://${process.argv[1]}`) {
try { await migrate(); } catch (e) { console.error((e as Error).message); await pool.end(); process.exit(1); }
try { await migrate({ resume: process.argv.includes('--resume') }); } catch (e) { console.error((e as Error).message); await pool.end(); process.exit(1); }
await pool.end();
}

View file

@ -0,0 +1,38 @@
import { describe, expect, it } from 'vitest';
import { mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { migrate } from '../src/cli/migrate.js';
import { one, run } from '../src/core/db.js';
const dirWith = (files: Record<string, string>) => { const d = mkdtempSync(join(tmpdir(), 'kc-mig-')); for (const [n, c] of Object.entries(files)) writeFileSync(join(d, n), c); return d; };
describe('Migrationen (#100)', () => {
it('parallele Läufe: einer bekommt die Sperre, der andere bricht ab; danach ist die Sperre frei', async () => {
const dir = dirWith({ '900_slow.sql': 'CREATE TABLE IF NOT EXISTS t_mig_slow (id INT);\nSELECT SLEEP(1);\n' });
const res = await Promise.allSettled([migrate({ dir, lockTimeoutSec: 0 }), migrate({ dir, lockTimeoutSec: 0 })]);
expect(res.filter((r) => r.status === 'fulfilled')).toHaveLength(1);
const failed = res.find((r) => r.status === 'rejected') as PromiseRejectedResult;
expect(String(failed.reason.message)).toMatch(/Sperre/);
expect(Number((await one("SELECT IS_FREE_LOCK('kc_migrate') AS f"))!.f)).toBe(1);
expect(await one("SELECT name FROM schema_migrations WHERE name = '900_slow.sql'")).toBeTruthy();
});
it('Abbruch mitten in einer Migration: Fortschritt bleibt erhalten, weitere Läufe verweigern, --resume setzt fort', async () => {
const dir = dirWith({ '901_multi.sql': 'CREATE TABLE t_mig_a (id INT);\nINSERT INTO t_mig_dep (id) VALUES (1);\nCREATE TABLE t_mig_b (id INT);\n' });
await expect(migrate({ dir })).rejects.toThrow(/901_multi.sql, Anweisung 2 von 3/);
expect(Number((await one("SELECT IS_FREE_LOCK('kc_migrate') AS f"))!.f)).toBe(1); // Sperre auch nach Fehler frei
const d = await one("SELECT statements_done, error FROM schema_migrations_dirty WHERE name = '901_multi.sql'");
expect(d!.statements_done).toBe(1); expect(d!.error).toMatch(/t_mig_dep/);
await expect(migrate({ dir })).rejects.toThrow(/unvollständig: 1 von 3/); // ohne --resume keine Arbeit
await run('CREATE TABLE t_mig_dep (id INT)'); // Ursache beheben
expect(await migrate({ dir, resume: true })).toEqual(['901_multi.sql']); // CREATE TABLE t_mig_a wird NICHT wiederholt (würde sonst fehlschlagen)
expect(await one("SELECT name FROM schema_migrations_dirty WHERE name = '901_multi.sql'")).toBeUndefined();
expect(await one('SELECT COUNT(*) AS n FROM t_mig_b')).toBeTruthy();
});
it('veränderte angewendete Migration wird erkannt', async () => {
const dir = dirWith({ '900_slow.sql': 'SELECT 1;\n' });
await expect(migrate({ dir })).rejects.toThrow(/Prüfsumme weicht ab/);
});
});

View file

@ -75,3 +75,11 @@ Ein ausgefallenes Ziel lässt den Lauf als Fehler zählen (Meldung), das lokale
## Vor größeren Änderungen
Vor Migrationen oder Updates manuell sichern: `systemctl start kc-backup`. Rollback einer fehlerhaften Migration = Wiederherstellung (Abschnitt oben) in eine Wegwerf-Datenbank prüfen, dann produktiv einspielen.
## Migrationen: Sperre und abgebrochene Läufe
`pnpm migrate` hält für den ganzen Lauf eine eigene Datenbankverbindung mit der Sperre `kc_migrate`; ein zweiter, gleichzeitiger Lauf wartet höchstens 10 s und bricht dann ab. Bereits angewendete Migrationen sind per SHA-256-Prüfsumme gegen nachträgliche Änderung geschützt.
DDL ist in MariaDB nicht transaktional. Bricht eine Migration mitten drin ab, steht der Fortschritt in `schema_migrations_dirty` (angewendete Anweisungen, Fehlermeldung). Jeder weitere `pnpm migrate` verweigert dann die Arbeit mit einem Hinweis. Vorgehen:
1. Fehlermeldung lesen, Datenbankzustand prüfen (`SELECT * FROM schema_migrations_dirty`), Ursache beheben (z. B. Datenkonflikt bereinigen). Die Migrationsdatei dabei **nicht** ändern – sonst ist Fortsetzen nicht mehr sicher und wird abgelehnt.
2. `pnpm migrate --resume` setzt bei der fehlgeschlagenen Anweisung fort; die bereits angewendeten werden nicht wiederholt.
3. Lässt sich der Zustand nicht sauber herstellen: Sicherung von vor dem Deploy in eine Wegwerf-Datenbank prüfen und einspielen (siehe oben).