Instance Migrator

Instance Migrator is a command-line utility for migrating and managing Nexus Repository instances. Use the Instance Migrator for the following migration scenarios:

Migrate from self-hosted Nexus Repository 3 to Nexus Repository Cloud
Migrate from legacy OrientDB-based Nexus Repository to self-hosted Nexus Repository that uses either H2 or PostgreSQL

Instance Migrator provides an interactive shell interface for user-friendly migration operations with support for automation via environment variables and configuration files.

Features and Key Capabilities

Configuration and Asset Migration
Export configuration-as-code from source instance to the target instance. Once the desired configuration is in place, repository content is queued for direct migration from the source instance to the target instance over time using configurable parallel asset migration.
Migration State Tracking
Persistent state management to track migration progress and resume operations. Detailed logging with separate tracking for successful and failed asset transfers. After content is migrated the polling features will continue to check to new assets to migrate when added to the repository to ensure consistency between instances.
Enhanced Logging and Error Handling
Separate log files for successful and failed transfers with structured logging services. The per-repository state management allows for automatic persistence and recovery. Detailed logging and graceful failure recovery with retry mechanisms for robust error handling.

Supported Migration Scenarios

The following are the migration scenarios supported:

Note
H2 databases are only appropriate for non-mission-critical deployments. Using an external PostgreSQL database is highly recommended for production deployments. See Database Options for details.

Self-Hosted OrientDB (3.70.5) to Nexus Repository Cloud
Self Hosted OrientDB (3.70.5) to Self-Hosted PostgreSQL (3.90.2 or later)
Self-Hosted OrientDB (3.70.5) to Self-Hosted H2 (3.90.2 or later)

The self-hosted migration path supports both Nexus Repository Pro and Nexus Repository Community Edition.

Requirements

General Requirements

Java 25
Administrator access to source instance
Administrator access to target instance

For self-hosted instance to Nexus Repository Cloud

Source Nexus Repository (OrientDB) with version 3.70.5
Target Nexus Repository 3 hosted by Sonatype in the cloud

For self-hosted (OrientDB) to self-hosted (H2 or PostgreSQL) instance

Source Nexus Repository (OrientDB) with version 3.70.5
Target Nexus Repository (H2 or PostgreSQL) with version 3.90.2 or later
Latest available version of Instance Migrator. See Downloads or Nexus Repository 3.70.x Downloads with OrientDB

Quick Start

Use this section to get started with Instance Migrator and understand the basic workflow before you begin a migration.

By default, the application runs in interactive shell mode. Use interactive shell mode to configure settings step by step and run migration commands manually.

Start interactive shell

    java -jar nexus-repository-instance-migrator-<version>-SNAPSHOT.jar
    ```

Where `<version>` is the released Instance Migrator version you downloaded.

- Configure settings using `config set` command
- Check connectivity with `status`
- Run migration operations with `migrate-configuration-read`, `migrate-configuration-write`, or `migrate-content`
- Get help with `migrate-help`

### Available Commands

| Command                           | Description                                                  |
|-----------------------------------|--------------------------------------------------------------|
| `status`                         | Check connectivity to both source and target Nexus instances |
| `migrate-configuration-read`     | Read configuration from source Nexus and save to JSON       |
| `migrate-configuration-write`    | Load configuration from JSON and write to target Nexus      |
| `migrate-content`                | Migrate repository content (assets) - supports multiple usage patterns |
| `stop-migrate-content`           | Stop one or more (or all) current migrate-content or migrate-content-polling actions |
| `migrate-content-polling`        | Start continuous polling for new assets (requires completed initial migration) |
| `config show`                    | Display current configuration values                         |
| `config set <key> <value>`      | Set a configuration value                                    |
| `config list`                   | List all available configuration keys                        |
| `migrate-help`                   | Show detailed help for migration commands                    |
| `help`                          | Show shell commands help                                     |
| `exit`                          | Exit the interactive shell                                   |

### Best Practices

- **Production Deployments**: Use environment variables or `application.properties` for production deployments instead of interactive `config set` commands. See [Configure the Migrator](https://help.sonatype.com/en/configure-the-migrator.html "Configure the Migrator").
- **Log Files**: Ensure log files (`nexus-migrator.log`, `asset-transfers.log`, `failed-asset-transfers.log`) have appropriate file system permissions.
- **Credential Management**: Consider using credential management systems or secret stores for production environments.
- **Session Security**: Each shell session does not persist history, so passwords entered are not recoverable after closing the application.

## Getting Started

Explore the following topics to learn about Instance Migrator:

1. [Configure the Migrator](https://help.sonatype.com/en/configure-the-migrator.html "Configure the Migrator")
2. [Run the Migrator](https://help.sonatype.com/en/run-the-migrator.html "Run The Migrator")
3. [Operational Behaviour](https://help.sonatype.com/en/migrator-operational-behaviour.html "Operational Behaviour")
4. [Self-Hosted to Cloud Migration](https://help.sonatype.com/en/self-hosted-to-cloud-migration.html "Self Hosted to Cloud Migration")
5. [OrientDB to Self-Hosted PostgreSQL Migration](https://help.sonatype.com/en/orientdb-to-self-hosted-postgresql-migration.html "OrientDB to Self-Hosted PostgreSQL Migration")
6. [Support](https://help.sonatype.com/en/support.html "Support")