Sonatype Security Research

OrientDB to PostgreSQL Migration

Reference Guide

Support for OrientDB databases with Nexus Repository is currently in extended maintenance, and will be officially sunset at the start of 2026. At that time, Sonatype will no longer support deployments using OrientDB. Database migrations often require some planning, so the time to begin preparing is now.

This document guides users through the process of migrating from OrientDB to PostgreSQL. The information here is pulled from our documentation, our Support Knowledge Base, and our Migration Specialists.

Jump Ahead

• Readiness Flowchart: Determine at-a-glance if you’re ready to begin migration.

• Migration Procedures: Follow our migration procedures and make the jump from OrientDB to PostgreSQL.

• Tips & Tricks: Solve potential problems preemptively.

• Troubleshooting: Identify common problems and error messages, and their solutions.

Why PostgreSQL?

Although it’s possible to migrate to an H2 database, Sonatype strongly suggests that customers move to PostgreSQL. PostgreSQL has a number of important advantages.

• PostgreSQL supports hot backups, high availability architectures, and cloud-native scaling, making it ideal for production and enterprise environments.
• Performance with PostgreSQL is generally better than OrientDB or H2, with faster queries, reduced latency, and better resource efficiency.
• Key features of Nexus Repository Pro — including some of the most powerful enterprise capabilities — require PostgreSQL. Future enhancements are being built exclusively for PostgreSQL users. Staying on OrientDB or moving to H2 means you’ll miss out on innovation.

Reach Out to our Migration Specialists

Users who have purchased Nexus Repository Pro, are on OrientDB, and are ready to migrate may have the opportunity to work directly with our Migration Specialists for hands-on guidance. If you have a Customer Success representative assigned, you’ll receive an email with more information. If you don’t, reach out to your account representative.

Repo Cloud

Migration is an opportunity to rethink the specifics of your deployment and consider the future. Nexus Repository Cloud is a SaaS deployment of Nexus Repository – we build the architecture, stay on top of versioning, and manage the database, and you reap the benefits. Reach out to your Sales or Customer Success representative to learn more.

Migration requires your deployment and environment to meet certain criteria. Review the flowchart below and be sure you can answer “yes” to all of the questions below before continuing.

• Upgrade to 3.70.4, the last version of Nexus Repository to support OrientDB.
• The migrator utility requires Java 8 or 11 on OpenJDK. Switch to this version of Java before continuing.
• This is requirement to upgrade beyond 3.70.4. Confirm you can use this version of Java before continuing.
• Upgrade to Postgres 14 or greater to ensure compatibility and future-proof your deployment.
• Allocate these resources to maintain acceptable system performance.

Readiness Flowchart

Are you on Nexus Repository 3.70.4?

Are you using OpenJDK?

Are you ready for Java 17?

Is your Postgres deployment on version 14 or newer?

Does your Postgres server have at least 2 CPUs, 8 GB RAM, and 200 GB of storage?

Does your Nexus Repository server have at least 2 CPUs, 8 GB RAM, and 20 GB of local blob storage?

Have you temporarily provisioned your Nexus Repository server with 16 GB RAM and 3x the storage space as your current database?

Will you test?

Manually checking the db directory in your file system, e.g. Allocate these resources to ensure “/nexus/sonatype-work/nexus3/db”. The migrator runs correctly. Check your current database size by: Running the command “du -sh /opt/sonatype/sonatype-work/nexus3/db” from your terminal.

Testing the migration in a non-production setting downtime. Identifies potential issues and helps you estimate Every user should test, regardless of any other circumstance.

Congrats! You’re ready to migrate to Postgres!

Migration Procedures

If you meet all the migration prerequisites, then follow these steps to migrate.

Remember, to isolate problems and estimate the actual time requirements, test this procedure with a backup before attempting it in production.

1. Perform a full backup of your Nexus Repository installation, including all directories and files.
2. Upgrade to Nexus Repository 3.70.4 following normal upgrade procedures. Check our documentation.
3. Download our migrator utility.
4. Create a user and database in your PostgreSQL deployment.

   CREATE USER nexus WITH PASSWORD '<nexus_password>' CREATEDB;
   CREATE DATABASE nexus OWNER nexus ENCODING 'UTF8';
   GRANT ALL PRIVILEGES ON SCHEMA public TO nexus;
   GRANT ALL PRIVILEGES ON DATABASE nexus TO nexus;
   

5. Configure PostgreSQL autovacuum configuration to be on.

   autovacuum = on
   

6. In your $data-dir/etc/fabric directory, create a file named nexus-store.properties and populate it with the following:

   username=nexus
   password=<nexus_password>
   jdbcUrl=jdbc:postgresql://<database-host>:<database-port>/nexus
   

Migration Procedures (Continued)

For large databases, increase the maximum number of connections from 100 to 200.

max_connections = 200

Also increase the connection pool size from 100 to 200 by adding the following to nexusstore.properties.

advanced=maximumPoolSize=200

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

nexus.datastore.enabled=true

Perform a full backup using Nexus Repository’s backup task.

Move the backup to a clean working location, somewhere outside of Nexus Repository’s db directory. Also move the migrator utility to this clean working location.

Start Nexus Repository.

