fix(database): migrate H2 safely and protect backup restores by Ludy87 · Pull Request #7207 · Stirling-Tools/Stirling-PDF

Ludy87 · 2026-07-30T19:00:06Z

Description of Changes

Upgraded the runtime H2 database dependency to 2.4.240.
Added an automatic startup migration that exports legacy H2 2.3.232 databases with the bundled legacy driver and imports them into a new H2 2.4.240 database file.
Preserved the original legacy database as a fallback and kept existing files in configs/backup untouched.
Hardened database restore operations by creating and verifying a pre-restore safety backup before applying an import.
Added automatic rollback when a restore import fails.
Prevented existing server-side backup files from being copied, overwritten, or deleted when applied.
Ensured temporary uploaded SQL files are cleaned up after successful or failed imports.
Added migration, restore rollback, backup preservation, and H2 version compatibility tests.
Added an H2 compatibility lock and a Gradle verification task that runs as part of :proprietary:check, blocking CI when runtime or migration-driver H2 versions differ from the reviewed lock.
Updated JaCoCo configuration to analyse compiled classes only, preventing the embedded legacy H2 JAR from causing duplicate-class coverage-report failures.

The change was made because H2 2.4 uses an incompatible database file format compared with H2 2.3. Existing installations and historical backups must remain recoverable during the upgrade.

Checklist

General

I have read the Contribution Guidelines
I have read the Stirling-PDF Developer Guide (if applicable)
I have read the How to add new languages to Stirling-PDF (if applicable)
I have performed a self-review of my own code
My changes generate no new warnings

Documentation

I have updated relevant docs on Stirling-PDF's doc repo (if functionality has heavily changed)
I have read the section Add New Translation Tags (for new translation tags only)

Translations (if applicable)

I ran scripts/counter_translation.py

UI Changes (if applicable)

Screenshots or videos demonstrating the UI changes are attached (e.g., as comments or direct attachments in the PR)

Testing (if applicable)

I have run task check to verify linters, typechecks, and tests pass
I have tested my changes locally. Refer to the Testing Guide for more details.

Add automated migration from legacy H2 2.3.232 on-disk DBs to H2 2.4.240: new H2DatabaseMigration class exports the old DB with a bundled 2.3 driver and imports into a new 2.4 database, invoked reflectively from SPDFApplication. Build and resources updated to bundle the old H2 driver for migration; default datasource names/URLs updated to the 2.4 filename. Harden DatabaseService import flow: verify backups, create a pre-restore safety backup, run import and restore on failure (propagating IOException). Minor fixes: DatabaseController temp-file cleanup, updated tests covering migration and import rollback, updated migration test script and fixture README.

Restrict jacocoReport to the project's compiled application classes and source dirs to avoid analysing embedded migration/dependency classes that appear in SourceSetOutput. Sets classDirectories to sourceSets.main.output.classesDirs and sourceDirectories to sourceSets.main.allSource.srcDirs so coverage only covers app code (keeps the existing dependsOn(test) and report settings).

aikido-pr-checks · 2026-07-30T21:56:55Z

        printStartupLogs();
    }

