Database and Instance Migration: OrientDB Sunset, H2/PostgreSQL Paths, and Migrator Workflows: Concepts, Architecture, and Mental Model

1. The practical problem: the database is part of the product state

Chapter 25 established that Nexus recovery depends on a coherent database/configuration and blob-store recovery set. Migration adds a second constraint: the source and target must be connected by a supported migration path. A database that is healthy on one Nexus release is not a portable file format that can be dropped under any later release. Schema evolution, Java requirements, storage metadata, security secrets, and format-specific generated metadata all participate in the transition.

The safe question is therefore not “How do I move $data-dir/db?” It is: “What exact source state do I have, what exact target state do I need, which current Sonatype migration workflow connects them, and how will I prove the result?”

2. Migration mental model

flowchart TD
  S[Source instance
version + edition + Java]
  D[(Source DB
OrientDB / H2 / PostgreSQL)]
  B[(Blob stores
file / object)]
  G{Compatibility gate
source + target + tool}
  DM[Database Migrator
offline DB transformation]
  IM[Instance Migrator
live config + hosted assets]
  T[Target instance
H2 / PostgreSQL]
  V[Validation
config + counts + hashes + auth + clients]
  C[Controlled cutover]
  R[Rollback checkpoint
untouched source + matching blobs]
  S --> G
  D --> G
  B --> G
  G -->|same deployment / DB platform change| DM
  G -->|source → new target / content movement| IM
  DM --> T
  IM --> T
  T --> V --> C
  G --> R

The diagram has two different migration engines because they solve different problems. Database Migrator transforms database state for a self-hosted deployment. Instance Migrator treats the source and target as separate running Nexus instances and moves supported configuration and hosted repository assets through the product interfaces while tracking transfer state.

3. Inventory the source before choosing a tool

Capture a source manifest before any migration action:

source:
  nexusVersion: "3.70.5"        # example legacy source
  edition: "Community"
  java: "11"                    # legacy OrientDB source only
  database: "OrientDB"
  blobStores:
    - name: "default"
      type: "file"
      location: "<documented-source-path>"
  repositories:
    hosted: 4
    proxy: 3
    group: 2
  security:
    localUsers: 7
    roles: 11
    externalIdentity: "LDAP"
  evidence:
    componentCount: 12543
    sampleSha256: "SYNTHETIC-EXPECTED-HASH"

The values are evidence, not decoration. They drive tool selection, target preparation, maintenance windows, secret handling, and acceptance criteria.

4. OrientDB is a legacy source state, not a modern target

OrientDB entered extended maintenance in 2024 and is officially sunset. Nexus Repository 3.70.x is the last line that supports OrientDB; 3.71.0 and later do not. A legacy OrientDB deployment that needs to move forward must first reach the supported migration source state—currently 3.70.5—while staying on the Java level that OrientDB supports. Only after the database transition does the instance move to newer Nexus/Java requirements.

This sequencing matters. Starting a 3.95.x binary against an OrientDB data directory is not an upgrade strategy. Neither is upgrading the legacy source to a Java release its database cannot use.

5. Database Migrator versus Instance Migrator

6. Database Migrator: metadata transformation, not blob transfer

For a current H2→PostgreSQL migration, Sonatype’s documented path is: back up H2, prepare PostgreSQL, shut down Nexus, run the current Database Migrator from the data database directory with the target JDBC connection, run the documented PostgreSQL maintenance step, then start Nexus and allow required post-migration rebuild tasks to complete.

7. Instance Migrator: a source→target migration

Current Instance Migrator documentation lists self-hosted OrientDB 3.70.5 as the source and a self-hosted 3.90.2+ target using H2 or PostgreSQL as supported scenarios, with Java 25 required for the migrator tool itself. Both instances are running. The utility exports configuration-as-code, queues hosted assets, maintains per-repository migration state, and can continue polling for new assets while the migration is in progress.

That does not mean every Nexus state object is identical after migration. Current target-specific documentation lists exclusions and manual follow-up such as LDAP connection configuration, realms, audit logs, some format-specific metadata, and other target constraints. Read the target-specific workflow instead of relying only on a high-level feature list.

8. PostgreSQL is not “a host and password”

Current Sonatype requirements expect the Nexus database user to own the database. Upgrades/schema changes require ownership, and a non-owner user is not a supported configuration. PostgreSQL also requires the pg_trgm extension. If a separate schema is used, the Nexus user needs appropriate USAGE/CREATE permissions and the schema must be on the user’s search path.

