werkjournal/docs/implementation/migration-rollback-acceptance.md

Real migration rollback acceptance (WJ-021)

productionAcceptance runs WJ-021 after packaging, alongside the production smoke scenario. tools/test-migration-rollback uses the packaged application and its bundled H2 driver in a temporary directory. No production database or server configuration is read. Mail is trapped and push is disabled.

The fixture starts release A, closes it, inserts an identifiable work entry, and starts it again. Candidate B is a copy of the same executable with one additional Liquibase SQL changeset: create a table, insert a row, then query a deliberately missing table. The test confirms that B exits unsuccessfully and that the first two statements actually persisted in H2 before rollback.

The real Deployment.deploy() implementation stages and checks the candidate, stops A, snapshots its closed database, switches releases, handles the failed migration and restores the snapshot. Before restarting A, the fixture verifies every restored database file against the snapshot inventory. After readiness, it checks the selected executable, retained work entry, absence of the partial schema change and unchanged migration history.

Only the host-specific service adapter is replaced: subprocesses stand in for systemd, and a loopback HTTP server serves the maintenance flag. The production file-transition algorithm is unchanged. The readiness adapter checks the real application info and Vaadin initialization endpoints on an ephemeral port. A 503 is required while restored A passes readiness, followed by public access after deployment removes maintenance. Actual Hostsharing/systemd integration and recovery from provider backups remain separate acceptance requirements.

The report is build/reports/production/migration-rollback.json; isolated JVM logs are retained in the sibling migration-rollback-logs directory. The Cucumber wrapper bounds execution to four minutes and stops remaining child processes on timeout. Each individual JVM readiness and stop operation is also bounded.

Verification: the standalone real-H2 probe passed, followed by productionAcceptance -Pproduction=true -x test on 0.1.79-SNAPSHOT: both production scenarios and all ten steps passed in 55.352 seconds. The JVM test task was excluded only from this targeted run; the normal CI wrapper still requires the complete JVM and browser suites before production acceptance. The completion push increments the version to 0.1.80-SNAPSHOT. CI execution of the new scenario is pending.