werkjournal/docs/implementation/h2-connection-lifecycle.md

# H2-Verbindungslebenszyklus

Am 2026-10-21, rund 72 Minuten nach dem Start von 0.1.123-SNAPSHOT, schlug in Produktion jeder
Schreibvorgang fehl, während Lesen durchgehend funktionierte. Im Journal stand nur
`UI failure <id> (org.h2.jdbc.JdbcSQLNonTransientConnectionException)`, weil
`UiErrorConfiguration` bewusst keine Exception-Meldungen protokolliert. Ein Neustart des Dienstes
hat den Zustand sofort und ohne Datenverlust beendet. Plattenplatz, Hostsharing-Quota, Dateirechte,
Datenbeschädigung und die Migration des Release waren bereits ausgeschlossen.

Dieses Arbeitspaket sollte die führende Erklärung prüfen — die Datasource-URL enthielt kein
`DB_CLOSE_DELAY`, H2 schließt die Datenbank dann, sobald die letzte Verbindung geht — und sie
beheben. Geprüft ist sie; belegt ist sie **nicht**. Der folgende Abschnitt hält fest, was die
Messungen hergeben, bevor die Härtung begründet wird.

## Was gemessen wurde

Alle Messungen mit H2 2.4.240 und HikariCP 6.3.3, den Fassungen aus `gradle/libs.versions.toml`.

**Der Fehlerfall ist so nicht reproduzierbar.** Ein Hikari-Pool mit `maximumPoolSize=4`, der seine
Verbindungen vollständig zurückzieht, bringt H2 dazu, die Datei-Datenbank zu schließen — der
anschließende Schreibvorgang öffnet sie aber einfach wieder und gelingt. Das gilt sowohl beim Leeren
über `idleTimeout`/`maxLifetime` als auch bei 8000 Öffnen-und-Schließen-Durchläufen auf vier
Threads, die das Rennen zwischen schließender und öffnender Sitzung absichtlich suchen. In keinem
Durchlauf trat eine Exception auf. Die Erklärung „der Pool zieht die letzte Verbindung zurück, H2
schließt die Datenbank weg, der nächste Schreibvorgang scheitert“ trägt also in dieser Form nicht.

**Die Annahme über die SQLState-Klasse trägt ebenfalls nicht.** H2 2.4.240 vergibt für die
90xxx-Fehler den Fehlercode selbst als SQLState, nicht eine 08er-Klasse; nur
`ERROR_OPENING_DATABASE_1` (8000) hat `08000`. Die Auswahl der Exception-Klasse läuft über den
Fehlercode, nicht über den SQLState. Von den im Auftrag genannten Kandidaten erzeugen
`OBJECT_CLOSED` (90007) und `IO_EXCEPTION` (90028/90031) **keine**
`JdbcSQLNonTransientConnectionException`, sondern `JdbcSQLNonTransientException` — sie scheiden
damit aus.

**Die Ursachenkette grenzt weiter ein.** `UiErrorConfiguration` protokolliert
`causes.lastOrNull()`, also die unterste Ursache (bis zu 16 Gliedern). Protokolliert wurde die
H2-Klasse selbst; die Exception hatte demnach keine weitere Ursache. Das schließt die Kandidaten
aus, die eine Ursache mitführen:

| Auslöser | Exception-Klasse | unterste Ursache |
| --- | --- | --- |
| `DATABASE_IS_CLOSED` (90098) | `JdbcSQLNonTransientConnectionException` | keine |
| `OutOfMemoryError` → `OUT_OF_MEMORY` (90108) | `JdbcSQLNonTransientConnectionException` | `java.lang.OutOfMemoryError` |
| `IOException` → `IO_EXCEPTION_2` (90031) | `JdbcSQLNonTransientException` | `java.io.IOException` |
| `MVStoreException` (`ERROR_CLOSED`, `ERROR_WRITING_FAILED`) | `JdbcSQLNonTransientException` | `org.h2.mvstore.MVStoreException` |

