Skip to main content

Migrating to a New Database

This topic covers migrating from OrientDB to H2 or PostgreSQL and between H2 and PostgreSQL using the Database Migrator utility. We highly recommend using 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.

In release 3.70.0, Sonatype changed the Database Migrator; however, we recognize that some customers may be using an older version of Sonatype Nexus Repository and, thus, an older Database Migrator. If you are using a Database Migrator that is older than version 3.70.0, refer to Migrating to a New Database (Legacy Method for Pre-3.70.0).

Are You Ready to Migrate?

The checklist below covers information you should review before migrating your Nexus Repository instance to a new database.

Warning

While migration is non-destructive, 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 a backup.

  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 from OrientDB to H2 or PostgreSQL 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).

Migration Environment Requirements

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

  • You should be on the latest Nexus Repository version.

  • You will need to download and use the latest Database Migrator utility; its version should match your 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';

  • Ensure you have at least 16GB RAM available.

  • Ensure you have a database backup in a clean working location on a different filesystem. When migrating off of OrientDB, you will run the database migrator utility from this location as the utility uses the backup files (e.g., component-<timestamp>.bak, config-<timestamp>.bak, security-<timestamp>.bak) for migration.

  • Ensure that there is enough disk space in your working location for both the backup and the extracted backup.

  • 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 From OrientDB to H2

  1. Perform a full backup using normal backup procedures.

  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. Run the following command from the clean working location containing your database backup. You may include any of the optional parameters listed in the section below when running this command.

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

  5. Copy the resultant nexus.mv.db file to your $data-dir/db directory.

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

    nexus.datastore.enabled=true

  7. Start Nexus Repository.

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

Optional Parameters

  • -y, --yes:

    Parameter to skip waiting for user input and assume a "yes" response to the initial warning.

  • --content_migration=false

    Parameter to only migrate the security and config tables: users, roles, and blobstore configuration. Repository content is not migrated.

  • --shutdown_compact=false

    Parameter to disable H2 Content DB compression; this is set to true by default.

  • --healthcheck

    Parameter to run a health check on your OrientDB database. This check focuses on detecting and reporting existing corruption in component and asset classes. The migration will not occur when using this parameter.

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

Migrating From PostgreSQL to H2

  1. Perform a full backup using normal backup procedures.

  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"

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

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

    nexus.datastore.enabled=true

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

  7. Start Nexus Repository.

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

Optional Parameters

  • -y, --yes:

    Parameter to skip waiting for user input and assume a "yes" response to the initial warning.

  • --content_migration=false

    Parameter to only migrate the security and config tables: users, roles, and blobstore configuration. Repository content is not migrated.

  • --shutdown_compact=false

    Parameter to disable H2 Content DB compression; this is set to true by default.

  • --healthcheck

    Parameter to run a health check on your OrientDB database. This check focuses on detecting and reporting existing corruption in component and asset classes. The migration will not occur when using this parameter.

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

Migrating From OrientDB to PostgreSQL

The section below covers migrating your Nexus Repository instance from OrientDB to an external PostgreSQL database.

Note

The Database Migrator does not support on-premises OrientDB to cloud PostgreSQL migration. Before using the Database Migrator, you need to ensure that the migrator can reach both locations (e.g., the on-premises file system and the new database). 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 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 called nexus. 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. 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.

    Note

    The user provided must be the database owner.

    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

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

  5. Add the following to $data-dir/etc/nexus.properties

    nexus.datastore.enabled=true

  6. Perform a full backup using normal backup procedures

  7. Copy the backup to a clean working location on a different filesystem so that any extraction doesn’t impact the existing production system

  8. Shut down Nexus Repository

  9. Update and run the following command from the clean working location containing your database backup. Use the appropriate values for host, port, username, password, and migrator utility jar file name. You can also include any of the optional parameters from the section below when running this command.

    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.

    • <database URL>:<port> – 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).

    • Use 2 dashes before the full-named parameters.

    • Use the db_url parameter value with double quotes.

  10. Run the following command after migrating the DB and before starting Nexus Repository. This will reclaims storage occupied by obsoleted tuples left from the migration.

    VACUUM(FULL, ANALYZE, VERBOSE);

  11. Start Nexus Repository.

Optional Parameters

  • -y, --yes:

    Parameter to skip waiting for user input and assume a "yes" response to the initial warning.

  • --content_migration=false

    Parameter to only migrate the security and config tables: users, roles, and blobstore configuration. Repository content is not migrated.

  • --shutdown_compact=false

    Parameter to disable H2 Content DB compression; this is set to true by default.

  • --healthcheck

    Parameter to run a health check on your OrientDB database. This check focuses on detecting and reporting existing corruption in component and asset classes. The migration will not occur when using this parameter.

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

Migrating From H2 to PostgreSQL

The section below covers migrating your Nexus Repository instance from an embedded H2 database to an external PostgreSQL database.

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

    Note

    The user provided must be the database owner.

    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

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

  5. Add the following to $data-dir/etc/nexus.properties

    nexus.datastore.enabled=true

  6. Perform a full backup using normal backup procedures

  7. Copy the backup to a clean working location on a different filesystem so that any extraction doesn’t impact the existing production system

  8. Shut down Nexus Repository

  9. Update and run the following command using your environment's details. You can include any of the optional parameters listed in the section below when running this command.

    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"

    • <database URL>:<port> – 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).

    • Use 2 dashes before the full-named parameters.

    • Use the db_url parameter value with double quotes.

  10. Run the following command after migrating the DB and before starting Nexus Repository. This will reclaims storage occupied by obsoleted tuples left from the migration.

    VACUUM(FULL, ANALYZE, VERBOSE);

  11. Remove or rename the nexus-store.properties file you used for H2 so that Nexus Repository will not continue to try and boot to that properties file.

  12. Start Nexus Repository.

Optional Parameters

  • -y, --yes:

    Parameter to skip waiting for user input and assume a "yes" response to the initial warning.

  • --content_migration=false

    Parameter to only migrate the security and config tables: users, roles, and blobstore configuration. Repository content is not migrated.

  • --shutdown_compact=false

    Parameter to disable H2 Content DB compression; this is set to true by default.

  • --healthcheck

    Parameter to run a health check on your OrientDB database. This check focuses on detecting and reporting existing corruption in component and asset classes. The migration will not occur when using this parameter.

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