-- Disposable example only; choose locale/settings for your platform.
CREATE USER nexus_lab WITH PASSWORD 'password-FAKE_DO_NOT_USE';
CREATE DATABASE nexus_lab OWNER nexus_lab ENCODING 'UTF8';
\c nexus_lab
CREATE SCHEMA nexus AUTHORIZATION nexus_lab;
CREATE EXTENSION pg_trgm SCHEMA nexus;

In a real environment, database creation belongs to the DBA/platform control plane and credentials belong in a secret store—not in lesson files or shell history.

9. Migration needs temporary capacity

Current Database Migrator guidance calls for substantial temporary resources: at least 16 GB available RAM and roughly three times the database-directory size in disk headroom, with a minimum temporary-space expectation. Treat those as preflight gates, not after-the-fact tuning tips. A migration that fills the source filesystem can turn a controlled change into a recovery incident.

10. “Migrator exited successfully” is not the finish line

After database migration, Nexus runs rebuild/normalization work for browse/search and other internal derived state. Some formats require additional metadata rebuild operations. Do not restart repeatedly or open production traffic while those required post-migration tasks are incomplete. Record task history/logs and wait for a stable target before acceptance testing.

11. Rollback is a state-consistency problem

Database Migrator is designed to leave the original source database unchanged, which is useful as a checkpoint. But once the migrated target starts accepting writes, database and blob content diverge from the source checkpoint. Reverting to an earlier database therefore requires the matching pre-migration blob state as well. The same principle applies to side-by-side cutover: preserve the source, freeze/route writes deliberately, and know exactly which post-cutover writes would be lost on rollback.

12. Acceptance ladder

1. Target starts on the intended Nexus/Java/database combination.
2. Repository definitions, blob-store mappings, cleanup/routing policies, users/roles/privileges, and external-identity configuration are accounted for.
3. Hosted component/asset counts are within explained expectations.
4. Sample/critical assets resolve and SHA-256 values match the source evidence.
5. Proxy/group behavior is tested as behavior, not inferred from hosted counts.
6. Least-privilege users can read/write only what the design permits.
7. Browse/search/format metadata rebuilds complete.
8. Logs/tasks show no unresolved migration failures.
9. A controlled client request succeeds against the target endpoint.
10. Rollback remains possible until the acceptance decision is signed off.

13. Why this matters in DevOps

A repository migration sits in the release path for every consumer that resolves dependencies or images. Treating migration as an audited change—with source evidence, compatibility gates, rehearsed rollback, deterministic validation, and explicit cutover—turns it from a risky “storage maintenance” event into normal platform engineering.

14. Knowledge check

15. Summary and bridge

You now have the migration mental model: inventory first, choose the tool from topology, respect legacy and target version gates, prepare PostgreSQL correctly, preserve coherent rollback state, and validate beyond a successful process exit. Lesson 2 turns that model into a disposable workflow with executable fixtures and current command shapes.

Official references and version notes

• Sonatype: What to Choose — Instance Migrator or Database Migrator — current division between live source→target migration and offline database transformation.
• Sonatype: Instance Migrator — supported OrientDB source/target versions, Java requirement, resumability, logging, and asset migration behavior.
• Sonatype: OrientDB to Self-Hosted PostgreSQL Migration — target preparation, migrator cipher, migrated/excluded state, and known limitations.
• Sonatype: Migrating to a New Database — Database Migrator scenarios, offline requirements, H2→PostgreSQL sequence, and post-migration tasks.
• Sonatype: Upgrading to Nexus Repository 3.71.0 and Beyond — OrientDB 3.70.x migration gate, H2/PostgreSQL paths, and Java transition.
• Sonatype: Nexus Repository Upgrade Paths — current version sequencing and breaking-version gates.
• Sonatype: Reverting Back to OrientDB — why the old database is a recovery point only when matching blob state is restored.
• Sonatype: Install Nexus Repository with PostgreSQL — database ownership, schema privileges, and pg_trgm requirement.
• Sonatype: Nexus Repository Database — H2 production limitations, PostgreSQL recommendation, and OrientDB sunset state.
• Sonatype: Nexus Repository 3.70.x Downloads with OrientDB — final OrientDB line and matching migration downloads.
• Sonatype: Download — current Nexus/Database Migrator/Instance Migrator download references.
• Sonatype: System Requirements — current Java/PostgreSQL requirements and supported database expectations.
• Sonatype: Nexus Repository 3.95.x Release Notes — dated current release line used as the modern target reference.