Übrig bleibt als Form, die genau zur protokollierten Zeile passt, ein ursachenloses
`DATABASE_IS_CLOSED`. Der Speichermangel — naheliegend bei `-Xmx384m` — hätte als unterste Ursache
`java.lang.OutOfMemoryError` hinterlassen, ein Schreibfehler der Ablage einen `MVStoreException`
oder `IOException`. Das Symptombild zeigt also auf eine geschlossene Datenbank; der Weg dorthin
bleibt offen, denn das Leeren des Pools allein genügt nachweislich nicht. Der Widerspruch, dass
Lesen weiter funktionierte, ist mit einer geschlossenen Datenbank ebenfalls nicht erklärt und bleibt
ungeklärt. **Die Ursache ist damit nicht bewiesen.**

Der fertige Commit auf `failure-diagnostics` ergänzt die Logzeile um die Kette der
Exception-Klassen samt `sqlState` und `errorCode`. Er wird getrennt ausgeliefert und ist das
Mittel, die Ursache beim nächsten Auftreten zu belegen statt zu raten.

## Was trotzdem belegt und behoben ist

Belegt ist die Vorbedingung: **ohne `DB_CLOSE_DELAY` schließt und öffnet der laufende Prozess seine
Datenbank wiederholt unter sich selbst.** Über einen `DATABASE_EVENT_LISTENER` sind die
`closingDatabase`-Ereignisse direkt sichtbar; ein Lauf von 16 Sekunden mit leerlaufendem Pool, einem
Anlegen und einem abschließenden Schreibvorgang zählte zwei Schließungen und drei Öffnungen, ohne
dass eine Anfrage fehlschlug. Jede dieser Öffnungen liest die Ablage neu ein und findet in einem
Zustand statt, den die Anwendung nicht erwartet. Das ist für sich genommen unnötiges Risiko, auch
wenn es den Vorfall nicht erklärt. Mit `DB_CLOSE_DELAY=-1` bleibt die Datenbank über die gesamte
Prozesslaufzeit genau einmal geöffnet.

Die Härtung ist damit als Beseitigung dieser Unruhe begründet, nicht als bewiesener Fix.

## Die Wahl zwischen den beiden Wegen

Zwei Wege standen zur Wahl.

**`;DB_CLOSE_DELAY=-1` an der Standard-URL in `application.properties`** — gewählt. Der Parameter
steht sichtbar in der Konfiguration, gilt für jede Verbindung des Pools und verändert nichts an den
gespeicherten Daten. Sein Nachteil ist, dass eine Umgebungsüberschreibung von
`WERKJOURNAL_DATABASE_URL` oder `SPRING_DATASOURCE_URL` ihn ersetzen könnte. Der Lesezugriff auf
`~/.config/werkjournal/environment` in Produktion zeigt, dass dort **keine** Überschreibung der
Datasource-URL gesetzt ist: die Datei führt ausschließlich `WERKJOURNAL_GUEST_MODE`,
`WERKJOURNAL_AUTH_BOOTSTRAP_CODE` und die drei Push-Schlüssel. Die Standard-URL ist in Produktion
also tatsächlich maßgeblich. Die Deployment-Preflight schließt die verbleibende Lücke, indem sie
eine künftige Überschreibung nur noch mit demselben Parameter annimmt.

**`spring.datasource.hikari.connection-init-sql=SET DB_CLOSE_DELAY -1`** — verworfen. Der Weg wirkt
zwar unabhängig von der URL, aber `SET DB_CLOSE_DELAY` ist in H2 eine **dauerhafte Einstellung der
Datenbankdatei**: nach einem Lauf mit dieser Anweisung meldet auch eine Verbindung ohne sie
`DB_CLOSE_DELAY = -1`. Die Einstellung wandert damit unsichtbar in die Daten und gilt anschließend
auch für Werkzeuge, die die Datei kurz öffnen — etwa den Offline-Befehl `AdminRecovery`. Eine
Konfigurationszeile, die sich zurücknehmen lässt, ist einer in die Datei geschriebenen Einstellung
vorzuziehen, die das nicht tut. Hinzu kommt, dass die Anweisung bei jeder neuen Verbindung läuft,
statt einmalig Teil der Verbindungsdaten zu sein.

