Skip to main content
Version: 0.7 (Latest)

Quick start guide

Three steps: create a credentials file, run a full migration, then add constraints. This guide describes MigratorXpress v0.7.3.

Prerequisites​

  1. MigratorXpress binary (Windows or Linux) downloaded from arpe.io
  2. Database access -- read access on the source, write access on the target, and a SQL Server or PostgreSQL database for migration tracking
  3. FastTransfer binary (>= 0.15.0) -- MigratorXpress calls FastTransfer for data movement. If FastTransfer is in the engine/ directory next to the MigratorXpress binary it is found automatically; otherwise pass --fasttransfer_dir_path
  4. A license (optional for evaluation) -- without a license, MigratorXpress runs in trial mode. See License Management

Step 1: Create a credentials file​

Save the connection details for every database involved in the migration. Each entry has a unique ID that you reference on the command line.

{
  "oracle_prod": {
    "ds_type": "oracle",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "your_password",
      "server": "oracle-host.example.com",
      "port": 1521,
      "database": "ORCLPDB1"
    }
  },
  "mssql_target": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "your_password",
      "server": "sql-host.example.com",
      "port": 1433,
      "database": "target_db"
    }
  },
  "ms_mig_log": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "your_password",
      "server": "sql-host.example.com",
      "port": 1433,
      "database": "migration_log"
    }
  }
}

Save the file as credentials.json in a secure location and restrict its permissions (for example chmod 600 credentials.json): values are used as written, so passwords are stored in clear text. port must be a JSON number, not a string.

Step 2: Run a full migration​

Migrate an Oracle schema to SQL Server -- translate the data types, create tables, transfer data, and validate.

The source and target databases are the database values of the source and target entries of the credentials file: --source_db_name and --target_db_name are not needed.

Linux​

./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name SALES \
  --target_db_auth_id mssql_target \
  --target_schema_name sales \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --fasttransfer_p 2 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff

Windows (PowerShell)​

.\MigratorXpress.exe --auth .\credentials.json `
  --source_db_auth_id oracle_prod `
  --source_schema_name SALES `
  --target_db_auth_id mssql_target `
  --target_schema_name sales `
  --migration_db_auth_id ms_mig_log `
  --n_jobs 4 `
  --fasttransfer_p 2 `
  --drop_tables_if_exists true `
  --task_list translate create transfer diff

The --task_list parameter controls which steps run. The four tasks above cover data type translation, table creation, data transfer, and validation. Tasks always run in the canonical order (translate, create, transfer, diff, copy_pk, copy_ak, copy_fk), and only some combinations are accepted -- see Migration Tasks.

At the end of the run, check the exit code and the RUN SUMMARY: n/m tables succeeded block: the process exits with code 0 when every table succeeded, 40 when some tables failed and 41 when all of them failed. Failed tables can be retried with --resume; the log prints the exact command. See Exit Codes.

Step 3: Add constraints​

Once data is transferred and validated, copy primary keys, alternate keys, and foreign keys in a separate run. This avoids constraint violations during the initial load. Constraint copy is available for Oracle, PostgreSQL and SQL Server sources; with a PostgreSQL target, use --task_list copy_pk copy_ak (copy_fk is SQL Server-only). See Constraint Copy Support.

Linux​

./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name SALES \
  --target_db_auth_id mssql_target \
  --target_schema_name sales \
  --migration_db_auth_id ms_mig_log \
  --task_list copy_pk copy_ak copy_fk

Windows (PowerShell)​

.\MigratorXpress.exe --auth .\credentials.json `
  --source_db_auth_id oracle_prod `
  --source_schema_name SALES `
  --target_db_auth_id mssql_target `
  --target_schema_name sales `
  --migration_db_auth_id ms_mig_log `
  --task_list copy_pk copy_ak copy_fk

Advanced: Multi-schema migration​

You can migrate multiple schemas in one run using SQL LIKE patterns (or a comma-separated list) for --source_schema_name. Omit --target_schema_name so that each source schema is recreated under its own name on the target:

Linux​

# Migrate all schemas starting with "APP_"
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name "APP_%" \
  --target_db_auth_id mssql_target \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff

Windows (PowerShell)​

# Migrate all schemas starting with "APP_"
.\MigratorXpress.exe --auth .\credentials.json `
  --source_db_auth_id oracle_prod `
  --source_schema_name "APP_%" `
  --target_db_auth_id mssql_target `
  --migration_db_auth_id ms_mig_log `
  --n_jobs 4 `
  --drop_tables_if_exists true `
  --task_list translate create transfer diff

Pattern examples:

  • APP_% -- all schemas starting with APP_
  • %_PROD -- all schemas ending with _PROD
  • % -- every schema in the database (same as omitting --source_schema_name)
warning

If you pass --target_schema_name together with a pattern or list, all matched source schemas are loaded into that single target schema. It is a plain name, not a pattern.

Next steps​

Copyright © 2026 Architecture & Performance.