Migrating to a New Database

Migrating to a New Database

Tip
Use Instance Migrator if you are on OrientDB and wish to migrate to a self-hosted instance (3.90.2+), or to Sonatype Cloud.

This page documents Database Migrator, the database-level migration utility for self-hosted Nexus Repository. Use Database Migrator when you need to change the database used by an existing self-hosted deployment. Database Migrator supports the following database migration scenarios:

Note
The documented workflows require you to shut down Nexus Repository during migration.

Download the latest database migrator utility to receive the latest performance improvements.

See Download the Latest Database Migrator Utility

Considerations Before Migrating

Review the following considerations before migrating:

The original Orient database is not changed and may be used as a recovery point. The migrator does not support migrating back to OrientDB from H2 or PostgreSQL. Running the migrator again overwrites any data in the target database.

Run the database migration in the same environment to avoid complications and to simplify recovery when something goes wrong. Use the same version you were using before the migration. Migrating directly to the cloud from on-premises is not supported.

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. The migration may skip artifacts from the source database when they are not found in the file reference. Consult the migration log files to valid the contents that was migrated.

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

PostgreSQL and H2 do not support Bower or the community formats (e.g., APK, Composer, CPAN, Puppet). A subset of Nuget v2 protocol does not work the same as from OrientDB. Unsupported formats are not migrated. Custom plugins that interact with the database, assets, or components may no longer work with the new databases.

Groovy scripting is not supported in later versions.

Note
Database Migrator Utility does not migrate Repository – Export assets and Repository – Import external files tasks. These tasks reference environment‑specific paths that change between instances. Recreate them in the new instance if the workflow requires Import/Export functionality.

Migration Environment Prerequisite Requirements

Review the requirements below for the database migration:

If you are using OrientDB, then you must upgrade to the latest 3.70.x version and use the database migrator that is associated with that version. See Upgrading to Nexus Repository 3.71.0 and Beyond and Nexus Repository 3.70.x Downloads with OrientDB

Post-Migration Tasks

These tasks are critical to the proper functioning of the repository after the migration process and may take a notable amount of time to complete.

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

  1. Run the following tasks manually when using these formats:

    Rebuild Helm metadata

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

    Rebuild repository browse
Rebuild repository search

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

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

  4. When migrating to H2, keep the nexus.mv.db and nexus.trace.db (if present). All other files and folders in db are legacy OrientDB data and can be removed. For PostgreSQL migrations, the entire db directory is no longer needed. Before deleting, it is strongly recommended to compress and move the db directory to a backup location.

Migrating From H2 to PostgreSQL

The section covers migrating Nexus Repository instance with an embedded H2 database to an external PostgreSQL database.

  1. Perform a backup of the H2 database using the Admin - Backup H2 Database task.

  2. Download the Database Migrator binary and copy it into the $data-dir/db directory.

See Directories for details on locating the $data-dir.

  1. A PostgreSQL server must be configured for Nexus Repository to connect to. Follow the instructions in Install Nexus Repository with PostgreSQL. Do not start Nexus Repository with the PostgreSQL configuration until after the migration is complete.

Note
If your database administrator provisions a database without a schema, you must create the schema manually and grant the required permissions to the Nexus Repository database user before proceeding:

CREATE SCHEMA <schema_name>;
GRANT USAGE, CREATE ON SCHEMA <schema_name> TO <nexus_user>;

If you use a schema name other than nexus, update the currentSchema parameter in the --db_url argument in Step 5 accordingly.

  1. Shut down Nexus Repository.

  2. Update the db_url in the following command using your PostgreSQL configuration.

    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"

This command must run in the $data-dir/db directory.

  1. Run the following command on the PostgreSQL database to reclaim storage occupied by obsoleted tuples left from the migration.

    VACUUM(FULL, ANALYZE, VERBOSE);

  2. Start Nexus Repository.

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"

Note

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

    nexus.datastore.enabled=true

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

  3. Start Nexus Repository.

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

Optional Parameters

Migrating From OrientDB to H2

Migrate Nexus Repository instance from OrientDB to H2.

  1. Perform a database backup using the Admin - Export Database for backup task. We recommend copying the backup to another filesystem to avoid impacting the production environment.

The migrator uses the following backup files:

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

  1. Shut down Nexus Repository.

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

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

See Directories for details.

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

    nexus.datastore.enabled=true

  2. Start Nexus Repository.

  3. Complete the post-migration tasks before upgrading Nexus Repository.

Optional Parameters

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
  1. 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
  1. Add the following to $data-dir/etc/nexus.properties
nexus.datastore.enabled=true

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

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

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

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