diff --git a/apps/api/src/cli/migrate.ts b/apps/api/src/cli/migrate.ts index 1d07980..0e0b91b 100644 --- a/apps/api/src/cli/migrate.ts +++ b/apps/api/src/cli/migrate.ts @@ -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 { - 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 { + 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(); } diff --git a/apps/api/test/migrate.test.ts b/apps/api/test/migrate.test.ts new file mode 100644 index 0000000..f90414a --- /dev/null +++ b/apps/api/test/migrate.test.ts @@ -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) => { 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/); + }); +}); diff --git a/docs/betrieb-backup-restore.md b/docs/betrieb-backup-restore.md index e9f61f2..4ffb436 100644 --- a/docs/betrieb-backup-restore.md +++ b/docs/betrieb-backup-restore.md @@ -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).