Skip to main content

Migrating to a New Database

This topic covers migrating the database Nexus Repository uses with the Database Migrator utility. Download the latest database migrator utility to receive the latest performance 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

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 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.

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

    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 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 H2 to PostgreSQL

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

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.

    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.

    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. Shut down Nexus Repository

  8. 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 from the $data-dir/db directory.

    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

  9. 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);

  10. 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.

  11. 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

    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.