## Preflight und die Sicherungsgarantie

`scripts/deploy-update-remote.py` hat eine Überschreibung bisher als Zeichenkette mit
`jdbc:h2:file:./data/werkjournal` verglichen. Diese Prüfung sichert zu, dass die Datenbank im
verwalteten Sicherungspfad liegt, denn das Deployment stoppt den Dienst und kopiert das geschlossene
Datenverzeichnis in ein Rollback-Bündel. Ein Zeichenkettenvergleich hätte die neue URL abgelehnt.

`check_database_url` vergleicht jetzt den **Dateipfad** statt der Zeichenkette: der Pfad aus der URL
wird — relativ wie absolut — gegen `<Arbeitsverzeichnis>/data/werkjournal` normalisiert und muss
genau darauf fallen. Alles, was aus dem Sicherungspfad hinausführt, wird weiterhin abgelehnt, auch
ein Umweg über `..`, ein anderer Dateiname im selben Verzeichnis und jede URL, die keine
Datei-Datenbank ist (`mem:`, `tcp:`). Zusätzlich muss die Überschreibung `DB_CLOSE_DELAY=-1`
mitführen, damit die Härtung nicht stillschweigend wieder verlorengeht, und jeder weitere Parameter
wird abgelehnt.

Dass jeder weitere Parameter abgelehnt wird, schützt vor allem `DB_CLOSE_ON_EXIT`. Die Vorgabe
`TRUE` bleibt bewusst stehen: der Shutdown-Hook schließt die Datenbank beim Prozessende sauber, und
genau darauf beruht die konsistente Sicherung des gestoppten Dienstes. Auch mit
`DB_CLOSE_DELAY=-1` ist das nachgewiesen — die Datenbank wird beim Prozessende weiterhin
geschlossen; `-1` verhindert nur das Schließen im Betrieb, nicht das beim Beenden.
`DB_CLOSE_ON_EXIT=FALSE` würde das Datenverzeichnis ohne diese Zusicherung zurücklassen und wird
deshalb von der Preflight zurückgewiesen.

Nicht angefasst ist die fest eingetragene URL in `AdminRecovery`: dieser Offline-Befehl läuft in
einem eigenen, kurzlebigen Prozess ohne Pool, in dem die Datenbank ohnehin nur einmal geöffnet und
beim Beenden geschlossen wird.

## Nachweise

- `H2ConnectionLifecycleTest`: liest die Parameter der konfigurierten Standard-URL aus
  `application.properties`, baut einen Pool in der Form der Produktion und zieht dessen Verbindungen
  zurück. Ohne Härtung zählt der `DATABASE_EVENT_LISTENER` mindestens eine Schließung der Datenbank,
  mit der konfigurierten URL keine. „Mindestens“, weil Hikari beim Aufbau des Pools eine
  Probeverbindung öffnet und wieder schließt, die ihrerseits schon eine Schließung auslösen kann; die
  Aussage ist, dass überhaupt geschlossen wird, nicht wie oft es in einem Lauf geschieht. Der zweite
  Test verlangt zusätzlich ausdrücklich, dass die konfigurierte URL `DB_CLOSE_DELAY=-1` führt.
- `tests/operations/test_update.py`, `ManagedDatabaseUrlTest`: die verwaltete Datei wird relativ,
  absolut und über einen Umweg akzeptiert, solange sie offen bleibt; Pfade außerhalb des
  Sicherungsverzeichnisses, ein anderer Dateiname, `mem:` und `tcp:` werden abgelehnt; die
  verwaltete Datei ohne `DB_CLOSE_DELAY=-1` wird abgelehnt; jeder weitere Parameter —
  `DB_CLOSE_ON_EXIT=FALSE`, `CIPHER`, ein Parameter ohne Wert — wird abgelehnt.
- `tests/operations/test_update.py`,
  `test_runtime_preflight_rejects_external_database_and_inline_overrides`: derselbe Weg durch die
  vollständige Preflight über die geschützte Umgebungsdatei, einschließlich der jetzt
  angenommenen gehärteten Überschreibung.