Upgrading to Drillbridge 4.0

Drillbridge 4.0 requires Java 17 or newer and changes the embedded repository from H2 1.4 PageStore (.h2.db) to H2 2 MVStore (.mv.db). Existing repository data remains supported, but the database must be converted before Drillbridge 4.0 starts.

Before upgrading

  1. Stop the Drillbridge service.

  2. Back up the complete installation directory, including the database and configuration.

  3. Record the currently installed Drillbridge version and confirm that the backup can be restored.

  4. Install Java 17 or newer.

  5. Do not allow the old and new Drillbridge versions to open the same database.

The conversion tools are in the upgrade directory of the Drillbridge 4.0 distribution. They include the old and new H2 drivers and scripts for Windows and macOS/Linux.

Convert the repository

The default repository is named drillbridge.h2.db. Copy it into the new distribution’s upgrade directory and run the script while the current directory is upgrade.

Windows:

upgrade_h2_windows.bat

macOS or Linux:

chmod +x upgrade_h2_macos.sh
./upgrade_h2_macos.sh

For a custom database basename, pass the basename without its directory or extension:

./upgrade_h2_macos.sh my_repository

The current utility expects the standard embedded-repository credentials sa / drillbridge.

The script creates a timestamped backup, exports the source with H2 1.4.196, imports it with H2 2.2.220, opens and queries the result, and compares row counts for the core configuration tables. The original database is retained as .h2.db.old. An export, import, query, or row-count failure triggers automatic rollback.

Move the resulting .mv.db to the same relative location used by the old database before starting Drillbridge 4.0.

Complete and verify the upgrade

On first startup, Drillbridge converts legacy Flyway history where necessary and applies every remaining schema migration through 4.0. Known checksums published by older Drillbridge releases are handled explicitly. An unknown checksum mismatch stops startup and is not repaired automatically.

  1. Start Drillbridge 4.0 in console mode first, when practical, and confirm that startup completes without a migration error.

  2. Verify users, connections, Essbase servers, reports, mappings, variables, and deployment specifications.

  3. Run representative drill-through requests.

  4. Install or start the service only after console verification succeeds.

  5. Retain the .h2.db.old file and timestamped conversion backup until verification is complete.

Third-party Drillbridge 3.x plugins are not binary-compatible with Drillbridge 4.0. Rebuild and migrate them for Java 17 and Jakarta APIs before enabling them.

Rollback

If conversion fails, confirm that the script restored the original .h2.db and review the timestamped upgrade_log.txt.

If conversion succeeds but application verification fails:

  1. Stop Drillbridge 4.0.

  2. Move the .mv.db aside for diagnosis. Do not open it with an older Drillbridge version.

  3. Rename the retained .h2.db.old to .h2.db, or restore the timestamped database backup.

  4. Restore the prior Drillbridge application directory and configuration.

  5. Start the prior Drillbridge version and verify service.

Application binaries and repository files must be rolled back together. Database backups and logical exports can contain sensitive configuration and should be protected accordingly.