Skip to main content

Migrating to a New Database

Note

Only available in Sonatype Nexus Repository Pro. Interested in a free trial? Start here.

Note

We highly recommend that you have your Nexus Repository 3 instance use an external PostgreSQL database. See our documentation on configuring Nexus Repository Pro for an external PostgreSQL database or on migrating an existing Nexus Repository 3 instance to a PostgreSQL database.

Are You Ready to Migrate?

Warning

While migration is non-destructive (i.e., OrientDB still exists, and you can manually revert back to OrientDB), 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 to review the following questions:

  1. Have you reviewed Feature Availability for PostgreSQL and H2 Databases to ensure your new database supports all your formats and see if any feature changes impact your Nexus Repository use?

    1. Unsupported formats will not be migrated.

    2. You will not be able to add new formats your new database does not support.

    3. There are functionality changes to the Asset Name Matcher for Cleanup Policies; you should take steps to ensure your configured regular expressions will not identify more items than desired after migration. See the Feature Changes section of the Feature Availability for PostgreSQL and H2 Databases documentation for an example.

    4. Note

      Notable Compatibility Change for H2 or PostgreSQL Database Deployments

      In Sonatype Nexus Repository release 3.43.0, we added compatibility with official NuGet v2 clients. The supported subset of the legacy NuGet v2 protocol is the same as that supported by Microsoft's NuGet Gallery, nuget.org. Use cases that rely on the deprecated parts of the v2 API are not supported, including many common Chocolatey use cases and some custom OData queries.

  2. Have you backed up your blob storage?

    1. Once you start your newly migrated Nexus Repository instance, database and blob storage contents will diverge.

    2. If you end up needing to revert to OrientDB, it will require restoring the blob store(s) from abackup.

  3. If migrating from on-premises OrientDB to cloud PostgreSQL, have you ensured that the Database Migrator can see both the on-premises file system and new database?

    1. The Database Migrator does not directly support on-premises OrientDB to cloud PostgreSQL migration.

    2. It is your DevOps Engineer's responsibility to set up the underlying architecture to ensure that the Database Migrator has this access before proceeding.

  4. Are you aware that migration is a one-time process?

    1. Attempts to migrate again will overwrite data in the target database.

  5. Have you ensured your migration environment meets the Database Migrator utility's requirements?

  6. Have you performed a test migration using a test instance or backup of your production instance?

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

    2. If testing this process first, we do not recommend using instances which use S3/Azure blob stores; your test instance may still point to production cloud storage locations and cause unintentional modification.

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

  7. Were you previously using Repository Replication (Legacy)? If so, delete the old replication connection before migrating in order to avoid a known issue that can prevent startup. This older replication feature is in extended maintenance and will be sunset at the end of 2023. Consider using the newer Content Replication feature after migrating to PostgreSQL.

Migration Overview

Migration converts an existing offline Nexus Repository instance to a new database mode. (This is different from the 2-to-3 upgrade wizard, which moves content between two instances of Nexus Repository running in parallel.)

During migration, component binaries are unaffected; they are not moved or modified during migration. The migration process only affects OrientDB's content (configuration and component metadata).

To carry out the actual migration, you will complete the following steps:

  1. Upgrade Nexus Repository Pro to the latest release

  2. Provision an external PostgreSQL database (external mode only); ensure that it uses UTF8 encoding

  3. Obtain the Database Migrator utility, which you can download from our Downloads page

  4. Ensure you are using OpenJDK 8 or 11

    1. Versions up to and including the 3.66.0 migrator utility require OpenJDK 8

    2. Versions 3.67.0+ can use OpenJDK 8 or 11

    3. The database migrator will not work with Oracle JDK

  5. Perform a full backup using normal backup procedures

  6. Shut down Nexus Repository

  7. Run the migrator utility from $data-dir/db directory

  8. Configure Nexus Repository to boot in the appropriate database mode

  9. Restart Nexus Repository

These steps are explained in detail below.

Migration Environment Requirements

You must meet the following migrator utility requirements in order to have a successful migration:

  • You should be on the latest 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';

  • Versions up to and including the 3.66.0 migrator utility require OpenJDK 8. Versions 3.67.0+ can use OpenJDK 8 or 11.

  • The migrator utility requires access to the $data-dir/dbdirectory.

  • 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

Controlling Database Migrator Logging

By default, the database migrator logs processing of individual components, assets, and content repository records at a TRACE level, which means they will not typically appear in logs.

Items that are skipped or encounter an error during processing will still appear in the logs.

You can modify logging levels using one of the following methods:

  • Create an application.properties file in the folder from which you are running the database migrator. Add a line like the following:

    logging.level.com.sonatype=TRACE

  • Pass an argument to the database migrator using a command like the following:

    --logging.level.com.sonatype=TRACE

Migrating to H2

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

  2. If migrating from OrientDB,run the following command: (See Optional Parameters before running.)

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

    If migrating from PostgreSQL, use the following command instead:(SeeOptional Parameters before running.)

    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.

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

    nexus.datastore.enabled=true

  4. If you are migrating to H2 from PostgreSQL, you must 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.

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

Migrating to PostgreSQL

Note

The Database Migrator does not directly support on-premises OrientDB to cloud PostgreSQL migration. Before using the Database Migrator, you need to ensure that it can see both locations (e.g., the on-premises file system and new database). It is your DevOps Engineer's responsibility to 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 fully succeed.

