Skip to main content

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

Tip

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

Release 3.70.0 upgraded Sonatype Nexus Repository's embedded H2 database from version 1.4.200 to the 2.x H2 version line. This means that Sonatype 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 in order to upgrade Nexus Repository to version 3.70.0+.

As noted in H2's own upgrade documentation, there are many changes between the 1.x and 2.x version lines, preventing a seamless upgrade to 2.x. Therefore, 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 Your H2 Database from 1.x to 2.x

Upgrading your H2 database involves generating an export of that database; should any changes continue to be made in your Nexus Repository instance after generating this export, those changes will be 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 Sonatype Nexus Repository 3.70.0+:

  1. Upgrade to Sonatype 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 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 Sonatype Nexus Repository versions beyond 3.70.0 will require Java 17.

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

Upgrading Your H2 Database and Nexus Repository Instance

After meeting all prerequisite steps in Prerequisites for Upgrading Your H2 Database from 1.x to 2.x, take the following steps to complete both your Sonatype Nexus Repository and H2 upgrades:

  1. Upgrade your Sonatype 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 Sonatype Nexus Repository instance.

  4. Sonatype 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 will need to roll back your Sonatype Nexus Repository upgrade as well. Before rolling anything back, check your $data-dir/db folder to see if it contains a nexus-<timestamp>-backup.zip file. If it does not, go back to Nexus Repository 3.69.0 and follow the same steps listed above in Prerequisites for Upgrading Your H2 Database from 1.x to 2.x and Upgrading Your H2 Database and Nexus Repository Instance.

If you do have a nexus-<timestamp>-backup.zip file, take the following steps to roll back an H2 upgrade:

  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 Sonatype Nexus Repository instance to version 3.69.0 and restart it.

  4. Follow the same steps listed above in Prerequisites for Upgrading Your H2 Database from 1.x to 2.x and Upgrading Your H2 Database and Nexus Repository Instance to redo the H2 upgrade.