Skip to main content

Migrating to a New Database

This topic covers migrating the database Nexus Repository uses with the Database Migrator utility.

Download and upgrade to the latest database migrator utility which contains many improvements.

Refer to the Migrating to a New Database (Legacy Method for Pre-3.70.0) documentation when on a release before Nexus Repository 3.70.0.

Long Running Database Post-Migration Tasks

After migrating your database, Nexus Repository automatically runs the following tasks:

Rebuild repository browse
Rebuild repository search

These tasks run automatically after restarting your Nexus Repository instance after the migration. They are critical to ensure the proper functioning of the repository after the migration process and may take a significant amount of time before they are complete.

A new backup database task does not automatically run and will have to be configured.

Do not restart your instance while the post-migration tasks are running to avoid damaging your browse and search index.

Use the below states in the task log to follow along with the post-migration process:

repository.rebuild-index 
repository.search.update 
create.browse.nodes
repository.yum.rebuild.metadata
component.normalize.version
repository.metrics.blob.size.copy
file.blobstore.metrics.datastore.migration

Considerations Before Migrating

While migration is non-destructive (i.e., OrientDB still exists), the migration process is one-way: the Database Migrator can extract configuration and component metadata from OrientDB and move it to H2 or PostgreSQL, but not vice versa. Therefore, it is important that you understand the following migration considerations before migrating:

Migration is a One-Time, One-Way Process

Multiple attempts to migrate a single instance will overwrite data in the target database. Also, the Database Migrator does not support migrating back to OrientDB from H2 or PostgreSQL.

Review Unsupported Formats (Includes Community Formats)

PostgreSQL and H2 do not support Bower or many community formats (e.g., APK, Composer, CPAN, Puppet). Unsupported formats will not be migrated, and you will not be able to add new formats that your database does not support.

Adjust Custom Plug-ins

You will likely need to adjust any custom plug-ins in order for them to work on an H2 or PostgreSQL database. Review any plug-ins that interact with the database, assets, or components.

Review Search Feature Differences

There are some search differences between different Nexus Repository environments. In H2 and non-High Availability (HA) PostgreSQL environments, you will experience the following differences:

  • Searching by Conan Package Id and Conan Package or Recipe Revisions is supported in an H2 environment.

  • When searching for raw components, you must use a leading slash (i.e., "/").

If you plan to implement an HA deployment, there are more extensive differences. See Searching for Components for details.

Review and Adjust Your Cleanup Policies

There are functionality changes to the Asset Name Matcher for cleanup policies. Evaluate and adjust your cleanup policies to ensure your configured regular expressions identify the correct components for cleanup. See our cleanup policies documentation for details.

NuGet v2 Client Compatibility

The supported subset of legacy Nuget v2 protocol in H2 and PostgreSQL environments is the same as that supported by Microsoft's NuGet Gallery, nuget.org. Use cases that rely on deprecated parts of the NuGet v2 API are not supported, including many common Chocolatey use cases and some custom OData queries.

Database Migrator Does Not Support Direct On-Premises OrientDB to Cloud PostgreSQL Migration

It is your DevOps Engineer's responsibility to set up the underlying architecture to ensure that the Database Migrator has access to the on-premises file system and new database before performing a database migration.

Test Your Migration Before Doing it in Production

Perform a test migration using a test instance or backup of your production instance.

We do not recommend using instances that use S3/Azure blob stores for this test as your test instance may still point to production cloud storage locations and cause unintentional modifications.

Similarly, any file-based blob stores should be a copy of production (i.e., not accessing the same file system).

Migration Environment Prerequisite Requirements