Note

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

  1. In a PostgreSQL server, create a database callednexus. 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. In the $data-dir/etc/fabric/directory,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. See the Migration Environment Requirements section for details on how to create a user and a database owned by that user.

    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

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

  4. Edit the $data-dir/etc/nexus.propertiesfile and add the following line:

    nexus.datastore.enabled=true

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

  6. When migrating from OrientDB, update and run the following command with the appropriate values for host, port, username, password, and migrator utility jar file name

    (See Optional Parameters before running.)

    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.

    --db_url="jdbc:postgresql://<database URL>:<port>/content?user=<postgres_user>&password=<postgres_password>&currentSchema=<name>"

    When migrating from H2 database, use the following command instead

    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"

    • --db_url="jdbc:postgresql://<database URL>:<port>/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.

Optional Parameters

    • -y or --yes

      - Use this optional parameter to skip waiting for user input and assume a "yes" response to the prompt "Please ensure any Nexus Repository instance has been gracefully shut down before proceeding. Do you want to continue?"

    • --content_migration=false – Use this parameter to disable content migration (optional); this is set to true by default. This parameter disables repository migration so that only data from security and config tables (e.g., users, roles, blobstore configuration, etc.) is migrated.

      • Note that you must enter two dashes before the content_migration parameter.

    • --shutdown_compact=false – Use this parameter to enable or disable H2 Content DB compression (optional); this is set to true by default.

    • --healthcheck – Use this parameter before migrating from OrientDB to run a health check on your OrientDB database (optional). This check will focus on detecting and reporting any existing corruption in component and asset classes.

Note

No migration will occur when you use the --healthcheck parameter; using this parameter will only return a report on your OrientDB database's health. The command to run your health check should look like the following:

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

The Database Migrator exports the OrientDB database to JSON files during the migration process and then deletes these files. You can use the following optional parameters to reuse these JSON files if the import to the target database finishes unexpectedly:

    • --save_migration_files NEW IN 3.41.0 - Use this parameter if you would prefer to not delete exported Orient JSON files (optional). You can use these files again without additional export.

    • --migration_folderNEW IN 3.41.0 - Use this parameter to identify the absolute path to the folder where previously exported Orient JSON files are stored (optional). This allows you to use these files again without additional export.

The following examples illustrate how to use the save_migration_files and migration_folder parameters and how to reuse the JSON files:

Example 1 - Initial Migration Attempt

The following example attempts migration. OrientDB is exported to JSON files that will not be deleted.

java -jar nexus-db-migrator-*.jar \ 
--migration_type=postgres \ 
--db_url='jdbc:postgresql://<databaseURL>' \ 
--content_migration=true \ 
--save_migration_files

Example 2 - Reuse Exported JSON Files

The following example attempts to import data to the target database from the existing JSON files created during a previous migration attempt. There is no export from OrientDB to JSON files.

java -jar nexus-db-migrator-*.jar \ 
--migration_type=postgres \ 
--db_url='jdbc:postgresql://<databaseURL>' \ 
--content_migration=true \ 
--migration_folder=<absolute/path/to/folder/of/exported/JSONs>

Determining Current Database

After migrating, you can confirm you are using the correct database by navigating to the Data Storescreen at Administration → Repository → Data Store. Here you will see the JDBC URL for your current database. See the Data Store topic for more information.

Note

Note that the Data Store screen only appears for those with a valid Nexus Repository Pro license who are using either an H2 or PostgreSQL database; it will not appear for OSS deployments or any deployment using OrientDB.

If you are in an administrator account and do not see the Data Store option, you are either using an OSS license or using OrientDB. If this is not what you were expecting, first confirm that you are using a valid Pro license.

If you are certain that you are using Nexus Repository Pro or if you are using OSS and just want to confirm your database, you can see if you are using OrientDB by looking at the System Information screen under Support → System Information; find the nexus-properties section, and check to see if nexus.orient.enabledis set to true. If it is, then you are using OrientDB.

Reverting Back to OrientDB

The migration process is one-way: the migrator utility can extract configuration and component metadata from OrientDB and move it to H2 or PostgreSQL, but not vice versa. However, migration is non-destructive, and the OrientDB still exists as a restoration point until you delete it.

Note

Once you start a Nexus Repository instance, database and blob storage contents will diverge. After this, reverting to Orient will require restoring the blobstore(s) from backup.

If it is necessary to revert back to OrientDB, take the following steps:

  1. Shut down Nexus Repository.

  2. Return to OrientDB mode byediting the $data-dir/etc/nexus.properties file and remove the following line:

    nexus.datastore.enabled=true

  3. Restart Nexus Repository.

This will bring Nexus Repository configuration and component metadata back to the point in time when the migration first took place. We recommend running the blob store reconciliation task after reverting to reconcile any changes to the blob store with the database.

This doesn't undo any additions or deletions to binaries that you may have made since the migration.

Restoring a Pre-Migration Backup

If you need to restore a particular backup from before migration to PostgreSQL, you would need to set up a new PostgreSQL instance and then complete the following steps:

  1. Extract the backup (.bak) files into a directory; ensure the Database Migrator can see both the location to which you've extracted these files as well as the new database.

  2. Run the Database Migrator, specifying the directory containing the extracted backup database directories.

    java -jar nexus-db-migrator-*.jar \ 
--migration_type=postgres \
--db_url="jdbc:postgresql://<database URL>:<port>/nexus?user=<postgres_user>&password=<postgres_password>" \
--orient.folder=<absolute/path/to/folder/of/extracted/files>

    Note

    Note that the Database Migrator expects that the directory specified to the --orient.folder flag contains three directories: component, config, and security.

  3. Finally, point your Nexus Repository instance to the new database (See Configuring Nexus Repository Pro for H2 or PostgreSQL).