Run the following command from the directory containing your database backup.

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=nexus&password=<nexus_password>"

If you’re using Java 11, you’ll need this additional parameter.

--add-exports java.base/sun.nio.ch=ALL-UNNAMED

Run the following command on the new database’s server.

VACUUM (FULL, ANALYZE, VERBOSE);

Start Nexus Repository.

Complete the Migration

Your migration isn’t finalized just yet! Check the following four items before moving on.

1. Allow Nexus Repository to complete the Rebuild repository browse and Rebuild repository search tasks.
2. If your Nexus Repository instance has a repository in the Helm format, manually run the task Rebuild Helm metadata.
3. Check the task log and confirm all of the tasks below are complete.
   • repository.rebuild-index
   • repository.search.update
   • create.browse.nodes
   • repository.yum.rebuild.metadata
   • component.normalize.version
   • repository.metrics.blob.size.copy
   • file.blobstore.metrics.datastore.migration
4. Install the trigram module to ensure Nexus Repository can accurately search components.

   sudo dnf install postgresql-contrib
   create extension pg_trgm;
   select * from pg_extension;
   

Tips and Tricks

Test with a backup before migrating your production instance

It is absolutely critical that you test the migration procedures with a backup before attempting to migrate in-prod. Testing is the only way to identify potential problems, estimate time/downtime requirements, and be certain that no data will be lost or compromised during the migration.

Identify important directories before beginning

Identifying key directories before starting migration will prevent confusion. Most deployments include two main directories:

• The installation directory.
• The data directory.

We recommend you start your migration procedure by backing up both the installation and work directory, including all subdirectories.

Plan for downtime

Migration requires a period of downtime, where Nexus Repository won’t be reachable by users or systems. If possible, plan to migrate during off-hours. Announce the downtime well in advance.

Migration is one-way

Migration is one-way. You cannot migrate from OrientDB to PostgreSQL and then migrate back to OrientDB.

However, migration is also non-destructive. Your old OrientDB database remains in your data directory and can be used as a restore point if that becomes necessary.

Ensure ownership is correct

If you’re using a Unix-based system, then the migration procedure may have changed the OS-level owner of certain files. To prevent this, ensure all files are owned by the service user under which the service is running. Set permissions recursively with the chown command:

sudo chown -R nexus:nexus /opt/nexus

Recognize unsupported formats

Nexus Repository + PostgreSQL does not support Bower or any of the community-created formats. Data in these formats will not be migrated by this procedure.

Review configuration options

Two key PostgreSQL configuration options can have a big impact on the specifics of your operation. Review changes to your PostgreSQL database, as necessary.

Migrate in the same datacenter

If downtime during the migration is a concern, perform the migration while the Nexus Repository server and the PostgreSQL server are in the same datacenter or availability region.

Upgrade, then Migrate, then Upgrade

1. Upgrade Nexus Repository to 3.70.4.
2. Migrate from OrientDB to PostgreSQL.
3. Upgrade to Java 21.
4. Upgrade Nexus Repository to the latest.

We strongly recommend you make time to upgrade Nexus Repository regularly. This ensures you’re receiving the value of new features and stability/performance improvements. Recognize that Java 21 is required starting with 3.87.0.

Review cleanup policies after migration

Postgres supports advanced search operations, and Nexus Repository takes advantage of this during cleanup tasks. After migrating, double-check that cleanup policies are accurately identifying the correct components.

Prepare for new backup procedures

Backup procedures for embedded databases like OrientDB and external databases like PostgreSQL differ in a few key ways. Review our documentation on backing up and PostgreSQL’s documentation for backing up before the migration and ensure you understand the new backup procedures.

Consider resilient architecture

One of the major benefits of PostgreSQL as a database option is that it’s compatible with resilient and high-availability architectures. Once you’re on PostgreSQL, begin considering resilient or high-availability architecture.

Troubleshooting

Repositories appear empty after migration

Run the Repair - Rebuild repository browse task to rectify potential discrepancies between the data model that handles browsing and the data model that handles component info.

If the problem persists, it’s possible that migration failed. If you’re a customer, open a Support ticket. If not, restore a backup with the OrientDB database and try migration again.

"Value too long for type character varying(250)"

The db_url value in your migration command is too long. A sample migration command is below:

"DB Files Detected"

Your Nexus Repository backup is located in your db directory. Move the backup to a clean working location and run the migration command again.

Nexus Repository can’t reach the Postgres server

Check that Nexus Repository can communicate with the Postgres server, and that its privileges are adequate.

"Permission denied for public schema"

The PostgreSQL user representing Nexus Repository (nexus) does not have appropriate privileges. Ideally, the user nexus will be the owner of the database. Alternatively, give the user the CREATE and USAGE (or the equivalent ALL) privilege:

GRANT ALL PRIVILEGES ON SCHEMA public TO nexus;

Sonatype is the leader in AI-driven DevSecOps. As the maintainers of Maven Central and creators of Nexus Repository, Sonatype has spent two decades pioneering how the world manages and secures open source software — making Sonatype the trusted authority for modern software supply chains. With unmatched open source visibility and a unified product suite built for modern software development, Sonatype gives enterprises the intelligence and automated governance they need to harness the full potential of open source and AI.