The checklist below covers requirements for a successful database migration:

  • Your Nexus Repository instance must be on the latest Nexus Repository version.

  • When you migrate your database, you will need to stop the Nexus Repository instance, migrate the database, and then re-start the instance using the same Nexus Repository version as you were before the migration. So, if you are using 3.70.x, you will need to start your newly migrated instance using that 3.70.x version before upgrading further. Post-migration tasks must complete before you can upgrade your Nexus Repository version.

  • The database migrator must use OpenJDK.

  • If you are migrating from OrientDB, you must migrate your database while using Java 8 or 11. You can upgrade to Java 17 after you are off of OrientDB.

  • You must download and use the database migrator that matches your Nexus Repository version.

  • The database user used must be the owner of the database (check the Owner column of "\l" output in the "psql" console).

    • A command like the following could be used to create a user and a database owned by that user:

      CREATE USER <username> WITH PASSWORD '<password>';
CREATE DATABASE <db-name> WITH OWNER <username> ENCODING 'UTF8';

  • You must have at least 16GB RAM available.

  • You must have a database backup in a clean working location on a different filesystem.

    • If migrating off of OrientDB, you will run the database migrator utility from this location.

    • The utility will use the backup files (e.g., component-<timestamp>.bak, config-<timestamp>.bak, security-<timestamp>.bak) for migration.

  • There must be enough disk space in your working location for both the backup and the extracted backup.

    • The migrator utility requires three times the disk space (minimum 10 GB) as your $data-dir/db directory.

    • The migrator checks the $data-dir/db directory and a temporary directory location (java.io.tmpdir) to ensure both have at least 10 GB of space.

    • If the temporary directory does not have enough free space, you can do one of the following:

      • Add more space to the default temporary directory (java.io.tmpdir)

      • Change the temporary directory that the migration tool uses to a location where there is more space by passing a command like the following to the migration tool:

        -Djava.io.tmpdir=/path/to/new/location/example

Migrating From OrientDB to H2

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

Migrating a Docker Image to H2

To migrate a Nexus Repository Docker image, log into the Docker image and run the Database Migrator following the normal instructions below.

  1. Perform a full backup using the backup task.

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

  3. Shut down Nexus Repository.

  4. Run the following command from the clean working location containing your database backup. You may include any of the optional parameters listed in the section below when running this command.

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

  5. Copy the resultant nexus.mv.db file to your $data-dir/db directory.

  6. Edit the $data-dir/etc/nexus.properties file and add the following line:

    nexus.datastore.enabled=true

  7. Start Nexus Repository.

    When you start Nexus Repository after migrating your database, you should start it up using the same version as you were using before the migration. For example, if you were using 3.70.x, start your instance up as 3.70.x before upgrading beyond this. Post-migration tasks must complete before you upgrade to another Nexus Repository version.

Your Nexus Repository instance will now start in H2 mode with a migrated H2 database.

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

Migrating From PostgreSQL to H2

This topic covers migrating from a PostgreSQL database to an embedded H2 database.

Migrating a Nexus Repository Docker Image to H2

If you are migrating a Nexus Repository Docker image, log into the Docker image and run the Database Migrator following the normal instructions below.

  1. Perform a full backup using the backup task.

  2. Shut down Nexus Repository.

  3. Using your system console, change the directory to$data-dir/db.

  4. Run the following command from the $data-dir/db directory. Note that you can also include any of the optional parameters listed in the section below when running this command.

    java -jar nexus-db-migrator-*.jar \ 
--migration_type=postgres_to_h2 \ 
--db_url="jdbc:postgresql://<database URL>:<port>/nexus?user=postgresUser&password=secretPassword&currentSchema=nexus"

    • --db_url="jdbc:postgresql://localhost:5432/nexus?user=postgresUser&password=secretPassword&currentSchema=nexus" – This is the URL to your Postgres database

      • nexus – database name

      • user=postgresUser – database user

      • password=secretPassword – database user password

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

        Note

        • Note that you must enter 2 dashes before the migration_type parameter.

        • You must wrap the db_url parameter value with double quotes and enter two dashes before the db_url parameter.

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

    nexus.datastore.enabled=true

  6. Remove or rename the nexus-store.properties file you used for PostgreSQL so that Nexus Repository will not continue to try and boot to that properties file.

  7. Start Nexus Repository.

