Skip to main content

Upgrading an H2 Database from 1.x to 2.x

Tip

This process is only required for Nexus Repository deployments on versions 3.69.0 and older that are already using an H2 database.

Release 3.70.0 upgraded Nexus Repository's embedded H2 database from version 1.4.200 to the 2.x H2 version line. This means that Nexus Repository versions 3.70.0 and beyond are no longer compatible with H2's version 1.x line, and upgrading your H2 database to 2.x is required to upgrade Nexus Repository to version 3.70.0+.

As noted in the H2 upgrade documentation, there are many changes between the 1.x and 2.x version lines. Sonatype created an easy way to help H2 users upgrade their H2 databases when upgrading to Nexus Repository 3.70.0 and beyond.

Prerequisites for Upgrading the H2 Database

Upgrading the H2 database involves exporting the database. Changes made after exporting are lost and not included in the exported file.

To minimize any potential for lost information during the upgrade period, complete the following prerequisite steps immediately before upgrading to Nexus Repository 3.70.0+:

  1. Upgrade to Nexus Repository version 3.69.0.

    1. Installation and Upgrades

    2. Upgrading a Standalone Instance

  2. In version 3.69.0, create and run the Admin - Export SQL database to the script task.

    • This task generates an SQL script export of your H2 database. By default, the export will be available at <data-dir>/nexus3/db and will be named nexus.<timestamp>.sql; however, you can also specify a different location when executing the task.

    • Note that this task always checks that there is at least 5GB space at the specified export location. However, before running the task for upgrading H2 to v2, you should ensure you have space equal to at least three times the size of your H2 v1 file (i.e., the nexus.mv.db file).

    • For example, if the file is 10GB, you need at least 30GB free disc space. This additional space is only needed temporarily. The exported SQL file will be a similar size to the existing database file, and the new H2 v2 file can double the H2 v1 file. After upgrading H2 to v2, Nexus Repository will delete the generated files and compact the new database file.

    • This task temporarily puts the repository into a read-only state.

  3. Check the $data-dir/db folder for the file that the task created; it will have a name like "nexus-<timestamp>.sql."

  4. If you have not already done so, upgrade your JDK version to version 17. See Upgrading Your Sonatype Nexus Repository Java Version for instructions if needed. We highly recommend this step because, as mentioned in our Java compatibility matrix, any Nexus Repository versions beyond 3.70.0 will require Java 17.

You can now continue to upgrade your Nexus Repository instance to version 3.70.0+

Upgrading Your H2 Database and Nexus Repository Instance

After meeting all prerequisite steps found here, take the following steps to complete both your Nexus Repository and H2 upgrades:

  1. Upgrade your Nexus Repository instance to 3.70.0+.

    1. Installation and Upgrades

    2. Upgrading a Standalone Instance

  2. Before starting your upgraded Nexus Repository instance, ensure the $data-dir/db folder contains the previously built nexus-<timestamp>.sql file and the H2 database file called "nexus.mv.db." Do not remove or rename the nexus.mv.db file.

  3. Start your Nexus Repository instance.

  4. Nexus Repository will now perform the H2 upgrade.

    1. As part of the upgrade process, Nexus Repository will create a backup of the H2 v1.4.200 database in the $data-dir/db folder should you need it for rollback purposes. This file will be called nexus-<timestamp>-backup.zip.

    2. Note that if multiple nexus-<timestamp>.sql files exist in the $data-dir/db folder, Nexus Repository will use the file with the most recent timestamp to create the H2 v2.2.224 database.

  5. Verify that Nexus Repository started correctly with all expected repository information.

  6. You can now delete the SQL and backup files.

Rolling Back an H2 Upgrade

Should you need to retry an H2 upgrade, you need to roll back your instance as well. Before rolling anything back, check your $data-dir/db folder to see if it contains a nexus-<timestamp>-backup.zip file. If not, go back to Nexus Repository 3.69.0.

  1. Delete the generated H2 database file called nexus.mv.db from the $data-dir/db folder.

  2. Unzip the nexus-<timestamp>-backup.zip file.

  3. Roll back your Nexus Repository instance to version 3.69.0 and restart it.

  4. Follow the same steps from Prerequisites and Upgrading H2 to redo the H2 upgrade.