Database and Instance Migration: OrientDB Sunset, H2/PostgreSQL Paths, and Migrator Workflows: Configuration, Design Choices, and Tradeoffs

1. Five decisions control most migration risk

Before writing commands, decide: (1) same deployment or separate target, (2) downtime budget, (3) target database, (4) whether blob location/type changes, and (5) how long the old source remains a tested rollback option. Tool choice follows those decisions.

2. Decision matrix

3. In-place minimizes topology change but couples rollback to the same environment

With an in-place database migration, repository URLs, blob locations, process identity, and surrounding network may remain stable. That reduces client cutover work. The tradeoff is that the maintenance window operates on the same platform and rollback must be especially disciplined. Preserve the source database plus matching blobs before the transformation, and do not let “same host” become permission to overwrite the only checkpoint.

4. Side-by-side buys validation and rollback isolation

A separate target can be built, patched, configured, and tested before traffic moves. This is attractive for legacy OrientDB modernization because the target can use a modern Nexus/Java/PostgreSQL stack while the source remains on the legacy compatibility line. It also enables canary client tests and keeps the old endpoint available during acceptance.

The cost is double capacity for a period, explicit DNS/repository URL cutover, secret/external identity setup, and a policy for writes that occur while both systems coexist.

5. “No downtime” does not mean “no cutover discipline”

Instance Migrator can move data while source and target are running and continue polling for new assets. You still need a final consistency/cutover phase: define when publication stops or is redirected, wait for the final transfer state, verify failures/retries, test consumers, and then move traffic. Otherwise two writable repositories can diverge and make rollback ambiguous.

6. H2 versus PostgreSQL is an operating-model choice

H2 remains useful for small, non-mission-critical deployments and learning, but current Sonatype guidance highlights concurrency, corruption, and high-availability limitations. PostgreSQL adds a separate database service, connection pool, network path, monitoring, backup/PITR, ownership, extension, and performance responsibilities—but is the recommended production database.

7. Database migration and blob migration are independent axes

Changing H2→PostgreSQL does not inherently require changing blob storage. Changing a file blob store to object storage does. Make this explicit in the plan:

migration:
  database:
    from: H2
    to: PostgreSQL
    tool: Database Migrator
  blobs:
    from: /srv/nexus/blobs
    to: /srv/nexus/blobs
    movementRequired: false
  endpoint:
    changes: false

If movementRequired becomes true, do not silently bolt a generic recursive copy onto the plan. Re-evaluate whether Instance Migrator or a Sonatype-supported blob/storage migration procedure is the correct method.

8. Secrets are migration state, not just configuration text

Repository upstream credentials, S3/object-store keys, LDAP bind passwords, SAML keys, user tokens/API keys, email credentials, and signing material may need special handling. Current Instance Migrator uses a migrator cipher for supported encrypted secrets; without the required cipher configuration, sensitive values may not migrate and must be reconfigured manually. That is preferable to silently leaking them into logs or export files.

9. Hosted content and proxy caches have different migration value

Current Instance Migrator guidance states that hosted repository content is migrated; proxy repository cached content is not the primary content-transfer target. That is sensible: a proxy cache can often be repopulated from the upstream, while hosted artifacts may be authoritative internal releases. But proxy repository configuration, routing, remote credentials, negative cache behavior, and network reachability still need validation.

10. Regenerated metadata is not evidence of artifact mutation

Format-specific index metadata may be regenerated on the target. Compare immutable artifact bytes/digests separately from generated Maven/APT/Yum/Helm/RubyGems metadata. A changed generated index can be expected while the underlying hosted artifact SHA-256 remains identical. Conversely, matching generated metadata cannot excuse a changed artifact checksum.

11. Rollback cost rises after every accepted write

Before cutover, rollback can be as simple as abandoning the target and keeping the source. After cutover, every target-only publication creates a reconciliation decision. Define a rollback window, a publication freeze or dual-write prohibition, and a source-of-truth rule. If rollback occurs, replay target-only legitimate artifacts from trusted CI/build evidence rather than inventing ad hoc database merges.

12. Separate migration from upgrade when the path requires it

Legacy OrientDB modernization often has two coupled changes: database migration and then Nexus/Java upgrade. Keep them as explicit phases with a validation checkpoint between them. If the migration is not validated, adding a major Nexus/Java upgrade makes diagnosis harder and can consume the rollback window.

13. Worked decision record

decision: "migrate production H2 to PostgreSQL"
source:
  nexus: "3.95.2-01"
  db: H2
  blob: file
constraints:
  maintenanceWindowMinutes: 180
  endpointMustStaySame: true
choice:
  pattern: "in-place database migration"
  tool: "Database Migrator"
  blobMovement: false
rollback:
  checkpoint: "verified pre-migration DB + corresponding blobs"
  targetWritesBeforeAcceptance: false
acceptance:
  - postMigrationTasksComplete
  - repositoryCountsExplained
  - criticalAssetSha256Matches
  - leastPrivilegeAuthPasses
  - controlledClientDownloadPasses

14. Knowledge check

15. Summary and bridge

You can now select a migration architecture, not merely a migrator binary. Lesson 4 applies this model to failures: wrong versions, wrong PostgreSQL ownership, missing extensions, blob mapping errors, incomplete post-migration tasks, and deceptively matching counts.

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.