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:
parent
ce71058b4d
commit
8ee2eecde8
3 changed files with 119 additions and 22 deletions
|
|
@ -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();
|
||||
}
|
||||
|
|
|
|||
38
apps/api/test/migrate.test.ts
Normal file
38
apps/api/test/migrate.test.ts
Normal 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/);
|
||||
});
|
||||
});
|
||||
|
|
@ -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).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue