Migrating an installation of Nexus Repository Pro to use a new database mode has two phases: planning/evaluation and the actual migration.

Migration Overview

Migration is In Place

The migrator utility takes OrientDB content and moves it to either an H2 database that it creates itself or a PostgreSQL database that you have prepared.

Migration is Offline

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

Migration is Rapid

Migration takes less than an hour for even the largest customer databases. This is because the component binaries are unaffected; they are not moved or modified during migration. The migration process only affects the content of OrientDB:

• Configuration (repositories, privileges, capabilities, etc.)
• Component metadata (lists of components in each repository)

Planning Your Migration

In planning your migration to a new database, we recommend the following:

1. Decide which database mode to use: external PostgreSQL or embedded H2

2. Determine if you require any formats that are not yet compatible with the new database architecture

   As mentioned above, unsupported formats will not be migrated; you will not be able to add new formats that your new database does not support. Review Feature Availability for PostgreSQL and H2 Databases for a full list of supported and incompatible formats.

3. Assess whether any of the feature changes affect your use of Nexus Repository

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

   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. Similarly, any file-based blob stores should be a copy of production (i.e., not accessing the same file system).

Performing the Migration

To carry out the actual migration, 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 here
4. Ensure you are using OpenJDK 8; 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

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 migrator utility requires OpenJDK8.
• The migrator utility requires access to the $data-dir/db directory. 
• 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 to H2

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

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

   java -Xmx4G -Xms4G -XX:MaxDirectMemorySize=4014M -jar /path/to/<migrator_utility>.jar --migration_type=h2

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

   NEW IN 3.35.0

   java -jar <Database_Migrator_JAR>.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 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

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.

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

   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

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.properties file and add the following line:

   nexus.datastore.enabled=true

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

6. If 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 -Xmx4G -Xms4G -XX:MaxDirectMemorySize=4014M \
   -jar /path/to/<migrator_utility>.jar \
   --migration_type=postgres \
   --db_url="jdbc:postgresql://<database URL>:<port>/nexus?user=<postgres_user>&password=<postgres_password>"

   If you use database names and schemas that do not match, you will need to add &currentSchema=<name> to the end of the line. See the following example:
   

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

   This is not expected to be a standard setup, so the variables are optional .

   
   If migrating from H2 database, use the following command instead: (See Optional Parameters before running.)

   java -Xmx4G -Xms4G -XX:MaxDirectMemorySize=4014M -jar <Database_Migrator_JAR>.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 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 NEW IN 3.41.0 - 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. 

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_folder NEW 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-<version>.jar --migration_type=postgres --db_url='jdbc:postgresql://<databaseURL> --content_migration=true --migrate_dev=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-<version>.jar --migration_type=postgres --db_url='jdbc:postgresql://<databaseURL>' --content_migration=true --migrate_dev=true --migration_folder=<absolute/path/to/folder/of/exported/JSONs>

Rolling Back a Migration

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 rollback point until you delete it. 

If it is necessary to roll back a migration, take the following steps:

1. Shut down Nexus Repository.

2. Return to OrientDB mode by editing 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 rollback 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. Unzip the backup file into a location, and ensure that the Database Migrator can see both locations (i.e., where you unzipped the backup file and the new database location). Run the Database Migrator on the .bak files to migrate the data to the second database. Finally, point your Nexus Repository instance to the new database.