Skip to main content

Upgrading to 3.71.0+ for Instances Using OrientDB, Nexus Repository 3.70.x, and Java 8 or 11

Nexus Repository 3.71.0 and beyond does not support an OrientDB database. To upgrade to version 3.71.0+, you will need to migrate to an H2 or PostgreSQL database.

Nexus Repository 3.71.0 and beyond also requires Java 17, so you will need to upgrade your Java version before upgrading to 3.71.0+.

Orient_370_java811.png

The sections below will walk you through the process.

Phase 1 - Migrate to H2 or PostgreSQL

In this phase, you will migrate your Nexus Repository instance to an H2 or PostgreSQL database.

Considerations Before Migrating

Review the following considerations before migrating:

  • Migration is non-destructive

    The original Orient database is not changed and may be used as a recovery point.

  • Migration is one-way

    The migrator does not support migrating back to OrientDB from H2 or PostgreSQL. Running the migrator again overwrites any data in the target database.

  • Test the migration before running in production

    We recommended performing a test migration using a backup of your production instance. Be aware that a backup instance connecting to cloud blob stores may still be connected to production data.

  • Review the difference in the search feature and cleanup policies

    Searching works differently in H2 and PostgreSQL databases. Evaluate that cleanup policies identify the correct components for cleanup.

  • Unsupported formats

    PostgreSQL and H2 do not support Bower or the community formats (e.g., APK, Composer, CPAN, Puppet). Unsupported formats are not migrated.

  • NuGet v2 client compatibility

    A subset of Nuget v2 protocol does not work the same as from Orient DB.

  • Review custom plug-ins

    Custom plugins that interact with the database, assets, or components may no longer work with the new databases. Adjust custom plug-ins to work with H2 or PostgreSQL database.

  • Migrating directly to the cloud from on-premises is not supported

    Your DevOps engineer's responsibility is to set up the underlying architecture to ensure that the migrator has access to the on-premises file system and new database before performing a database migration.

Migration Environment Prerequisite Requirements

Review the requirements below for the database migration:

  • The database migrator requires OpenJDK

    Note that OrientDB requires using Java 8 or 11.

  • Use the migrator that matches your Nexus Repository version

    Visit Downloads to get the supported version. We recommend upgrading to the latest version first when possible.

  • OrientDB migration requirements

    Your Nexus Repository instance must be on the latest 3.70.x version to migration from OrientDB.

    See OrientDB Deployments.

  • High-availability deployments require adjusting the default max connections

    Multiple nodes connecting to the same database require increasing the allowed connections to PostgreSQL.

    See Adjusting the PostgreSQL Max Connections

  • The database user must be the owner of the database

    The following example creates a user and a database owned by that user:

    CREATE USER <username> WITH PASSWORD '<password>';
CREATE DATABASE <db-name> WITH OWNER <username> ENCODING 'UTF8';
  • The migrator requires at least 16GM of RAM available
  • The migrator requires three times the disk space as your instance's database directory (minimum 10 GB)

    The $data-dir/db directory and the temp directory must have enough space for both the backup and the extracted backup to the tmp directory.

Migrating From OrientDB to PostgreSQL

The section below covers migrating your Nexus Repository instance from OrientDB to an external PostgreSQL database.

When using AWS Aurora as your database, include gssEncMode=disable as a query parameter of JDBC URL.

  1. Create a database called nexus on the PostgreSQL server. Use UTF8 as its character set to be compatible with Nexus Repository.

  2. We recommend setting the PostgreSQL autovacuum configuration to be on.

  3. In the sonatype-work/nexus3/etc/fabric/ directory (i.e., $data-dir/etc/fabric), create nexus-store.properties; below is a sample that you will need to update with the appropriate configuration.

    The user provided must be the database owner.

    username=<postgres_user>
password=<postgres_password> 
jdbcUrl=jdbc\:postgresql\://<database-host>\:<database-port>/nexus

    For versions 3.31.0 - 3.34.1, you will need the following additional properties in your nexus-store.properties file:

    name=nexus
type=jdbc

  4. Servers under heavy load may also need to configure the connection pool size for the database. Nexus Repository uses a default pool of 100, but you may increase this by appending a line like the following example to nexus-store.properties:

    advanced=maximumPoolSize\=200

  5. Add the following to $data-dir/etc/nexus.properties

    nexus.datastore.enabled=true

  6. Perform a full backup using the backup task

  7. Copy the backup to a clean working location on a different filesystem so that any extraction doesn’t impact the existing production system

  8. Shut down Nexus Repository

  9. Update and run the following command from the location containing your database backup. Use the appropriate values for host, port, username, password, and migrator utility jar file name.

    The following parameter is needed for OrientDB Java 11 deployments.

    --add-exports java.base/sun.nio.ch=ALL-UNNAMED
    java -Xmx16G -Xms16G -XX:+UseG1GC \
