Migrating to a New Database
Only available in Nexus Repository Pro. Interested in a free trial? Start here.
Migrating an installation of Nexus Repository Pro to use a new database mode has two phases: planning/evaluation and the actual migration.
There are two important considerations to keep in mind before migrating to a new database:
- 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 and ensure that your new database supports all of your formats before migrating.
- Migration is a one-time process; attempts to migrate again will overwrite data.
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:
- Decide which database mode to use: external PostgreSQL or embedded H2
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.
- Assess whether any of the feature changes affect your use of Nexus Repository
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:
- Upgrade Nexus Repository Pro to the latest release
- Provision an external PostgreSQL database (external mode only)
- 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
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 tmp location (java.io.tmpdir) to ensure both have at least 10 GB of space.
- The migrator checks the
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 /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.0java -jar <Database_Migrator_JAR>.jar --migration_type=postgres_to_h2 --db_url="jdbc:postgresql://<database URL>:<port>/nexus?user=postgresUser&password=secretPassword¤tSchema=nexus"
--db_url="jdbc:postgresql://localhost:5432/nexus?user=postgresUser&password=secretPassword¤tSchema=nexus"
– This is the URL to your Postgres databasenexus
– database nameuser=postgresUser
– database userpassword=secretPassword
– database user passwordcurrentSchema=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 thedb_url
parameter.
- Note that you must enter 2 dashes before the
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
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. In the
$data-dir/etc/fabric/
directory, createnexus-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 /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
¤tSchema=<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>¤tSchema=<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¤tSchema=nexus"
-
--db_url="jdbc:postgresql://<database URL>:<port>/nexus?user=postgresUser&password=secretPassword¤tSchema=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 thedb_url
parameter.
-
Optional Parameters
-
--content_migration=false
– Use this parameter to disable content migration (optional); this is set totrue
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.
- Note that you must enter two dashes before the
-
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. This check will focus on detecting and reporting any existing corruption in component and asset classes.NEW IN 3.36.0
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-version.jar> --healthcheck
-
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.
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 roll back a migration, 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 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.