Migrating to a New Database

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

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?

Checkpoint: Are You Ready to Migrate?

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 very important to review the following questions to ensure you are ready to migrate before doing so:

Have you reviewed Feature Availability for PostgreSQL and H2 Databases to ensure that your new database supports all of your formats and to 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 that your new database does not support.
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 backup.
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.
Are you aware that migration is a one-time process?
1. Attempts to migrate again will overwrite data in the target database.
Have you ensured your migration environment meets the Database Migrator utility's requirements?
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).

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:

Upgrade Nexus Repository Pro to the latest release
Provision an external PostgreSQL database (external mode only); ensure that it uses UTF8 encoding.
Obtain the Database Migrator utility, which you can download from here
Ensure you are using OpenJDK 8; the database migrator will not work with Oracle JDK
Perform a full backup using normal backup procedures
Shut down Nexus Repository
Run the migrator utility from $data-dir/db directory
Configure Nexus Repository to boot in the appropriate database mode
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 DB 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';
```
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

Using your system console, change directory to $data-dir/db.
If migrating from OrientDB, run the following command: (See Optional Parameters before running.)
```
java -Xmx4G -Xms4G -XX:MaxDirectMemorySize=4014M -jar nexus-db-migrator-*.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 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 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.
Edit the $data-dir/etc/nexus.properties file and add the following line:
```
nexus.datastore.enabled=true
```
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

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.

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

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.
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
```
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
```
Edit the $data-dir/etc/nexus.properties file and add the following line:
```
nexus.datastore.enabled=true
```
Using your system console, change directory to $data-dir/db.
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 nexus-db-migrator-*.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 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 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.

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_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-*.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 Store screen 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 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.enabled is 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.

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:

Shut down Nexus Repository.
Return to OrientDB mode by editing the $data-dir/etc/nexus.properties file and remove the following line:
```
nexus.datastore.enabled=true
```
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:

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.
Run the Database Migrator, specifing 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 that the Database Migrator expects that the directory specified to the --orient.folder flag contains three directories: component, config, and security.
Finally, point your Nexus Repository instance to the new database (See Configuring Nexus Repository Pro for H2 or PostgreSQL).