-XX:MaxDirectMemorySize=28672M \
-jar nexus-db-migrator-*.jar \
--migration_type=postgres \
--db_url="jdbc:postgresql://<database URL>:<port>/nexus?user=<postgres_user>&password=<postgres_password>"

    When using database names and schemas that do not match, you need to add the variable &currentSchema=<name> to the end of the line. This variable is optional as this is not expected in a standard setup.

    • <database URL>:<port> – This is the URL to your Postgres database

    • nexus – database name

    • user – database user

    • password– database user password

    • currentSchema=nexus – example database schema (optional).

    • Use 2 dashes before the full-named parameters.

    • Use the db_url parameter value with double quotes.

  10. Run the following command on the Nexus Repository database after migrating but before starting Nexus Repository. This will reclaim storage occupied by obsoleted tuples left from the migration.

    VACUUM(FULL, ANALYZE, VERBOSE);

  11. Start Nexus Repository.

    Ensure you are still on the same Nexus Repository version you were before the migration (e.g., if you were using 3.70.x, start your newly migrated instance as 3.70.x before upgrading beyond this).

    Post-migration tasks must be completed before you can upgrade your Nexus Repository version.

    If you encounter errors during the migration to PostgreSQL, it may be necessary to recreate the PostgreSQL database (or schema) before retrying the migration. This ensures a clean environment for the migration process.

Optional Parameters

  • -y, --yes:

    Parameter to skip waiting for user input and assume a "yes" response to the initial warning.

  • --content_migration=false

    Parameter to only migrate the security and config tables: users, roles, and blobstore configuration. Repository content is not migrated.

  • --shutdown_compact=false

    Parameter to disable H2 Content DB compression; this is set to true by default.

  • --healthcheck

    Parameter to run a health check on your OrientDB database. This check focuses on detecting and reporting existing corruption in component and asset classes. The migration will not occur when using this parameter.

    java -jar nexus-db-migrator-*.jar --healthcheck

    The optional healthcheck parameter has been known to cause the migration command to fail when they try to run it against the OrientDB "*.bak" files. Do not use the "--healthcheck" option with *.bak files.

Migrating From OrientDB to H2

This section covers migrating your Nexus Repository instance from OrientDB to H2.

  1. Perform a full backup using the backup task.

    We recommend copying the backup to another filesystem to avoid impacting the production system.

    The migrator uses the following backup files:

    component-<timestamp>.bak
config-<timestamp>.bak 
security-<timestamp>.bak

  2. Shut down Nexus Repository.

  3. Run the following command from the location containing your backup.

    java -Xmx16G -Xms16G -XX:+UseG1GC \ 
-XX:MaxDirectMemorySize=28672M \ 
-jar nexus-db-migrator-*.jar \ 
--migration_type=h2

  4. Copy the produced nexus.mv.db file to your $data-dir/db directory.

  5. Edit $data-dir/etc/nexus.properties file with the following line:

    nexus.datastore.enabled=true

  6. Start Nexus Repository.

    Complete the post-migration tasks before you upgrade to another Nexus Repository version.

Optional Parameters

  • -y, --yes:

    Parameter to skip waiting for user input and assume a "yes" response to the initial warning.

  • --content_migration=false

    Parameter to only migrate the security and config tables: users, roles, and blobstore configuration. Repository content is not migrated.

  • --shutdown_compact=false

    Parameter to disable H2 Content DB compression; this is set to true by default.

  • --healthcheck

    Parameter to run a health check on your OrientDB database. This check focuses on detecting and reporting existing corruption in component and asset classes. The migration will not occur when using this parameter.

    java -jar nexus-db-migrator-*.jar --healthcheck

    The optional healthcheck parameter has been known to cause the migration command to fail when they try to run it against the OrientDB "*.bak" files. Do not use the "--healthcheck" option with *.bak files.

Phase 2 - Upgrade Nexus Repository and Java

You can now upgrade your Nexus Repository instance to 3.71.0+ but will also need to upgrade your Java version to Java 17; Nexus Repository 3.71.0+ do not support Java 8 or 11. If you do not know how to change your Java version, see our documentation on how to change your Java version.

Otherwise, follow normal upgrade procedures; see our help documentation for upgrading a standalone instance.