Your Nexus Repository instance will now start in H2 mode with a migrated H2 database.

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

Migrating From OrientDB to PostgreSQL

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

Note

The Database Migrator does not support on-premises OrientDB to cloud PostgreSQL migration. Before using the Database Migrator, you need to ensure that the migrator can reach both locations (e.g., the on-premises file system and the new database). Set up the underlying architecture to ensure that the Database Migrator has this access before proceeding.

Reminder: You must have a Pro (licensed) instance to use this feature. Attempting this on an OSS (unlicensed) instance may appear to function, but it will not succeed.

Note

If using AWS Aurora as your database, you will need to include gssEncMode=disable as a query parameter of JDBC URL.

If you are migrating a Nexus Repository Docker image, log into the Docker image and run the database migrator following the normal instructions below.

  1. In a PostgreSQL server, create a database called nexus. You may use an alternative name if desired, but this document will refer to the example provided.

    Note

    When creating your database, ensure it is set to use UTF8 as its character set in order to be compatible with Nexus Repository's character set. For more information, see the PostgreSQL documentation on setting your character set.

  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.

    Note

    The user provided must be the database owner.

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

    Note

    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 clean working location containing your database backup. Use the appropriate values for host, port, username, password, and migrator utility jar file name. You can also include any of the optional parameters from the section below when running this command.

    Note

    If you are using Java 8, omit the parameter --add-exports java.base/sun.nio.ch=ALL-UNNAMED from the command as this is not supported by Java 8 and will cause a failure.

    This parameter is only needed for OrientDB Java 11 deployments.

    java -Xmx16G -Xms16G -XX:+UseG1GC -XX:MaxDirectMemorySize=28672M \
--add-exports java.base/sun.nio.ch=ALL-UNNAMED -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=postgresUser – database user

    • password=secretPassword– 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 complete 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

Migrating From H2 to PostgreSQL

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

Reminder: You must have a Pro (licensed) instance to use this feature. Attempting this on an OSS (unlicensed) instance may appear to function, but it will not succeed.

Note

If using AWS Aurora as your database, you will need to include gssEncMode=disable as a query parameter of JDBC URL.

If you are migrating a Nexus Repository Docker image, log into the Docker image and run the Database Migrator following the normal instructions below.

  1. In a PostgreSQL server, create a database called nexus. You may use an alternative name if desired, but this document will refer to the example provided.

    Note

    When creating your database, ensure it is set to use UTF8 as its character set in order to be compatible with Nexus Repository's character set. For more information, see the PostgreSQL documentation on setting your character set.

  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.

    Note

    The user provided must be the database owner.

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

    Note

    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 using your environment's details. You can include any of the optional parameters listed in the section below when running this command.

    java -Xmx16G -Xms16G -XX:+UseG1GC -XX:MaxDirectMemorySize=28672M \ 
-jar nexus-db-migrator-*.jar \ 
--migration_type=h2_to_postgres \ 
--db_url="jdbc:postgresql://<database URL>:<port>/nexus?user=postgresUser&password=secretPassword&currentSchema=nexus"

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

    • nexus – database name

    • user=postgresUser – database user

    • password=secretPassword– 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 the database but before starting Nexus Repository. This will reclaim storage occupied by obsoleted tuples left from the migration.

    VACUUM(FULL, ANALYZE, VERBOSE);

  11. Remove or rename the nexus-store.properties file you used for H2 so that Nexus Repository will not continue to try and boot to that properties file.

  12. Start Nexus Repository.

    When you start Nexus Repository after migrating your database, you should start it up using the same version as you were using before the migration. For example, if you were using 3.70.x, start your instance up as 3.70.x before upgrading beyond this. Post-migration tasks must complete before you can upgrade your 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