+    private static void migrateLegacyH2Database() throws IOException {


Introduced reflective startup of H2 migration via Class.forName/method.invoke; prefer explicit wiring to keep startup behaviour transparent

Details

✨ AI Reasoning
The code attempts to run an optional migration class by loading it reflectively and invoking its migrateIfNeeded method. Reflection and dynamic invocation can obscure behavior from static analysis and reviewers because the class may be absent in some builds (caught ClassNotFoundException) and the invocation path is not visible in normal call graphs. This construct changes startup semantics and was added in this change set, increasing the use of reflection in startup flow which can be used to hide or dynamically alter behavior.

🔧 How do I fix it?
Ensure code is transparent and not intentionally obfuscated. Avoid hiding functionality from code review. Focus on intent and deception, not specific patterns.

_{Reply @AikidoSec feedback: [FEEDBACK] to get better review comments in the future.}
_{Reply @AikidoSec ignore: [REASON] to ignore this issue.}
_{More info}

aikido-pr-checks · 2026-07-30T21:56:55Z

+                        + database.toAbsolutePath()
+                        + ";IFEXISTS=TRUE;ACCESS_MODE_DATA=r;DB_CLOSE_ON_EXIT=FALSE;MODE=PostgreSQL";
+        ClassLoader previous = Thread.currentThread().getContextClassLoader();
+        try (URLClassLoader loader =


Uses URLClassLoader + Thread.setContextClassLoader + reflective invocation of org.h2.tools.Script.process; dynamic loading obscures runtime behavior

Details

✨ AI Reasoning
The migration class extracts a bundled legacy H2 JAR to a temp file, creates a URLClassLoader over it, sets it as the thread context class loader, and then reflectively looks up and invokes org.h2.tools.Script.process. These steps intentionally divert classloading and invocation into a dynamically-loaded JAR, making it harder to inspect via static analysis and obscuring the executed code path. This exact mechanism was added by the PR, increasing obfuscation-like patterns.

🔧 How do I fix it?
Ensure code is transparent and not intentionally obfuscated. Avoid hiding functionality from code review. Focus on intent and deception, not specific patterns.

_{Reply @AikidoSec feedback: [FEEDBACK] to get better review comments in the future.}
_{Reply @AikidoSec ignore: [REASON] to ignore this issue.}
_{More info}

stirlingbot · 2026-08-23T11:25:42Z

✅ Backend License Check Passed

All backend dependencies have valid and allowed licenses.

The backend license report has been updated successfully.

github-actions · 2026-08-23T11:34:58Z

🚀 V2 Auto-Deployment Complete!

🔗 Direct Test URL (non-SSL) http://54.175.155.236:7207

🧩 Admin portal included - try it at http://54.175.155.236:7207/portal.

This deployment will be automatically cleaned up when the PR is closed.

🔄 Auto-deployed for approved V2 contributors.

Ludy87 changed the title ~~H2 DB migration to 2.4 and safer imports~~ fix(database): migrate H2 safely and protect backup restores Jul 30, 2026

block

c3a7bd4

stirlingbot Bot added the Bugfix Pull requests that fix bugs label Jul 30, 2026

Update README.md

a377b47

Ludy87 marked this pull request as ready for review July 30, 2026 21:56

Ludy87 requested review from ConnorYoh, Frooodle and jbrunton96 as code owners July 30, 2026 21:56

dosubot Bot added the size:L This PR changes 100-499 lines ignoring generated files. label Jul 30, 2026

aikido-pr-checks Bot reviewed Jul 30, 2026

View reviewed changes

stirlingbot Bot added the has conflicts Pull request has merge conflicts with the base branch label Aug 3, 2026

Merge branch 'main' into bump_h2_2_4_240

98ce291

stirlingbot Bot removed the has conflicts Pull request has merge conflicts with the base branch label Aug 3, 2026

stirlingbot Bot added the has conflicts Pull request has merge conflicts with the base branch label Aug 12, 2026

Ludy87 marked this pull request as draft August 13, 2026 11:54

Merge branch 'main' into bump_h2_2_4_240

5819e4c

Ludy87 temporarily deployed to pr-preview August 23, 2026 11:23 — with GitHub Actions Inactive

github-actions Bot removed the has conflicts Pull request has merge conflicts with the base branch label Aug 23, 2026

github-actions Bot deleted a comment from stirlingbot Bot Aug 23, 2026

Navigation Menu

Uh oh!

fix(database): migrate H2 safely and protect backup restores - #7207

fix(database): migrate H2 safely and protect backup restores#7207
Ludy87 wants to merge 6 commits into
mainfrom
bump_h2_2_4_240

Ludy87 commented Jul 30, 2026 •

edited

Loading

Uh oh!

aikido-pr-checks Bot Jul 30, 2026

Uh oh!

aikido-pr-checks Bot Jul 30, 2026

Uh oh!

stirlingbot Bot commented Aug 23, 2026

Uh oh!

github-actions Bot commented Aug 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Ludy87 commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Changes

Checklist

General

Documentation

Translations (if applicable)

UI Changes (if applicable)

Testing (if applicable)

Uh oh!

aikido-pr-checks Bot Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

aikido-pr-checks Bot Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

stirlingbot Bot commented Aug 23, 2026

✅ Backend License Check Passed

Uh oh!

github-actions Bot commented Aug 23, 2026

🚀 V2 Auto-Deployment Complete!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Ludy87 commented Jul 30, 2026 •

edited

Loading