# MigratorXpress Documentation

> An efficient database migration tool for cross-platform schema and data transfer. Migrates Oracle, PostgreSQL, SQL Server and Netezza schemas to SQL Server or PostgreSQL, with parallel data transfer through FastTransfer.


## 0.6

An efficient database migration tool for cross-platform schema and data migration.

- [MigratorXpress](/0.6.md): An efficient database migration tool for cross-platform schema and data migration.

### compatibility

Supported databases and platforms for MigratorXpress.

- [Compatibility](/0.6/compatibility.md): Supported databases and platforms for MigratorXpress.

### configuration

- [Database Connections](/0.6/configuration/database-configuration.md): Configure database connections for MigratorXpress source, target, and migration tracking databases.
- [Netezza](/0.6/configuration/databases/netezza.md): Configure Netezza connections for MigratorXpress source databases.
- [Oracle](/0.6/configuration/databases/oracle.md): Configure Oracle connections for MigratorXpress source databases.
- [PostgreSQL](/0.6/configuration/databases/postgresql.md): Configure PostgreSQL connections for MigratorXpress source and target databases.
- [PostgreSQL as Target](/0.6/configuration/databases/postgresql-as-target.md): Configure PostgreSQL as a migration target database for MigratorXpress.
- [PostgreSQL as Migration Tracking](/0.6/configuration/databases/postgresql-as-tracking.md): Configure PostgreSQL as the migration tracking database for MigratorXpress.
- [SQL Server](/0.6/configuration/databases/sql-server.md): Configure SQL Server connections for MigratorXpress source, target, and migration tracking databases.
- [SQL Server as Target](/0.6/configuration/databases/sql-server-as-target.md): Configure SQL Server as a migration target database for MigratorXpress.
- [SQL Server as Migration Tracking](/0.6/configuration/databases/sql-server-as-tracking.md): Configure SQL Server as the migration tracking database for MigratorXpress.
- [FastTransfer Configuration](/0.6/configuration/fasttransfer-configuration.md): Configure FastTransfer for high-performance data transfer in MigratorXpress.
- [Migration Tasks](/0.6/configuration/migration-tasks.md): Understanding MigratorXpress migration tasks and their execution order.

### guides

- [Examples and use cases](/0.6/guides/examples.md): Real-world migration scenarios with complete command examples.
- [Quick start guide](/0.6/guides/quickstart.md): Get up and running with MigratorXpress in 5 minutes.

### reference

- [CLI Reference](/0.6/reference/cli-reference.md): Complete reference for all MigratorXpress command-line arguments.
- [Logging and Monitoring](/0.6/reference/logging.md): Database logging, file-based logging, and monitoring for MigratorXpress migrations.
- [MigratorXpress SBOM Downloads](/0.6/reference/sbom.md): Software Bill of Materials downloads and verification for MigratorXpress.
- [Troubleshooting](/0.6/reference/troubleshooting.md): Common issues and solutions when using MigratorXpress.

### wizard

Build your MigratorXpress command interactively.

- [Command Builder](/0.6/wizard.md): Build your MigratorXpress command interactively.

## latest

An efficient database migration tool for cross-platform schema and data migration.

- [MigratorXpress](/latest.md): An efficient database migration tool for cross-platform schema and data migration.

### ai

- [MigratorXpress Agent Skill](/latest/ai/agent-skills.md): Install the official arpe.io agent skill that teaches Claude Code, Codex, Cursor, Copilot and other AI agents to build correct MigratorXpress command lines
- [MigratorXpress MCP Server](/latest/ai/mcp-server.md): Connect Claude, ChatGPT, Cursor, VS Code and other AI assistants to the arpe.io MCP server to build, check and run MigratorXpress commands

### compatibility

Supported databases and platforms for MigratorXpress.

- [Compatibility](/latest/compatibility.md): Supported databases and platforms for MigratorXpress.

### configuration

- [Database Connections](/latest/configuration/database-configuration.md): Configure database connections for MigratorXpress source, target, and migration tracking databases.
- [Netezza](/latest/configuration/databases/netezza.md): Configure Netezza connections for MigratorXpress source databases.
- [Oracle](/latest/configuration/databases/oracle.md): Configure Oracle connections for MigratorXpress source databases.
- [PostgreSQL](/latest/configuration/databases/postgresql.md): Configure PostgreSQL connections for MigratorXpress source and target databases.
- [PostgreSQL as Target](/latest/configuration/databases/postgresql-as-target.md): Configure PostgreSQL as a migration target database for MigratorXpress.
- [PostgreSQL as Migration Tracking](/latest/configuration/databases/postgresql-as-tracking.md): Configure PostgreSQL as the migration tracking database for MigratorXpress.
- [SQL Server](/latest/configuration/databases/sql-server.md): Configure SQL Server connections for MigratorXpress source, target, and migration tracking databases.
- [SQL Server as Target](/latest/configuration/databases/sql-server-as-target.md): Configure SQL Server as a migration target database for MigratorXpress.
- [SQL Server as Migration Tracking](/latest/configuration/databases/sql-server-as-tracking.md): Configure SQL Server as the migration tracking database for MigratorXpress.
- [FastTransfer Configuration](/latest/configuration/fasttransfer-configuration.md): Configure FastTransfer for high-performance data transfer in MigratorXpress.
- [Migration Tasks](/latest/configuration/migration-tasks.md): Understanding MigratorXpress migration tasks and their execution order.

### guides

- [Examples and use cases](/latest/guides/examples.md): Real-world migration scenarios with complete command examples.
- [Quick start guide](/latest/guides/quickstart.md): Get up and running with MigratorXpress in 5 minutes.

### installation

Install MigratorXpress on Windows or Linux, save your license file, and check the bundled FastTransfer engine.

- [Installation](/latest/installation.md): Install MigratorXpress on Windows or Linux, save your license file, and check the bundled FastTransfer engine.

### reference

- [CLI Reference](/latest/reference/cli-reference.md): Complete reference for all MigratorXpress command-line arguments.
- [Logging and Monitoring](/latest/reference/logging.md): Database logging, file-based logging, and monitoring for MigratorXpress migrations.
- [MigratorXpress SBOM Downloads](/latest/reference/sbom.md): Software Bill of Materials downloads and verification for MigratorXpress.
- [Troubleshooting](/latest/reference/troubleshooting.md): Common issues and solutions when using MigratorXpress.

### wizard

Build your MigratorXpress command interactively.

- [Command Builder](/latest/wizard.md): Build your MigratorXpress command interactively.


---

# Full Documentation Content

# MigratorXpress

## What is MigratorXpress?[​](#what-is-migratorxpress "Direct link to What is MigratorXpress?")

MigratorXpress is a CLI tool for database migrations between platforms. It translates schemas, transfers data, copies constraints, and validates results -- all from a single command. Under the hood it uses [FastTransfer](https://www.arpe.io/fasttransfer/) for streaming data transfer, so datasets of any size move without saturating memory.

## Architecture[​](#architecture "Direct link to Architecture")

MigratorXpress connects three databases during a migration:

<!-- -->

### Source Database[​](#source-database "Direct link to Source Database")

The database you are migrating from. MigratorXpress reads schema metadata, profiles column types, and streams table data from the source.

Supported sources: Oracle, PostgreSQL, SQL Server, Netezza.

### Target Database[​](#target-database "Direct link to Target Database")

The database that receives the translated schema and data. MigratorXpress creates tables, loads data via FastTransfer, and optionally copies constraints.

Supported targets: PostgreSQL, SQL Server.

### Migration Tracking DB[​](#migration-tracking-db "Direct link to Migration Tracking DB")

A SQL Server **or PostgreSQL** database where MigratorXpress logs every migration step -- table discovery, translation, transfer status, diff results, and constraint operations. This enables auditing, monitoring, and resuming failed migrations. The backend is auto-detected from the auth entry's `ds_type` (`mssql` or `postgres`); no CLI flag is required.

## Key features[​](#key-features "Direct link to Key features")

* **Cross-platform** -- native binaries for Windows and Linux.
* **Multi-database** -- Oracle, PostgreSQL, SQL Server, and Netezza as sources; PostgreSQL and SQL Server as targets.
* **Dual-level parallelism** -- migrate multiple tables at once with `--n_jobs` and partition large tables internally with `--fasttransfer_p`.
* **Schema translation** -- automatic DDL conversion between database dialects.
* **Data validation** -- the `diff` task compares row counts and content between source and target.
* **Flexible task management** -- run any combination of `translate`, `create`, `transfer`, `diff`, `copy_pk`, `copy_ak`, `copy_fk`, or use `--task_list all`.

## Supported migration paths[​](#supported-migration-paths "Direct link to Supported migration paths")

| Database   | As Source | As Target | Migration Tracking |
| ---------- | --------- | --------- | ------------------ |
| Oracle     | ✅        | ❌        | ❌                 |
| PostgreSQL | ✅        | ✅        | ✅                 |
| SQL Server | ✅        | ✅        | ✅                 |
| Netezza    | ✅        | ❌        | ❌                 |

## Quick example[​](#quick-example "Direct link to Quick example")

A full Oracle-to-PostgreSQL migration on Linux:

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_db_name ORCL \
  --source_schema_name SALES \
  --target_db_auth_id postgres_dev \
  --target_db_name analytics \
  --target_schema_name sales_copy \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 2 \
  --fasttransfer_p 2 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff
```

This single command translates the Oracle `SALES` schema to PostgreSQL DDL, creates the tables, streams the data with two parallel workers per table, and validates the result with a diff.

## Data transfer with FastTransfer[​](#data-transfer-with-fasttransfer "Direct link to Data transfer with FastTransfer")

MigratorXpress delegates all data movement to FastTransfer, which uses a streaming architecture. Rows flow directly from source to target without being buffered entirely in memory. This design handles tables with billions of rows on modest hardware and avoids the out-of-memory failures common with dump-and-load approaches.

## Next steps[​](#next-steps "Direct link to Next steps")

Ready to migrate?

[Get Started](/0.6/guides/quickstart.md)[Command Builder](/0.6/wizard.md)[Examples & Use Cases](/0.6/guides/examples.md)


---

# Compatibility

## Supported Databases[​](#supported-databases "Direct link to Supported Databases")

| Database   | As Source    | As Target    | Migration Tracking |
| ---------- | ------------ | ------------ | ------------------ |
| Oracle     | ✅ Supported | ❌           | ❌                 |
| PostgreSQL | ✅ Supported | ✅ Supported | ✅ Supported       |
| SQL Server | ✅ Supported | ✅ Supported | ✅ Supported       |
| Netezza    | ✅ Supported | ❌           | ❌                 |

### Source databases[​](#source-databases "Direct link to Source databases")

Any of the four supported databases can serve as a migration source. MigratorXpress reads the schema metadata and data, translates the DDL to the target dialect, and streams rows via FastTransfer.

* **[Oracle](/0.6/configuration/databases/oracle.md)** -- thin and thick client modes, Rowid-based parallel extraction
* **[PostgreSQL](/0.6/configuration/databases/postgresql.md)** -- Ctid-based parallel extraction
* **[SQL Server](/0.6/configuration/databases/sql-server.md)** -- PhysLoc-based parallel extraction
* **Netezza** -- source-only support, default port 5480

### Target databases[​](#target-databases "Direct link to Target databases")

PostgreSQL and SQL Server are supported as migration targets. MigratorXpress creates the schema, transfers data, and optionally copies constraints (PK, AK, FK).

* **[PostgreSQL](/0.6/configuration/databases/postgresql.md)** -- target schema is created automatically
* **[SQL Server](/0.6/configuration/databases/sql-server.md)** -- supports Clustered Columnstore Indexes via `--cci_threshold`

### Migration tracking database[​](#migration-tracking-database "Direct link to Migration tracking database")

The migration tracking database can be **SQL Server** or **PostgreSQL**. It stores per-table transfer status, row counts, constraint copy results, and event logs. This database enables the `--resume` capability and provides a full audit trail. The backend is selected by the `ds_type` of the entry referenced by `--migration_db_auth_id` (`mssql` or `postgres`) and is auto-detected; no extra flag is required.

* **[SQL Server as Migration Tracking](/0.6/configuration/databases/sql-server-as-tracking.md)** -- default, mature path
* **[PostgreSQL as Migration Tracking](/0.6/configuration/databases/postgresql-as-tracking.md)** -- added in v0.6.32, tracking tables live in the `public` schema

## Supported Platforms[​](#supported-platforms "Direct link to Supported Platforms")

| Platform | Architecture |
| -------- | ------------ |
| Windows  | x64          |
| Linux    | x64          |

MigratorXpress ships as a native binary for each platform. No runtime installation (Python, Java, .NET) is required.

## See Also[​](#see-also "Direct link to See Also")

* [Quick Start Guide](/0.6/guides/quickstart.md) -- get started in 5 minutes
* [CLI Reference](/0.6/reference/cli-reference.md) -- all command-line options
* [Database Configuration](/0.6/configuration/database-configuration.md) -- connection setup for each database type


---

# Database Connections

MigratorXpress requires three database connections for every migration:

1. **Source Database** -- the database you are migrating from.
2. **Target Database** -- the database that receives the translated schema and data.
3. **Migration Tracking Database** -- a SQL Server database that records every migration step for auditing and resumability.

## Supported Databases[​](#supported-databases "Direct link to Supported Databases")

### Source Databases[​](#source-databases "Direct link to Source Databases")

| Database                                                     | Parallel Transfer Method | Notes                                                                              |
| ------------------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------- |
| **[PostgreSQL](/0.6/configuration/databases/postgresql.md)** | Ctid                     | No key column required                                                             |
| **[Oracle](/0.6/configuration/databases/oracle.md)**         | Rowid                    | Thin and thick client modes; requires `SELECT_CATALOG_ROLE` for parallel transfers |
| **[SQL Server](/0.6/configuration/databases/sql-server.md)** | Standard                 | Also usable as target and migration tracking                                       |
| **[Netezza](/0.6/configuration/databases/netezza.md)**       | NZDataSlice              | Source-only; default port 5480                                                     |

### Target Databases[​](#target-databases "Direct link to Target Databases")

| Database                                                     | Notes                                                                 |
| ------------------------------------------------------------ | --------------------------------------------------------------------- |
| **[PostgreSQL](/0.6/configuration/databases/postgresql.md)** | Default target for most migrations                                    |
| **[SQL Server](/0.6/configuration/databases/sql-server.md)** | Supports columnstore index options (`cci_threshold`, `aci_threshold`) |

### Migration Tracking Database[​](#migration-tracking-database "Direct link to Migration Tracking Database")

| Database                                                     | Notes                                                                          |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| **[SQL Server](/0.6/configuration/databases/sql-server.md)** | Required for all migrations; stores run history, task status, and resume state |

## Authentication File Format[​](#authentication-file-format "Direct link to Authentication File Format")

Create a JSON file containing one entry per database connection. Each entry has a unique identifier (the JSON key), a `ds_type`, an `auth_mode`, and an `info` object with connection details.

```
{
  "source_oracle": {
    "ds_type": "oracle",
    "auth_mode": "classic",
    "info": {
      "username": "$env{ORACLE_USER}",
      "password": "$env{ORACLE_PASSWORD}",
      "server": "oracle-prod.company.com",
      "port": 1521,
      "database": "PRODPDB"
    }
  },
  "source_postgres": {
    "ds_type": "postgres",
    "auth_mode": "classic",
    "info": {
      "username": "$env{PG_USER}",
      "password": "$env{PG_PASSWORD}",
      "server": "pg-prod.company.com",
      "port": 5432,
      "database": "analytics"
    }
  },
  "target_mssql": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "$env{MSSQL_USER}",
      "password": "$env{MSSQL_PASSWORD}",
      "server": "sql-host.company.com",
      "port": 1433,
      "database": "target_db"
    }
  },
  "source_netezza": {
    "ds_type": "netezza",
    "auth_mode": "classic",
    "info": {
      "username": "$env{NZ_USER}",
      "password": "$env{NZ_PASSWORD}",
      "server": "nz-host.company.com",
      "port": 5480,
      "database": "PROD_DB"
    }
  },
  "migration_tracking": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "$env{MIG_USER}",
      "password": "$env{MIG_PASSWORD}",
      "server": "sql-host.company.com",
      "port": 1433,
      "database": "migration_log"
    }
  }
}
```

Environment variable substitution

Use `$env{VAR_NAME}` in any string value to reference an environment variable at runtime. MigratorXpress raises an error if a referenced variable is not set. Plain-text values also work -- values without `$env{` are returned as-is.

```
# Linux
export ORACLE_USER="migrator"
export ORACLE_PASSWORD="SecureP@ssw0rd"

# Windows (PowerShell)
$env:ORACLE_USER = "migrator"
$env:ORACLE_PASSWORD = "SecureP@ssw0rd"
```

## Using the Auth File[​](#using-the-auth-file "Direct link to Using the Auth File")

Reference the file with `--auth` and point to individual entries by their ID:

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id source_oracle \
  --target_db_auth_id target_mssql \
  --migration_db_auth_id migration_tracking \
  --source_schema_name SALES \
  --target_schema_name sales \
  --task_list translate create transfer diff
```

## Security Best Practices[​](#security-best-practices "Direct link to Security Best Practices")

### 1. Credential Storage[​](#1-credential-storage "Direct link to 1. Credential Storage")

* Never commit credentials to version control.
* Restrict `credentials.json` permissions:
  <!-- -->
  ```
  chmod 600 credentials.json
  ```
* Use environment-specific auth files (dev, staging, prod).

### 2. Least Privilege[​](#2-least-privilege "Direct link to 2. Least Privilege")

* Create dedicated database users for MigratorXpress.
* Grant only SELECT on source databases.
* Grant CREATE, INSERT, UPDATE, DELETE on target databases.
* Use a dedicated SQL Server database for migration tracking.

### 3. Network Security[​](#3-network-security "Direct link to 3. Network Security")

* Use SSL/TLS connections where supported.
* Restrict database access by IP.
* Use VPN or private networks for cross-environment migrations.

### 4. Password Management[​](#4-password-management "Direct link to 4. Password Management")

* Use strong passwords (12+ characters, mixed case, numbers, symbols).
* Rotate passwords regularly.
* Consider secret managers (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault).

## See Also[​](#see-also "Direct link to See Also")

* [PostgreSQL](/0.6/configuration/databases/postgresql.md) -- Source and target configuration
* [Oracle](/0.6/configuration/databases/oracle.md) -- Source configuration with thin/thick modes
* [SQL Server](/0.6/configuration/databases/sql-server.md) -- Source, target, and migration tracking configuration
* [Netezza](/0.6/configuration/databases/netezza.md) -- Source configuration
* [Quick Start Guide](/0.6/guides/quickstart.md) -- Getting started with MigratorXpress
* [CLI Reference](/0.6/reference/cli-reference.md) -- Command-line options


---

# Netezza

Netezza is supported as a source-only database in MigratorXpress. It uses NZDataSlice-based parallel transfers for efficient extraction of large tables.

## Connection Parameters[​](#connection-parameters "Direct link to Connection Parameters")

| Parameter   | Required | Description                 |
| ----------- | -------- | --------------------------- |
| `ds_type`   | Yes      | Must be `"netezza"`         |
| `auth_mode` | Yes      | Must be `"classic"`         |
| `username`  | Yes      | Netezza username            |
| `password`  | Yes      | Netezza password            |
| `server`    | Yes      | Hostname or IP address      |
| `port`      | Yes      | Port number (default: 5480) |
| `database`  | Yes      | Database name               |

## NZDataSlice Parallel Transfer[​](#nzdataslice-parallel-transfer "Direct link to NZDataSlice Parallel Transfer")

Netezza distributes data across internal data slices. MigratorXpress leverages this architecture by reading from individual data slices in parallel, which significantly improves throughput for large tables. No key column is required -- the parallelism is based on Netezza's internal data distribution.

The number of parallel streams is controlled by the `--fasttransfer_p` parameter. For best results, set it to a value that aligns with the number of data slices on your Netezza appliance.

## Required Permissions[​](#required-permissions "Direct link to Required Permissions")

```
-- Grant read access to the migration user
GRANT SELECT ON TABLE schema_name.table_name TO migratorxpress_user;

-- Or grant list access for an entire schema
GRANT LIST ON schema_name TO migratorxpress_user;
GRANT SELECT ON schema_name TO migratorxpress_user;
```

## Example[​](#example "Direct link to Example")

```
{
  "netezza_prod": {
    "ds_type": "netezza",
    "auth_mode": "classic",
    "info": {
      "username": "$env{NZ_USER}",
      "password": "$env{NZ_PASSWORD}",
      "server": "nz-prod.company.com",
      "port": 5480,
      "database": "PROD_DB"
    }
  }
}
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**Connection refused:** Verify that the Netezza appliance is running and accessible. The default port is 5480, not the standard PostgreSQL port of 5432. Check firewall rules and network connectivity:

```
# Test connectivity
telnet nz-prod.company.com 5480
```

**Authentication failed:** Confirm the username and password are correct. Verify that the user has not been locked out and has the required permissions on the target database.

## See Also[​](#see-also "Direct link to See Also")

* [Database Connections Overview](/0.6/configuration/database-configuration.md) -- Auth file format and security best practices


---

# Oracle

Oracle is supported as a source database in MigratorXpress. It supports both thin and thick client modes and uses Rowid-based parallel transfers for large tables.

## Connection Parameters[​](#connection-parameters "Direct link to Connection Parameters")

| Parameter   | Required | Description                                       |
| ----------- | -------- | ------------------------------------------------- |
| `ds_type`   | Yes      | Must be `"oracle"`                                |
| `auth_mode` | Yes      | Must be `"classic"`                               |
| `username`  | Yes      | Oracle username                                   |
| `password`  | Yes      | Oracle password                                   |
| `server`    | Yes      | Hostname or IP address                            |
| `port`      | Yes      | Port number (default: 1521)                       |
| `database`  | Yes      | Service name or SID                               |
| `lib_dir`   | No       | Oracle Instant Client directory (thick mode only) |

## Thin vs Thick Mode[​](#thin-vs-thick-mode "Direct link to Thin vs Thick Mode")

**Thin Mode (Recommended):**

* No Oracle client libraries required on the machine running MigratorXpress.
* Requires Oracle 12.1 or later.
* Omit the `lib_dir` parameter.

**Thick Mode:**

* Required for Oracle 11.2 and earlier.
* Requires Oracle Instant Client installed locally.
* Set `lib_dir` to the Instant Client directory path.

## Required Permissions[​](#required-permissions "Direct link to Required Permissions")

Grant `SELECT_CATALOG_ROLE` to enable parallel Rowid-based transfers and metadata discovery:

```
-- As Oracle DBA (e.g., sys as sysdba)
GRANT SELECT_CATALOG_ROLE TO your_username;
```

This role provides access to data dictionary views needed for Rowid range partitioning and transfer method selection.

## Example: Thin Mode[​](#example-thin-mode "Direct link to Example: Thin Mode")

```
{
  "oracle_prod": {
    "ds_type": "oracle",
    "auth_mode": "classic",
    "info": {
      "username": "$env{ORACLE_USER}",
      "password": "$env{ORACLE_PASSWORD}",
      "server": "oracle-prod.company.com",
      "port": 1521,
      "database": "PRODPDB"
    }
  }
}
```

## Example: Thick Mode[​](#example-thick-mode "Direct link to Example: Thick Mode")

```
{
  "oracle_legacy": {
    "ds_type": "oracle",
    "auth_mode": "classic",
    "info": {
      "username": "$env{ORACLE_USER}",
      "password": "$env{ORACLE_PASSWORD}",
      "server": "oracle-11g.company.com",
      "port": 1521,
      "database": "LEGACY",
      "lib_dir": "/opt/oracle/instantclient_19_8"
    }
  }
}
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**ORA-12154: TNS could not resolve connect identifier:** Verify the service name in the `database` field. Check `tnsnames.ora` if applicable. Try using the IP address instead of the hostname and confirm the Oracle listener is running (`lsnrctl status`).

**ORA-28000: account is locked:**

```
ALTER USER your_username ACCOUNT UNLOCK;
```

**Thick mode library not found:** Verify that the `lib_dir` path exists and contains the Instant Client shared libraries. Confirm Oracle Instant Client is installed and check file permissions. On Linux, you may also need to set `LD_LIBRARY_PATH`:

```
export LD_LIBRARY_PATH=/opt/oracle/instantclient_19_8:$LD_LIBRARY_PATH
```

## See Also[​](#see-also "Direct link to See Also")

* [Database Connections Overview](/0.6/configuration/database-configuration.md) -- Auth file format and security best practices


---

# PostgreSQL

PostgreSQL can serve as both a source and a target database in MigratorXpress migrations. As a source, it supports Ctid-based parallel transfers for large tables.

## Connection Parameters[​](#connection-parameters "Direct link to Connection Parameters")

| Parameter   | Required | Description                 |
| ----------- | -------- | --------------------------- |
| `ds_type`   | Yes      | Must be `"postgres"`        |
| `auth_mode` | Yes      | `"classic"` or `"odbc"`     |
| `username`  | Yes      | PostgreSQL username         |
| `password`  | Yes      | PostgreSQL password         |
| `server`    | Yes      | Hostname or IP address      |
| `port`      | Yes      | Port number (default: 5432) |
| `database`  | Yes      | Database name               |

## Required Permissions[​](#required-permissions "Direct link to Required Permissions")

### As Source[​](#as-source "Direct link to As Source")

```
-- Grant read access to the migration user
GRANT USAGE ON SCHEMA public TO migratorxpress_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO migratorxpress_user;

-- For multiple schemas, repeat for each schema:
GRANT USAGE ON SCHEMA my_schema TO migratorxpress_user;
GRANT SELECT ON ALL TABLES IN SCHEMA my_schema TO migratorxpress_user;
```

### As Target[​](#as-target "Direct link to As Target")

```
-- Grant write access to the migration user
GRANT CREATE ON DATABASE target_db TO migratorxpress_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO migratorxpress_user;

-- If using a custom target schema:
CREATE SCHEMA IF NOT EXISTS target_schema;
GRANT ALL PRIVILEGES ON SCHEMA target_schema TO migratorxpress_user;
```

## Example: Classic Authentication[​](#example-classic-authentication "Direct link to Example: Classic Authentication")

```
{
  "postgres_source": {
    "ds_type": "postgres",
    "auth_mode": "classic",
    "info": {
      "username": "$env{PG_USER}",
      "password": "$env{PG_PASSWORD}",
      "server": "pg-prod.company.com",
      "port": 5432,
      "database": "analytics"
    }
  }
}
```

## Example: ODBC Mode[​](#example-odbc-mode "Direct link to Example: ODBC Mode")

When ODBC drivers are available, you can use ODBC mode for additional connection options:

```
{
  "postgres_odbc": {
    "ds_type": "postgres",
    "auth_mode": "odbc",
    "info": {
      "connection_string": "Driver={PostgreSQL};Server=pg-prod.company.com;Port=5432;Database=analytics;Uid=$env{PG_USER};Pwd=$env{PG_PASSWORD};"
    }
  }
}
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**Connection refused:** Check that PostgreSQL is running (`systemctl status postgresql`), verify `pg_hba.conf` allows connections from your IP, and check firewall rules (`sudo ufw allow 5432/tcp`).

**Authentication failed:** Verify credentials, check the password encryption method in `pg_hba.conf` (md5, scram-sha-256), and confirm the user exists:

```
SELECT * FROM pg_user WHERE usename = 'your_user';
```

## See Also[​](#see-also "Direct link to See Also")

* [Database Connections Overview](/0.6/configuration/database-configuration.md) -- Auth file format and security best practices


---

# PostgreSQL as Target

PostgreSQL is a fully supported migration target. MigratorXpress creates the target schema automatically and streams data via FastTransfer.

For the complete connection reference, authentication modes, and troubleshooting, see the canonical **[PostgreSQL](/0.6/configuration/databases/postgresql.md)** page.

## Target-specific Permissions[​](#target-specific-permissions "Direct link to Target-specific Permissions")

```
-- Grant write access to the migration user
GRANT CREATE ON DATABASE target_db TO migratorxpress_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO migratorxpress_user;

-- If using a custom target schema:
CREATE SCHEMA IF NOT EXISTS target_schema;
GRANT ALL PRIVILEGES ON SCHEMA target_schema TO migratorxpress_user;
```

## Example Auth Entry[​](#example-auth-entry "Direct link to Example Auth Entry")

```
{
  "postgres_target": {
    "ds_type": "postgres",
    "auth_mode": "classic",
    "info": {
      "username": "$env{PG_USER}",
      "password": "$env{PG_PASSWORD}",
      "server": "pg-target.company.com",
      "port": 5432,
      "database": "target_db"
    }
  }
}
```

Reference it on the command line with `--target_db_auth_id postgres_target`.

## See Also[​](#see-also "Direct link to See Also")

* [PostgreSQL](/0.6/configuration/databases/postgresql.md) -- full connection reference
* [Database Connections](/0.6/configuration/database-configuration.md) -- auth file format and security


---

# PostgreSQL as Migration Tracking

Since v0.6.32, the migration tracking database can be PostgreSQL in addition to SQL Server. The two backends share the same schema (table names, columns, foreign keys, the `v_sourcetargetdiff` view) and the same workflow (run history, per-table task status, row counts, constraint copy results, event logs, `--resume`). MigratorXpress auto-detects the backend from the `ds_type` of the auth entry referenced by `--migration_db_auth_id` -- no extra CLI flag is required.

For the full PostgreSQL connection reference (authentication modes, ODBC, troubleshooting), see the canonical **[PostgreSQL](/0.6/configuration/databases/postgresql.md)** page.

## Schema and Object Naming[​](#schema-and-object-naming "Direct link to Schema and Object Naming")

* Tracking tables and the `v_sourcetargetdiff` view live in the `public` schema.
* Types map to PG natives: `timestamp`, `text`, `boolean`, `varchar(N)`, `numeric(32,6)`.
* The internal sequence `seq_id_load` is a standard `CREATE SEQUENCE`.
* Idempotent DDL uses `CREATE TABLE IF NOT EXISTS`, `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`, `CREATE OR REPLACE VIEW`, and `INSERT ... ON CONFLICT DO UPDATE`.

## Tracking-specific Permissions[​](#tracking-specific-permissions "Direct link to Tracking-specific Permissions")

The tracking role needs full DDL/DML rights on the database hosting the tracking tables, because MigratorXpress creates tables, evolves the schema on upgrade, and writes rows continuously during a migration.

```
-- Full access to the migration tracking database
GRANT CREATE ON DATABASE migration_log TO migratorxpress_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO migratorxpress_user;
ALTER SCHEMA public OWNER TO migratorxpress_user;
```

If the role is not the schema owner, future schema upgrades (added columns, new tables) can fail with `permission denied for schema public`. Owning the schema (or granting `ALL` on it) avoids that.

## Migration DB Modes[​](#migration-db-modes "Direct link to Migration DB Modes")

The `--migration_db_mode` flag controls how MigratorXpress treats the tracking schema at startup. Behavior is identical on SQL Server and PostgreSQL.

| Mode                 | Behavior                                       |
| -------------------- | ---------------------------------------------- |
| `preserve` (default) | Keep tracking data; required to use `--resume` |
| `truncate`           | Clear data, keep schema                        |
| `drop`               | Drop and recreate the tracking schema          |

## Example Auth Entry[​](#example-auth-entry "Direct link to Example Auth Entry")

```
{
  "migration_tracking": {
    "ds_type": "postgres",
    "auth_mode": "classic",
    "info": {
      "username": "$env{MIG_USER}",
      "password": "$env{MIG_PASSWORD}",
      "server": "pg-host.company.com",
      "port": 5432,
      "database": "migration_log"
    }
  }
}
```

Reference it on the command line with `--migration_db_auth_id migration_tracking`. The rest of the CLI is unchanged.

## Querying the Tracking Tables[​](#querying-the-tracking-tables "Direct link to Querying the Tracking Tables")

The schema is the same across both backends, so any dashboard query that uses portable SQL (no `DATEDIFF`, `GETDATE()`, `TOP`, `+` for string concat) works on either. Example: list tables with errors for a given run.

```
SELECT src_tablename, eventmessage, eventtimestamp
FROM eventlog
WHERE eventrunid = '20260511-...'
  AND eventstatus = 'failed'
ORDER BY eventtimestamp DESC;
```

For PG-specific date arithmetic and other reporting patterns, see [Logging and Monitoring](/0.6/reference/logging.md).

## See Also[​](#see-also "Direct link to See Also")

* [PostgreSQL](/0.6/configuration/databases/postgresql.md) -- full connection reference
* [SQL Server as Migration Tracking](/0.6/configuration/databases/sql-server-as-tracking.md) -- equivalent doc for the SQL Server backend
* [Database Connections](/0.6/configuration/database-configuration.md) -- auth file format and security
* [Logging and Monitoring](/0.6/reference/logging.md) -- schema details and dashboard queries


---

# SQL Server

SQL Server is the most versatile database in MigratorXpress -- it can serve as a source, a target, and the migration tracking database.

## Connection Parameters[​](#connection-parameters "Direct link to Connection Parameters")

| Parameter   | Required | Description                                                    |
| ----------- | -------- | -------------------------------------------------------------- |
| `ds_type`   | Yes      | Must be `"mssql"`                                              |
| `auth_mode` | Yes      | `"classic"`, `"odbc"`, or `"connection_string"`                |
| `username`  | Yes\*    | SQL Server username (\*not required for Windows auth via ODBC) |
| `password`  | Yes\*    | SQL Server password (\*not required for Windows auth via ODBC) |
| `server`    | Yes      | Hostname or IP address                                         |
| `port`      | Yes      | Port number (default: 1433)                                    |
| `database`  | Yes      | Database name                                                  |

note

SQL Server is the only database that can fill all three roles in a MigratorXpress migration. You can even use the same SQL Server instance for source, target, and migration tracking by creating separate database entries in your auth file.

## Required Permissions[​](#required-permissions "Direct link to Required Permissions")

### As Source[​](#as-source "Direct link to As Source")

```
-- Grant read access for data transfer and schema discovery
GRANT SELECT ON SCHEMA::dbo TO migratorxpress_user;
GRANT VIEW DEFINITION ON SCHEMA::dbo TO migratorxpress_user;
```

### As Target[​](#as-target "Direct link to As Target")

```
-- Grant permissions for schema creation and data loading
GRANT CREATE TABLE TO migratorxpress_user;
GRANT ALTER ON SCHEMA::dbo TO migratorxpress_user;
GRANT INSERT ON SCHEMA::dbo TO migratorxpress_user;
GRANT UPDATE ON SCHEMA::dbo TO migratorxpress_user;
GRANT DELETE ON SCHEMA::dbo TO migratorxpress_user;
```

### As Migration Tracking[​](#as-migration-tracking "Direct link to As Migration Tracking")

```
-- Full access to the migration tracking database
ALTER ROLE db_owner ADD MEMBER migratorxpress_user;
```

The migration tracking user needs full access to create and manage the internal tables that track migration runs, task statuses, and resume state.

## Example: Classic Authentication[​](#example-classic-authentication "Direct link to Example: Classic Authentication")

```
{
  "mssql_target": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "$env{MSSQL_USER}",
      "password": "$env{MSSQL_PASSWORD}",
      "server": "sql-prod.company.com",
      "port": 1433,
      "database": "TargetDB"
    }
  }
}
```

## Example: Windows Trusted Authentication (ODBC)[​](#example-windows-trusted-authentication-odbc "Direct link to Example: Windows Trusted Authentication (ODBC)")

Use ODBC mode with `Trusted_Connection=yes` for Windows integrated authentication:

```
{
  "mssql_trusted": {
    "ds_type": "mssql",
    "auth_mode": "odbc",
    "info": {
      "connection_string": "Driver={ODBC Driver 17 for SQL Server};Server=sql-prod.company.com;Database=TargetDB;Trusted_Connection=yes;"
    }
  }
}
```

## Example: Connection String Mode[​](#example-connection-string-mode "Direct link to Example: Connection String Mode")

For full control over the connection string:

```
{
  "mssql_connstr": {
    "ds_type": "mssql",
    "auth_mode": "connection_string",
    "info": {
      "connection_string": "Driver={ODBC Driver 17 for SQL Server};Server=sql-prod.company.com,1433;Database=TargetDB;Uid=$env{MSSQL_USER};Pwd=$env{MSSQL_PASSWORD};Encrypt=yes;TrustServerCertificate=no;"
    }
  }
}
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**Login failed for user:** Confirm that SQL Server authentication mode is set to "SQL Server and Windows Authentication" (mixed mode), not Windows-only. Verify the user exists with the correct permissions and check for IP restrictions.

**Cannot open database requested by the login:** Verify the database name, check that the user has been granted access, and confirm the database is online:

```
SELECT name, state_desc FROM sys.databases WHERE name = 'YourDB';
```

## See Also[​](#see-also "Direct link to See Also")

* [Database Connections Overview](/0.6/configuration/database-configuration.md) -- Auth file format and security best practices


---

# SQL Server as Target

SQL Server is a fully supported migration target. MigratorXpress creates the target schema, streams data via FastTransfer, and can apply Clustered Columnstore Index (CCI) or archive compression based on row-count thresholds.

For the complete connection reference, authentication modes (classic / ODBC / connection string), and troubleshooting, see the canonical **[SQL Server](/0.6/configuration/databases/sql-server.md)** page.

## Target-specific Permissions[​](#target-specific-permissions "Direct link to Target-specific Permissions")

```
-- Grant permissions for schema creation and data loading
GRANT CREATE TABLE TO migratorxpress_user;
GRANT ALTER ON SCHEMA::dbo TO migratorxpress_user;
GRANT INSERT ON SCHEMA::dbo TO migratorxpress_user;
GRANT UPDATE ON SCHEMA::dbo TO migratorxpress_user;
GRANT DELETE ON SCHEMA::dbo TO migratorxpress_user;
```

## Target-specific CLI Options[​](#target-specific-cli-options "Direct link to Target-specific CLI Options")

| Option                                   | Purpose                                                                |
| ---------------------------------------- | ---------------------------------------------------------------------- |
| `--cci_threshold N`                      | Create a Clustered Columnstore Index when a table has more than N rows |
| `--aci_threshold N`                      | Apply archive compression when a table has more than N rows            |
| `--fk_mode {disabled,untrusted,trusted}` | Foreign-key enforcement strategy after `copy_fk`                       |

## Example Auth Entry[​](#example-auth-entry "Direct link to Example Auth Entry")

```
{
  "mssql_target": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "$env{MSSQL_USER}",
      "password": "$env{MSSQL_PASSWORD}",
      "server": "sql-target.company.com",
      "port": 1433,
      "database": "TargetDB"
    }
  }
}
```

Reference it on the command line with `--target_db_auth_id mssql_target`.

## See Also[​](#see-also "Direct link to See Also")

* [SQL Server](/0.6/configuration/databases/sql-server.md) -- full connection reference
* [Database Connections](/0.6/configuration/database-configuration.md) -- auth file format and security


---

# SQL Server as Migration Tracking

The migration tracking database is required for every MigratorXpress migration and **must be SQL Server**. It records run history, per-table task status, row counts, constraint copy results, and event logs. This database also enables `--resume` for interrupted migrations.

For the complete connection reference, authentication modes (classic / ODBC / connection string), and troubleshooting, see the canonical **[SQL Server](/0.6/configuration/databases/sql-server.md)** page.

## Tracking-specific Permissions[​](#tracking-specific-permissions "Direct link to Tracking-specific Permissions")

```
-- Full access to the migration tracking database
ALTER ROLE db_owner ADD MEMBER migratorxpress_user;
```

The tracking user needs full access to create and manage the internal tables that record migration runs, task statuses, and resume state.

## Migration DB Modes[​](#migration-db-modes "Direct link to Migration DB Modes")

The `--migration_db_mode` flag controls how MigratorXpress treats the tracking schema at startup.

| Mode                 | Behavior                                       |
| -------------------- | ---------------------------------------------- |
| `preserve` (default) | Keep tracking data; required to use `--resume` |
| `truncate`           | Clear data, keep schema                        |
| `drop`               | Drop and recreate the tracking schema          |

## Example Auth Entry[​](#example-auth-entry "Direct link to Example Auth Entry")

```
{
  "migration_tracking": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "$env{MIG_USER}",
      "password": "$env{MIG_PASSWORD}",
      "server": "sql-host.company.com",
      "port": 1433,
      "database": "migration_log"
    }
  }
}
```

Reference it on the command line with `--migration_db_auth_id migration_tracking`.

## See Also[​](#see-also "Direct link to See Also")

* [SQL Server](/0.6/configuration/databases/sql-server.md) -- full connection reference
* [Database Connections](/0.6/configuration/database-configuration.md) -- auth file format and security


---

# FastTransfer Configuration

MigratorXpress delegates all data movement to [FastTransfer](https://www.arpe.io/fasttransfer/) (>= 0.15.0 required), which uses a streaming architecture. Rows flow directly from source to target without being buffered entirely in memory, so tables with billions of rows can be transferred on modest hardware.

## FastTransfer Location[​](#fasttransfer-location "Direct link to FastTransfer Location")

Point `--fasttransfer_dir_path` to the directory containing the FastTransfer binary. Since v0.6.25, if this flag is omitted, MigratorXpress auto-detects a bundled FastTransfer in the `engine/` subdirectory next to the binary. Trial distributions ship with FastTransfer pre-bundled.

## Key Parameters[​](#key-parameters "Direct link to Key Parameters")

| Parameter                 | Type    | Default       | Description                                                                 |
| ------------------------- | ------- | ------------- | --------------------------------------------------------------------------- |
| `--fasttransfer_dir_path` | Path    | Auto-detected | Directory containing the FastTransfer binary                                |
| `--fasttransfer_p`        | Integer | 1             | Number of parallel streams within FastTransfer for large table partitioning |
| `--ft_large_table_th`     | Integer | 250,000,000   | Row count threshold above which a table is eligible for parallel transfer   |
| `--n_jobs`                | Integer | 1             | Number of tables to transfer simultaneously                                 |

### Dual-Level Parallelism[​](#dual-level-parallelism "Direct link to Dual-Level Parallelism")

MigratorXpress supports two levels of parallelism:

* **`--n_jobs`** controls how many tables are transferred concurrently.
* **`--fasttransfer_p`** controls how many parallel streams each large table uses internally.

For example, `--n_jobs 4 --fasttransfer_p 2` transfers 4 tables simultaneously, and any table above the large table threshold is split into 2 parallel streams.

## Parallel Transfer Methods[​](#parallel-transfer-methods "Direct link to Parallel Transfer Methods")

Each source database uses a different method to partition tables for parallel transfer:

| Source Database | Method      | Key Column Required | Description                                              |
| --------------- | ----------- | ------------------- | -------------------------------------------------------- |
| PostgreSQL      | Ctid        | No                  | Splits by physical tuple ID                              |
| Oracle          | Rowid       | No                  | Splits by physical ROWID; requires `SELECT_CATALOG_ROLE` |
| Netezza         | NZDataSlice | No                  | Splits by internal data slice distribution               |
| SQL Server      | Standard    | N/A                 | Standard transfer without physical partitioning          |

### Method Selection Logic[​](#method-selection-logic "Direct link to Method Selection Logic")

MigratorXpress selects the parallel transfer method automatically based on the source database type. No manual configuration is needed. If `--fasttransfer_p` is set to 1 or the table row count is below `--ft_large_table_th`, the table is transferred as a single stream regardless of the source type.

## Performance Tuning[​](#performance-tuning "Direct link to Performance Tuning")

### PostgreSQL Sources[​](#postgresql-sources "Direct link to PostgreSQL Sources")

Ctid-based parallelism works well with minimal configuration. Increase `--fasttransfer_p` for tables with hundreds of millions of rows. Start with 2-4 parallel streams and scale up based on available CPU and I/O bandwidth.

### Oracle Sources[​](#oracle-sources "Direct link to Oracle Sources")

Rowid-based parallelism requires `SELECT_CATALOG_ROLE` (see [Oracle configuration](/0.6/configuration/databases/oracle.md)). Oracle parallel transfers benefit from higher stream counts on large tables. Consider 4-8 streams for tables exceeding 100M rows.

### Netezza Sources[​](#netezza-sources "Direct link to Netezza Sources")

NZDataSlice parallelism aligns with Netezza's internal data distribution. Set `--fasttransfer_p` to match or be a factor of the number of data slices on the appliance.

### SQL Server Sources[​](#sql-server-sources "Direct link to SQL Server Sources")

SQL Server uses standard (non-partitioned) transfers. Parallelism is achieved at the table level via `--n_jobs`. For SQL Server sources, increase `--n_jobs` rather than `--fasttransfer_p`.

## SQL Server Target Options[​](#sql-server-target-options "Direct link to SQL Server Target Options")

When SQL Server is the target database, MigratorXpress supports additional options for columnstore indexes and foreign key handling.

### Columnstore Indexes[​](#columnstore-indexes "Direct link to Columnstore Indexes")

| Parameter         | Type    | Default     | Description                                                         |
| ----------------- | ------- | ----------- | ------------------------------------------------------------------- |
| `--cci_threshold` | Integer | 1,000,000   | Create Clustered Columnstore Index for tables above this row count  |
| `--aci_threshold` | Integer | 100,000,000 | Use archive compression (COLUMNSTORE\_ARCHIVE) above this row count |

Tables >= `cci_threshold` but < `aci_threshold` get a standard CCI. Tables >= `aci_threshold` get a CCI with `DATA_COMPRESSION = COLUMNSTORE_ARCHIVE`. Tables below `cci_threshold` remain as standard rowstore tables.

### Foreign Key Mode[​](#foreign-key-mode "Direct link to Foreign Key Mode")

| Parameter   | Type   | Default    | Description                                                                                                                     |
| ----------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `--fk_mode` | String | `disabled` | FK enforcement: `disabled` (created with NOCHECK and disabled), `untrusted` (NOCHECK but enabled), `trusted` (full enforcement) |

## Row Count Options[​](#row-count-options "Direct link to Row Count Options")

| Parameter          | Type    | Default | Description                                                       |
| ------------------ | ------- | ------- | ----------------------------------------------------------------- |
| `--compute_nbrows` | Boolean | false   | Use `COUNT(*)` for exact row counts instead of database estimates |
| `--without_xid`    | Flag    | false   | Disable transaction ID usage in Netezza and Oracle                |

## Configuration Examples[​](#configuration-examples "Direct link to Configuration Examples")

### Small Migration (< 10 tables, < 1M rows total)[​](#small-migration--10-tables--1m-rows-total "Direct link to Small Migration (< 10 tables, < 1M rows total)")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name HR \
  --target_db_auth_id postgres_dev \
  --target_schema_name hr \
  --fasttransfer_dir_path ./FastTransfer_linux-x64_v0.12.4/ \
  --migration_db_auth_id ms_mig_log \
  --task_list translate create transfer diff
```

Default parallelism is sufficient. Single-stream transfer per table, one table at a time.

### Medium Migration (10-100 tables, up to 100M rows)[​](#medium-migration-10-100-tables-up-to-100m-rows "Direct link to Medium Migration (10-100 tables, up to 100M rows)")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name SALES \
  --target_db_auth_id postgres_dev \
  --target_schema_name sales \
  --fasttransfer_dir_path ./FastTransfer_linux-x64_v0.12.4/ \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --fasttransfer_p 2 \
  --task_list translate create transfer diff
```

Four tables in parallel, large tables split into 2 streams each.

### Large Migration (100+ tables, billions of rows)[​](#large-migration-100-tables-billions-of-rows "Direct link to Large Migration (100+ tables, billions of rows)")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name WAREHOUSE \
  --target_db_auth_id postgres_dev \
  --target_schema_name warehouse \
  --fasttransfer_dir_path ./FastTransfer_linux-x64_v0.12.4/ \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 8 \
  --fasttransfer_p 4 \
  --ft_large_table_th 500000 \
  --task_list translate create transfer diff
```

Eight tables in parallel, large tables (> 500K rows) split into 4 streams. Adjust thresholds based on hardware capacity.

## Monitoring Performance[​](#monitoring-performance "Direct link to Monitoring Performance")

During and after a migration, you can query the migration tracking database to check progress and identify slow tables.

### Check Overall Progress[​](#check-overall-progress "Direct link to Check Overall Progress")

```
SELECT
    task_name,
    COUNT(*) AS total_tables,
    SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) AS completed,
    SUM(CASE WHEN status = 'running' THEN 1 ELSE 0 END) AS running,
    SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failed
FROM migration_tasks
WHERE run_id = 'YOUR_RUN_ID'
GROUP BY task_name;
```

### Identify Slow Tables[​](#identify-slow-tables "Direct link to Identify Slow Tables")

```
SELECT
    table_name,
    task_name,
    DATEDIFF(SECOND, start_time, ISNULL(end_time, GETDATE())) AS duration_seconds,
    row_count
FROM migration_tasks
WHERE run_id = 'YOUR_RUN_ID'
    AND task_name = 'transfer'
ORDER BY duration_seconds DESC;
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**FastTransfer binary not found:** Verify the `--fasttransfer_dir_path` points to the correct directory containing the FastTransfer executable. Check file permissions and ensure the binary is executable (`chmod +x FastTransfer` on Linux).

**Transfer stalls on large tables:** Reduce `--fasttransfer_p` if the source or target database is under heavy load. Check network bandwidth between the MigratorXpress host and the databases.

**Out of memory errors:** FastTransfer's streaming architecture normally prevents memory issues. If they occur, reduce `--n_jobs` to lower the number of concurrent table transfers.

**Slow transfer throughput:**

* Increase `--fasttransfer_p` for large tables.
* Increase `--n_jobs` if the bottleneck is small-table overhead rather than individual table speed.
* Check that the network path between source and target is not saturated.
* Verify that the source database is not under heavy concurrent load.

## See Also[​](#see-also "Direct link to See Also")

* [Migration Tasks](/0.6/configuration/migration-tasks.md) -- Task execution order and combinations
* [Database Connections](/0.6/configuration/database-configuration.md) -- Auth file configuration
* [Quick Start Guide](/0.6/guides/quickstart.md) -- Getting started with MigratorXpress
* [CLI Reference](/0.6/reference/cli-reference.md) -- Full command-line reference


---

# Migration Tasks

MigratorXpress organizes migrations into discrete tasks. You specify which tasks to run with the `--task_list` parameter, and MigratorXpress executes them in the order listed. Use `--task_list all` as a shortcut for the full sequence.

## Available Tasks[​](#available-tasks "Direct link to Available Tasks")

| Task        | Description                                                               | When to Use                 |
| ----------- | ------------------------------------------------------------------------- | --------------------------- |
| `translate` | Convert source DDL to the target platform's SQL dialect                   | First step of any migration |
| `create`    | Create tables in the target database using the translated DDL             | After translation           |
| `transfer`  | Copy data from source to target (requires FastTransfer)                   | After tables are created    |
| `diff`      | Validate data integrity by comparing row counts between source and target | After transfer              |
| `copy_pk`   | Copy primary key constraints to the target database                       | After transfer              |
| `copy_ak`   | Copy alternate key (unique) constraints to the target database            | After primary keys          |
| `copy_fk`   | Copy foreign key constraints to the target database                       | After all other keys        |

## Task Dependencies and Recommended Order[​](#task-dependencies-and-recommended-order "Direct link to Task Dependencies and Recommended Order")

Tasks should follow a logical sequence. Running them out of order will cause failures -- for example, `transfer` fails if the target tables do not exist yet.

**Recommended full migration order:**

```
translate → create → transfer → diff → copy_pk → copy_ak → copy_fk
```

The `diff` task is optional but recommended. It provides a quick sanity check before committing to constraint creation.

Constraint copying limitations

Constraint copying (`copy_pk`, `copy_ak`, `copy_fk`) is currently supported only for Oracle to SQL Server migrations. For other migration paths, create constraints manually on the target database after the data transfer.

## Common Task Combinations[​](#common-task-combinations "Direct link to Common Task Combinations")

### Full Migration[​](#full-migration "Direct link to Full Migration")

Translate the schema, create tables, transfer data, and validate:

```
--task_list translate create transfer diff
```

### Schema Only[​](#schema-only "Direct link to Schema Only")

Translate and create tables without transferring data. Useful for validating the DDL translation before committing to a full migration:

```
--task_list translate create
```

### Data Only[​](#data-only "Direct link to Data Only")

Transfer data into existing tables. The schema must already exist in the target database:

```
--task_list transfer
```

### Data Append (Load Mode)[​](#data-append-load-mode "Direct link to Data Append (Load Mode)")

Transfer data without dropping or truncating existing tables. Use `--load_mode append` to insert rows into existing tables:

```
--task_list transfer --load_mode append
```

### Constraints Only[​](#constraints-only "Direct link to Constraints Only")

Copy constraints after a successful data transfer. Run this as a separate step to avoid constraint violations during the initial load:

```
--task_list copy_pk copy_ak copy_fk
```

## Migration Database Modes[​](#migration-database-modes "Direct link to Migration Database Modes")

The `--drop_tables_if_exists` parameter controls how MigratorXpress handles existing tables in the target database:

| Value   | Behavior                                         |
| ------- | ------------------------------------------------ |
| `true`  | Drop and recreate target tables before migration |
| `false` | Fail if target tables already exist (default)    |

For iterative development and testing, `--drop_tables_if_exists true` is convenient. For production migrations, leave it as `false` and manage table lifecycle explicitly.

## Resume Functionality[​](#resume-functionality "Direct link to Resume Functionality")

If a migration fails partway through, you can resume from the point of failure instead of starting over:

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_db_name ORCL \
  --target_db_auth_id postgres_dev \
  --target_db_name tpch \
  --migration_db_auth_id ms_mig_log \
  --resume 20260203-cf5be0ac-159f-4dad-861e-8b2b6f3868d7
```

MigratorXpress skips tasks and tables that already completed successfully and resumes from the first incomplete item. Since v0.6.22, you do not need to specify `--task_list` or `--source_schema_name` when resuming -- they are retrieved automatically from the migration database.

tip

The run ID is displayed in the console output when the migration starts (format: `YYYYMMDD-{uuid}`). You can also query the migration tracking database to find it.

## Full Example[​](#full-example "Direct link to Full Example")

A complete Oracle-to-PostgreSQL migration in two steps -- first data, then constraints:

```
# Step 1: Schema, data, and validation
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name SALES \
  --target_db_auth_id postgres_dev \
  --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

# Step 2: Constraints (after verifying diff results)
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name SALES \
  --target_db_auth_id postgres_dev \
  --target_schema_name sales \
  --migration_db_auth_id ms_mig_log \
  --task_list copy_pk copy_ak copy_fk
```

## See Also[​](#see-also "Direct link to See Also")

* [FastTransfer Configuration](/0.6/configuration/fasttransfer-configuration.md) -- Parallel transfer tuning and performance
* [Database Connections](/0.6/configuration/database-configuration.md) -- Auth file configuration
* [Quick Start Guide](/0.6/guides/quickstart.md) -- Getting started with MigratorXpress
* [CLI Reference](/0.6/reference/cli-reference.md) -- Full command-line reference


---

# Examples and use cases

Complete command examples for every supported migration path, plus advanced scenarios. Each example assumes you already have a `credentials.json` file configured (see the [Quick Start Guide](/0.6/guides/quickstart.md)).

***

## Oracle to PostgreSQL[​](#oracle-to-postgresql "Direct link to Oracle to PostgreSQL")

Full schema and data migration with validation.

### Linux[​](#linux "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name HR \
  --target_db_auth_id postgres_dev \
  --target_schema_name hr \
  --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)[​](#windows-powershell "Direct link to Windows (PowerShell)")

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

***

## Oracle to SQL Server[​](#oracle-to-sql-server "Direct link to Oracle to SQL Server")

Two-phase approach: transfer data first, then add constraints.

### Phase 1: Schema and data[​](#phase-1-schema-and-data "Direct link to Phase 1: Schema and data")

#### Linux[​](#linux-1 "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name FINANCE \
  --target_db_auth_id mssql_target \
  --target_schema_name finance \
  --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)[​](#windows-powershell-1 "Direct link to Windows (PowerShell)")

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

### Phase 2: Constraints[​](#phase-2-constraints "Direct link to Phase 2: Constraints")

#### Linux[​](#linux-2 "Direct link to Linux")

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

#### Windows (PowerShell)[​](#windows-powershell-2 "Direct link to Windows (PowerShell)")

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

***

## PostgreSQL to PostgreSQL[​](#postgresql-to-postgresql "Direct link to PostgreSQL to PostgreSQL")

Clone a schema across servers or within the same server.

### Linux[​](#linux-3 "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id postgres_prod \
  --source_schema_name public \
  --target_db_auth_id postgres_staging \
  --target_schema_name public_copy \
  --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)[​](#windows-powershell-3 "Direct link to Windows (PowerShell)")

```
.\MigratorXpress.exe --auth .\credentials.json `
  --source_db_auth_id postgres_prod `
  --source_schema_name public `
  --target_db_auth_id postgres_staging `
  --target_schema_name public_copy `
  --migration_db_auth_id ms_mig_log `
  --n_jobs 4 `
  --fasttransfer_p 2 `
  --drop_tables_if_exists true `
  --task_list translate create transfer diff
```

***

## PostgreSQL to SQL Server[​](#postgresql-to-sql-server "Direct link to PostgreSQL to SQL Server")

### Linux[​](#linux-4 "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id postgres_prod \
  --source_schema_name analytics \
  --target_db_auth_id mssql_target \
  --target_schema_name analytics \
  --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)[​](#windows-powershell-4 "Direct link to Windows (PowerShell)")

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

***

## SQL Server to PostgreSQL[​](#sql-server-to-postgresql "Direct link to SQL Server to PostgreSQL")

### Linux[​](#linux-5 "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id mssql_source \
  --source_schema_name dbo \
  --target_db_auth_id postgres_dev \
  --target_schema_name dbo_migrated \
  --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)[​](#windows-powershell-5 "Direct link to Windows (PowerShell)")

```
.\MigratorXpress.exe --auth .\credentials.json `
  --source_db_auth_id mssql_source `
  --source_schema_name dbo `
  --target_db_auth_id postgres_dev `
  --target_schema_name dbo_migrated `
  --migration_db_auth_id ms_mig_log `
  --n_jobs 4 `
  --fasttransfer_p 2 `
  --drop_tables_if_exists true `
  --task_list translate create transfer diff
```

***

## Netezza to PostgreSQL[​](#netezza-to-postgresql "Direct link to Netezza to PostgreSQL")

### Linux[​](#linux-6 "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id netezza_source \
  --source_schema_name ADMIN \
  --target_db_auth_id postgres_dev \
  --target_schema_name admin \
  --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)[​](#windows-powershell-6 "Direct link to Windows (PowerShell)")

```
.\MigratorXpress.exe --auth .\credentials.json `
  --source_db_auth_id netezza_source `
  --source_schema_name ADMIN `
  --target_db_auth_id postgres_dev `
  --target_schema_name admin `
  --migration_db_auth_id ms_mig_log `
  --n_jobs 4 `
  --fasttransfer_p 2 `
  --drop_tables_if_exists true `
  --task_list translate create transfer diff
```

***

## Netezza to SQL Server[​](#netezza-to-sql-server "Direct link to Netezza to SQL Server")

### Linux[​](#linux-7 "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id netezza_source \
  --source_schema_name WAREHOUSE \
  --target_db_auth_id mssql_target \
  --target_schema_name warehouse \
  --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)[​](#windows-powershell-7 "Direct link to Windows (PowerShell)")

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

***

## SQL Server to SQL Server[​](#sql-server-to-sql-server "Direct link to SQL Server to SQL Server")

Clone or migrate schemas between SQL Server instances.

### Linux[​](#linux-8 "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id mssql_source \
  --source_schema_name dbo \
  --target_db_auth_id mssql_target \
  --target_schema_name dbo \
  --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)[​](#windows-powershell-8 "Direct link to Windows (PowerShell)")

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

***

## Advanced scenarios[​](#advanced-scenarios "Direct link to Advanced scenarios")

### Incremental data sync[​](#incremental-data-sync "Direct link to Incremental data sync")

Re-run only the `transfer` and `diff` tasks to refresh data without recreating tables. Useful for periodic syncs during a phased migration.

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

tip

Use `--drop_tables_if_exists true` with `transfer` to truncate and reload. Omit it if the target tables support upsert logic in your workflow.

### Schema-only migration[​](#schema-only-migration "Direct link to Schema-only migration")

Translate and create the schema without transferring any data. Useful for reviewing the translated DDL before committing to a full migration.

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name INVENTORY \
  --target_db_auth_id postgres_dev \
  --target_schema_name inventory \
  --migration_db_auth_id ms_mig_log \
  --drop_tables_if_exists true \
  --task_list translate create
```

### Parallel large tables[​](#parallel-large-tables "Direct link to Parallel large tables")

For schemas with very large tables, increase both parallelism levels:

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name EVENTS \
  --target_db_auth_id postgres_dev \
  --target_schema_name events \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 8 \
  --fasttransfer_p 4 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff
```

* `--n_jobs 8` migrates up to 8 tables concurrently.
* `--fasttransfer_p 4` splits each table into 4 partitions for parallel transfer.

warning

Higher parallelism increases load on both the source and target databases. Monitor CPU and I/O during large migrations and adjust values as needed.

### Multi-schema patterns[​](#multi-schema-patterns "Direct link to Multi-schema patterns")

Migrate multiple schemas in one run (v0.6.12+):

```
# All schemas starting with "app_"
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name "app_%" \
  --target_db_auth_id postgres_dev \
  --target_schema_name "app_%" \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff
```

```
# Every schema in the database
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name "%" \
  --target_db_auth_id postgres_dev \
  --target_schema_name "%" \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff
```

***

## Best practices[​](#best-practices "Direct link to Best practices")

1. **Migrate data before constraints.** Run `translate create transfer diff` first, then `copy_pk copy_ak copy_fk` in a separate step. This avoids constraint-violation errors during bulk loading.

2. **Start with a small schema.** Test the full workflow on a schema with a few tables before migrating a large production database.

3. **Use `diff` to validate.** Always include `diff` in your task list to verify row counts match between source and target.

4. **Tune parallelism gradually.** Begin with `--n_jobs 2 --fasttransfer_p 2` and increase based on observed throughput and system load.

5. **Secure your credentials file.** Use `$env{VAR_NAME}` references instead of plain-text passwords, and restrict file permissions to the migration user.

6. **Review translated DDL.** Run a `translate`-only step first to inspect the generated DDL before creating tables on the target.

## Next steps[​](#next-steps "Direct link to Next steps")

* [Quick Start Guide](/0.6/guides/quickstart.md) -- step-by-step setup
* [CLI Reference](/0.6/reference/cli-reference.md) -- all available options and flags
* [Command Wizard](/0.6/wizard.md) -- build your command interactively


---

# Quick start guide

Three steps: create a credentials file, run a full migration, then add constraints.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

1. **MigratorXpress binary** (Windows or Linux) downloaded from [arpe.io](https://www.arpe.io/migratorxpress/)
2. **Database access** -- read access on the source, write access on the target, and a SQL Server database for migration tracking
3. **FastTransfer binary** (>= 0.15.0) -- MigratorXpress calls FastTransfer for data movement. Trial distributions include FastTransfer in the `engine/` directory. Otherwise, place it in a known directory and pass `--fasttransfer_dir_path`

## Step 1: Create a credentials file[​](#step-1-create-a-credentials-file "Direct link to 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": "$env{ORA_USER}",
      "password": "$env{ORA_PASSWORD}",
      "server": "oracle-host.example.com",
      "port": 1521,
      "database": "ORCL"
    }
  },
  "postgres_dev": {
    "ds_type": "postgres",
    "auth_mode": "classic",
    "info": {
      "username": "$env{PG_USER}",
      "password": "$env{PG_PASSWORD}",
      "server": "pg-host.example.com",
      "port": 5432,
      "database": "analytics"
    }
  },
  "mssql_target": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "$env{MSSQL_USER}",
      "password": "$env{MSSQL_PASSWORD}",
      "server": "sql-host.example.com",
      "port": 1433,
      "database": "target_db"
    }
  },
  "ms_mig_log": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "$env{MIG_LOG_USER}",
      "password": "$env{MIG_LOG_PASSWORD}",
      "server": "sql-host.example.com",
      "port": 1433,
      "database": "migration_log"
    }
  },
  "netezza_source": {
    "ds_type": "netezza",
    "auth_mode": "classic",
    "info": {
      "username": "$env{NZ_USER}",
      "password": "$env{NZ_PASSWORD}",
      "server": "nz-host.example.com",
      "port": 5480,
      "database": "PROD_DB"
    }
  }
}
```

Save the file as `credentials.json` in a secure location.

Environment variables

Use `$env{VAR_NAME}` in any string value to reference an environment variable at runtime. MigratorXpress raises an error if the variable is not set. Plain-text values also work if you prefer.

```
# Linux
export ORA_USER="system"
export ORA_PASSWORD="your_password"

# Windows (PowerShell)
$env:ORA_USER = "system"
$env:ORA_PASSWORD = "your_password"
```

## Step 2: Run a full migration[​](#step-2-run-a-full-migration "Direct link to Step 2: Run a full migration")

Migrate an Oracle schema to PostgreSQL -- translate the DDL, create tables, transfer data, and validate.

### Linux[​](#linux "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name SALES \
  --target_db_auth_id postgres_dev \
  --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)[​](#windows-powershell "Direct link to Windows (PowerShell)")

```
.\MigratorXpress.exe --auth .\credentials.json `
  --source_db_auth_id oracle_prod `
  --source_schema_name SALES `
  --target_db_auth_id postgres_dev `
  --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 schema translation, table creation, data transfer, and row-count validation.

## Step 3: Add constraints[​](#step-3-add-constraints "Direct link to Step 3: Add constraints")

Once data is transferred and validated, copy primary keys, alternate keys, and foreign keys in a separate step. This avoids constraint violations during the initial load.

### Linux[​](#linux-1 "Direct link to Linux")

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

### Windows (PowerShell)[​](#windows-powershell-1 "Direct link to Windows (PowerShell)")

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

## Advanced: Multi-schema migration[​](#advanced-multi-schema-migration "Direct link to Advanced: Multi-schema migration")

Starting with v0.6.12, you can migrate multiple schemas in one run using SQL `LIKE` patterns for `--source_schema_name`:

### Linux[​](#linux-2 "Direct link to 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 postgres_dev \
  --target_schema_name "app_%" \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff
```

### Windows (PowerShell)[​](#windows-powershell-2 "Direct link to 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 postgres_dev `
  --target_schema_name "app_%" `
  --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

## Next steps[​](#next-steps "Direct link to Next steps")

* [CLI Reference](/0.6/reference/cli-reference.md) -- all available options and flags
* [Examples & Use Cases](/0.6/guides/examples.md) -- real-world migration scenarios
* [Command Wizard](/0.6/wizard.md) -- build your command interactively


---

# CLI Reference

Complete reference for every MigratorXpress command-line argument.

## Basic Usage[​](#basic-usage "Direct link to Basic Usage")

```
./MigratorXpress [OPTIONS]
```

MigratorXpress runs as a single command. On Windows, use `.\MigratorXpress.exe`.

## Authentication[​](#authentication "Direct link to Authentication")

| Option              | Type | Required | Description                       |
| ------------------- | ---- | -------- | --------------------------------- |
| `-a`, `--auth PATH` | Path | Yes      | Path to the JSON credentials file |

The credentials file contains connection details for every database involved in the migration. Each entry has a unique ID that you reference with other flags. See [Credentials File Format](#credentials-file-format) below.

## Source Database[​](#source-database "Direct link to Source Database")

| Option                         | Type   | Required | Description                                                                  |
| ------------------------------ | ------ | -------- | ---------------------------------------------------------------------------- |
| `--source_db_auth_id ID`       | String | Yes      | Source database identifier in the credentials file                           |
| `--source_db_name NAME`        | String | Yes      | Source database name (e.g., `orclpdb1`, `tpch`)                              |
| `--source_schema_name PATTERN` | String | No       | Source schema name, pattern, or comma-separated list. All schemas if omitted |

### Schema selection[​](#schema-selection "Direct link to Schema selection")

The `--source_schema_name` flag supports three modes:

**Single schema:**

```
--source_schema_name SALES
```

**SQL LIKE patterns (v0.6.12+):**

```
# All schemas starting with "app_"
--source_schema_name "app_%"

# Multiple patterns
--source_schema_name "APP_%, TENANT_%"
```

**Exact comma-separated list (v0.6.21+):**

```
# Multiple specific schemas without wildcards
--source_schema_name "tpch_1, tpch_2, tpch_3"
```

When omitted, MigratorXpress discovers and migrates all visible schemas in the source database.

When using patterns or lists, target schemas are created automatically with the same names as the source schemas. The `--target_schema_name` flag is only used for single-schema migrations.

## Target Database[​](#target-database "Direct link to Target Database")

| Option                      | Type   | Required | Description                                                                |
| --------------------------- | ------ | -------- | -------------------------------------------------------------------------- |
| `--target_db_auth_id ID`    | String | Yes      | Target database identifier in the credentials file                         |
| `--target_db_name NAME`     | String | Yes      | Target database name                                                       |
| `--target_schema_name NAME` | String | No       | Target schema name. Defaults to source schema name. Not used with patterns |

Supported targets: PostgreSQL and SQL Server. See the [compatibility matrix](/0.6/compatibility.md).

## Migration Database[​](#migration-database "Direct link to Migration Database")

| Option                      | Type   | Required | Description                                           |
| --------------------------- | ------ | -------- | ----------------------------------------------------- |
| `--migration_db_auth_id ID` | String | Yes      | SQL Server database identifier for migration tracking |

The migration database must be a SQL Server instance. MigratorXpress creates its tracking tables automatically on first use.

## Task Control[​](#task-control "Direct link to Task Control")

| Option                 | Type      | Description                              |
| ---------------------- | --------- | ---------------------------------------- |
| `--task_list TASKS...` | String(s) | Space-separated list of tasks to execute |

Tasks run in the order specified. Available tasks: `translate`, `create`, `transfer`, `diff`, `copy_pk`, `copy_ak`, `copy_fk`, or `all`.

Use `all` as a shortcut for the full sequence: `translate create transfer diff copy_pk copy_ak copy_fk`.

```
# Full migration
--task_list translate create transfer diff

# Schema only
--task_list translate create

# Data only (tables already exist)
--task_list transfer

# Constraints only (after data is loaded)
--task_list copy_pk copy_ak copy_fk

# Everything
--task_list all
```

Constraint copying limitations

Constraint copying (`copy_pk`, `copy_ak`, `copy_fk`) is currently supported only for **Oracle to SQL Server** migrations. For other migration paths, create constraints manually on the target database.

## Resume Operations[​](#resume-operations "Direct link to Resume Operations")

| Option                         | Type   | Description                                                |
| ------------------------------ | ------ | ---------------------------------------------------------- |
| `-r RUN_ID`, `--resume RUN_ID` | String | Resume a previously interrupted migration using its run ID |

When a migration is interrupted, use `--resume` with the run ID to pick up from the last completed step. Only tables that did not finish successfully are re-processed.

Since v0.6.22, resume automatically retrieves the original task list and schema names from the migration database. You do not need to specify `--task_list` or `--source_schema_name` when resuming.

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id ds_09_ms \
  --source_db_name tpch \
  --target_db_auth_id ds_04_pg \
  --target_db_name tpch \
  --migration_db_auth_id ds_02_ms \
  --resume 20260203-cf5be0ac-159f-4dad-861e-8b2b6f3868d7
```

The run ID is displayed in the console output when a migration starts (format: `YYYYMMDD-{uuid}`). You can also query the migration tracking database to find it.

## Run Tagging[​](#run-tagging "Direct link to Run Tagging")

| Option           | Type   | Description                                                                             |
| ---------------- | ------ | --------------------------------------------------------------------------------------- |
| `--project NAME` | String | Optional project tag attached to every row this run writes in the migration tracking DB |

Since v0.6.30, a user-supplied `--project` tag groups runs that belong to the same engagement. The tag is stored alongside `run_id` on `sourcetargetloads`, `eventlog`, and `sourcetargetdiff`, making all runs for a given project retrievable with a single SQL filter weeks or months later.

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id ds_09_ms --source_db_name tpch \
  --target_db_auth_id ds_04_pg --target_db_name tpch \
  --migration_db_auth_id ds_02_ms \
  --task_list all \
  --project bob_bods_oracle
```

Then, to find every run tagged with that project:

```
SELECT DISTINCT eventrunid
  FROM eventlog
 WHERE project = 'bob_bods_oracle';
```

**Validation:** 1–64 characters, letters, digits, underscore, or hyphen only (e.g. `bob_bods_oracle`, `cust-2026-q2`). Invalid values are rejected at CLI parse time, before any database write.

**Optional and backward compatible:** Runs without `--project` store `NULL`. Existing tracking databases are auto-upgraded with the new columns on the next startup via idempotent `ALTER TABLE … ADD COLUMN` statements.

**`mxp_init` also accepts `--project`** for the discovery phase.

Immutable per run\_id

On `--resume`, any `--project` value on the command line is ignored with a warning, and the original run's tag is inherited from the migration DB. This keeps every row for a given `run_id` tagged consistently, even across multiple resumes.

## FastTransfer[​](#fasttransfer "Direct link to FastTransfer")

| Option                         | Type    | Default       | Description                                               |
| ------------------------------ | ------- | ------------- | --------------------------------------------------------- |
| `--fasttransfer_dir_path PATH` | Path    | Auto-detected | Directory containing the FastTransfer binary              |
| `-p`, `--fasttransfer_p INT`   | Integer | 1             | Parallel streams per large table (Ctid/Rowid/NZDataSlice) |
| `--ft_large_table_th INT`      | Integer | 250,000,000   | Row count threshold for parallel transfer methods         |

MigratorXpress delegates all data movement to [FastTransfer](https://www.arpe.io/fasttransfer/). FastTransfer >= 0.15.0 is required; the version is validated at startup.

Since v0.6.25, if `--fasttransfer_dir_path` is omitted, MigratorXpress auto-detects a bundled FastTransfer in the `engine/` subdirectory next to the binary. Trial distributions ship with FastTransfer pre-bundled.

```
# Explicit path
--fasttransfer_dir_path ./FastTransfer_linux-x64_v0.15.0/

# Or omit to use the bundled engine/ directory
```

### Parallel transfer methods[​](#parallel-transfer-methods "Direct link to Parallel transfer methods")

Tables with row count >= `--ft_large_table_th` and `--fasttransfer_p` > 1 use database-specific parallel methods:

| Source Database | Method      | Description                                               |
| --------------- | ----------- | --------------------------------------------------------- |
| PostgreSQL      | Ctid        | Splits by physical tuple ID                               |
| Oracle          | Rowid       | Splits by physical ROWID (requires `SELECT_CATALOG_ROLE`) |
| Netezza         | NZDataSlice | Splits by internal data slice distribution                |
| SQL Server      | Standard    | No physical partitioning; parallelism via `--n_jobs` only |

## Performance[​](#performance "Direct link to Performance")

| Option                  | Type    | Default | Description                                                       |
| ----------------------- | ------- | ------- | ----------------------------------------------------------------- |
| `--n_jobs INT`          | Integer | 1       | Number of tables to process in parallel                           |
| `--compute_nbrows BOOL` | Boolean | false   | Use `COUNT(*)` for exact row counts instead of database estimates |
| `--without_xid`         | Flag    | false   | Disable transaction ID usage for Netezza and Oracle               |

`--n_jobs` controls table-level parallelism (how many tables transfer simultaneously). Combined with `--fasttransfer_p`, this gives dual-level parallelism:

```
# 4 tables at once, each large table split into 2 parallel streams
--n_jobs 4 --fasttransfer_p 2
```

## Table Filtering[​](#table-filtering "Direct link to Table Filtering")

| Option                           | Type    | Default       | Description                                                        |
| -------------------------------- | ------- | ------------- | ------------------------------------------------------------------ |
| `-i`, `--include_tables PATTERN` | String  | `%` (all)     | Include only tables matching SQL `LIKE` patterns (comma-separated) |
| `-e`, `--exclude_tables PATTERN` | String  | None          | Exclude tables matching SQL `LIKE` patterns (comma-separated)      |
| `-min`, `--min_rows NROWS`       | Integer | -1 (disabled) | Exclude tables with fewer rows than this value                     |
| `-max`, `--max_rows NROWS`       | Integer | -1 (disabled) | Exclude tables with row count >= this value                        |

Exclude patterns are applied after include patterns. Filters are pushed to SQL level for performance (v0.6.12+).

```
# Include only tables starting with "fact_" or "dim_"
-i "fact_%,dim_%"

# Spaces after commas are trimmed automatically
-i "fact_%, dim_%"

# Exclude temporary and test tables
-e "tmp_%,test_%"

# Combine filters
-i "%" -e "tmp_%,log_%" -min 100 -max 10000000
```

Shell quoting

Quote the entire comma-separated string as one argument. Do not quote each pattern separately:

```
# CORRECT
-i "fact_%,dim_%"

# WRONG — shell interprets as multiple arguments
-i 'fact_%','dim_%'
```

## Migration Options[​](#migration-options "Direct link to Migration Options")

| Option                         | Type    | Default    | Description                                                                                                   |
| ------------------------------ | ------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| `--drop_tables_if_exists BOOL` | Boolean | false      | Drop target tables before creating them                                                                       |
| `--load_mode MODE`             | String  | `truncate` | `truncate`: clear target before loading. `append`: add rows without clearing                                  |
| `--migration_db_mode MODE`     | String  | `preserve` | `preserve`: keep tracking data (enables resume). `truncate`: clear data, keep schema. `drop`: recreate schema |
| `--basic_diff`                 | Flag    | false      | Row/column count comparison only (skip content-level diff)                                                    |
| `-f`, `--force`                | Flag    | false      | Force migration by cleaning existing tracking data for these schemas                                          |

## SQL Server Target Options[​](#sql-server-target-options "Direct link to SQL Server Target Options")

These options apply only when the target database is SQL Server.

| Option                | Type    | Default     | Description                                                         |
| --------------------- | ------- | ----------- | ------------------------------------------------------------------- |
| `--cci_threshold INT` | Integer | 1,000,000   | Create Clustered Columnstore Index for tables above this row count  |
| `--aci_threshold INT` | Integer | 100,000,000 | Use archive compression (COLUMNSTORE\_ARCHIVE) above this row count |
| `--fk_mode MODE`      | String  | `disabled`  | Foreign key enforcement: `disabled`, `untrusted`, or `trusted`      |

**Columnstore behavior:**

* Tables >= `cci_threshold` but < `aci_threshold`: Standard Clustered Columnstore Index
* Tables >= `aci_threshold`: CCI with `DATA_COMPRESSION = COLUMNSTORE_ARCHIVE`
* Tables < `cci_threshold`: Standard rowstore

**Foreign key modes:**

* `disabled` (default): FK constraints created with `WITH NOCHECK` and disabled. Fastest for loading.
* `untrusted`: FK constraints created with `WITH NOCHECK` but left enabled. Enforced for new data only.
* `trusted`: Standard FK constraints with full enforcement. Slowest but provides complete referential integrity.

## Oracle Source Options[​](#oracle-source-options "Direct link to Oracle Source Options")

These options apply only when the source database is Oracle.

| Option                           | Type      | Default | Description                                                                            |
| -------------------------------- | --------- | ------- | -------------------------------------------------------------------------------------- |
| `--forced_int_id_prefixes S...`  | String(s) | None    | Space-separated column name prefixes to force as integer type                          |
| `--forced_int_id_suffixes S...`  | String(s) | None    | Space-separated column name suffixes to force as integer type                          |
| `--profiling_sample_pc NUMBER`   | Integer   | 10      | Percentage of rows to sample for Oracle DATE/NUMBER profiling                          |
| `--min_sample_pc_profile NUMBER` | Integer   | 100,000 | Row count threshold below which tables are profiled in full (no sampling)              |
| `--p_query NUMBER`               | Integer   | 6       | Inner level of query parallelism for Oracle profiling queries (`PARALLEL` hint degree) |

Oracle stores many integer values in `NUMBER` columns without precision. MigratorXpress profiles DATE and NUMBER columns to select optimal target types. Use `--forced_int_id_prefixes` and `--forced_int_id_suffixes` to skip profiling for known ID columns:

```
# Space-separated, case-insensitive matching
--forced_int_id_prefixes ID_ PK_ KEY_ \
--forced_int_id_suffixes _ID _KEY _PK
```

**Sampling behavior:**

* Tables >= `min_sample_pc_profile` rows: sampled at `profiling_sample_pc`% using Oracle `SAMPLE(n)`
* Tables < `min_sample_pc_profile` rows: profiled in full
* Set `--profiling_sample_pc 100` to disable sampling

## Logging Options[​](#logging-options "Direct link to Logging Options")

| Option              | Type   | Default           | Description                                                                 |
| ------------------- | ------ | ----------------- | --------------------------------------------------------------------------- |
| `--log_level LEVEL` | String | `INFO`            | Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`              |
| `--log_dir PATH`    | Path   | Current directory | Directory for log files                                                     |
| `--no_banner`       | Flag   | false             | Suppress the startup banner                                                 |
| `--no_progress`     | Flag   | false             | Disable the progress bar                                                    |
| `--quiet_ft`        | Flag   | false             | Suppress FastTransfer subprocess output from console (still logged to file) |

See [Logging and Monitoring](/0.6/reference/logging.md) for details on log format and database logging.

## License Management[​](#license-management "Direct link to License Management")

| Option                | Type   | Description                 |
| --------------------- | ------ | --------------------------- |
| `--license TEXT`      | String | License text (ECDSA signed) |
| `--license_file PATH` | Path   | Path to license file        |

**License sources (in order of precedence):**

1. `--license` command-line argument
2. `--license_file` command-line argument
3. `MIGRATORXPRESS_LICENSE` environment variable
4. Default location: `~/.migratorxpress/license.key` (Linux) or `%APPDATA%/MigratorXpress/license.key` (Windows)
5. Trial mode (automatic fallback)

Trial mode provides all features without restrictions and is suitable for evaluation.

## Utility[​](#utility "Direct link to Utility")

| Option         | Description                             |
| -------------- | --------------------------------------- |
| `--version`    | Display MigratorXpress version and exit |
| `-h`, `--help` | Show help message and exit              |

## Database Parameters[​](#database-parameters "Direct link to Database Parameters")

### Connection parameters by database type[​](#connection-parameters-by-database-type "Direct link to Connection parameters by database type")

| Parameter   | Oracle           | PostgreSQL          | SQL Server          | Netezza       |
| ----------- | ---------------- | ------------------- | ------------------- | ------------- |
| `ds_type`   | `oracle`         | `postgres`          | `mssql`             | `netezza`     |
| `auth_mode` | `classic`        | `classic` or `odbc` | `classic` or `odbc` | `classic`     |
| `username`  | Required         | Required            | Required            | Required      |
| `password`  | Required         | Required            | Required            | Required      |
| `server`    | Required         | Required            | Required            | Required      |
| `port`      | 1521             | 5432                | 1433                | 5480          |
| `database`  | Service name/SID | Database name       | Database name       | Database name |
| `lib_dir`   | Thick mode only  | --                  | --                  | --            |

## Credentials File Format[​](#credentials-file-format "Direct link to Credentials File Format")

The credentials file is a JSON object where each key is an identifier you reference on the command line.

```
{
  "oracle_prod": {
    "ds_type": "oracle",
    "auth_mode": "classic",
    "info": {
      "username": "$env{ORA_USER}",
      "password": "$env{ORA_PASSWORD}",
      "server": "oracle-host.example.com",
      "port": 1521,
      "database": "ORCL"
    }
  },
  "postgres_dev": {
    "ds_type": "postgres",
    "auth_mode": "classic",
    "info": {
      "username": "$env{PG_USER}",
      "password": "$env{PG_PASSWORD}",
      "server": "pg-host.example.com",
      "port": 5432,
      "database": "analytics"
    }
  },
  "ms_mig_log": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "$env{MIG_USER}",
      "password": "$env{MIG_PASSWORD}",
      "server": "sql-host.example.com",
      "port": 1433,
      "database": "migration_log"
    }
  },
  "netezza_source": {
    "ds_type": "netezza",
    "auth_mode": "classic",
    "info": {
      "username": "$env{NZ_USER}",
      "password": "$env{NZ_PASSWORD}",
      "server": "nz-host.example.com",
      "port": 5480,
      "database": "PROD_DB"
    }
  }
}
```

Use `$env{VAR_NAME}` to reference environment variables. An error is raised if the variable is not set. Plain-text values work as well.

## Authentication Modes[​](#authentication-modes "Direct link to Authentication Modes")

### Classic (all databases)[​](#classic-all-databases "Direct link to Classic (all databases)")

Standard username/password authentication. Works with all supported database types.

```
{
  "my_db": {
    "ds_type": "postgres",
    "auth_mode": "classic",
    "info": {
      "username": "user",
      "password": "pass",
      "server": "host",
      "port": 5432,
      "database": "dbname"
    }
  }
}
```

### Oracle Thick Mode[​](#oracle-thick-mode "Direct link to Oracle Thick Mode")

For Oracle 11.2 and earlier, set `lib_dir` to the Oracle Instant Client directory. Later versions use thin mode by default (omit `lib_dir`).

```
{
  "oracle_thick": {
    "ds_type": "oracle",
    "auth_mode": "classic",
    "info": {
      "username": "user",
      "password": "pass",
      "server": "host",
      "port": 1521,
      "database": "SID",
      "lib_dir": "/opt/oracle/instantclient_19_8"
    }
  }
}
```

### PostgreSQL ODBC[​](#postgresql-odbc "Direct link to PostgreSQL ODBC")

```
{
  "pg_odbc": {
    "ds_type": "postgres",
    "auth_mode": "odbc",
    "info": {
      "dsn": "PostgreSQL",
      "username": "user",
      "password": "pass"
    }
  }
}
```

### SQL Server Trusted Authentication[​](#sql-server-trusted-authentication "Direct link to SQL Server Trusted Authentication")

Windows integrated authentication using ODBC:

```
{
  "mssql_trusted": {
    "ds_type": "mssql",
    "auth_mode": "odbc",
    "info": {
      "trusted": true,
      "instance": "server.domain.com\\INSTANCE",
      "database": "dbname"
    }
  }
}
```

### Connection String[​](#connection-string "Direct link to Connection String")

For advanced scenarios, pass a raw connection string:

```
{
  "mssql_custom": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "connect_string": "mssql+pymssql://user:pass@host:port/database"
    }
  }
}
```

## Supported Database Types[​](#supported-database-types "Direct link to Supported Database Types")

| Database   | `ds_type` value | Default Port | As Source | As Target | As Migration DB |
| ---------- | --------------- | ------------ | --------- | --------- | --------------- |
| Oracle     | `oracle`        | 1521         | Yes       | No        | No              |
| PostgreSQL | `postgres`      | 5432         | Yes       | Yes       | No              |
| SQL Server | `mssql`         | 1433         | Yes       | Yes       | Yes             |
| Netezza    | `netezza`       | 5480         | Yes       | No        | No              |

## See Also[​](#see-also "Direct link to See Also")

* [Quick Start Guide](/0.6/guides/quickstart.md) -- get started in 5 minutes
* [Migration Tasks](/0.6/configuration/migration-tasks.md) -- task types and execution order
* [FastTransfer Configuration](/0.6/configuration/fasttransfer-configuration.md) -- parallel transfer tuning
* [Logging and Monitoring](/0.6/reference/logging.md) -- log format and database tracking
* [Troubleshooting](/0.6/reference/troubleshooting.md) -- common issues and solutions


---

# Logging and Monitoring

MigratorXpress uses two logging systems: a tracking database (SQL Server or PostgreSQL) for structured migration history and log files for operational details.

## Database Logging[​](#database-logging "Direct link to Database Logging")

The migration tracking database records every step of a migration for auditing, resumability, and troubleshooting. Either **SQL Server** or **PostgreSQL** can host it -- the schema and behavior are identical across both backends. The dialect is auto-detected from the `ds_type` of the entry pointed to by `--migration_db_auth_id`. On PostgreSQL the tracking tables live in the `public` schema; on SQL Server they live in `dbo`.

### Database Schema Overview[​](#database-schema-overview "Direct link to Database Schema Overview")

![Migration Database Schema](/assets/images/migration_db_schema-1520c7e05cb5f53e7ca90bf75c7e471c.png)

Primary keys are marked with key symbols and relationships show cardinality (1<!-- -->:N<!-- -->).

### Key Tables[​](#key-tables "Direct link to Key Tables")

#### sources[​](#sources "Direct link to sources")

Source database metadata:

* Source identifier and database type
* Connection details (server, port, database)
* Schema name and discovery timestamp
* Table count and total row count

#### targets[​](#targets "Direct link to targets")

Target database metadata:

* Target identifier and database type
* Connection details (server, port, database)
* Schema name
* Creation timestamp

#### sourcecolumns[​](#sourcecolumns "Direct link to sourcecolumns")

Column-level metadata from the source:

* Table and column name (composite key)
* Source data type, precision, scale
* Ordinal position, length, nullability
* Primary key flag

#### targetcolumns[​](#targetcolumns "Direct link to targetcolumns")

Column-level metadata for the target:

* Table and column name (composite key)
* Translated data type, precision, scale
* Ordinal position, length, nullability
* Mapping from source column

#### sourcetargetloads[​](#sourcetargetloads "Direct link to sourcetargetloads")

Per-table transfer tracking:

* Source and target table identification
* Transfer status (pending, running, completed, failed)
* Row counts (source, transferred, validated)
* Start and completion timestamps
* Transfer method and parallel degree
* Error messages on failure
* Resume checkpoint data

#### eventlog[​](#eventlog "Direct link to eventlog")

Event log for migration activity:

* Log ID and timestamp
* Migration run identifier
* Log level (INFO, WARNING, ERROR, DEBUG)
* Event type and status
* Table context (schema, table)
* Event message and error details
* Elapsed time in seconds

#### sourceconstraints[​](#sourceconstraints "Direct link to sourceconstraints")

Constraint metadata from the source:

* Constraint name and type (PK, AK, FK)
* Source table and columns
* Referenced table and columns (for FKs)
* Copy status and timestamp

## File-Based Logging[​](#file-based-logging "Direct link to File-Based Logging")

Each migration run creates a log file for detailed operational tracing.

### Naming Pattern[​](#naming-pattern "Direct link to Naming Pattern")

```
migratorxpress_YYYYMMDD_HHMMSS_<run_id>.log
```

### Log Format[​](#log-format "Direct link to Log Format")

Structured format with timestamp, log level, process ID, and context:

```
[YYYY-MM-DD HH:MM:SS.fff+TZ :: LEVEL :: PID :: Context] Message
```

### Sample Output[​](#sample-output "Direct link to Sample Output")

```
[2026-01-15 09:30:12.145+01:00 :: INFO :: 8421 :: MainProcess] Log file path: /var/log/migratorxpress/migratorxpress_20260115_093012_a1b2c3d4.log
[2026-01-15 09:30:12.146+01:00 :: INFO :: 8421 :: MainProcess] **** Starting migration run ****
[2026-01-15 09:30:12.147+01:00 :: INFO :: 8421 :: MainProcess] Source: Oracle - ORCL.SALES
[2026-01-15 09:30:12.148+01:00 :: INFO :: 8421 :: MainProcess] Target: PostgreSQL - analytics.sales
[2026-01-15 09:30:12.250+01:00 :: INFO :: 8421 :: MainProcess] Discovered 42 tables for migration
[2026-01-15 09:30:12.385+01:00 :: INFO :: 8421 :: MainProcess] Task list: translate create transfer diff
[2026-01-15 09:30:13.102+01:00 :: INFO :: 8421 :: Worker-1] Translating DDL: ORDERS
[2026-01-15 09:30:13.456+01:00 :: INFO :: 8421 :: Worker-1] Creating table: sales.orders
[2026-01-15 09:30:14.210+01:00 :: INFO :: 8421 :: Worker-1] Transferring: ORDERS (estimated 1.2M rows)
[2026-01-15 09:30:36.721+01:00 :: INFO :: 8421 :: Worker-1] Transfer completed: ORDERS - 1,234,567 rows in 22.511s
[2026-01-15 09:30:37.102+01:00 :: INFO :: 8421 :: Worker-1] Diff: ORDERS - source=1,234,567 target=1,234,567 OK
```

## Log Levels[​](#log-levels "Direct link to Log Levels")

Set via `--log_level`:

| Level      | Description                                                                 |
| ---------- | --------------------------------------------------------------------------- |
| `DEBUG`    | SQL queries, FastTransfer commands, detailed diagnostics                    |
| `INFO`     | Progress, row counts, task completion (default)                             |
| `WARNING`  | Non-critical issues such as type conversion fallbacks or schema differences |
| `ERROR`    | Failures preventing a table from migrating                                  |
| `CRITICAL` | Fatal errors stopping the entire run                                        |

## Log Location[​](#log-location "Direct link to Log Location")

Defaults to the current working directory. Override with `--log_dir`:

```
./MigratorXpress --log_dir /var/log/migratorxpress \
  --auth ./credentials.json \
  ...
```

## Terminal Output[​](#terminal-output "Direct link to Terminal Output")

Logs are mirrored to the terminal with color coding:

* **Green** -- success messages (table created, transfer completed)
* **Yellow** -- warnings (type conversion fallback, schema mismatch)
* **Red** -- errors (transfer failed, connection lost)
* **Cyan** -- informational messages (discovery, progress)

## Monitoring Best Practices[​](#monitoring-best-practices "Direct link to Monitoring Best Practices")

### During migration[​](#during-migration "Direct link to During migration")

* Watch the terminal for real-time progress on each table.
* Use `--n_jobs 1` for initial test runs so log output is sequential and easier to follow.
* Set `--log_level DEBUG` to capture SQL statements when diagnosing issues.

### After migration[​](#after-migration "Direct link to After migration")

* Query the `sourcetargetloads` table for per-table transfer status and row counts.
* Query the `eventlog` table for errors and warnings.
* Use the `diff` task to validate row counts and content between source and target.

### Resuming failed runs[​](#resuming-failed-runs "Direct link to Resuming failed runs")

If a migration is interrupted, the tracking database preserves the state of each table. Use `--resume` to pick up from where it stopped -- only tables that did not complete successfully are reprocessed.

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name SALES \
  --target_db_auth_id postgres_dev \
  --target_schema_name sales \
  --migration_db_auth_id ms_mig_log \
  --resume
```

## Integration with Monitoring Tools[​](#integration-with-monitoring-tools "Direct link to Integration with Monitoring Tools")

### Log file ingestion[​](#log-file-ingestion "Direct link to Log file ingestion")

MigratorXpress log files use a structured format that can be parsed by log aggregation tools:

* **Filebeat / Logstash** -- configure a file input pointing to `migratorxpress_*.log` with a grok pattern for the bracket-delimited format.
* **Fluentd** -- use a regexp parser matching `\[(?<time>[^\]]+) :: (?<level>\w+) :: (?<pid>\d+) :: (?<context>[^\]]+)\] (?<message>.*)`.
* **Splunk** -- index the log directory and create field extractions for timestamp, level, PID, and context.

### Database queries for dashboards[​](#database-queries-for-dashboards "Direct link to Database queries for dashboards")

Connect your monitoring tool (Grafana, Power BI, etc.) directly to the migration tracking database. The examples below use SQL Server syntax; the equivalent on PostgreSQL is shown alongside.

```
-- Tables with errors (portable)
SELECT source_table, error_message, started_at
FROM sourcetargetloads
WHERE status = 'failed'
ORDER BY started_at DESC;

-- Transfer throughput -- SQL Server
SELECT source_table, row_count,
       DATEDIFF(SECOND, started_at, completed_at) AS duration_seconds,
       row_count / NULLIF(DATEDIFF(SECOND, started_at, completed_at), 0) AS rows_per_second
FROM sourcetargetloads
WHERE status = 'completed'
ORDER BY rows_per_second DESC;

-- Transfer throughput -- PostgreSQL
SELECT source_table, row_count,
       EXTRACT(EPOCH FROM (completed_at - started_at)) AS duration_seconds,
       row_count / NULLIF(EXTRACT(EPOCH FROM (completed_at - started_at)), 0) AS rows_per_second
FROM sourcetargetloads
WHERE status = 'completed'
ORDER BY rows_per_second DESC;
```

## See Also[​](#see-also "Direct link to See Also")

* [CLI Reference](/0.6/reference/cli-reference.md) -- `--log_level`, `--log_dir`, and other options
* [Troubleshooting](/0.6/reference/troubleshooting.md) -- common issues and solutions


---

# MigratorXpress SBOM Downloads

## Latest Version: 0.6.29[​](#latest-version-0629 "Direct link to Latest Version: 0.6.29")

Last updated: 2026-04-16

### Download Files[​](#download-files "Direct link to Download Files")

#### JSON Format (CycloneDX 1.5)[​](#json-format-cyclonedx-15 "Direct link to JSON Format (CycloneDX 1.5)")

* **Download**: [migratorxpress-v0.6.29-sbom.json](/assets/files/migratorxpress-v0.6.29-sbom-ad9a5841736c8f1adf36f9aac5a127df.json)
* **SHA256**: *(available after release)*
* **Checksum file**: [migratorxpress-v0.6.29-sbom.json.sha256](/assets/files/migratorxpress-v0.6.29-sbom.json-1171f66966b0e14e4533d78ac2778d20.sha256)

#### XML Format (CycloneDX 1.5)[​](#xml-format-cyclonedx-15 "Direct link to XML Format (CycloneDX 1.5)")

* **Download**: [migratorxpress-v0.6.29-sbom.xml](/assets/files/migratorxpress-v0.6.29-sbom-f0de12f64d3412a1ee339d090779f659.xml)
* **SHA256**: *(available after release)*
* **Checksum file**: [migratorxpress-v0.6.29-sbom.xml.sha256](/assets/files/migratorxpress-v0.6.29-sbom.xml-8b92f4a3b90b7ec4e8c6f168f8b38a8d.sha256)

### All Checksums[​](#all-checksums "Direct link to All Checksums")

* **Combined checksums**: [checksums.txt](/assets/files/checksums-7fbdbf4613e80ff7dae1182b7a65c814.txt)

### Verification Instructions[​](#verification-instructions "Direct link to Verification Instructions")

To verify the integrity of downloaded SBOM files:

```
# Download SBOM and checksum
wget https://migratorxpress.arpe.io/sboms/latest/migratorxpress-v0.6.29-sbom.json
wget https://migratorxpress.arpe.io/sboms/latest/migratorxpress-v0.6.29-sbom.json.sha256

# Verify
sha256sum -c migratorxpress-v0.6.29-sbom.json.sha256
```

### Quick Download Script[​](#quick-download-script "Direct link to Quick Download Script")

Save this as `download-sbom.sh`:

```
#!/bin/bash
# Download and verify MigratorXpress SBOM

BASE_URL="https://migratorxpress.arpe.io/sboms/latest"
VERSION="v0.6.29"

# Download JSON SBOM and verify
echo "Downloading JSON SBOM..."
wget "${BASE_URL}/migratorxpress-${VERSION}-sbom.json"
wget "${BASE_URL}/migratorxpress-${VERSION}-sbom.json.sha256"
sha256sum -c "migratorxpress-${VERSION}-sbom.json.sha256" || exit 1

# Download XML SBOM and verify
echo "Downloading XML SBOM..."
wget "${BASE_URL}/migratorxpress-${VERSION}-sbom.xml"
wget "${BASE_URL}/migratorxpress-${VERSION}-sbom.xml.sha256"
sha256sum -c "migratorxpress-${VERSION}-sbom.xml.sha256" || exit 1

echo "SBOMs downloaded and verified!"
```

### Version History[​](#version-history "Direct link to Version History")

SBOMs of previous releases are kept under `https://migratorxpress-docs.arpe.io/sboms/v<version>/` (for example `/sboms/v0.6.29/`), with the same file names as above for that version.

### About These SBOMs[​](#about-these-sboms "Direct link to About These SBOMs")

The Software Bill of Materials (SBOM) provides a complete inventory of all components in MigratorXpress:

* All direct dependencies with exact versions
* Package URLs (PURLs) for each component
* License information where available
* CycloneDX 1.5 format compatible with security scanning tools

### Integration with Security Tools[​](#integration-with-security-tools "Direct link to Integration with Security Tools")

Use these SBOMs with:

* **Grype**: `grype sbom:migratorxpress-v0.6.29-sbom.json`
* **Trivy**: `trivy sbom migratorxpress-v0.6.29-sbom.json`
* **OWASP Dependency-Track**: Import via UI or API

***

*This page is automatically updated when new releases are created.*


---

# Troubleshooting

Common issues encountered during MigratorXpress migrations and how to resolve them.

## Connection Issues[​](#connection-issues "Direct link to Connection Issues")

### Cannot connect to source database[​](#cannot-connect-to-source-database "Direct link to Cannot connect to source database")

**Symptoms:** Connection timeout or authentication error when MigratorXpress starts.

**Solutions:**

1. Verify that the credentials file is valid JSON and that the `--source_db_auth_id` matches a key in the file.
2. Test connectivity independently (e.g., `psql`, `sqlplus`, `sqlcmd`) before running MigratorXpress.
3. Check that environment variables referenced with `$env{VAR_NAME}` are set in the current shell session.
4. Confirm the server hostname, port, and database name are correct.

```
# Verify environment variables are set
echo $ORA_USER
echo $ORA_PASSWORD

# Test Oracle connectivity
sqlplus $ORA_USER/$ORA_PASSWORD@//oracle-host:1521/ORCL

# Test PostgreSQL connectivity
psql -h pg-host -p 5432 -U $PG_USER -d analytics

# Test SQL Server connectivity
sqlcmd -S sql-host,1433 -U $MSSQL_USER -P $MSSQL_PASSWORD -d target_db
```

### Migration database not accessible[​](#migration-database-not-accessible "Direct link to Migration database not accessible")

**Symptoms:** Error connecting to the migration tracking database or error creating tables.

**Solutions:**

1. The migration database must be **SQL Server** -- other database types are not supported for migration tracking.
2. Enable **mixed-mode authentication** (SQL Server Authentication + Windows Authentication) on the SQL Server instance.
3. The connecting user must have **CREATE TABLE** permissions in the target database.
4. Verify the `--migration_db_auth_id` references a valid `mssql` entry in the credentials file.

```
-- Grant CREATE TABLE permission
USE migration_log;
GRANT CREATE TABLE TO your_migration_user;
GRANT ALTER ON SCHEMA::dbo TO your_migration_user;
GRANT INSERT, UPDATE, DELETE, SELECT ON SCHEMA::dbo TO your_migration_user;
```

## PostgreSQL Issues[​](#postgresql-issues "Direct link to PostgreSQL Issues")

### Connection refused[​](#connection-refused "Direct link to Connection refused")

**Symptoms:** `could not connect to server: Connection refused`

**Solutions:**

* Verify PostgreSQL is running:
  <!-- -->
  ```
  systemctl status postgresql
  ```

* Check that `pg_hba.conf` allows connections from your IP address. Add a line such as:

  <!-- -->

  ```
  host    all    all    10.0.0.0/8    md5
  ```

  <!-- -->

  Then reload the configuration:

  <!-- -->

  ```
  sudo systemctl reload postgresql
  ```

* Check firewall rules:
  <!-- -->
  ```
  sudo ufw allow 5432/tcp
  ```

* Confirm PostgreSQL is listening on the correct interface. Check `listen_addresses` in `postgresql.conf`:
  <!-- -->
  ```
  listen_addresses = '*'
  ```

### Authentication failed[​](#authentication-failed "Direct link to Authentication failed")

**Symptoms:** `FATAL: password authentication failed for user`

**Solutions:**

* Verify the username and password are correct.
* Check the password encryption method in `pg_hba.conf` (`md5` vs `scram-sha-256`).
* Confirm the user exists:
  <!-- -->
  ```
  SELECT * FROM pg_user WHERE usename = 'your_user';
  ```
* If using `$env{PG_PASSWORD}`, verify the environment variable does not contain trailing whitespace or special characters that need escaping.

## Oracle Issues[​](#oracle-issues "Direct link to Oracle Issues")

### ORA-12154: TNS could not resolve connect identifier[​](#ora-12154-tns-could-not-resolve-connect-identifier "Direct link to ORA-12154: TNS could not resolve connect identifier")

**Symptoms:** Connection fails with TNS resolution error.

**Solutions:**

* Verify the service name or SID in the credentials file matches the Oracle listener configuration.
* Check `tnsnames.ora` if using TNS aliases.
* Try using the IP address instead of the hostname.
* Confirm the Oracle listener is running:
  <!-- -->
  ```
  lsnrctl status
  ```
* If using Oracle thick mode, verify that `$ORACLE_HOME/network/admin/tnsnames.ora` or `$TNS_ADMIN/tnsnames.ora` is correctly configured.

### ORA-28000: account is locked[​](#ora-28000-account-is-locked "Direct link to ORA-28000: account is locked")

**Symptoms:** Login fails because the Oracle account is locked.

**Solutions:**

* Unlock the account as a DBA:
  <!-- -->
  ```
  ALTER USER your_username ACCOUNT UNLOCK;
  ```
* Check if the account was locked due to too many failed login attempts. Review the account profile:
  <!-- -->
  ```
  SELECT profile FROM dba_users WHERE username = 'YOUR_USER';
  SELECT resource_name, limit FROM dba_profiles WHERE profile = 'DEFAULT' AND resource_name = 'FAILED_LOGIN_ATTEMPTS';
  ```

### Thick mode library not found[​](#thick-mode-library-not-found "Direct link to Thick mode library not found")

**Symptoms:** Error loading Oracle client libraries, typically `DPI-1047: Cannot locate a 64-bit Oracle Client library`.

**Solutions:**

* Verify the `lib_dir` path in the credentials file points to a valid Oracle Instant Client directory.
* Confirm the Instant Client version matches the platform (64-bit required).
* Check file permissions on the Instant Client directory.
* On Linux, set `LD_LIBRARY_PATH`:
  <!-- -->
  ```
  export LD_LIBRARY_PATH=/opt/oracle/instantclient_19_8:$LD_LIBRARY_PATH
  ```
* On Linux, you may also need `libaio`:
  <!-- -->
  ```
  sudo apt-get install libaio1    # Debian/Ubuntu
  sudo yum install libaio         # RHEL/CentOS
  ```

## SQL Server Issues[​](#sql-server-issues "Direct link to SQL Server Issues")

### Login failed for user[​](#login-failed-for-user "Direct link to Login failed for user")

**Symptoms:** `Login failed for user 'username'`

**Solutions:**

* Confirm SQL Server is configured for **SQL Server Authentication** (mixed mode), not Windows Authentication only.
* Verify the username and password are correct.
* Check that the user exists and is not disabled:
  <!-- -->
  ```
  SELECT name, is_disabled FROM sys.sql_logins WHERE name = 'your_user';
  ```
* Check for IP restrictions or firewall rules blocking the connection.

### Cannot open database requested by the login[​](#cannot-open-database-requested-by-the-login "Direct link to Cannot open database requested by the login")

**Symptoms:** `Cannot open database "dbname" requested by the login. The login failed.`

**Solutions:**

* Verify the database name in the credentials file is spelled correctly (case-sensitive on Linux-hosted SQL Server).
* Confirm the user has access to the database:
  <!-- -->
  ```
  USE your_database;
  SELECT * FROM sys.database_principals WHERE name = 'your_user';
  ```
* Check the database is online:
  <!-- -->
  ```
  SELECT name, state_desc FROM sys.databases WHERE name = 'your_database';
  ```

## Netezza Issues[​](#netezza-issues "Direct link to Netezza Issues")

### Connection refused[​](#connection-refused-1 "Direct link to Connection refused")

**Symptoms:** `could not connect to server: Connection refused` on port 5480.

**Solutions:**

* Verify the Netezza appliance is powered on and the NPS service is running.
* Confirm the correct port (default: **5480**, not 5432).
* Check network connectivity:
  <!-- -->
  ```
  telnet nz-host 5480
  ```
* Verify firewall rules allow traffic to port 5480.
* Confirm the ODBC driver for Netezza is installed on the MigratorXpress host.

### Authentication failed[​](#authentication-failed-1 "Direct link to Authentication failed")

**Symptoms:** `FATAL: password authentication failed`

**Solutions:**

* Verify the username and password.
* Confirm the user exists in the Netezza system:
  <!-- -->
  ```
  SELECT username FROM _v_user WHERE username = 'YOUR_USER';
  ```
* Check that the user has access to the target database:
  <!-- -->
  ```
  SELECT * FROM _v_object_data WHERE objname = 'YOUR_DATABASE';
  ```

## General Tips[​](#general-tips "Direct link to General Tips")

### Enable debug logging[​](#enable-debug-logging "Direct link to Enable debug logging")

Set `--log_level DEBUG` to capture detailed diagnostics including SQL statements, FastTransfer commands, and connection details:

```
./MigratorXpress --auth ./credentials.json \
  --log_level DEBUG \
  --log_dir /tmp/mig_debug \
  ...
```

### Check the log file[​](#check-the-log-file "Direct link to Check the log file")

Every migration run creates a log file named `migratorxpress_YYYYMMDD_HHMMSS_<run_id>.log`. Review the full log for error context that may not appear in the terminal summary.

### Resume after failure[​](#resume-after-failure "Direct link to Resume after failure")

If a migration fails partway through, use `--resume` to continue from the last successful table rather than starting over:

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name SALES \
  --target_db_auth_id postgres_dev \
  --target_schema_name sales \
  --migration_db_auth_id ms_mig_log \
  --resume
```

### Verify FastTransfer binary[​](#verify-fasttransfer-binary "Direct link to Verify FastTransfer binary")

Confirm the FastTransfer binary is executable and the path is correct:

```
ls -la ./FastTransfer_linux-x64_v0.12.4/
./FastTransfer_linux-x64_v0.12.4/FastTransfer --version
```

## See Also[​](#see-also "Direct link to See Also")

* [CLI Reference](/0.6/reference/cli-reference.md) -- all command-line options
* [Logging and Monitoring](/0.6/reference/logging.md) -- log format and database tracking
* [Database Configuration](/0.6/configuration/database-configuration.md) -- connection setup
* [PostgreSQL](/0.6/configuration/databases/postgresql.md) -- PostgreSQL-specific configuration
* [Oracle](/0.6/configuration/databases/oracle.md) -- Oracle-specific configuration
* [SQL Server](/0.6/configuration/databases/sql-server.md) -- SQL Server-specific configuration


---

# Command Builder

Build your MigratorXpress command step by step using the interactive wizard below.

<!-- -->

Expand All\[ ]

### Platform <!-- -->Linux

Linux

Windows (PowerShell)

### Source Database

| Authentication File:             | credentials.json                                                                                                                   |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Source Database ID (required):   | e.g., ds\_08\_oracleID from your credentials JSON file                                                                             |
| Source Database Name (required): | e.g., orclpdb1Must match the database of the source entry in the credentials file                                                  |
| Source Schema Name:              | e.g., SALES or APP\_%Supports SQL LIKE patterns (%, \_). Comma-separated for multiple. Omit for all schemas. Not used with Resume. |

### Target Database

| Target Database ID (required):                   | e.g., ds\_05\_msID from your credentials JSON file. SQL Server target (PostgreSQL target is experimental in 0.7.x)                                                         |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Target Database Name (<!-- -->required<!-- -->): | e.g., tpchUse the database of the target entry in the credentials file                                                                                                     |
| Target Schema Name:                              | e.g., tpch\_1\_copyLeave empty to keep the source schema name(s). If set with a pattern/list (or no source schema), all source schemas are loaded into this single schema. |

### Migration Tracking Database

| Migration DB ID (required): | e.g., ds\_02\_msSQL Server or PostgreSQL database for migration tracking and logging                                                                  |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Migration DB Mode:          | preservetruncatedroppreserve: keep tracking data (enables resume). truncate: delete all tracking data (all runs). drop: recreate all tracking tables. |

### Migration Tasks <!-- -->translate, create, transfer, diff

|                                                                                                                              |   |
| ---------------------------------------------------------------------------------------------------------------------------- | - |
| \[x]`translate` — <!-- -->Translate source column types to target types                                                      |   |
| \[x]`create` — <!-- -->Create tables in target database                                                                      |   |
| \[x]`transfer` — <!-- -->Copy data (requires FastTransfer)                                                                   |   |
| \[x]`diff` — <!-- -->Validate data integrity                                                                                 |   |
| \[ ]`copy_pk` — <!-- -->Copy primary key constraints                                                                         |   |
| \[ ]`copy_ak` — <!-- -->Copy alternate key constraints                                                                       |   |
| \[ ]`copy_fk` — <!-- -->Copy foreign key constraints                                                                         |   |
| Tasks always run in this order.<!-- --> <!-- -->copy\_pk/copy\_ak/copy\_fk require an Oracle source and a SQL Server target. |   |

### FastTransfer Configuration

### Table Filtering

### Migration Options

### Oracle Source Options

### Logging & Output

### Resume

### License

### Generated Command

Multi-line\[x]

```
./MigratorXpress \
  --auth credentials.json \
  --source_db_auth_id <source_db_auth_id> \
  --source_db_name <source_db_name> \
  --target_db_auth_id <target_db_auth_id> \
  --target_db_name <target_db_name> \
  --migration_db_auth_id <migration_db_auth_id> \
  --task_list translate create transfer diff
```

copy


---

# MigratorXpress

## What is MigratorXpress?[​](#what-is-migratorxpress "Direct link to What is MigratorXpress?")

MigratorXpress is a CLI tool for database migrations between platforms. This documentation describes MigratorXpress v0.7.3. It translates schemas, transfers data, copies constraints, and validates results -- all from a single command. Under the hood it uses [FastTransfer](https://www.arpe.io/fasttransfer/) for streaming data transfer, so datasets of any size move without saturating memory.

## Architecture[​](#architecture "Direct link to Architecture")

MigratorXpress connects three databases during a migration:

<!-- -->

### Source Database[​](#source-database "Direct link to Source Database")

The database you are migrating from. MigratorXpress reads schema metadata, profiles column types, and streams table data from the source.

Supported sources: Oracle, PostgreSQL, SQL Server, Netezza.

### Target Database[​](#target-database "Direct link to Target Database")

The database that receives the translated schema and data. MigratorXpress creates tables, loads data via FastTransfer, and optionally copies constraints.

Supported targets: SQL Server and PostgreSQL. PostgreSQL targets can be loaded from Oracle, PostgreSQL and SQL Server sources (see [Compatibility](/latest/compatibility.md)).

### Migration Tracking DB[​](#migration-tracking-db "Direct link to Migration Tracking DB")

A SQL Server **or PostgreSQL** database where MigratorXpress logs every migration step -- table discovery, translation, transfer status, diff results, and constraint operations. This enables auditing, monitoring, and resuming failed migrations. The backend is auto-detected from the auth entry's `ds_type` (`mssql` or `postgres`); no CLI flag is required.

## Key features[​](#key-features "Direct link to Key features")

* **Cross-platform** -- native binaries for Windows and Linux.
* **Multi-database** -- Oracle, PostgreSQL, SQL Server, and Netezza as sources; SQL Server or PostgreSQL as target; SQL Server or PostgreSQL for migration tracking.
* **Dual-level parallelism** -- migrate multiple tables at once with `--n_jobs` and partition large tables internally with `--fasttransfer_p`.
* **Schema translation** -- automatic data type translation to SQL Server or PostgreSQL types, with column profiling for Oracle `NUMBER`/`DATE` columns.
* **Data validation** -- the `diff` task compares row counts, column counts and per-column statistics between source and target.
* **Flexible task management** -- run `translate`, `create`, `transfer`, `diff`, `copy_pk`, `copy_ak`, `copy_fk` (or `--task_list all`); tasks always execute in this canonical order.
* **Scheduler-friendly exit codes** -- `0` when every table succeeded, `40`/`41` when some or all tables failed (retry with `--resume`), `10`/`20` for configuration and validation errors detected before any connection.

## Supported migration paths[​](#supported-migration-paths "Direct link to Supported migration paths")

| Database   | As Source | As Target | Migration Tracking |
| ---------- | --------- | --------- | ------------------ |
| Oracle     | ✅        | ❌        | ❌                 |
| PostgreSQL | ✅        | ✅        | ✅                 |
| SQL Server | ✅        | ✅        | ✅                 |
| Netezza    | ✅        | ❌        | ❌                 |

## Quick example[​](#quick-example "Direct link to Quick example")

A full Oracle-to-SQL Server migration on Linux (the database names come from the auth entries of `credentials.json`):

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

This single command translates the Oracle `SALES` schema to SQL Server data types, creates the tables, streams the data (two tables at a time, large tables split into two parallel streams), and validates the result with a diff.

## Data transfer with FastTransfer[​](#data-transfer-with-fasttransfer "Direct link to Data transfer with FastTransfer")

MigratorXpress delegates all data movement to FastTransfer, which uses a streaming architecture. Rows flow directly from source to target without being buffered entirely in memory. This design handles tables with billions of rows on modest hardware and avoids the out-of-memory failures common with dump-and-load approaches.

## What's new in 0.7[​](#whats-new-in-07 "Direct link to What's new in 0.7")

* **Per-run metadata snapshots (0.7.0)** -- the catalog tables of the tracking database (`sources`, `sourcecolumns`, `sourceconstraints`, `targets`, `targetcolumns`) now include `run_id` in their primary keys. Each run keeps its own snapshot, and a run only acts on the tables discovered in that same run (no more "ghost" tables from earlier runs reported as failures).
* **Tracking database upgrade (0.7.0)** -- tracking databases created by 0.6.x are upgraded in place, automatically on the first 0.7 run or manually with `--upgrade_migdb`. Back up the tracking database first. See [Upgrading the tracking database](/latest/reference/cli-reference.md#upgrading-the-tracking-database).
* **Diff fix (0.7.1)** -- the `diff` task no longer fails with `Reindexing only valid with uniquely valued Index objects` on tracking databases holding several runs (SQL Server, Oracle and Netezza statistics queries are now scoped to the current run).
* **PostgreSQL target (0.7.2)** -- data types are translated for the (source, target) pair, so SQL Server, Oracle and PostgreSQL sources can be migrated to PostgreSQL. Target schema, table and column names are lower-cased. `copy_fk` stays SQL Server-only. Since 0.7.3, data is transferred exactly (binary, fractional seconds, time zones) and `diff` works against a PostgreSQL target.
* **More authentication modes (0.7.2)** -- `connection_string` (PostgreSQL, SQL Server), `trusted` (SQL Server integrated authentication, Kerberos on Linux) and `odbc` (SQL Server source or tracking database). See [Authentication modes](/latest/configuration/database-configuration.md#authentication-modes).
* **Startup checks and exit codes (0.7.2, 0.7.3)** -- auth entries and unsupported combinations are rejected before any connection (exit code `10`), invalid task options exit with `20`, and a run with failed tables exits with `40` (some) or `41` (all) instead of `0`. See [Exit Codes](/latest/reference/cli-reference.md#exit-codes).
* **Database names from the auth file (0.7.2)** -- `--source_db_name` is deprecated and ignored, and `--target_db_name` is optional (when given, it must match the target auth entry).
* **`--drop_tables_if_exists false` fixed (0.7.2)** -- `false`/`no`/`0` now disable the option; before, any value enabled it.
* **Constraint copy from PostgreSQL and SQL Server sources (0.7.3)** -- `copy_pk`, `copy_ak` and `copy_fk` are no longer limited to Oracle sources. See [Migration Tasks](/latest/configuration/migration-tasks.md#constraint-copy-support).
* **Safer FastTransfer calls (0.7.2)** -- FastTransfer is started without a shell, so passwords with special characters or spaces reach it unchanged, and passwords and connection strings are masked in the logs.

## Next steps[​](#next-steps "Direct link to Next steps")

Ready to migrate?

[Get Started](/latest/guides/quickstart.md)[Command Builder](/latest/wizard.md)[Examples & Use Cases](/latest/guides/examples.md)


---

# MigratorXpress Agent Skill

arpe.io publishes official agent skills in the [arpe-io/arpeio-skills](https://github.com/arpe-io/arpeio-skills) GitHub repository. The [`migratorxpress`](https://github.com/arpe-io/arpeio-skills/tree/main/plugins/migratorxpress/skills/migratorxpress) skill teaches your AI agent how to build, explain and troubleshoot MigratorXpress migrations: the credentials file, task lists, schema and table selection, resuming a failed run, and the mistakes to avoid.

The same repository also has skills for FastBCP, FastTransfer, LakeXpress and the arpe.io ADBC drivers.

Skill or MCP server?

The skill is a set of instructions: it teaches the agent how MigratorXpress works, and the agent writes the command. The [arpe.io MCP server](/latest/ai/mcp-server.md) gives the agent tools that build, validate and, if you allow it, run MigratorXpress commands. The two work well together, so install both if your agent supports them.

## Claude Code[​](#claude-code "Direct link to Claude Code")

Install the skill as a plugin from the arpe.io marketplace:

```
/plugin install migratorxpress --marketplace arpe-io/arpeio-skills
```

Or in two steps:

```
/plugin marketplace add arpe-io/arpeio-skills
/plugin install migratorxpress@arpe-io
```

Then just ask, for example: *"Migrate the HR schema from Oracle to PostgreSQL with MigratorXpress"*.

To get the latest version of the skill later:

```
/plugin marketplace update arpe-io
/plugin update migratorxpress@arpe-io
```

## Other agents (Codex, Cursor, GitHub Copilot, Gemini CLI…)[​](#other-agents-codex-cursor-github-copilot-gemini-cli "Direct link to Other agents (Codex, Cursor, GitHub Copilot, Gemini CLI…)")

Copy the skill folder into the directory your agent reads skills from:

```
git clone https://github.com/arpe-io/arpeio-skills.git
cp -r arpeio-skills/plugins/migratorxpress/skills/migratorxpress <your-agent-skills-dir>/
```

For agents without skill support, paste the content of [`SKILL.md`](https://github.com/arpe-io/arpeio-skills/blob/main/plugins/migratorxpress/skills/migratorxpress/SKILL.md) as custom instructions. The files in its `references/` folder can be attached or pasted when needed.

## Product version[​](#product-version "Direct link to Product version")

The skill states the MigratorXpress version its facts were checked against. Before building a command, it asks the agent to check the installed version (`MigratorXpress --version`) and to confirm against this documentation when the installed product is newer.

## Reporting issues[​](#reporting-issues "Direct link to Reporting issues")

If the agent gets something wrong, open an issue at [github.com/arpe-io/arpeio-skills/issues](https://github.com/arpe-io/arpeio-skills/issues) with the MigratorXpress version, the prompt you gave, and the command the agent produced (with passwords and licence text removed).


---

# MigratorXpress MCP Server

The [arpe.io MCP server](https://github.com/arpe-io/arpeio-mcp) (`arpeio-mcp`) gives AI assistants a set of tools for the arpe.io products: FastBCP, FastTransfer, MigratorXpress, LakeXpress and the arpe.io ADBC drivers. [MCP](https://modelcontextprotocol.io) (Model Context Protocol) is the open standard that Claude, ChatGPT, Cursor, VS Code and most other assistants use to call external tools.

For MigratorXpress, the assistant can ask the server to validate a set of parameters and render the exact MigratorXpress command, look up what MigratorXpress supports, read the release notes and search this documentation. If MigratorXpress is installed on your machine, it can also run the command.

The server runs in one of two modes:

* **Command builder**, the default. The tools build, validate and explain commands; no MigratorXpress binary is needed. The hosted server works this way, so it never connects to your databases.
* **Execution**. When you install the server on your own machine and point it at your MigratorXpress binary, the assistant can also run the command it built, once you confirm it.

MCP server or agent skill?

The MCP server gives the assistant tools to call. The [agent skill](/latest/ai/agent-skills.md) is a set of instructions that teaches it how the product works. The two work well together, so install both if your assistant supports them.

## Connect your assistant[​](#connect-your-assistant "Direct link to Connect your assistant")

arpe.io hosts the server, so there is nothing to install. Add this URL to your assistant:

```
https://arpe-io-arpeio-mcp.hf.space/sse
```

* Claude Code
* Claude Desktop
* ChatGPT
* Cursor
* VS Code (Copilot)
* Gemini CLI
* Windsurf
* Le Chat (Mistral)

```
claude mcp add --transport sse arpeio https://arpe-io-arpeio-mcp.hf.space/sse
```

Add the server to your Claude Desktop configuration file:

* **Linux**: `~/.config/Claude/claude_desktop_config.json`
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```
{
  "mcpServers": {
    "arpeio": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://arpe-io-arpeio-mcp.hf.space/sse"
      ]
    }
  }
}
```

Custom connectors need a paid plan (Plus, Pro, Team or Enterprise).

1. Open ChatGPT in your browser, go to **Settings** > **Apps and connectors**.
2. Open **Advanced settings** and enable **Developer mode**.
3. Go to **Connectors** > **Browse connectors** > **Add a new connector**.
4. Set the URL to `https://arpe-io-arpeio-mcp.hf.space/sse` and save.

Open Cursor Settings, search for "MCP" and add a server with this configuration:

```
{
  "mcpServers": {
    "arpeio": {
      "url": "https://arpe-io-arpeio-mcp.hf.space/sse"
    }
  }
}
```

Run **MCP: Open User Configuration** from the Command Palette and add:

```
{
  "servers": {
    "arpeio": {
      "url": "https://arpe-io-arpeio-mcp.hf.space/sse",
      "type": "sse"
    }
  }
}
```

Add the server to `~/.gemini/settings.json`:

```
{
  "mcpServers": {
    "arpeio": {
      "uri": "https://arpe-io-arpeio-mcp.hf.space/sse"
    }
  }
}
```

Add the server to `~/.codeium/windsurf/mcp_config.json` (Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`):

```
{
  "mcpServers": {
    "arpeio": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://arpe-io-arpeio-mcp.hf.space/sse"
      ]
    }
  }
}
```

Available on all plans, including the free one.

1. Go to **Intelligence** > **Connectors**.
2. Click **Add connector** > **Custom MCP Connector**.
3. Set the name to `Arpe.io` and the URL to `https://arpe-io-arpeio-mcp.hf.space/sse`.
4. Leave authentication disabled and click **Create**.

Instructions for HuggingChat and Kiro are in the [server README](https://github.com/arpe-io/arpeio-mcp#connect-your-ai-assistant).

## Run MigratorXpress from the assistant[​](#run-migratorxpress-from-the-assistant "Direct link to Run MigratorXpress from the assistant")

To let the assistant run MigratorXpress, install the server on the machine where MigratorXpress is installed (Python 3.10 or later):

```
pip install arpeio-mcp
```

Then register the `arpeio-mcp` command instead of the hosted URL, with the path to your binary. In Claude Code:

```
claude mcp add --transport stdio --env MIGRATORXPRESS_PATH=/path/to/MigratorXpress --env FASTTRANSFER_DIR_PATH=/path/to/FastTransfer/directory arpeio -- arpeio-mcp
```

In Claude Desktop, and in other clients that use the `mcpServers` format:

```
{
  "mcpServers": {
    "arpeio": {
      "command": "arpeio-mcp",
      "env": {
        "MIGRATORXPRESS_PATH": "/path/to/MigratorXpress",
        "FASTTRANSFER_DIR_PATH": "/path/to/FastTransfer/directory"
      }
    }
  }
}
```

| Variable                 | Description                                                                               |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| `MIGRATORXPRESS_PATH`    | Path to the MigratorXpress binary. Without it, the server only builds commands.           |
| `FASTTRANSFER_DIR_PATH`  | Directory holding the FastTransfer binary that MigratorXpress uses for the data transfer. |
| `MIGRATORXPRESS_TIMEOUT` | Execution timeout, in seconds. Optional.                                                  |
| `MIGRATORXPRESS_LOG_DIR` | Directory for the execution logs. Optional.                                               |
| `LOG_LEVEL`              | Server log level: `DEBUG`, `INFO` (default), `WARNING` or `ERROR`.                        |

## Tools[​](#tools "Direct link to Tools")

| Tool                                | What it does                                                                                 |
| ----------------------------------- | -------------------------------------------------------------------------------------------- |
| `migratorxpress_info`               | Reference information, picked with `action`: capabilities, workflow tips, version detection. |
| `migratorxpress_validate_auth_file` | Checks a credentials (auth) JSON file before it is used.                                     |
| `migratorxpress_preview_command`    | Validates the parameters and renders the MigratorXpress command.                             |
| `migratorxpress_execute_command`    | Runs the previewed command. Needs a local MigratorXpress binary and `confirmation: true`.    |

Tools shared by all arpe.io products:

| Tool                 | What it does                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| `arpe_quick_start`   | Picks the right arpe.io product for a use case described in plain English and returns a workflow guide. |
| `arpe_get_status`    | Shows which arpe.io binaries the server can run, and which are in command-builder mode only.            |
| `arpe_release_notes` | Returns release notes for a product, or for one version.                                                |
| `search_docs`        | Full-text search over the arpe.io documentation sites, this one included, and the arpe.io blog.         |

## How a request flows[​](#how-a-request-flows "Direct link to How a request flows")

1. You describe what you want, for example: *"Check my auth file, then migrate the HR schema from Oracle to PostgreSQL"*.
2. The assistant calls `migratorxpress_preview_command`. The tool checks the parameters and returns the MigratorXpress command, an explanation, and warnings when an option does not exist in the MigratorXpress version you run.
3. You review the command. Passwords are masked in the displayed version.
4. If execution is enabled, the assistant calls `migratorxpress_execute_command`. The tool refuses to run unless the call carries `confirmation: true`, and it returns the exit code, the output and a diagnosis of known errors.

Most clients also ask for your approval before each tool call.

## Prompts and resources[​](#prompts-and-resources "Direct link to Prompts and resources")

Clients that support MCP prompts (Claude Desktop, Cursor and others) list conversation starters: `migrate-database` for MigratorXpress, and `troubleshoot` to explain a failed run from its error message. The server also exposes the MigratorXpress capability matrix as the MCP resource `arpeio://capabilities/migratorxpress-capabilities`.

## Reporting issues[​](#reporting-issues "Direct link to Reporting issues")

If a tool returns a wrong command or wrong information, open an issue at [github.com/arpe-io/arpeio-mcp/issues](https://github.com/arpe-io/arpeio-mcp/issues) with the prompt you gave and the tool output (with passwords and licence text removed).


---

# Compatibility

This page describes MigratorXpress v0.7.3.

## Supported Databases[​](#supported-databases "Direct link to Supported Databases")

| Database   | As Source    | As Target    | Migration Tracking |
| ---------- | ------------ | ------------ | ------------------ |
| Oracle     | ✅ Supported | ❌           | ❌                 |
| PostgreSQL | ✅ Supported | ✅ Supported | ✅ Supported       |
| SQL Server | ✅ Supported | ✅ Supported | ✅ Supported       |
| Netezza    | ✅ Supported | ❌           | ❌                 |

### Source databases[​](#source-databases "Direct link to Source databases")

Any of the four supported databases can serve as a migration source. MigratorXpress reads the schema metadata and data, translates the column data types, and streams rows via FastTransfer.

* **[Oracle](/latest/configuration/databases/oracle.md)** -- thin and thick client modes, Rowid-based parallel extraction
* **[PostgreSQL](/latest/configuration/databases/postgresql.md)** -- Ctid-based parallel extraction
* **[SQL Server](/latest/configuration/databases/sql-server.md)** -- no intra-table parallel method; use `--n_jobs` for table-level parallelism
* **[Netezza](/latest/configuration/databases/netezza.md)** -- NZDataSlice-based parallel extraction

### Target databases[​](#target-databases "Direct link to Target databases")

SQL Server and PostgreSQL can be migration targets. MigratorXpress translates the column data types for the target, creates the target schema and tables, transfers data, and optionally copies constraints.

* **[SQL Server](/latest/configuration/databases/sql-server-as-target.md)** -- supports Clustered Columnstore Indexes via `--cci_threshold` / `--aci_threshold`, and foreign key copy with `--fk_mode`
* **[PostgreSQL](/latest/configuration/databases/postgresql-as-target.md)** -- from Oracle, PostgreSQL and SQL Server sources; schema, table and column names are created in lower case; no `copy_fk`

### Supported migration paths[​](#supported-migration-paths "Direct link to Supported migration paths")

| Source → Target         | `translate` / `create` / `transfer` / `diff` | `copy_pk` / `copy_ak` | `copy_fk` |
| ----------------------- | -------------------------------------------- | --------------------- | --------- |
| Oracle → SQL Server     | ✅                                           | ✅                    | ✅        |
| PostgreSQL → SQL Server | ✅                                           | ✅                    | ✅        |
| SQL Server → SQL Server | ✅                                           | ✅                    | ✅        |
| Netezza → SQL Server    | ✅                                           | ❌                    | ❌        |
| Oracle → PostgreSQL     | ✅                                           | ✅                    | ❌        |
| PostgreSQL → PostgreSQL | ✅                                           | ✅                    | ❌        |
| SQL Server → PostgreSQL | ✅                                           | ✅                    | ❌        |
| Netezza → PostgreSQL    | ❌                                           | ❌                    | ❌        |

Unsupported combinations are rejected at startup, before any connection, with exit code `10`: Netezza to PostgreSQL (`UNSUPPORTED_SOURCE_TARGET_PAIR`), a `copy_*` task with a Netezza source (`CONSTRAINT_COPY_UNSUPPORTED_SOURCE`), and `copy_fk` -- including `--task_list all` -- with a PostgreSQL target (`COPY_FK_UNSUPPORTED_TARGET`).

Foreign keys that reference a table in another schema are logged as a warning and not copied: the target foreign keys are created within the target schema.

Oracle to PostgreSQL

The exactness of transferred values (binary columns, fractional seconds, time zones) was checked for PostgreSQL and SQL Server sources loaded into PostgreSQL, but not for Oracle sources. Run the `diff` task and spot-check date, timestamp and binary columns after an Oracle to PostgreSQL migration.

### Migration tracking database[​](#migration-tracking-database "Direct link to Migration tracking database")

The migration tracking database can be **SQL Server** or **PostgreSQL**. It stores per-table task status, metadata snapshots, diff results, constraint metadata, and event logs. This database enables the `--resume` capability and provides a full audit trail. The backend is selected by the `ds_type` of the entry referenced by `--migration_db_auth_id` (`mssql` or `postgres`); no extra flag is required.

* **[SQL Server as Migration Tracking](/latest/configuration/databases/sql-server-as-tracking.md)** -- tracking tables in the default schema (`dbo`)
* **[PostgreSQL as Migration Tracking](/latest/configuration/databases/postgresql-as-tracking.md)** -- tracking tables in the `public` schema

## Supported Platforms[​](#supported-platforms "Direct link to Supported Platforms")

| Platform | Architecture |
| -------- | ------------ |
| Windows  | x64          |
| Linux    | x64          |

MigratorXpress ships as a native binary for each platform. No runtime installation (Python, Java, .NET) is required. Data transfer requires [FastTransfer](https://www.arpe.io/fasttransfer/) 0.15.0 or later.

## See Also[​](#see-also "Direct link to See Also")

* [Quick Start Guide](/latest/guides/quickstart.md) -- get started in 5 minutes
* [CLI Reference](/latest/reference/cli-reference.md) -- all command-line options
* [Database Configuration](/latest/configuration/database-configuration.md) -- connection setup for each database type


---

# Database Connections

MigratorXpress requires three database connections for every migration:

1. **Source Database** -- the database you are migrating from.
2. **Target Database** -- the database that receives the translated schema and data.
3. **Migration Tracking Database** -- a SQL Server or PostgreSQL database that records every migration step for auditing and resumability.

## Supported Databases[​](#supported-databases "Direct link to Supported Databases")

### Source Databases[​](#source-databases "Direct link to Source Databases")

| Database                                                        | Parallel Transfer Method            | Notes                                                                              |
| --------------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------- |
| **[PostgreSQL](/latest/configuration/databases/postgresql.md)** | Ctid                                | No key column required                                                             |
| **[Oracle](/latest/configuration/databases/oracle.md)**         | Rowid                               | Thin and thick client modes; requires `SELECT_CATALOG_ROLE` for parallel transfers |
| **[SQL Server](/latest/configuration/databases/sql-server.md)** | None (table-level parallelism only) | Also usable as target and migration tracking                                       |
| **[Netezza](/latest/configuration/databases/netezza.md)**       | NZDataSlice                         | Source-only; default port 5480                                                     |

### Target Databases[​](#target-databases "Direct link to Target Databases")

| Database                                                                  | Notes                                                                          |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **[SQL Server](/latest/configuration/databases/sql-server-as-target.md)** | Supported target; columnstore index options (`cci_threshold`, `aci_threshold`) |
| **[PostgreSQL](/latest/configuration/databases/postgresql-as-target.md)** | From Oracle, PostgreSQL and SQL Server sources; lower-case names; no `copy_fk` |

### Migration Tracking Database[​](#migration-tracking-database "Direct link to Migration Tracking Database")

| Database                                                                    | Notes                                                    |
| --------------------------------------------------------------------------- | -------------------------------------------------------- |
| **[SQL Server](/latest/configuration/databases/sql-server-as-tracking.md)** | `ds_type: "mssql"`; tables in the default schema (`dbo`) |
| **[PostgreSQL](/latest/configuration/databases/postgresql-as-tracking.md)** | `ds_type: "postgres"`; tables in the `public` schema     |

A tracking database is required for every migration; it stores run history, task status, and resume state. The backend is detected from the `ds_type` of the entry referenced by `--migration_db_auth_id`.

## Authentication File Format[​](#authentication-file-format "Direct link to Authentication File Format")

Create a JSON file containing one entry per database connection. Each entry has a unique identifier (the JSON key), a `ds_type`, an `auth_mode`, and an `info` object with connection details. No other key is accepted.

The fields of a `classic` entry (the mode available for every database type; see [Authentication modes](#authentication-modes) for the others):

| Field           | Required | Description                                          |
| --------------- | -------- | ---------------------------------------------------- |
| `ds_type`       | Yes      | `oracle`, `postgres`, `mssql`, or `netezza`          |
| `auth_mode`     | Yes      | `classic`, `connection_string`, `trusted` or `odbc`  |
| `info.username` | Yes      | Database user                                        |
| `info.password` | Yes      | Password (plain text)                                |
| `info.server`   | Yes      | Hostname or IP address                               |
| `info.port`     | Yes      | Port, as a JSON integer (1-65535)                    |
| `info.database` | Yes      | Database name (Oracle: service name)                 |
| `info.lib_dir`  | No       | Oracle only: Instant Client directory for thick mode |

```
{
  "source_oracle": {
    "ds_type": "oracle",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "oracle-prod.company.com",
      "port": 1521,
      "database": "PRODPDB"
    }
  },
  "source_postgres": {
    "ds_type": "postgres",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "pg-prod.company.com",
      "port": 5432,
      "database": "analytics"
    }
  },
  "target_mssql": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "sql-host.company.com",
      "port": 1433,
      "database": "target_db"
    }
  },
  "source_netezza": {
    "ds_type": "netezza",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "nz-host.company.com",
      "port": 5480,
      "database": "PROD_DB"
    }
  },
  "migration_tracking": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "sql-host.company.com",
      "port": 1433,
      "database": "migration_log"
    }
  }
}
```

No environment variable substitution

Values in the credentials file are used exactly as written. MigratorXpress does not expand environment variables (a value such as `$env{PG_PASSWORD}` would be sent literally as the password). Protect the file with file-system permissions (see below), or generate it from your secret manager just before the run.

## Authentication Modes[​](#authentication-modes "Direct link to Authentication Modes")

| `auth_mode`         | Database types                                        | `info` keys                                                                                        |
| ------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `classic`           | All                                                   | `username`, `password`, `server`, `port`, `database` (required); `lib_dir` (Oracle only, optional) |
| `connection_string` | PostgreSQL, SQL Server                                | `connection_string` (required); `driver_options` (optional)                                        |
| `trusted`           | SQL Server                                            | `server`, `database` (required); `port`, `driver_options` (optional)                               |
| `odbc`              | SQL Server, as a **source or tracking database only** | `dsn` (required); `username`, `password`, `database`, `driver_options` (optional)                  |

Oracle and Netezza support `classic` only.

### `connection_string`[​](#connection_string "Direct link to connection_string")

`info.connection_string` is an ADO.NET connection string, as understood by FastTransfer: Npgsql keywords for PostgreSQL, SqlClient keywords for SQL Server. It is passed unchanged to FastTransfer, and parsed for the metadata connections that MigratorXpress opens itself. The database name is taken from the connection string.

```
{
  "pg_target": {
    "ds_type": "postgres",
    "auth_mode": "connection_string",
    "info": {
      "connection_string": "Host=pg.company.com;Port=5432;Database=dwh;Username=migrator;Password=********;SSL Mode=Require"
    }
  },
  "mssql_cs": {
    "ds_type": "mssql",
    "auth_mode": "connection_string",
    "info": {
      "connection_string": "Server=tcp:sql-host.company.com,1433;Database=target_db;User ID=migrator;Password=********;Encrypt=True;TrustServerCertificate=True",
      "driver_options": { "login_timeout": 30 }
    }
  }
}
```

* Keywords are case-insensitive and their usual aliases are accepted; quoted values, `host,port`, `host\instance` and `tcp:` server forms are understood.
* `SSL Mode`, `Timeout`, `Application Name` and `Root Certificate` (PostgreSQL), and `Encrypt`, `Connect Timeout` and `Application Name` (SQL Server) are also applied to the metadata connections. `TrustServerCertificate` and unknown keywords are logged as a warning and used by FastTransfer only.
* The optional `info.driver_options` object is merged over the arguments of the metadata connections (psycopg2 for PostgreSQL, pymssql for SQL Server).
* For SQL Server, `Integrated Security=true` (or `SSPI`) or `Trusted_Connection=yes` uses integrated authentication, as `trusted` below; a `User ID` / `Password` is then ignored with a warning.

### `trusted` (SQL Server integrated authentication)[​](#trusted-sql-server-integrated-authentication "Direct link to trusted-sql-server-integrated-authentication")

No user name or password: the connection uses the account running MigratorXpress -- SSPI on Windows, Kerberos on Linux.

```
{
  "mssql_trusted": {
    "ds_type": "mssql",
    "auth_mode": "trusted",
    "info": {
      "server": "sql-host.corp.company.com",
      "port": 1433,
      "database": "target_db"
    }
  }
}
```

On Linux, MigratorXpress and FastTransfer both need:

* a Kerberos ticket for the account running the migration (`kinit`, or `kinit -kt` with a keytab), valid for the whole run;
* `/etc/krb5.conf` with the realm and its KDC;
* the server given by its fully qualified domain name (not an IP address or a CNAME alias);
* the service principal `MSSQLSvc/<fqdn>:<port>` registered for the SQL Server service account;
* the system GSSAPI library (`libgssapi_krb5`) for FastTransfer.

### `odbc` (SQL Server source or tracking database)[​](#odbc-sql-server-source-or-tracking-database "Direct link to odbc-sql-server-source-or-tracking-database")

```
{
  "mssql_src_odbc": {
    "ds_type": "mssql",
    "auth_mode": "odbc",
    "info": {
      "dsn": "MSSQL_DSN",
      "username": "migrator",
      "password": "********",
      "database": "SourceDB"
    }
  }
}
```

* `odbc` cannot be used for the target (FastTransfer has no ODBC target): use `classic`, `connection_string` or `trusted` there. Such an entry is rejected at startup with exit code `10`.
* Set `info.database`; without it, the database name is read from the server. `info.driver_options` holds extra `pyodbc.connect` arguments.
* ODBC is **not bundled**. On Linux, install the unixODBC driver manager (`libodbc.so.2`); on every platform, install the Microsoft ODBC Driver 18 for SQL Server and declare the DSN (`/etc/odbc.ini` or `~/.odbc.ini`, or the Windows ODBC Data Source Administrator). When they are missing, the run stops at startup with exit code `10` and a message saying what to install.

### Validation at startup[​](#validation-at-startup "Direct link to Validation at startup")

Every entry referenced on the command line is checked right after the file is loaded, before any connection is opened. An unknown `ds_type`, an `auth_mode` not supported for the database type (`AUTH_MODE_NOT_SUPPORTED`), a missing or unexpected `info` key (`INVALID_AUTH_ENTRY`), an unparsable connection string (`INVALID_CONNECTION_STRING`), or an auth ID that is not a key of the file stops the run with exit code `10`. The message names the entry and the key, never the value.

## Using the Auth File[​](#using-the-auth-file "Direct link to Using the Auth File")

Reference the file with `--auth` and point to individual entries by their ID. The source and target database names are taken from the entries, so `--source_db_name` (deprecated, ignored) and `--target_db_name` (optional; when given, it must match the target entry) are not needed:

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id source_oracle \
  --target_db_auth_id target_mssql \
  --migration_db_auth_id migration_tracking \
  --source_schema_name SALES \
  --target_schema_name sales \
  --task_list translate create transfer diff
```

## Security Best Practices[​](#security-best-practices "Direct link to Security Best Practices")

### 1. Credential Storage[​](#1-credential-storage "Direct link to 1. Credential Storage")

* Never commit credentials to version control.
* Restrict `credentials.json` permissions:
  <!-- -->
  ```
  chmod 600 credentials.json
  ```
* Use environment-specific auth files (dev, staging, prod).

### 2. Least Privilege[​](#2-least-privilege "Direct link to 2. Least Privilege")

* Create dedicated database users for MigratorXpress.
* Grant only SELECT on source databases.
* Grant CREATE, INSERT, UPDATE, DELETE on target databases.
* Use a dedicated database (SQL Server or PostgreSQL) for migration tracking.

### 3. Network Security[​](#3-network-security "Direct link to 3. Network Security")

* `classic` entries have no TLS options; use a `connection_string` entry (`SSL Mode` for PostgreSQL, `Encrypt` for SQL Server), server-side encryption settings, or a private network.
* Restrict database access by IP.
* Use VPN or private networks for cross-environment migrations.

### 4. Password Management[​](#4-password-management "Direct link to 4. Password Management")

* Use strong passwords (12+ characters, mixed case, numbers, symbols).
* Rotate passwords regularly.
* Consider secret managers (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault).

## See Also[​](#see-also "Direct link to See Also")

* [PostgreSQL](/latest/configuration/databases/postgresql.md) -- Source, target, and tracking configuration
* [Oracle](/latest/configuration/databases/oracle.md) -- Source configuration with thin/thick modes
* [SQL Server](/latest/configuration/databases/sql-server.md) -- Source, target, and migration tracking configuration
* [Netezza](/latest/configuration/databases/netezza.md) -- Source configuration
* [Quick Start Guide](/latest/guides/quickstart.md) -- Getting started with MigratorXpress
* [CLI Reference](/latest/reference/cli-reference.md) -- Command-line options


---

# Netezza

Netezza is supported as a source-only database in MigratorXpress, with SQL Server as the target (Netezza to PostgreSQL is not supported, and the constraint copy tasks `copy_pk`, `copy_ak` and `copy_fk` are not available for a Netezza source: both are rejected at startup with exit code `10`). It uses NZDataSlice-based parallel transfers for efficient extraction of large tables.

## Connection Parameters[​](#connection-parameters "Direct link to Connection Parameters")

| Parameter   | Required | Description                                               |
| ----------- | -------- | --------------------------------------------------------- |
| `ds_type`   | Yes      | Must be `"netezza"`                                       |
| `auth_mode` | Yes      | Must be `"classic"` (the only mode supported for Netezza) |
| `username`  | Yes      | Netezza username                                          |
| `password`  | Yes      | Netezza password                                          |
| `server`    | Yes      | Hostname or IP address                                    |
| `port`      | Yes      | Port number, as a JSON integer (usually 5480)             |
| `database`  | Yes      | Database name                                             |

## NZDataSlice Parallel Transfer[​](#nzdataslice-parallel-transfer "Direct link to NZDataSlice Parallel Transfer")

Netezza distributes data across internal data slices. MigratorXpress leverages this architecture by reading from individual data slices in parallel, which significantly improves throughput for large tables. No key column is required -- the parallelism is based on Netezza's internal data distribution.

The number of parallel streams is controlled by the `--fasttransfer_p` parameter. For best results, set it to a value that aligns with the number of data slices on your Netezza appliance.

## Required Permissions[​](#required-permissions "Direct link to Required Permissions")

```
-- Grant read access to the migration user
GRANT SELECT ON TABLE schema_name.table_name TO migratorxpress_user;

-- Or grant list access for an entire schema
GRANT LIST ON schema_name TO migratorxpress_user;
GRANT SELECT ON schema_name TO migratorxpress_user;
```

## Example[​](#example "Direct link to Example")

```
{
  "netezza_prod": {
    "ds_type": "netezza",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "nz-prod.company.com",
      "port": 5480,
      "database": "PROD_DB"
    }
  }
}
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

MigratorXpress connects to Netezza with the pure-Python `nzpy` driver: no ODBC driver is required on the MigratorXpress host.

**Connection refused:** Verify that the Netezza appliance is running and accessible. The default port is 5480, not the standard PostgreSQL port of 5432. Check firewall rules and network connectivity:

```
# Test connectivity
telnet nz-prod.company.com 5480
```

**Authentication failed:** Confirm the username and password are correct. Verify that the user has not been locked out and has the required permissions on the target database.

## See Also[​](#see-also "Direct link to See Also")

* [Database Connections Overview](/latest/configuration/database-configuration.md) -- Auth file format and security best practices


---

# Oracle

Oracle is supported as a source database in MigratorXpress. It supports both thin and thick client modes and uses Rowid-based parallel transfers for large tables.

## Connection Parameters[​](#connection-parameters "Direct link to Connection Parameters")

| Parameter   | Required | Description                                                           |
| ----------- | -------- | --------------------------------------------------------------------- |
| `ds_type`   | Yes      | Must be `"oracle"`                                                    |
| `auth_mode` | Yes      | Must be `"classic"` (the only mode supported for Oracle)              |
| `username`  | Yes      | Oracle username                                                       |
| `password`  | Yes      | Oracle password                                                       |
| `server`    | Yes      | Hostname or IP address                                                |
| `port`      | Yes      | Port number, as a JSON integer (usually 1521)                         |
| `database`  | Yes      | Service name (connections use `service_name`; SIDs are not supported) |
| `lib_dir`   | No       | Oracle Instant Client directory (thick mode only)                     |

## Thin vs Thick Mode[​](#thin-vs-thick-mode "Direct link to Thin vs Thick Mode")

**Thin Mode (Recommended):**

* No Oracle client libraries required on the machine running MigratorXpress.
* Requires Oracle 12.1 or later.
* Omit the `lib_dir` parameter.

**Thick Mode:**

* Required for Oracle 11.2 and earlier.
* Requires Oracle Instant Client installed locally.
* Set `lib_dir` to the Instant Client directory path.

## Required Permissions[​](#required-permissions "Direct link to Required Permissions")

Grant `SELECT_CATALOG_ROLE` to enable parallel Rowid-based transfers and metadata discovery:

```
-- As Oracle DBA (e.g., sys as sysdba)
GRANT SELECT_CATALOG_ROLE TO your_username;
```

This role provides access to data dictionary views needed for Rowid range partitioning and transfer method selection.

## Example: Thin Mode[​](#example-thin-mode "Direct link to Example: Thin Mode")

```
{
  "oracle_prod": {
    "ds_type": "oracle",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "oracle-prod.company.com",
      "port": 1521,
      "database": "PRODPDB"
    }
  }
}
```

## Example: Thick Mode[​](#example-thick-mode "Direct link to Example: Thick Mode")

```
{
  "oracle_legacy": {
    "ds_type": "oracle",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "oracle-11g.company.com",
      "port": 1521,
      "database": "LEGACY",
      "lib_dir": "/opt/oracle/instantclient_19_8"
    }
  }
}
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**ORA-12154: TNS could not resolve connect identifier:** Verify the service name in the `database` field (MigratorXpress connects with `host:port/service_name`, so TNS aliases from `tnsnames.ora` are not used). Try using the IP address instead of the hostname and confirm the Oracle listener is running (`lsnrctl status`).

**ORA-28000: account is locked:**

```
ALTER USER your_username ACCOUNT UNLOCK;
```

**Thick mode library not found:** Verify that the `lib_dir` path exists and contains the Instant Client shared libraries. Confirm Oracle Instant Client is installed and check file permissions. On Linux, you may also need to set `LD_LIBRARY_PATH`:

```
export LD_LIBRARY_PATH=/opt/oracle/instantclient_19_8:$LD_LIBRARY_PATH
```

## See Also[​](#see-also "Direct link to See Also")

* [Database Connections Overview](/latest/configuration/database-configuration.md) -- Auth file format and security best practices


---

# PostgreSQL

PostgreSQL can serve as a source, as a target, and as the migration tracking database in MigratorXpress. As a source, it supports Ctid-based parallel transfers for large tables. As a target, see [PostgreSQL as Target](/latest/configuration/databases/postgresql-as-target.md) for the target-specific behavior (lower-case names, no `copy_fk`).

## Connection Parameters[​](#connection-parameters "Direct link to Connection Parameters")

| Parameter   | Required | Description                                                                                                                                                    |
| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ds_type`   | Yes      | Must be `"postgres"`                                                                                                                                           |
| `auth_mode` | Yes      | `"classic"` (the parameters below) or `"connection_string"` (see [Authentication modes](/latest/configuration/database-configuration.md#authentication-modes)) |
| `username`  | Yes      | PostgreSQL username                                                                                                                                            |
| `password`  | Yes      | PostgreSQL password                                                                                                                                            |
| `server`    | Yes      | Hostname or IP address                                                                                                                                         |
| `port`      | Yes      | Port number, as a JSON integer (usually 5432)                                                                                                                  |
| `database`  | Yes      | Database name                                                                                                                                                  |

## Required Permissions[​](#required-permissions "Direct link to Required Permissions")

### As Source[​](#as-source "Direct link to As Source")

```
-- Grant read access to the migration user
GRANT USAGE ON SCHEMA public TO migratorxpress_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO migratorxpress_user;

-- For multiple schemas, repeat for each schema:
GRANT USAGE ON SCHEMA my_schema TO migratorxpress_user;
GRANT SELECT ON ALL TABLES IN SCHEMA my_schema TO migratorxpress_user;
```

### As Target[​](#as-target "Direct link to As Target")

```
-- Grant write access to the migration user
GRANT CREATE ON DATABASE target_db TO migratorxpress_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO migratorxpress_user;

-- If using a custom target schema:
CREATE SCHEMA IF NOT EXISTS target_schema;
GRANT ALL PRIVILEGES ON SCHEMA target_schema TO migratorxpress_user;
```

## Example[​](#example "Direct link to Example")

```
{
  "postgres_source": {
    "ds_type": "postgres",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "pg-prod.company.com",
      "port": 5432,
      "database": "analytics"
    }
  }
}
```

As a source, PostgreSQL provides its primary, unique and foreign keys (from `pg_constraint`) to the `copy_pk`, `copy_ak` and `copy_fk` tasks since 0.7.3, and the `NOT NULL` constraint of its columns is kept on the target.

## Example: Connection String[​](#example-connection-string "Direct link to Example: Connection String")

```
{
  "postgres_cs": {
    "ds_type": "postgres",
    "auth_mode": "connection_string",
    "info": {
      "connection_string": "Host=pg-prod.company.com;Port=5432;Database=analytics;Username=migrator;Password=********;SSL Mode=Require"
    }
  }
}
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**Connection refused:** Check that PostgreSQL is running (`systemctl status postgresql`), verify `pg_hba.conf` allows connections from your IP, and check firewall rules (`sudo ufw allow 5432/tcp`).

**Authentication failed:** Verify credentials, check the password encryption method in `pg_hba.conf` (md5, scram-sha-256), and confirm the user exists:

```
SELECT * FROM pg_user WHERE usename = 'your_user';
```

## See Also[​](#see-also "Direct link to See Also")

* [Database Connections Overview](/latest/configuration/database-configuration.md) -- Auth file format and security best practices


---

# PostgreSQL as Target

PostgreSQL can be the migration target for **SQL Server, Oracle and PostgreSQL** sources (since 0.7.2). A Netezza source cannot be migrated to PostgreSQL: the run stops at startup with exit code `10` (`UNSUPPORTED_SOURCE_TARGET_PAIR`).

When used as a target, MigratorXpress translates the source column types to PostgreSQL types, creates the target schema automatically (`CREATE SCHEMA IF NOT EXISTS`) and loads data with FastTransfer's PostgreSQL `COPY` loader (`pgcopy`).

## Behavior with a PostgreSQL Target[​](#behavior-with-a-postgresql-target "Direct link to Behavior with a PostgreSQL Target")

* **Lower-case names.** Target schema, table and column names are created in lower case: a source table `Sales.Orders` lands in `sales.orders`. The names are recorded in lower case in the tracking database and passed in lower case to FastTransfer.
* **Constraints.** `copy_pk` and `copy_ak` are supported. `copy_fk` (and `--fk_mode`) is SQL Server-only: a task list containing `copy_fk` -- including `--task_list all` -- is rejected at startup with exit code `10` (`COPY_FK_UNSUPPORTED_TARGET`). Use an explicit list such as `--task_list translate create transfer diff copy_pk copy_ak`.
* **No columnstore options.** `--cci_threshold` and `--aci_threshold` are ignored (logged as such).
* **Unsupported column types.** SQL Server `GEOGRAPHY` / `GEOMETRY` columns (PostGIS is not handled) and PostgreSQL `ARRAY` / user-defined columns make the `translate` task fail for their table, which is then not created. Exclude these tables (`--exclude_tables`) and migrate them separately.
* **Exact data.** A PostgreSQL source is read with FastTransfer's `pgcopy` source mode, and the date/time and binary columns of a SQL Server source are read as text that PostgreSQL parses back exactly (since 0.7.3). The exactness of an Oracle to PostgreSQL transfer was not verified: run `diff` and spot-check date, timestamp and binary columns.
* **Diff.** Source and target columns are matched case-insensitively, so `diff` works with the lower-cased target columns (since 0.7.3).

Resuming older runs

Runs started with a version older than 0.7.2 against a PostgreSQL target used the source case for schema and table names. Do not `--resume` them; start a new run.

For the complete connection reference and troubleshooting, see the canonical **[PostgreSQL](/latest/configuration/databases/postgresql.md)** page.

## Target-specific Permissions[​](#target-specific-permissions "Direct link to Target-specific Permissions")

```
-- Grant write access to the migration user
GRANT CREATE ON DATABASE target_db TO migratorxpress_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO migratorxpress_user;

-- If using a custom target schema:
CREATE SCHEMA IF NOT EXISTS target_schema;
GRANT ALL PRIVILEGES ON SCHEMA target_schema TO migratorxpress_user;
```

## Example Auth Entry[​](#example-auth-entry "Direct link to Example Auth Entry")

```
{
  "postgres_target": {
    "ds_type": "postgres",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "pg-target.company.com",
      "port": 5432,
      "database": "target_db"
    }
  }
}
```

Reference it on the command line with `--target_db_auth_id postgres_target`.

## See Also[​](#see-also "Direct link to See Also")

* [PostgreSQL](/latest/configuration/databases/postgresql.md) -- full connection reference
* [Database Connections](/latest/configuration/database-configuration.md) -- auth file format and security


---

# PostgreSQL as Migration Tracking

The migration tracking database can be PostgreSQL in addition to SQL Server. The two backends share the same schema (table names, columns, foreign keys, the `v_sourcetargetdiff` view) and the same workflow (run history, per-table task status, row counts, constraint copy results, event logs, `--resume`). MigratorXpress auto-detects the backend from the `ds_type` of the auth entry referenced by `--migration_db_auth_id` -- no extra CLI flag is required.

For the full PostgreSQL connection reference and troubleshooting, see the canonical **[PostgreSQL](/latest/configuration/databases/postgresql.md)** page.

## Schema and Object Naming[​](#schema-and-object-naming "Direct link to Schema and Object Naming")

* Tracking tables and the `v_sourcetargetdiff` view live in the `public` schema.
* Types map to PG natives: `timestamp`, `text`, `boolean`, `varchar(N)`, `numeric(32,6)`.
* The internal sequence `seq_id_load` is a standard `CREATE SEQUENCE`.
* Idempotent DDL uses `CREATE TABLE IF NOT EXISTS`, `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`, `CREATE OR REPLACE VIEW`, and `INSERT ... ON CONFLICT DO UPDATE`.

## Tracking-specific Permissions[​](#tracking-specific-permissions "Direct link to Tracking-specific Permissions")

The tracking role needs full DDL/DML rights on the database hosting the tracking tables, because MigratorXpress creates tables, evolves the schema on upgrade, and writes rows continuously during a migration.

```
-- Full access to the migration tracking database
GRANT CREATE ON DATABASE migration_log TO migratorxpress_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO migratorxpress_user;
ALTER SCHEMA public OWNER TO migratorxpress_user;
```

If the role is not the schema owner, future schema upgrades (added columns, new tables) can fail with `permission denied for schema public`. Owning the schema (or granting `ALL` on it) avoids that.

## Migration DB Modes[​](#migration-db-modes "Direct link to Migration DB Modes")

The `--migration_db_mode` flag controls how MigratorXpress treats the tracking schema at startup. Behavior is identical on SQL Server and PostgreSQL.

| Mode                 | Behavior                                                              |
| -------------------- | --------------------------------------------------------------------- |
| `preserve` (default) | Keep tracking data; required to use `--resume`                        |
| `truncate`           | Delete the content of all tracking tables (all runs), keep the tables |
| `drop`               | Drop and recreate all tracking tables                                 |

## Upgrading from 0.6[​](#upgrading-from-06 "Direct link to Upgrading from 0.6")

Tracking databases created by 0.6.x are upgraded in place to the 0.7 schema (`run_id` added to the catalog primary keys), automatically on the first 0.7 run or manually with `--upgrade_migdb`. Back up the database first. See [Upgrading the tracking database](/latest/reference/cli-reference.md#upgrading-the-tracking-database).

## Example Auth Entry[​](#example-auth-entry "Direct link to Example Auth Entry")

```
{
  "migration_tracking": {
    "ds_type": "postgres",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "pg-host.company.com",
      "port": 5432,
      "database": "migration_log"
    }
  }
}
```

Reference it on the command line with `--migration_db_auth_id migration_tracking`. The rest of the CLI is unchanged. The entry can also use `auth_mode` `connection_string` (see [Authentication modes](/latest/configuration/database-configuration.md#authentication-modes)).

## Querying the Tracking Tables[​](#querying-the-tracking-tables "Direct link to Querying the Tracking Tables")

The schema is the same across both backends, so any dashboard query that uses portable SQL (no `DATEDIFF`, `GETDATE()`, `TOP`, `+` for string concat) works on either. Example: list tables with errors for a given run.

```
SELECT src_schemaname, src_tablename, id_step, eventmessage, eventtimestamp
FROM eventlog
WHERE eventrunid = '20260511-...'
  AND eventstatus = 'FAILED'
ORDER BY eventtimestamp DESC;
```

For PG-specific date arithmetic and other reporting patterns, see [Logging and Monitoring](/latest/reference/logging.md).

## See Also[​](#see-also "Direct link to See Also")

* [PostgreSQL](/latest/configuration/databases/postgresql.md) -- full connection reference
* [SQL Server as Migration Tracking](/latest/configuration/databases/sql-server-as-tracking.md) -- equivalent doc for the SQL Server backend
* [Database Connections](/latest/configuration/database-configuration.md) -- auth file format and security
* [Logging and Monitoring](/latest/reference/logging.md) -- schema details and dashboard queries


---

# SQL Server

SQL Server is the most versatile database in MigratorXpress -- it can serve as a source, a target, and the migration tracking database.

## Connection Parameters[​](#connection-parameters "Direct link to Connection Parameters")

| Parameter   | Required | Description                                                                                                                                                                                                      |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ds_type`   | Yes      | Must be `"mssql"`                                                                                                                                                                                                |
| `auth_mode` | Yes      | `"classic"` (SQL Server authentication, the parameters below), `"connection_string"`, `"trusted"` or `"odbc"` (see [Authentication modes](/latest/configuration/database-configuration.md#authentication-modes)) |
| `username`  | Yes      | SQL Server login                                                                                                                                                                                                 |
| `password`  | Yes      | SQL Server password                                                                                                                                                                                              |
| `server`    | Yes      | Hostname or IP address                                                                                                                                                                                           |
| `port`      | Yes      | Port number, as a JSON integer (usually 1433)                                                                                                                                                                    |
| `database`  | Yes      | Database name                                                                                                                                                                                                    |

MigratorXpress connects to SQL Server with the `pymssql` driver: no ODBC driver is required on the MigratorXpress host, except for `odbc` entries. Besides SQL Server authentication (`classic`), SQL Server entries can use an ADO.NET connection string (`connection_string`), integrated authentication -- SSPI on Windows, Kerberos on Linux (`trusted`), or an ODBC DSN (`odbc`, for a source or the tracking database only). See [Authentication modes](/latest/configuration/database-configuration.md#authentication-modes).

note

SQL Server can fill all three roles in a MigratorXpress migration. You can even use the same SQL Server instance for source, target, and migration tracking by creating separate database entries in your auth file.

## Required Permissions[​](#required-permissions "Direct link to Required Permissions")

### As Source[​](#as-source "Direct link to As Source")

```
-- Grant read access for data transfer and schema discovery
GRANT SELECT ON SCHEMA::dbo TO migratorxpress_user;
GRANT VIEW DEFINITION ON SCHEMA::dbo TO migratorxpress_user;
```

### As Target[​](#as-target "Direct link to As Target")

```
-- Grant permissions for schema creation and data loading
GRANT CREATE TABLE TO migratorxpress_user;
GRANT ALTER ON SCHEMA::dbo TO migratorxpress_user;
GRANT INSERT ON SCHEMA::dbo TO migratorxpress_user;
GRANT UPDATE ON SCHEMA::dbo TO migratorxpress_user;
GRANT DELETE ON SCHEMA::dbo TO migratorxpress_user;
```

As a source, SQL Server has no intra-table parallel transfer method: use `--n_jobs` to transfer several tables at once. Since 0.7.3, a SQL Server source provides its primary, unique and foreign keys (from `sys.key_constraints` and `sys.foreign_keys`) to the `copy_pk`, `copy_ak` and `copy_fk` tasks.

### As Migration Tracking[​](#as-migration-tracking "Direct link to As Migration Tracking")

```
-- Full access to the migration tracking database
ALTER ROLE db_owner ADD MEMBER migratorxpress_user;
```

The migration tracking user needs full access to create and manage the internal tables that track migration runs, task statuses, and resume state.

## Example: Classic Authentication[​](#example-classic-authentication "Direct link to Example: Classic Authentication")

```
{
  "mssql_target": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "sql-prod.company.com",
      "port": 1433,
      "database": "TargetDB"
    }
  }
}
```

## Example: Integrated Authentication[​](#example-integrated-authentication "Direct link to Example: Integrated Authentication")

```
{
  "mssql_trusted": {
    "ds_type": "mssql",
    "auth_mode": "trusted",
    "info": {
      "server": "sql-prod.corp.company.com",
      "port": 1433,
      "database": "TargetDB"
    }
  }
}
```

On Linux, integrated authentication uses Kerberos: see the prerequisites in [Authentication modes](/latest/configuration/database-configuration.md#trusted-sql-server-integrated-authentication).

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**Login failed for user:** With `classic` entries, confirm that SQL Server authentication mode is set to "SQL Server and Windows Authentication" (mixed mode), not Windows-only. Verify the user exists with the correct permissions and check for IP restrictions.

**Cannot open database requested by the login:** Verify the database name, check that the user has been granted access, and confirm the database is online:

```
SELECT name, state_desc FROM sys.databases WHERE name = 'YourDB';
```

## See Also[​](#see-also "Direct link to See Also")

* [Database Connections Overview](/latest/configuration/database-configuration.md) -- Auth file format and security best practices


---

# SQL Server as Target

SQL Server is a migration target for every supported source (Oracle, PostgreSQL, SQL Server, Netezza). MigratorXpress translates source column types to SQL Server types, creates the target schema, streams data via FastTransfer, and can apply Clustered Columnstore Index (CCI) or archive compression based on row-count thresholds.

For the complete connection reference and troubleshooting, see the canonical **[SQL Server](/latest/configuration/databases/sql-server.md)** page.

## Target-specific Permissions[​](#target-specific-permissions "Direct link to Target-specific Permissions")

```
-- Grant permissions for schema creation and data loading
GRANT CREATE TABLE TO migratorxpress_user;
GRANT ALTER ON SCHEMA::dbo TO migratorxpress_user;
GRANT INSERT ON SCHEMA::dbo TO migratorxpress_user;
GRANT UPDATE ON SCHEMA::dbo TO migratorxpress_user;
GRANT DELETE ON SCHEMA::dbo TO migratorxpress_user;
```

## Target-specific CLI Options[​](#target-specific-cli-options "Direct link to Target-specific CLI Options")

| Option                                   | Purpose                                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------------------------ |
| `--cci_threshold N`                      | Create a Clustered Columnstore Index when a table has at least N rows (default 1,000,000)  |
| `--aci_threshold N`                      | Apply archive compression when a table has at least N rows (default 100,000,000)           |
| `--fk_mode {disabled,untrusted,trusted}` | Foreign-key enforcement strategy for `copy_fk` (Oracle, PostgreSQL and SQL Server sources) |

## Example Auth Entry[​](#example-auth-entry "Direct link to Example Auth Entry")

```
{
  "mssql_target": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "sql-target.company.com",
      "port": 1433,
      "database": "TargetDB"
    }
  }
}
```

Reference it on the command line with `--target_db_auth_id mssql_target`. A target entry can also use `auth_mode` `connection_string` or `trusted`, but not `odbc` (see [Authentication modes](/latest/configuration/database-configuration.md#authentication-modes)).

## See Also[​](#see-also "Direct link to See Also")

* [SQL Server](/latest/configuration/databases/sql-server.md) -- full connection reference
* [Database Connections](/latest/configuration/database-configuration.md) -- auth file format and security


---

# SQL Server as Migration Tracking

The migration tracking database is required for every MigratorXpress migration. It can be SQL Server (this page) or [PostgreSQL](/latest/configuration/databases/postgresql-as-tracking.md). It records run history, per-run metadata snapshots, per-table task status, row counts, constraint copy results, and event logs. This database also enables `--resume` for interrupted migrations.

For the complete connection reference and troubleshooting, see the canonical **[SQL Server](/latest/configuration/databases/sql-server.md)** page.

## Tracking-specific Permissions[​](#tracking-specific-permissions "Direct link to Tracking-specific Permissions")

```
-- Full access to the migration tracking database
ALTER ROLE db_owner ADD MEMBER migratorxpress_user;
```

The tracking user needs full access to create and manage the internal tables that record migration runs, task statuses, and resume state.

## Migration DB Modes[​](#migration-db-modes "Direct link to Migration DB Modes")

The `--migration_db_mode` flag controls how MigratorXpress treats the tracking schema at startup.

| Mode                 | Behavior                                                              |
| -------------------- | --------------------------------------------------------------------- |
| `preserve` (default) | Keep tracking data; required to use `--resume`                        |
| `truncate`           | Delete the content of all tracking tables (all runs), keep the tables |
| `drop`               | Drop and recreate all tracking tables                                 |

## Upgrading from 0.6[​](#upgrading-from-06 "Direct link to Upgrading from 0.6")

Tracking databases created by 0.6.x are upgraded in place to the 0.7 schema (`run_id` added to the catalog primary keys), automatically on the first 0.7 run or manually with `--upgrade_migdb`. Back up the database first; on large tracking databases the clustered primary key rebuild is the slowest step. See [Upgrading the tracking database](/latest/reference/cli-reference.md#upgrading-the-tracking-database).

## Example Auth Entry[​](#example-auth-entry "Direct link to Example Auth Entry")

```
{
  "migration_tracking": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "sql-host.company.com",
      "port": 1433,
      "database": "migration_log"
    }
  }
}
```

Reference it on the command line with `--migration_db_auth_id migration_tracking`. The tracking tables are created in the default schema of the login (normally `dbo`). The tracking entry can also use `auth_mode` `connection_string`, `trusted` or `odbc` (see [Authentication modes](/latest/configuration/database-configuration.md#authentication-modes)).

## See Also[​](#see-also "Direct link to See Also")

* [SQL Server](/latest/configuration/databases/sql-server.md) -- full connection reference
* [Database Connections](/latest/configuration/database-configuration.md) -- auth file format and security


---

# FastTransfer Configuration

MigratorXpress delegates all data movement to [FastTransfer](https://www.arpe.io/fasttransfer/) (>= 0.15.0 required), which uses a streaming architecture. Rows flow directly from source to target without being buffered entirely in memory, so tables with billions of rows can be transferred on modest hardware.

## FastTransfer Location[​](#fasttransfer-location "Direct link to FastTransfer Location")

`--fasttransfer_dir_path` is optional. When omitted, MigratorXpress looks for FastTransfer in the `engine/` subdirectory next to the MigratorXpress binary. Pass the flag to use a FastTransfer installed elsewhere. The FastTransfer version is checked at startup; an error is logged if it is older than 0.15.0.

FastTransfer is started directly from an argument list, without a shell, using the absolute path of the executable: passwords containing `"`, `$`, `` ` ``, `%` or spaces reach it unchanged. Passwords and connection strings are masked in the logged command and in FastTransfer's logged output.

## Connection Types[​](#connection-types "Direct link to Connection Types")

| Database   | As source                                        | As target |
| ---------- | ------------------------------------------------ | --------- |
| PostgreSQL | `pgsql` (`pgcopy` when the target is PostgreSQL) | `pgcopy`  |
| Oracle     | `oraodp`                                         | --        |
| SQL Server | `mssql` (`odbc` for an `odbc` auth entry)        | `msbulk`  |
| Netezza    | `nzsql`                                          | --        |

For a SQL Server source and a PostgreSQL target, tables with date/time (`datetime2`, `datetime`, `smalldatetime`, `datetimeoffset`, `time`) or binary (`binary`, `varbinary`, `image`) columns are read through a query (`--query`) that converts these columns to text that PostgreSQL parses back exactly. Other tables are read with `--sourceschema` / `--sourcetable`.

## Key Parameters[​](#key-parameters "Direct link to Key Parameters")

| Parameter                 | Type    | Default                      | Description                                                                                               |
| ------------------------- | ------- | ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--fasttransfer_dir_path` | Path    | `engine/` next to the binary | Directory containing the FastTransfer binary (optional)                                                   |
| `--fasttransfer_p`        | Integer | 1                            | Number of parallel streams within FastTransfer for large table partitioning                               |
| `--ft_large_table_th`     | Integer | 250,000,000                  | Tables with an estimated row count greater than or equal to this value are eligible for parallel transfer |
| `--n_jobs`                | Integer | 1                            | Number of tables to transfer simultaneously                                                               |

### Dual-Level Parallelism[​](#dual-level-parallelism "Direct link to Dual-Level Parallelism")

MigratorXpress supports two levels of parallelism:

* **`--n_jobs`** controls how many tables are transferred concurrently.
* **`--fasttransfer_p`** controls how many parallel streams each large table uses internally.

For example, `--n_jobs 4 --fasttransfer_p 2` transfers 4 tables simultaneously, and any table at or above the large table threshold is split into 2 parallel streams (except SQL Server sources, see below).

## Parallel Transfer Methods[​](#parallel-transfer-methods "Direct link to Parallel Transfer Methods")

Each source database uses a different method to partition tables for parallel transfer:

| Source Database | Method      | Key Column Required | Description                                                  |
| --------------- | ----------- | ------------------- | ------------------------------------------------------------ |
| PostgreSQL      | Ctid        | No                  | Splits by physical tuple ID                                  |
| Oracle          | Rowid       | No                  | Splits by physical ROWID; requires `SELECT_CATALOG_ROLE`     |
| Netezza         | NZDataSlice | No                  | Splits by internal data slice distribution                   |
| SQL Server      | None        | N/A                 | No intra-table parallelism; `--fasttransfer_p` has no effect |

### Method Selection Logic[​](#method-selection-logic "Direct link to Method Selection Logic")

MigratorXpress selects the parallel transfer method automatically based on the source database type. No manual configuration is needed. If `--fasttransfer_p` is 1 or the table's estimated row count is below `--ft_large_table_th`, the table is transferred as a single stream regardless of the source type. Row counts are database estimates unless `--compute_nbrows true` is set.

## Performance Tuning[​](#performance-tuning "Direct link to Performance Tuning")

### PostgreSQL Sources[​](#postgresql-sources "Direct link to PostgreSQL Sources")

Ctid-based parallelism works well with minimal configuration. Increase `--fasttransfer_p` for tables with hundreds of millions of rows. Start with 2-4 parallel streams and scale up based on available CPU and I/O bandwidth.

### Oracle Sources[​](#oracle-sources "Direct link to Oracle Sources")

Rowid-based parallelism requires `SELECT_CATALOG_ROLE` (see [Oracle configuration](/latest/configuration/databases/oracle.md)). Oracle parallel transfers benefit from higher stream counts on large tables. Consider 4-8 streams for tables exceeding 100M rows.

### Netezza Sources[​](#netezza-sources "Direct link to Netezza Sources")

NZDataSlice parallelism aligns with Netezza's internal data distribution. Set `--fasttransfer_p` to match or be a factor of the number of data slices on the appliance.

### SQL Server Sources[​](#sql-server-sources "Direct link to SQL Server Sources")

SQL Server sources use non-partitioned transfers. Parallelism is achieved at the table level via `--n_jobs`. For SQL Server sources, increase `--n_jobs` rather than `--fasttransfer_p`.

## SQL Server Target Options[​](#sql-server-target-options "Direct link to SQL Server Target Options")

When SQL Server is the target database, MigratorXpress supports additional options for columnstore indexes and foreign key handling. With a PostgreSQL target, `--cci_threshold` and `--aci_threshold` are ignored.

### Columnstore Indexes[​](#columnstore-indexes "Direct link to Columnstore Indexes")

| Parameter         | Type    | Default     | Description                                                         |
| ----------------- | ------- | ----------- | ------------------------------------------------------------------- |
| `--cci_threshold` | Integer | 1,000,000   | Create Clustered Columnstore Index for tables above this row count  |
| `--aci_threshold` | Integer | 100,000,000 | Use archive compression (COLUMNSTORE\_ARCHIVE) above this row count |

Tables >= `cci_threshold` but < `aci_threshold` get a standard CCI. Tables >= `aci_threshold` get a CCI with `DATA_COMPRESSION = COLUMNSTORE_ARCHIVE`. Tables below `cci_threshold` remain as standard rowstore tables.

### Foreign Key Mode[​](#foreign-key-mode "Direct link to Foreign Key Mode")

| Parameter   | Type   | Default    | Description                                                                                                                                                            |
| ----------- | ------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--fk_mode` | String | `disabled` | FK enforcement for `copy_fk` (SQL Server target only): `disabled` (created with NOCHECK and disabled), `untrusted` (NOCHECK but enabled), `trusted` (full enforcement) |

## Row Count Options[​](#row-count-options "Direct link to Row Count Options")

| Parameter          | Type    | Default | Description                                                                                                                                                                                                                                                                                                                  |
| ------------------ | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--compute_nbrows` | Boolean | false   | `true` to use `COUNT(*)` for exact row counts instead of database estimates                                                                                                                                                                                                                                                  |
| `--with_xid`       | Flag    | false   | Oracle and Netezza sources: skip a table whose maximum ROWID (Oracle) or creation transaction ID (Netezza) is unchanged since the last `--with_xid` run and whose target table holds rows. Ignored with `--drop_tables_if_exists`; no effect for PostgreSQL and SQL Server sources. Before 0.8.0 this skip was on by default |
| `--without_xid`    | Flag    | false   | Deprecated and ignored (warning): since 0.8.0 the skip is off unless `--with_xid` is given                                                                                                                                                                                                                                   |

## Configuration Examples[​](#configuration-examples "Direct link to Configuration Examples")

### Small Migration (< 10 tables, < 1M rows total)[​](#small-migration--10-tables--1m-rows-total "Direct link to Small Migration (< 10 tables, < 1M rows total)")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name HR \
  --target_db_auth_id mssql_target \
  --target_schema_name hr \
  --fasttransfer_dir_path ./FastTransfer_linux-x64_v0.15.0/ \
  --migration_db_auth_id ms_mig_log \
  --task_list translate create transfer diff
```

Default parallelism is sufficient. Single-stream transfer per table, one table at a time.

### Medium Migration (10-100 tables, up to 100M rows)[​](#medium-migration-10-100-tables-up-to-100m-rows "Direct link to Medium Migration (10-100 tables, up to 100M rows)")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name SALES \
  --target_db_auth_id mssql_target \
  --target_schema_name sales \
  --fasttransfer_dir_path ./FastTransfer_linux-x64_v0.15.0/ \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --fasttransfer_p 2 \
  --task_list translate create transfer diff
```

Four tables in parallel, large tables split into 2 streams each.

### Large Migration (100+ tables, billions of rows)[​](#large-migration-100-tables-billions-of-rows "Direct link to Large Migration (100+ tables, billions of rows)")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name WAREHOUSE \
  --target_db_auth_id mssql_target \
  --target_schema_name warehouse \
  --fasttransfer_dir_path ./FastTransfer_linux-x64_v0.15.0/ \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 8 \
  --fasttransfer_p 4 \
  --ft_large_table_th 500000 \
  --task_list translate create transfer diff
```

Eight tables in parallel, large tables (>= 500,000 rows) split into 4 streams. Adjust thresholds based on hardware capacity.

## Monitoring Performance[​](#monitoring-performance "Direct link to Monitoring Performance")

During and after a migration, you can query the migration tracking database to check progress and identify slow tables.

### Check Overall Progress[​](#check-overall-progress "Direct link to Check Overall Progress")

Per-table jobs live in `sourcetargetloads` (one row per table and task). `status` is `NULL` (or `NOT STARTED`) before a job runs, then `STARTED`, `DONE`, or `FAILED`.

```
SELECT
    l.desc_step,
    COUNT(*) AS total_tables,
    SUM(CASE WHEN s.status = 'DONE' THEN 1 ELSE 0 END) AS done,
    SUM(CASE WHEN s.status = 'STARTED' THEN 1 ELSE 0 END) AS running,
    SUM(CASE WHEN s.status = 'FAILED' THEN 1 ELSE 0 END) AS failed
FROM sourcetargetloads AS s
JOIN loadsteps AS l ON l.id_step = s.id_step
WHERE s.run_id = 'YOUR_RUN_ID'
GROUP BY l.desc_step;
```

### Identify Slow Tables[​](#identify-slow-tables "Direct link to Identify Slow Tables")

Each finished job writes an `eventlog` row with its elapsed time. Step `3` is `data_transfer`:

```
SELECT
    src_schemaname,
    src_tablename,
    eventstatus,
    elapsedtimeseconds
FROM eventlog
WHERE eventrunid = 'YOUR_RUN_ID'
    AND id_step = 3
    AND eventstatus IN ('DONE', 'FAILED')
ORDER BY elapsedtimeseconds DESC;
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**FastTransfer binary not found:** If you rely on auto-detection, check that FastTransfer is in the `engine/` directory next to the MigratorXpress binary. Otherwise verify that `--fasttransfer_dir_path` points to the directory containing the FastTransfer executable. Check file permissions and ensure the binary is executable (`chmod +x FastTransfer` on Linux).

**Transfer stalls on large tables:** Reduce `--fasttransfer_p` if the source or target database is under heavy load. Check network bandwidth between the MigratorXpress host and the databases.

**Out of memory errors:** FastTransfer's streaming architecture normally prevents memory issues. If they occur, reduce `--n_jobs` to lower the number of concurrent table transfers.

**Slow transfer throughput:**

* Increase `--fasttransfer_p` for large tables.
* Increase `--n_jobs` if the bottleneck is small-table overhead rather than individual table speed.
* Check that the network path between source and target is not saturated.
* Verify that the source database is not under heavy concurrent load.

## See Also[​](#see-also "Direct link to See Also")

* [Migration Tasks](/latest/configuration/migration-tasks.md) -- Task execution order and combinations
* [Database Connections](/latest/configuration/database-configuration.md) -- Auth file configuration
* [Quick Start Guide](/latest/guides/quickstart.md) -- Getting started with MigratorXpress
* [CLI Reference](/latest/reference/cli-reference.md) -- Full command-line reference


---

# Migration Tasks

MigratorXpress organizes migrations into discrete tasks. You choose which tasks to run with the `--task_list` parameter. Use `--task_list all` as a shortcut for all seven tasks.

## Available Tasks[​](#available-tasks "Direct link to Available Tasks")

| Task        | Description                                                                                                                              | When to Use                 |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `translate` | Translate source column data types to the target (SQL Server or PostgreSQL) data types, with profiling of Oracle `NUMBER`/`DATE` columns | First step of any migration |
| `create`    | Create the target tables from the translated columns (a table whose translation failed is not created)                                   | After translation           |
| `transfer`  | Copy data from source to target with FastTransfer                                                                                        | After tables are created    |
| `diff`      | Compare source and target: row and column counts, plus per-column statistics unless `--basic_diff` is set                                | After transfer              |
| `copy_pk`   | Copy primary key constraints to the target database                                                                                      | After transfer              |
| `copy_ak`   | Copy alternate key (unique) constraints to the target database                                                                           | After primary keys          |
| `copy_fk`   | Copy foreign key constraints to the target database (SQL Server target only)                                                             | After primary keys          |

## Execution Order[​](#execution-order "Direct link to Execution Order")

`all` is a shortcut for the seven tasks; since it includes `copy_fk`, it is rejected with a PostgreSQL target.

Tasks always run in this canonical order, **whatever order you type them in**:

```
translate → create → transfer → diff → copy_pk → copy_ak → copy_fk
```

`--task_list diff transfer` and `--task_list transfer diff` are equivalent; the sorted list is written to the log (`sorted task list : [...]`). Each task is completed for every selected table (and every schema, in multi-schema runs) before the next task starts. Duplicated or unknown task names are rejected.

## Accepted Combinations[​](#accepted-combinations "Direct link to Accepted Combinations")

Not every subset is accepted. A task list must be one of these combinations (shown in execution order), otherwise the run stops with `incorrect task sequence`:

| Tasks   | Accepted combinations                                                                                                                                                                                                                                                                                              |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 task  | any single task                                                                                                                                                                                                                                                                                                    |
| 2 tasks | `translate create`, `create transfer`, `transfer diff`, `transfer copy_pk`, `diff copy_pk`, `copy_pk copy_ak`, `copy_pk copy_fk`, `copy_ak copy_fk`                                                                                                                                                                |
| 3 tasks | `translate create transfer`, `translate create copy_pk`, `create transfer diff`, `transfer diff copy_pk`, `transfer copy_pk copy_ak`, `diff copy_pk copy_ak`, `transfer copy_pk copy_fk`, `diff copy_pk copy_fk`, `copy_pk copy_ak copy_fk`                                                                        |
| 4 tasks | `translate create transfer diff`, `translate create transfer copy_pk`, `translate create transfer copy_ak`, `create transfer diff copy_pk`, `create transfer copy_pk copy_ak`, `transfer diff copy_pk copy_ak`, `create transfer copy_pk copy_fk`, `transfer diff copy_pk copy_fk`, `diff copy_pk copy_ak copy_fk` |
| 5 tasks | `translate create transfer diff copy_pk`, `translate create transfer copy_pk copy_ak`, `translate create transfer copy_pk copy_fk`, `translate create transfer copy_ak copy_fk`, `create transfer diff copy_pk copy_ak`, `create transfer diff copy_pk copy_fk`, `create transfer diff copy_ak copy_fk`            |
| 6 tasks | `translate create transfer diff copy_pk copy_ak`, `translate create transfer diff copy_pk copy_fk`, `translate create transfer copy_pk copy_ak copy_fk`, `create transfer diff copy_pk copy_ak copy_fk`                                                                                                            |
| 7 tasks | `all` (or the seven tasks listed explicitly)                                                                                                                                                                                                                                                                       |

For example, `translate transfer` (skipping `create`) and `translate diff` are rejected.

When `--task_list` and `--resume` are both missing or both given, or when the task list is invalid (duplicated or unknown task, combination not accepted), MigratorXpress logs the problem and stops with exit code `20` (`VALIDATION_ERROR`) before connecting to any database.

## Constraint Copy Support[​](#constraint-copy-support "Direct link to Constraint Copy Support")

| Source → Target                             | `copy_pk` / `copy_ak`                   | `copy_fk`                               |
| ------------------------------------------- | --------------------------------------- | --------------------------------------- |
| Oracle, PostgreSQL, SQL Server → SQL Server | ✅                                      | ✅                                      |
| Oracle, PostgreSQL, SQL Server → PostgreSQL | ✅                                      | ❌ rejected at startup (exit code `10`) |
| Netezza → SQL Server                        | ❌ rejected at startup (exit code `10`) | ❌ rejected at startup (exit code `10`) |

* Primary keys, unique (alternate) keys and foreign keys are read from the source catalog (the Oracle data dictionary, `pg_constraint` for PostgreSQL, `sys.key_constraints` and `sys.foreign_keys` for SQL Server). Multi-column keys keep their column order.
* Foreign keys that reference a table in another schema are logged as a warning and not copied: the target foreign keys are created within the target schema.
* With a PostgreSQL target, primary and unique key columns are referenced in lower case, like the created columns.
* SQL Server refuses a primary key on a nullable column. Since 0.7.3, `NOT NULL` columns of a PostgreSQL source are created `NOT NULL` on the target; tables created from a PostgreSQL source by an older version have nullable columns and must be recreated (`--drop_tables_if_exists true`) before `copy_pk`.

For the unsupported paths, create the constraints manually on the target database after the data transfer.

## Common Task Combinations[​](#common-task-combinations "Direct link to Common Task Combinations")

### Full Migration[​](#full-migration "Direct link to Full Migration")

Translate the schema, create tables, transfer data, and validate:

```
--task_list translate create transfer diff
```

### Schema Only[​](#schema-only "Direct link to Schema Only")

Translate and create tables without transferring data. Useful for validating the type translation before committing to a full migration:

```
--task_list translate create
```

### Data Only[​](#data-only "Direct link to Data Only")

Transfer data into existing tables. The tables must already exist in the target database:

```
--task_list transfer
```

### Data Append (Load Mode)[​](#data-append-load-mode "Direct link to Data Append (Load Mode)")

By default (`--load_mode truncate`), `transfer` empties each target table before loading it. Use `--load_mode append` to add rows to existing tables without clearing them:

```
--task_list transfer --load_mode append
```

### Constraints Only[​](#constraints-only "Direct link to Constraints Only")

Copy constraints after a successful data transfer. Run this as a separate step to avoid constraint violations during the initial load:

```
# SQL Server target
--task_list copy_pk copy_ak copy_fk

# PostgreSQL target (no copy_fk)
--task_list copy_pk copy_ak
```

## Existing Target Tables[​](#existing-target-tables "Direct link to Existing Target Tables")

Two options control what happens to tables that already exist on the target:

| Option                                               | Applies to | Behavior                                                                                                             |
| ---------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------- |
| `--drop_tables_if_exists true` (or the bare flag)    | `create`   | Drop existing target tables (and foreign keys referencing them), then recreate them. `--with_xid` is ignored with it |
| *(flag omitted)*, or `--drop_tables_if_exists false` | `create`   | Keep existing tables; only missing tables are created                                                                |
| `--load_mode truncate` (default)                     | `transfer` | Empty each target table before loading                                                                               |
| `--load_mode append`                                 | `transfer` | Insert rows without emptying the table                                                                               |

Changed in 0.7.2

Up to 0.7.1, any value given to `--drop_tables_if_exists` enabled it, including `false`. Since 0.7.2, `true`/`yes`/`1` (or the bare flag) enable it, `false`/`no`/`0` disable it, and any other value is rejected (exit code `2`).

For iterative development and testing, `--drop_tables_if_exists true` is convenient. For production migrations, omit it and manage the table lifecycle explicitly.

## Migration Database Modes[​](#migration-database-modes "Direct link to Migration Database Modes")

`--migration_db_mode` controls what MigratorXpress does with the tracking database at startup:

| Mode                 | Behavior                                                               |
| -------------------- | ---------------------------------------------------------------------- |
| `preserve` (default) | Keep all tracking data. Required to use `--resume`                     |
| `truncate`           | Delete the content of all tracking tables (every run), keep the tables |
| `drop`               | Drop and recreate all tracking tables                                  |

## Resume Functionality[​](#resume-functionality "Direct link to Resume Functionality")

If a migration fails partway through, or some tables failed (exit code `40` or `41`), resume the run instead of starting over. The log of a run with failed tables ends with the `--resume <run_id>` command to use. `--resume` requires the run ID:

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --target_db_auth_id mssql_target \
  --migration_db_auth_id ms_mig_log \
  --resume 20260203-cf5be0ac-159f-4dad-861e-8b2b6f3868d7
```

MigratorXpress replays the run's steps and only processes the table jobs that are not yet `DONE`. Do not pass `--task_list` with `--resume`; `--source_schema_name` and `--target_schema_name` are not needed because the jobs are read from the tracking database. The source, target and tracking auth IDs are still required. With a PostgreSQL target, do not resume a run started with a version older than 0.7.2: start a new run.

tip

The run ID has the format `YYYYMMDD-<uuid4>`. It appears in the log file name (`mig_YYYYMMDD_HHMMSS_<run_id>.log`), in the console output, and in the tracking database (`sourcetargetloads.run_id`).

## Full Example[​](#full-example "Direct link to Full Example")

A complete Oracle-to-SQL Server migration in two steps -- first data, then constraints:

```
# Step 1: Schema, data, and validation
./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

# Step 2: Constraints (after verifying diff results)
./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
```

## See Also[​](#see-also "Direct link to See Also")

* [FastTransfer Configuration](/latest/configuration/fasttransfer-configuration.md) -- Parallel transfer tuning and performance
* [Database Connections](/latest/configuration/database-configuration.md) -- Auth file configuration
* [Quick Start Guide](/latest/guides/quickstart.md) -- Getting started with MigratorXpress
* [CLI Reference](/latest/reference/cli-reference.md) -- Full command-line reference


---

# Examples and use cases

Complete command examples for the supported migration paths, plus advanced scenarios. Each example assumes a `credentials.json` file with these entries (see the [Quick Start Guide](/latest/guides/quickstart.md) and [Database Connections](/latest/configuration/database-configuration.md)):

| Auth ID          | Role               | `ds_type`               | `database`      |
| ---------------- | ------------------ | ----------------------- | --------------- |
| `oracle_prod`    | Source             | `oracle`                | `ORCLPDB1`      |
| `postgres_prod`  | Source             | `postgres`              | `analytics`     |
| `mssql_source`   | Source             | `mssql`                 | `SourceDB`      |
| `netezza_source` | Source             | `netezza`               | `PROD_DB`       |
| `mssql_target`   | Target             | `mssql`                 | `target_db`     |
| `pg_target`      | Target             | `postgres`              | `dwh`           |
| `ms_mig_log`     | Migration tracking | `mssql` (or `postgres`) | `migration_log` |

The source and target database names are taken from these entries, so the commands do not pass `--source_db_name` or `--target_db_name`. The examples describe MigratorXpress v0.8.0.

The examples assume the license file is saved in a default location (`~/.migratorxpress/license.lic`, `%APPDATA%\MigratorXpress\license.lic` or `./license.lic`). Otherwise add `--license_file <path>`, as in the first example below; see also [Providing the license](#providing-the-license).

***

## Oracle to SQL Server[​](#oracle-to-sql-server "Direct link to Oracle to SQL Server")

Two-phase approach: transfer data first, then add constraints.

### Phase 1: Schema and data[​](#phase-1-schema-and-data "Direct link to Phase 1: Schema and data")

#### Linux[​](#linux "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name FINANCE \
  --target_db_auth_id mssql_target \
  --target_schema_name finance \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --fasttransfer_p 2 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff \
  --license_file ~/licenses/MigratorXpress.lic
```

#### Windows (PowerShell)[​](#windows-powershell "Direct link to Windows (PowerShell)")

```
.\MigratorXpress.exe --auth .\credentials.json `
  --source_db_auth_id oracle_prod `
  --source_schema_name FINANCE `
  --target_db_auth_id mssql_target `
  --target_schema_name finance `
  --migration_db_auth_id ms_mig_log `
  --n_jobs 4 `
  --fasttransfer_p 2 `
  --drop_tables_if_exists true `
  --task_list translate create transfer diff `
  --license_file C:\licenses\MigratorXpress.lic
```

### Phase 2: Constraints[​](#phase-2-constraints "Direct link to Phase 2: Constraints")

Constraint copy (`copy_pk`, `copy_ak`, `copy_fk`) is available for Oracle, PostgreSQL and SQL Server sources with a SQL Server target. Foreign keys are created according to `--fk_mode` (default `disabled`).

#### Linux[​](#linux-1 "Direct link to Linux")

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

#### Windows (PowerShell)[​](#windows-powershell-1 "Direct link to Windows (PowerShell)")

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

***

## PostgreSQL to SQL Server[​](#postgresql-to-sql-server "Direct link to PostgreSQL to SQL Server")

### Linux[​](#linux-2 "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id postgres_prod \
  --source_schema_name analytics \
  --target_db_auth_id mssql_target \
  --target_schema_name analytics \
  --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)[​](#windows-powershell-2 "Direct link to Windows (PowerShell)")

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

***

## SQL Server to PostgreSQL[​](#sql-server-to-postgresql "Direct link to SQL Server to PostgreSQL")

Target schema, table and column names are created in lower case on PostgreSQL (`dbo.Orders` lands in `sales.orders` below). `copy_fk` is not available for a PostgreSQL target, so constraints are limited to `copy_pk copy_ak`.

### Linux[​](#linux-3 "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id mssql_source \
  --source_schema_name dbo \
  --target_db_auth_id pg_target \
  --target_schema_name sales \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff copy_pk copy_ak
```

### Windows (PowerShell)[​](#windows-powershell-3 "Direct link to Windows (PowerShell)")

```
.\MigratorXpress.exe --auth .\credentials.json `
  --source_db_auth_id mssql_source `
  --source_schema_name dbo `
  --target_db_auth_id pg_target `
  --target_schema_name sales `
  --migration_db_auth_id ms_mig_log `
  --n_jobs 4 `
  --drop_tables_if_exists true `
  --task_list translate create transfer diff copy_pk copy_ak
```

The same command works from an Oracle (`oracle_prod`) or PostgreSQL (`postgres_prod`) source. For an Oracle source, check the result of `diff` and spot-check date, timestamp and binary columns: the exactness of Oracle to PostgreSQL transfers was not verified.

***

## Netezza to SQL Server[​](#netezza-to-sql-server "Direct link to Netezza to SQL Server")

A Netezza source can only be migrated to SQL Server, and without constraint copy (`copy_pk`, `copy_ak` and `copy_fk` are rejected at startup with exit code `10`).

### Linux[​](#linux-4 "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id netezza_source \
  --source_schema_name WAREHOUSE \
  --target_db_auth_id mssql_target \
  --target_schema_name warehouse \
  --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)[​](#windows-powershell-4 "Direct link to Windows (PowerShell)")

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

***

## SQL Server to SQL Server[​](#sql-server-to-sql-server "Direct link to SQL Server to SQL Server")

Clone or migrate schemas between SQL Server instances. SQL Server sources have no intra-table parallel method, so `--fasttransfer_p` has no effect; use `--n_jobs` for parallelism.

### Linux[​](#linux-5 "Direct link to Linux")

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id mssql_source \
  --source_schema_name dbo \
  --target_db_auth_id mssql_target \
  --target_schema_name dbo \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff
```

### Windows (PowerShell)[​](#windows-powershell-5 "Direct link to Windows (PowerShell)")

```
.\MigratorXpress.exe --auth .\credentials.json `
  --source_db_auth_id mssql_source `
  --source_schema_name dbo `
  --target_db_auth_id mssql_target `
  --target_schema_name dbo `
  --migration_db_auth_id ms_mig_log `
  --n_jobs 4 `
  --drop_tables_if_exists true `
  --task_list translate create transfer diff
```

***

## Advanced scenarios[​](#advanced-scenarios "Direct link to Advanced scenarios")

### Incremental data sync[​](#incremental-data-sync "Direct link to Incremental data sync")

Re-run only the `transfer` and `diff` tasks to refresh data without recreating tables. Useful for periodic syncs during a phased migration.

```
./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 \
  --task_list transfer diff
```

tip

`transfer` empties each target table before reloading it (default `--load_mode truncate`); use `--load_mode append` to add rows instead. `--drop_tables_if_exists` only affects the `create` task, so it is not needed here.

Every table is transferred on every run. For Oracle and Netezza sources, add `--with_xid` to skip a table whose maximum ROWID (Oracle) or creation transaction ID (Netezza) has not changed since the previous `--with_xid` run and whose target table holds rows. This only detects new rows, not updates or deletes. Before 0.8.0 this skip was on by default and `--without_xid` turned it off; `--without_xid` is now ignored.

### Providing the license[​](#providing-the-license "Direct link to Providing the license")

A license file outside the default locations: add `--license_file`. A scheduled job needs an absolute path, since its working and home directories are often not those of your interactive session:

```
./MigratorXpress --auth /opt/migratorxpress/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 transfer diff \
  --license_file /opt/migratorxpress/license/MigratorXpress.lic \
  --no_banner --no_progress
```

CI and containers: the `MIGRATORXPRESS_LICENSE` environment variable holds the license text itself, for example from a CI secret, so no file has to be copied onto the machine:

```
export MIGRATORXPRESS_LICENSE="$(cat /opt/migratorxpress/license/MigratorXpress.lic)"
./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 translate create transfer diff
```

```
$env:MIGRATORXPRESS_LICENSE = Get-Content -Raw C:\licenses\MigratorXpress.lic
.\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 translate create transfer diff
```

When `MIGRATORXPRESS_LICENSE` is set, it wins over `--license_file`, even if it holds an invalid license (exit 13). Prefer the file or the variable to `--license "<text>"`: a command-line argument is visible to other users of the machine in the process list. See [License Management](/latest/reference/cli-reference.md#license-management).

### Schema-only migration[​](#schema-only-migration "Direct link to Schema-only migration")

Translate and create the schema without transferring any data. Useful for reviewing the translated column types (stored in the `targetcolumns` tracking table) before committing to a full migration.

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name INVENTORY \
  --target_db_auth_id mssql_target \
  --target_schema_name inventory \
  --migration_db_auth_id ms_mig_log \
  --drop_tables_if_exists true \
  --task_list translate create
```

### Parallel large tables[​](#parallel-large-tables "Direct link to Parallel large tables")

For schemas with very large tables, increase both parallelism levels:

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name EVENTS \
  --target_db_auth_id mssql_target \
  --target_schema_name events \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 8 \
  --fasttransfer_p 4 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff
```

* `--n_jobs 8` migrates up to 8 tables concurrently.
* `--fasttransfer_p 4` splits each table whose estimated row count is at least `--ft_large_table_th` (default 250,000,000) into 4 parallel streams. Lower the threshold to parallelize smaller tables.

warning

Higher parallelism increases load on both the source and target databases. Monitor CPU and I/O during large migrations and adjust values as needed.

### Multi-schema patterns[​](#multi-schema-patterns "Direct link to Multi-schema patterns")

Migrate multiple schemas in one run with SQL `LIKE` patterns or a comma-separated list. Omit `--target_schema_name` so that each source schema keeps its name on the target:

```
# All schemas starting with "APP_", each recreated under its own name
./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
```

```
# Every user schema in the database (--source_schema_name omitted)
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --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
```

To consolidate several source schemas into **one** target schema, give `--target_schema_name` a plain name. Tables with the same name in different source schemas would collide, so use this only when table names are unique:

```
# SALES_EU and SALES_US merged into the single target schema sales_all
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --source_schema_name "SALES_EU, SALES_US" \
  --target_db_auth_id mssql_target \
  --target_schema_name sales_all \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --drop_tables_if_exists true \
  --task_list translate create transfer diff
```

### Resume a run[​](#resume-a-run "Direct link to Resume a run")

If a run is interrupted or some tables failed (see the `RUN SUMMARY` at the end of the log), resume it with its run ID. Schema names and the task list come from the tracking database:

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --target_db_auth_id mssql_target \
  --migration_db_auth_id ms_mig_log \
  --n_jobs 4 \
  --resume 20260203-cf5be0ac-159f-4dad-861e-8b2b6f3868d7
```

***

## Best practices[​](#best-practices "Direct link to Best practices")

1. **Migrate data before constraints.** Run `translate create transfer diff` first, then `copy_pk copy_ak copy_fk` in a separate run. This avoids constraint-violation errors during bulk loading.

2. **Start with a small schema.** Test the full workflow on a schema with a few tables before migrating a large production database.

3. **Use `diff` to validate.** Always include `diff` in your task list to compare row counts, column counts and column statistics between source and target.

4. **Tune parallelism gradually.** Begin with `--n_jobs 2 --fasttransfer_p 2` and increase based on observed throughput and system load.

5. **Secure your credentials file.** Passwords are stored in clear text in the credentials file: restrict its permissions to the migration user and keep it out of version control.

6. **Review translated types.** Run `translate create` first and inspect the created tables (or the `targetcolumns` tracking table) before transferring data.

7. **Check the exit code and the run summary.** The process exits with code `40` when some tables failed and `41` when all of them failed; read the `RUN SUMMARY: n/m tables succeeded` block and resume failed runs with `--resume`.

## Next steps[​](#next-steps "Direct link to Next steps")

* [Quick Start Guide](/latest/guides/quickstart.md) -- step-by-step setup
* [CLI Reference](/latest/reference/cli-reference.md) -- all available options and flags
* [Command Wizard](/latest/wizard.md) -- build your command interactively


---

# Quick start guide

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

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

1. **MigratorXpress installed** (Windows or Linux) with its license file -- see [Installation](/latest/installation.md)
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** -- required, including for evaluation: the free 30-day trial license is emailed by the [trial request](https://arpe.io/get-trial?product=MigratorXpress). See [Installation](/latest/installation.md#license-information)

## Step 1: Create a credentials file[​](#step-1-create-a-credentials-file "Direct link to 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[​](#step-2-run-a-full-migration "Direct link to 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[​](#linux "Direct link to 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 \
  --license_file ~/licenses/MigratorXpress.lic
```

### Windows (PowerShell)[​](#windows-powershell "Direct link to 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 `
  --license_file C:\licenses\MigratorXpress.lic
```

`--license_file` points to your license file. You can leave it out when the file is saved in a default location: `~/.migratorxpress/license.lic` (Linux), `%APPDATA%\MigratorXpress\license.lic` (Windows) or `./license.lic`. See [License Management](/latest/reference/cli-reference.md#license-management) for the other ways to provide it.

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](/latest/configuration/migration-tasks.md).

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`](/latest/reference/cli-reference.md#resume-operations); the log prints the exact command. See [Exit Codes](/latest/reference/cli-reference.md#exit-codes).

## Step 3: Add constraints[​](#step-3-add-constraints "Direct link to 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](/latest/configuration/migration-tasks.md#constraint-copy-support).

### Linux[​](#linux-1 "Direct link to 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)[​](#windows-powershell-1 "Direct link to 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[​](#advanced-multi-schema-migration "Direct link to 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[​](#linux-2 "Direct link to 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)[​](#windows-powershell-2 "Direct link to 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[​](#next-steps "Direct link to Next steps")

* [CLI Reference](/latest/reference/cli-reference.md) -- all available options and flags
* [Examples & Use Cases](/latest/guides/examples.md) -- real-world migration scenarios
* [Command Wizard](/latest/wizard.md) -- build your command interactively


---

# Installation

## Instructions[​](#instructions "Direct link to Instructions")

* Windows
* Linux

To start using MigratorXpress, first **[request a trial](https://arpe.io/get-trial?product=MigratorXpress)**: you receive the download link and a free 30-day license file by email. Customers download the same package.

Once downloaded, unzip MigratorXpress to a directory of your choice.

```
Expand-Archive -Path .\MigratorXpress-Full-win-x64.zip -DestinationPath .\MigratorXpress
```

Save the license file you received by email (`TRIAL-MigratorXpress-….lic`, or `SUBSCRIPTION-MigratorXpress-….lic` for customers) as `%APPDATA%\MigratorXpress\license.lic`:

```
New-Item -ItemType Directory -Force "$env:APPDATA\MigratorXpress" | Out-Null
Copy-Item .\*-MigratorXpress-*.lic "$env:APPDATA\MigratorXpress\license.lic"
```

MigratorXpress does not run without it. For other ways to provide it, see [License Information](#license-information).

You can verify the installation by checking the version:

```
.\MigratorXpress.exe --version
```

The output ends with the version, for example `migratorxpress 0.8.0`.

To start using MigratorXpress, first **[request a trial](https://arpe.io/get-trial?product=MigratorXpress)**: you receive the download link and a free 30-day license file by email. Customers download the same package.

Once downloaded, unzip MigratorXpress to a directory of your choice.

```
unzip MigratorXpress-Full-linux-x64.zip -d MigratorXpress
```

On **Linux**, you need to give execution rights to the MigratorXpress binary and to the bundled FastTransfer engine:

```
chmod +x MigratorXpress engine/FastTransfer
```

<br />

Save the license file you received by email (`TRIAL-MigratorXpress-….lic`, or `SUBSCRIPTION-MigratorXpress-….lic` for customers) as `~/.migratorxpress/license.lic`:

```
mkdir -p ~/.migratorxpress
cp *-MigratorXpress-*.lic ~/.migratorxpress/license.lic
```

MigratorXpress does not run without it. For other ways to provide it, see [License Information](#license-information).

You can verify the installation by checking the version:

```
./MigratorXpress --version
```

The output ends with the version, for example `migratorxpress 0.8.0`.

<br />

**Next step:** follow the [Quick Start Guide](/latest/guides/quickstart.md) to create a credentials file and run a first migration.

## What's Included[​](#whats-included "Direct link to What's Included")

There is a single package per platform, for the trial and for subscriptions (the license file makes the difference). It has the following layout:

* Windows
* Linux

```
MigratorXpress/
├── MigratorXpress.exe       - Main executable
├── MigratorXpress-sbom.*    - Software Bill of Materials (JSON, XML) and checksums
└── engine/
    └── FastTransfer.exe     - Bundled FastTransfer engine (auto-discovered)
```

```
MigratorXpress/
├── MigratorXpress           - Main executable
├── MigratorXpress-sbom.*    - Software Bill of Materials (JSON, XML) and checksums
└── engine/
    └── FastTransfer         - Bundled FastTransfer engine (auto-discovered)
```

Bundled FastTransfer Engine

The package includes the FastTransfer engine in the `engine/` directory, found automatically: no need to specify `--fasttransfer_dir_path`. It is the FastTransfer version this MigratorXpress release was tested with (0.18.1 for MigratorXpress 0.8.0). Your MigratorXpress license also licenses it: no separate `FastTransfer.lic` is needed.

To use another FastTransfer installation (0.15.0 or later), pass its folder with `--fasttransfer_dir_path`.

## License Information[​](#license-information "Direct link to License Information")

License Information

MigratorXpress needs a license file to run, including during the free trial: the [trial request](https://arpe.io/get-trial?product=MigratorXpress) emails you a 30-day trial license. MigratorXpress resolves the license in the following order:

1. **`MIGRATORXPRESS_LICENSE` environment variable** — set this for CI/CD or containerized deployments

2. **`--license TEXT`** CLI argument — pass the license content directly

3. **`--license_file PATH`** CLI argument — point to a license file

4. **Default file locations:**

   * `~/.migratorxpress/license.lic` (Linux)
   * `%APPDATA%\MigratorXpress\license.lic` (Windows)
   * `./license.lic` (current directory)

If no valid license is found, MigratorXpress stops with exit code 13 (`LICENSE_ERROR`). `--help` and `--version` work without a license.

The license file also carries the FastTransfer and ADBC driver licenses: keep the whole file as delivered. MigratorXpress passes them to FastTransfer through a private temporary file that it removes when it exits. You do not need a separate `FastTransfer.lic`.

A license issued before October 26, 2026 has no FastTransfer block. MigratorXpress then logs a warning and FastTransfer uses its own `FastTransfer.lic`, as before. Request an updated license to drop it.

See [License Management](/latest/reference/cli-reference.md#license-management) in the CLI Reference for details.


---

# CLI Reference

Complete reference for every MigratorXpress command-line argument. This page describes MigratorXpress v0.7.3.

## Basic Usage[​](#basic-usage "Direct link to Basic Usage")

```
./MigratorXpress [OPTIONS]
```

MigratorXpress runs as a single command. On Windows, use `.\MigratorXpress.exe`.

Every migration command needs:

* `--auth` -- the credentials file
* `--source_db_auth_id`
* `--target_db_auth_id`
* `--migration_db_auth_id`
* exactly one of `--task_list` (new run) or `--resume RUN_ID` (resume a run)

The source and target database names are taken from the auth entries: `--source_db_name` and `--target_db_name` are optional since 0.7.2 (see [Database names](#database-names)).

A missing required argument is rejected by the argument parser before anything else runs (exit code 2). The only exception is `--upgrade_migdb`, which needs `--auth` and `--migration_db_auth_id` only (see [Upgrading the tracking database](#upgrading-the-tracking-database)).

## Authentication[​](#authentication "Direct link to Authentication")

| Option              | Type | Required | Description                       |
| ------------------- | ---- | -------- | --------------------------------- |
| `-a`, `--auth PATH` | Path | Yes      | Path to the JSON credentials file |

The credentials file contains connection details for every database involved in the migration. Each entry has a unique ID that you reference with other flags. See [Credentials File Format](#credentials-file-format) below.

## Source Database[​](#source-database "Direct link to Source Database")

| Option                         | Type   | Required | Description                                                                                                                |
| ------------------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `--source_db_auth_id ID`       | String | Yes      | Source database identifier in the credentials file                                                                         |
| `--source_db_name NAME`        | String | No       | **Deprecated and ignored.** The source database is the one of the source auth entry. See [Database names](#database-names) |
| `--source_schema_name PATTERN` | String | No       | Source schema name, SQL `LIKE` pattern(s), or comma-separated list. All schemas if omitted                                 |

### Schema selection[​](#schema-selection "Direct link to Schema selection")

The `--source_schema_name` flag supports four modes:

**Single schema:**

```
--source_schema_name SALES
```

**SQL LIKE patterns (any value containing `%`):**

```
# All schemas starting with "app_"
--source_schema_name "app_%"

# Multiple patterns
--source_schema_name "APP_%, TENANT_%"
```

**Exact comma-separated list:**

```
# Multiple specific schemas without wildcards
--source_schema_name "tpch_1, tpch_2, tpch_3"
```

**Omitted:** MigratorXpress discovers and migrates all user schemas in the source database.

### Target schema naming[​](#target-schema-naming "Direct link to Target schema naming")

How target schemas are named depends on `--target_schema_name`:

| Source schema selection   | `--target_schema_name` omitted                      | `--target_schema_name NAME` given                                              |
| ------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------ |
| Single schema             | Target schema = source schema name                  | Target schema = `NAME`                                                         |
| Pattern, list, or omitted | Each source schema keeps its own name on the target | **All** matched source schemas are loaded into the single target schema `NAME` |

`--target_schema_name` is a plain name, never a pattern. To keep one target schema per source schema in a multi-schema run, omit it. Target schemas are created automatically if they do not exist.

## Target Database[​](#target-database "Direct link to Target Database")

| Option                      | Type   | Required | Description                                                                                                                                  |
| --------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--target_db_auth_id ID`    | String | Yes      | Target database identifier in the credentials file                                                                                           |
| `--target_db_name NAME`     | String | No       | Target database name. Defaults to the database of the target auth entry; when given, it must match it. See [Database names](#database-names) |
| `--target_schema_name NAME` | String | No       | Target schema name. See [Target schema naming](#target-schema-naming)                                                                        |

Supported targets: SQL Server and PostgreSQL. A PostgreSQL target can be loaded from SQL Server, Oracle and PostgreSQL sources (not from Netezza). See the [compatibility matrix](/latest/compatibility.md).

With a **PostgreSQL target**:

* the target schema, table and column names are created in **lower case** (a source table `Sales.Orders` lands in `sales.orders`), and they are recorded in lower case in the tracking database;
* `copy_fk` (and therefore `--task_list all`) is not supported: the run stops at startup with exit code `10`. Use an explicit task list such as `translate create transfer diff copy_pk copy_ak`;
* `--cci_threshold` and `--aci_threshold` are ignored (logged as such);
* columns that cannot be migrated -- SQL Server `GEOGRAPHY` / `GEOMETRY` and PostgreSQL `ARRAY` / user-defined types -- make `translate` fail for their table, which is then not created.

### Database names[​](#database-names "Direct link to Database names")

MigratorXpress takes the database names from the auth file:

* **Source:** the database is always the one of the source auth entry (`info.database`, or the `Database` of a connection string). `--source_db_name` is deprecated and ignored; passing it logs a warning.
* **Target:** the database defaults to the one of the target auth entry. When `--target_db_name` is given, it must match that entry (case-insensitively for SQL Server, exactly for PostgreSQL), otherwise the run stops with `TARGET_DB_NAME_MISMATCH` (exit code `20`) before connecting to any database.

Omit both options unless you have a reason to pass them.

## Migration Tracking Database[​](#migration-tracking-database "Direct link to Migration Tracking Database")

| Option                      | Type   | Required | Description                                                           |
| --------------------------- | ------ | -------- | --------------------------------------------------------------------- |
| `--migration_db_auth_id ID` | String | Yes      | Identifier of the migration tracking database in the credentials file |
| `--migration_db_mode MODE`  | String | No       | `preserve` (default), `truncate`, or `drop`. See below                |
| `--upgrade_migdb`           | Flag   | No       | Upgrade the tracking database to the 0.7 schema, then exit            |

The tracking database can be **SQL Server** (`ds_type: "mssql"`) or **PostgreSQL** (`ds_type: "postgres"`). The backend is detected from the `ds_type` of the referenced auth entry. MigratorXpress creates its tracking tables automatically on first use.

| `--migration_db_mode` | Behavior at startup                                                        |
| --------------------- | -------------------------------------------------------------------------- |
| `preserve` (default)  | Keep all tracking data. Required to `--resume` later                       |
| `truncate`            | Delete the content of **all** tracking tables (every run), keep the tables |
| `drop`                | Drop and recreate all tracking tables                                      |

### Upgrading the tracking database[​](#upgrading-the-tracking-database "Direct link to Upgrading the tracking database")

Since 0.7.0 the catalog tables (`sources`, `sourcecolumns`, `sourceconstraints`, `targets`, `targetcolumns`) include `run_id` in their primary keys, so each run keeps its own metadata snapshot. A tracking database created by 0.6.x must be upgraded in place. Two options:

* **Automatic:** on the first 0.7 run against an old tracking database, MigratorXpress detects the old schema and upgrades it before continuing.
* **Manual:** run the upgrade on its own. Only `--auth` and `--migration_db_auth_id` are needed:

```
./MigratorXpress --auth ./credentials.json \
  --migration_db_auth_id ms_mig_log \
  --upgrade_migdb
```

The upgrade is idempotent (a second run does nothing) and resumable (an interrupted upgrade completes on the next attempt). Existing catalog rows are backfilled with `run_id = 'legacy'`. **Back up the tracking database first.** On large SQL Server tracking databases the slowest step is the rebuild of the clustered primary keys.

## Task Control[​](#task-control "Direct link to Task Control")

| Option                  | Type      | Description                                                          |
| ----------------------- | --------- | -------------------------------------------------------------------- |
| `--task_list TASKS...`  | String(s) | Space-separated list of tasks for a new run                          |
| `-r`, `--resume RUN_ID` | String    | Resume an existing run (see [Resume Operations](#resume-operations)) |

Give **exactly one** of `--task_list` or `--resume`.

Available tasks: `translate`, `create`, `transfer`, `diff`, `copy_pk`, `copy_ak`, `copy_fk`, or `all` (shortcut for all seven).

**Execution order is fixed.** Whatever order you type, tasks are re-sorted into the canonical order `translate → create → transfer → diff → copy_pk → copy_ak → copy_fk` (the sorted list is logged as `sorted task list`). Duplicates are rejected.

**Only some combinations are accepted.** The task set must be one of the sequences below, otherwise the run stops with `incorrect task sequence` (exit code `20`):

| Tasks   | Accepted combinations                                                                                                                                                                                                                                                                                              |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 task  | any single task                                                                                                                                                                                                                                                                                                    |
| 2 tasks | `translate create`, `create transfer`, `transfer diff`, `transfer copy_pk`, `diff copy_pk`, `copy_pk copy_ak`, `copy_pk copy_fk`, `copy_ak copy_fk`                                                                                                                                                                |
| 3 tasks | `translate create transfer`, `translate create copy_pk`, `create transfer diff`, `transfer diff copy_pk`, `transfer copy_pk copy_ak`, `diff copy_pk copy_ak`, `transfer copy_pk copy_fk`, `diff copy_pk copy_fk`, `copy_pk copy_ak copy_fk`                                                                        |
| 4 tasks | `translate create transfer diff`, `translate create transfer copy_pk`, `translate create transfer copy_ak`, `create transfer diff copy_pk`, `create transfer copy_pk copy_ak`, `transfer diff copy_pk copy_ak`, `create transfer copy_pk copy_fk`, `transfer diff copy_pk copy_fk`, `diff copy_pk copy_ak copy_fk` |
| 5 tasks | `translate create transfer diff copy_pk`, `translate create transfer copy_pk copy_ak`, `translate create transfer copy_pk copy_fk`, `translate create transfer copy_ak copy_fk`, `create transfer diff copy_pk copy_ak`, `create transfer diff copy_pk copy_fk`, `create transfer diff copy_ak copy_fk`            |
| 6 tasks | `translate create transfer diff copy_pk copy_ak`, `translate create transfer diff copy_pk copy_fk`, `translate create transfer copy_pk copy_ak copy_fk`, `create transfer diff copy_pk copy_ak copy_fk`                                                                                                            |
| 7 tasks | `all` (or the seven tasks listed explicitly)                                                                                                                                                                                                                                                                       |

For example `translate transfer` (skipping `create`) is rejected.

```
# Schema, data and validation
--task_list translate create transfer diff

# Schema only
--task_list translate create

# Data only (tables already exist)
--task_list transfer

# Constraints only (after data is loaded)
--task_list copy_pk copy_ak copy_fk

# Everything
--task_list all
```

A missing `--task_list`/`--resume`, both given together, a duplicated or unknown task, or an invalid task sequence is logged (`CRITICAL`) and stops the run with exit code `20` (`VALIDATION_ERROR`) before any database is opened. See [Exit Codes](#exit-codes).

Constraint copying limitations

`copy_pk` and `copy_ak` are supported for **Oracle, PostgreSQL and SQL Server sources**, with a SQL Server or PostgreSQL target. `copy_fk` is supported for the same sources with a **SQL Server target** only. A Netezza source with a `copy_*` task, or `copy_fk` with a PostgreSQL target, is rejected at startup with exit code `10`. Foreign keys that reference a table in another schema are logged as a warning and not copied. For the unsupported paths, create the constraints manually on the target database.

## Resume Operations[​](#resume-operations "Direct link to Resume Operations")

| Option                         | Type   | Description                                             |
| ------------------------------ | ------ | ------------------------------------------------------- |
| `-r RUN_ID`, `--resume RUN_ID` | String | Resume a previous run using its run ID (required value) |

When a migration is interrupted or some tables failed, use `--resume` with the run ID to finish it. MigratorXpress replays the steps of that run and only processes the table jobs that are not yet `DONE` in the tracking database.

On resume:

* `--task_list` must **not** be given, and `--source_schema_name` / `--target_schema_name` are not needed: the jobs (tables, schemas, tasks) are read from the tracking database.
* The other required arguments (`--auth`, `--source_db_auth_id`, `--target_db_auth_id`, `--migration_db_auth_id`) are still mandatory.
* Performance and logging options (`--n_jobs`, `--fasttransfer_p`, `--log_dir`, ...) are taken from the resume command line.
* Keep the default `--migration_db_mode preserve`: `truncate` or `drop` would delete the run you are trying to resume.
* With a PostgreSQL target, do not resume a run started with a version older than 0.7.2 (target names were not lower-cased then): start a new run.

A run that ends with failed tables logs the `--resume <run_id>` command to use and exits with code `40` or `41`.

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id mssql_source \
  --target_db_auth_id mssql_target \
  --migration_db_auth_id ms_mig_log \
  --resume 20260203-cf5be0ac-159f-4dad-861e-8b2b6f3868d7
```

The run ID has the format `YYYYMMDD-<uuid4>`. It appears in the log file name and in the console output (`run_id : ...`), and is stored in the tracking database (`sourcetargetloads.run_id`, `eventlog.eventrunid`).

## Run Tagging[​](#run-tagging "Direct link to Run Tagging")

| Option           | Type   | Description                                                                             |
| ---------------- | ------ | --------------------------------------------------------------------------------------- |
| `--project NAME` | String | Optional project tag attached to every row this run writes in the migration tracking DB |

A user-supplied `--project` tag groups runs that belong to the same engagement. The tag is stored alongside `run_id` on `sourcetargetloads`, `eventlog`, and `sourcetargetdiff`, so all runs for a given project can be retrieved with a single SQL filter.

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --target_db_auth_id mssql_target \
  --migration_db_auth_id ms_mig_log \
  --source_schema_name SALES \
  --task_list all \
  --project bob_bods_oracle
```

Then, to find every run tagged with that project:

```
SELECT DISTINCT eventrunid
  FROM eventlog
 WHERE project = 'bob_bods_oracle';
```

**Validation:** 1–64 characters, letters, digits, underscore, or hyphen only (e.g. `bob_bods_oracle`, `cust-2026-q2`). Invalid values are rejected at CLI parse time (exit code 2), before any database write.

**Optional:** Runs without `--project` store `NULL`. Older tracking databases get the `project` columns added automatically on startup.

Immutable per run\_id

On `--resume`, any `--project` value on the command line is ignored with a warning, and the original run's tag is inherited from the migration DB. This keeps every row for a given `run_id` tagged consistently, even across multiple resumes.

## FastTransfer[​](#fasttransfer "Direct link to FastTransfer")

| Option                         | Type    | Default       | Description                                               |
| ------------------------------ | ------- | ------------- | --------------------------------------------------------- |
| `--fasttransfer_dir_path PATH` | Path    | Auto-detected | Directory containing the FastTransfer binary. Optional    |
| `-p`, `--fasttransfer_p INT`   | Integer | 1             | Parallel streams per large table (Ctid/Rowid/NZDataSlice) |
| `--ft_large_table_th INT`      | Integer | 250,000,000   | Row count threshold for parallel transfer methods         |

MigratorXpress delegates all data movement to [FastTransfer](https://www.arpe.io/fasttransfer/). FastTransfer >= 0.15.0 is required; the version is checked at startup and an error is logged if it is older.

If `--fasttransfer_dir_path` is omitted, MigratorXpress looks for a bundled FastTransfer in the `engine/` subdirectory next to the MigratorXpress binary. Distributions that ship FastTransfer in `engine/` need no flag.

```
# Explicit path
--fasttransfer_dir_path ./FastTransfer_linux-x64_v0.15.0/

# Or omit to use the bundled engine/ directory
```

### Parallel transfer methods[​](#parallel-transfer-methods "Direct link to Parallel transfer methods")

Tables whose estimated row count is **greater than or equal to** `--ft_large_table_th`, with `--fasttransfer_p` > 1, use a database-specific parallel method:

| Source Database | Method      | Description                                                 |
| --------------- | ----------- | ----------------------------------------------------------- |
| PostgreSQL      | Ctid        | Splits by physical tuple ID                                 |
| Oracle          | Rowid       | Splits by physical ROWID (requires `SELECT_CATALOG_ROLE`)   |
| Netezza         | NZDataSlice | Splits by internal data slice distribution                  |
| SQL Server      | None        | No intra-table parallelism; parallelism via `--n_jobs` only |

Below the threshold, or with `--fasttransfer_p 1`, each table is transferred as a single stream.

## Performance[​](#performance "Direct link to Performance")

| Option                  | Type    | Default | Description                                                                                                                                                                                                                         |
| ----------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--n_jobs INT`          | Integer | 1       | Number of tables to process in parallel                                                                                                                                                                                             |
| `--compute_nbrows BOOL` | Boolean | false   | Use `COUNT(*)` for exact row counts instead of database estimates (`true`/`false`)                                                                                                                                                  |
| `--with_xid`            | Flag    | false   | Oracle and Netezza sources: skip a table whose maximum ROWID (Oracle) or creation transaction ID (Netezza) is unchanged since the last `--with_xid` run and whose target table holds rows. Before 0.8.0 this skip was on by default |
| `--without_xid`         | Flag    | false   | Deprecated and ignored (warning): since 0.8.0 the skip is off unless `--with_xid` is given                                                                                                                                          |

`--n_jobs` controls table-level parallelism (how many tables transfer simultaneously). Combined with `--fasttransfer_p`, this gives dual-level parallelism:

```
# 4 tables at once, each large table split into 2 parallel streams
--n_jobs 4 --fasttransfer_p 2
```

## Table Filtering[​](#table-filtering "Direct link to Table Filtering")

| Option                           | Type    | Default       | Description                                                        |
| -------------------------------- | ------- | ------------- | ------------------------------------------------------------------ |
| `-i`, `--include_tables PATTERN` | String  | `%` (all)     | Include only tables matching SQL `LIKE` patterns (comma-separated) |
| `-e`, `--exclude_tables PATTERN` | String  | None          | Exclude tables matching SQL `LIKE` patterns (comma-separated)      |
| `-min`, `--min_rows NROWS`       | Integer | -1 (disabled) | Exclude tables with strictly fewer rows than this value            |
| `-max`, `--max_rows NROWS`       | Integer | -1 (disabled) | Exclude tables with row count >= this value                        |

Exclude patterns are applied after include patterns.

```
# Include only tables starting with "fact_" or "dim_"
--include_tables "fact_%,dim_%"

# Spaces after commas are trimmed automatically
--include_tables "fact_%, dim_%"

# Exclude temporary and test tables
--exclude_tables "tmp_%,test_%"

# Combine filters
--include_tables "%" --exclude_tables "tmp_%,log_%" --min_rows 100 --max_rows 10000000
```

Shell quoting

Quote the entire comma-separated string as one argument. Do not quote each pattern separately:

```
# CORRECT
--include_tables "fact_%,dim_%"

# WRONG — shell interprets as multiple arguments
--include_tables 'fact_%','dim_%'
```

## Migration Options[​](#migration-options "Direct link to Migration Options")

| Option                           | Type    | Default    | Description                                                                         |
| -------------------------------- | ------- | ---------- | ----------------------------------------------------------------------------------- |
| `--drop_tables_if_exists [BOOL]` | Boolean | false      | Drop existing target tables in the `create` task before recreating them             |
| `--load_mode MODE`               | String  | `truncate` | `truncate`: clear target tables before loading. `append`: add rows without clearing |
| `--basic_diff`                   | Flag    | false      | `diff` compares row and column counts only (skips per-column statistics)            |
| `-f`, `--force`                  | Flag    | false      | Delete existing tracking rows for the source database/schema before the run         |

### `--drop_tables_if_exists`[​](#--drop_tables_if_exists "Direct link to --drop_tables_if_exists")

Without this flag, the `create` task keeps tables that already exist on the target (it only creates missing ones); `transfer` then loads into them according to `--load_mode`.

With the flag enabled, existing target tables (and the foreign keys that reference them) are dropped and recreated. With it, `--with_xid` is ignored (warning). A table whose `translate` step failed is neither dropped nor created.

| Value                                                          | Effect                                          |
| -------------------------------------------------------------- | ----------------------------------------------- |
| `true`, `yes`, `1`, or the bare flag `--drop_tables_if_exists` | Enabled                                         |
| `false`, `no`, `0`, or the flag omitted                        | Disabled                                        |
| Any other value                                                | Rejected by the argument parser (exit code `2`) |

Changed in 0.7.2

Up to 0.7.1, any value enabled the option, including `false`. Since 0.7.2, `--drop_tables_if_exists false` keeps the existing tables.

### Diff[​](#diff "Direct link to Diff")

The `diff` task compares source and target row counts and column counts. When both match and the table is not empty, it also compares per-column statistics: minimum, maximum, distinct count, number of missing values and, for numeric columns, the mean (with a numeric tolerance). `--basic_diff` restricts the comparison to row and column counts. Results are stored in `sourcetargetdiff` (and the `v_sourcetargetdiff` view).

Columns are matched by name, case-insensitively when the exact name is absent (a PostgreSQL target lower-cases column names). Differences found by `diff` are reported but do not fail the table, and do not change the exit code.

## SQL Server Target Options[​](#sql-server-target-options "Direct link to SQL Server Target Options")

These options apply only when the target database is SQL Server. With a PostgreSQL target, `--cci_threshold` and `--aci_threshold` are ignored, and `copy_fk` (the only task that uses `--fk_mode`) is not supported.

| Option                | Type    | Default     | Description                                                                                                                     |
| --------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `--cci_threshold INT` | Integer | 1,000,000   | Create a Clustered Columnstore Index for tables above this row count                                                            |
| `--aci_threshold INT` | Integer | 100,000,000 | Use archive compression (COLUMNSTORE\_ARCHIVE) above this row count                                                             |
| `--fk_mode MODE`      | String  | `disabled`  | Foreign key enforcement for `copy_fk`: `disabled`, `untrusted`, or `trusted`. Any other value stops the run with exit code `20` |

**Columnstore behavior:**

* Tables >= `cci_threshold` but < `aci_threshold`: Standard Clustered Columnstore Index
* Tables >= `aci_threshold`: CCI with `DATA_COMPRESSION = COLUMNSTORE_ARCHIVE`
* Tables < `cci_threshold`: Standard rowstore

**Foreign key modes:**

* `disabled` (default): FK constraints created `WITH NOCHECK` and then disabled. Fastest for loading.
* `untrusted`: FK constraints created `WITH NOCHECK` but left enabled. Enforced for new data only.
* `trusted`: Standard FK constraints with full validation of existing data.

## Oracle Source Options[​](#oracle-source-options "Direct link to Oracle Source Options")

These options apply only when the source database is Oracle.

| Option                           | Type      | Default | Description                                                                            |
| -------------------------------- | --------- | ------- | -------------------------------------------------------------------------------------- |
| `--forced_int_id_prefixes S...`  | String(s) | None    | Space-separated column name prefixes to force as integer type                          |
| `--forced_int_id_suffixes S...`  | String(s) | None    | Space-separated column name suffixes to force as integer type                          |
| `--profiling_sample_pc NUMBER`   | Integer   | 10      | Percentage of rows to sample for Oracle DATE/NUMBER profiling                          |
| `--min_sample_pc_profile NUMBER` | Integer   | 100,000 | Row count threshold below which tables are profiled in full (no sampling)              |
| `--p_query NUMBER`               | Integer   | 6       | Inner level of query parallelism for Oracle profiling queries (`PARALLEL` hint degree) |

Oracle stores many integer values in `NUMBER` columns without precision. MigratorXpress profiles DATE and NUMBER columns to select optimal target types. Use `--forced_int_id_prefixes` and `--forced_int_id_suffixes` to skip profiling for known ID columns:

```
# Space-separated, case-insensitive matching
--forced_int_id_prefixes ID_ PK_ KEY_ \
--forced_int_id_suffixes _ID _KEY _PK
```

**Sampling behavior:**

* Tables >= `min_sample_pc_profile` rows: sampled at `profiling_sample_pc`% using Oracle `SAMPLE(n)`
* Tables < `min_sample_pc_profile` rows: profiled in full
* Set `--profiling_sample_pc 100` to disable sampling

## Logging Options[​](#logging-options "Direct link to Logging Options")

| Option              | Type   | Default           | Description                                                                       |
| ------------------- | ------ | ----------------- | --------------------------------------------------------------------------------- |
| `--log_level LEVEL` | String | `INFO`            | Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` (case-insensitive) |
| `--log_dir PATH`    | Path   | Current directory | Directory for log files (created if missing)                                      |
| `--no_banner`       | Flag   | false             | Suppress the startup banner                                                       |
| `--no_progress`     | Flag   | false             | Disable the progress display                                                      |
| `--quiet_ft`        | Flag   | false             | Suppress FastTransfer subprocess output from console (still logged to file)       |

See [Logging and Monitoring](/latest/reference/logging.md) for details on log format and database logging.

## License Management[​](#license-management "Direct link to License Management")

| Option                | Type   | Description            |
| --------------------- | ------ | ---------------------- |
| `--license TEXT`      | String | License text           |
| `--license_file PATH` | Path   | Path to a license file |

**License lookup order** (the first source found is used):

1. `MIGRATORXPRESS_LICENSE` environment variable
2. `--license` command-line argument
3. `--license_file` command-line argument
4. Default license file: `~/.migratorxpress/license.lic` (Linux) or `%APPDATA%\MigratorXpress\license.lic` (Windows)
5. `license.lic` in the current working directory

A license is required, including for the free 30-day trial: the [trial request](https://arpe.io/get-trial?product=MigratorXpress) emails you a trial license file. Without a valid license, MigratorXpress stops with exit code 13 (`LICENSE_ERROR`); `--help` and `--version` work without one.

The license file also carries the FastTransfer and ADBC driver licenses: keep the whole file as delivered. MigratorXpress passes them to FastTransfer through a private temporary file, removed when it exits, so a separate `FastTransfer.lic` is not needed. A license issued before October 26, 2026 has no FastTransfer block: MigratorXpress then logs a warning and FastTransfer keeps using its own `FastTransfer.lic`.

Examples:

```
# A license file outside the default locations
./MigratorXpress --auth ./credentials.json ... --license_file /opt/migratorxpress/license/MigratorXpress.lic

# CI, containers: the license text from a secret, no file on the machine
export MIGRATORXPRESS_LICENSE="$(cat /opt/migratorxpress/license/MigratorXpress.lic)"
./MigratorXpress --auth ./credentials.json ...
```

```
.\MigratorXpress.exe --auth .\credentials.json ... --license_file C:\licenses\MigratorXpress.lic

$env:MIGRATORXPRESS_LICENSE = Get-Content -Raw C:\licenses\MigratorXpress.lic
```

* `MIGRATORXPRESS_LICENSE` comes first: when it is set, `--license` and `--license_file` are ignored, even if it holds an invalid license (exit 13). Unset it (`unset MIGRATORXPRESS_LICENSE`, `Remove-Item Env:MIGRATORXPRESS_LICENSE`) if a run does not pick up the file you pass.
* Prefer `--license_file` or the variable to `--license "<text>"`: a command-line argument is visible to other users of the machine in the process list (`ps`, Task Manager).
* In a scheduled job (cron, Task Scheduler, Airflow), use an absolute `--license_file` path: the job's working and home directories are often not those of your interactive session.

More complete commands: [Providing the license](/latest/guides/examples.md#providing-the-license).

## Exit Codes[​](#exit-codes "Direct link to Exit Codes")

| Code | Name               | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `0`  | `SUCCESS`          | Every table of the run succeeded every task. Differences found by `diff` do not fail a table                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `1`  | `GENERAL_ERROR`    | Other error: migration error, invalid `--migration_db_mode`, unexpected exception                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `2`  | --                 | Command-line parsing error: missing required argument, invalid `--load_mode`/`--log_level`/`--project`, invalid boolean value (`--compute_nbrows`, `--drop_tables_if_exists`), non-integer value                                                                                                                                                                                                                                                                                                                   |
| `10` | `CONFIG_ERROR`     | Configuration error detected at startup, before any connection: invalid auth entry (unknown `ds_type`, `auth_mode` not supported for the database type, missing or unexpected `info` key, unparsable connection string), auth ID not found in the credentials file, `odbc` used for the target or ODBC prerequisites missing, target or tracking database type not supported, unsupported source/target pair (e.g. Netezza to PostgreSQL), `copy_*` task with a Netezza source, `copy_fk` with a PostgreSQL target |
| `12` | `CONNECTION_ERROR` | Connection to the source, target, or tracking database failed                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `13` | `LICENSE_ERROR`    | License missing, invalid, expired, or not yet active                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `20` | `VALIDATION_ERROR` | Invalid task options (`--task_list`/`--resume` missing or both given, duplicated or unknown task, invalid task sequence), invalid `--fk_mode`, `--target_db_name` not matching the target auth entry, database name that cannot be determined                                                                                                                                                                                                                                                                      |
| `40` | `PARTIAL_FAILURE`  | Some tables failed a task. Retry them with `--resume <run_id>`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `41` | `ALL_JOBS_FAILED`  | Every table of the run failed a task                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

When tables failed, the `RUN SUMMARY: n/m tables succeeded` block at the end of the log lists them, and the log ends with the `--resume <run_id>` command that retries them.

For schedulers: codes `10` to `29` need a fix before the run is started again; codes `40` and `41` can be retried with `--resume`.

Changed in 0.7.2 and 0.7.3

Up to 0.7.1, a run with failed tables and an invalid task list both exited with code `0`, and invalid auth entries failed later with code `1` or `12`. Scripts and schedulers that relied on those codes must be updated.

## Utility[​](#utility "Direct link to Utility")

| Option         | Description                             |
| -------------- | --------------------------------------- |
| `--version`    | Display MigratorXpress version and exit |
| `-h`, `--help` | Show help message and exit              |

## Database Parameters[​](#database-parameters "Direct link to Database Parameters")

### Connection parameters by database type[​](#connection-parameters-by-database-type "Direct link to Connection parameters by database type")

`classic` entries:

| Parameter   | Oracle                    | PostgreSQL              | SQL Server              | Netezza                 |
| ----------- | ------------------------- | ----------------------- | ----------------------- | ----------------------- |
| `ds_type`   | `oracle`                  | `postgres`              | `mssql`                 | `netezza`               |
| `auth_mode` | `classic`                 | `classic`               | `classic`               | `classic`               |
| `username`  | Required                  | Required                | Required                | Required                |
| `password`  | Required                  | Required                | Required                | Required                |
| `server`    | Required                  | Required                | Required                | Required                |
| `port`      | Required (usually 1521)   | Required (usually 5432) | Required (usually 1433) | Required (usually 5480) |
| `database`  | Service name              | Database name           | Database name           | Database name           |
| `lib_dir`   | Optional, thick mode only | --                      | --                      | --                      |

### Authentication modes by database type[​](#authentication-modes-by-database-type "Direct link to Authentication modes by database type")

| `ds_type`  | `classic` | `connection_string` | `trusted` | `odbc`                               |
| ---------- | --------- | ------------------- | --------- | ------------------------------------ |
| `oracle`   | ✅        | ❌                  | ❌        | ❌                                   |
| `postgres` | ✅        | ✅                  | ❌        | ❌                                   |
| `mssql`    | ✅        | ✅                  | ✅        | ✅ source and tracking database only |
| `netezza`  | ✅        | ❌                  | ❌        | ❌                                   |

See [Authentication modes](/latest/configuration/database-configuration.md#authentication-modes) for the `info` keys of each mode.

## Credentials File Format[​](#credentials-file-format "Direct link to Credentials File Format")

The credentials file is a JSON object where each key is an identifier you reference on the command line. Each entry has:

* `ds_type`: `oracle`, `postgres`, `mssql`, or `netezza`
* `auth_mode`: `classic`, `connection_string`, `trusted` or `odbc` (see [Authentication modes by database type](#authentication-modes-by-database-type))
* `info`: for `classic`, `username`, `password`, `server`, `port` (a JSON integer between 1 and 65535), `database`, and for Oracle optionally `lib_dir`

For `classic`, all `info` fields except `lib_dir` are required and must be non-empty. No other key is accepted, in the entry or in `info`. Every entry referenced on the command line is validated at startup, before any connection is opened: an invalid entry stops the run with exit code `10` and a message naming the entry and the key (never the value). Values are used as written: there is no environment variable substitution, so protect the file with file-system permissions.

```
{
  "oracle_prod": {
    "ds_type": "oracle",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "oracle-host.example.com",
      "port": 1521,
      "database": "ORCLPDB1"
    }
  },
  "mssql_target": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "sql-host.example.com",
      "port": 1433,
      "database": "target_db"
    }
  },
  "ms_mig_log": {
    "ds_type": "mssql",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "sql-host.example.com",
      "port": 1433,
      "database": "migration_log"
    }
  },
  "netezza_source": {
    "ds_type": "netezza",
    "auth_mode": "classic",
    "info": {
      "username": "migrator",
      "password": "********",
      "server": "nz-host.example.com",
      "port": 5480,
      "database": "PROD_DB"
    }
  }
}
```

### Oracle Thick Mode[​](#oracle-thick-mode "Direct link to Oracle Thick Mode")

For Oracle 11.2 and earlier, set `lib_dir` to the Oracle Instant Client directory. Later versions use thin mode by default (omit `lib_dir`).

```
{
  "oracle_thick": {
    "ds_type": "oracle",
    "auth_mode": "classic",
    "info": {
      "username": "user",
      "password": "pass",
      "server": "host",
      "port": 1521,
      "database": "LEGACY",
      "lib_dir": "/opt/oracle/instantclient_19_8"
    }
  }
}
```

## Supported Database Types[​](#supported-database-types "Direct link to Supported Database Types")

| Database   | `ds_type` value | Usual Port | As Source                | As Target                                 | As Migration DB |
| ---------- | --------------- | ---------- | ------------------------ | ----------------------------------------- | --------------- |
| Oracle     | `oracle`        | 1521       | Yes                      | No                                        | No              |
| PostgreSQL | `postgres`      | 5432       | Yes                      | Yes (from Oracle, PostgreSQL, SQL Server) | Yes             |
| SQL Server | `mssql`         | 1433       | Yes                      | Yes                                       | Yes             |
| Netezza    | `netezza`       | 5480       | Yes (to SQL Server only) | No                                        | No              |

## See Also[​](#see-also "Direct link to See Also")

* [Quick Start Guide](/latest/guides/quickstart.md) -- get started in 5 minutes
* [Migration Tasks](/latest/configuration/migration-tasks.md) -- task types and execution order
* [FastTransfer Configuration](/latest/configuration/fasttransfer-configuration.md) -- parallel transfer tuning
* [Logging and Monitoring](/latest/reference/logging.md) -- log format and database tracking
* [Troubleshooting](/latest/reference/troubleshooting.md) -- common issues and solutions


---

# Logging and Monitoring

MigratorXpress uses two logging systems: a tracking database (SQL Server or PostgreSQL) for structured migration history, and log files plus console output for operational details.

## Database Logging[​](#database-logging "Direct link to Database Logging")

The migration tracking database records every step of a migration for auditing, resumability, and troubleshooting. Either **SQL Server** or **PostgreSQL** can host it -- the tables and behavior are the same on both backends. The dialect is detected from the `ds_type` of the entry referenced by `--migration_db_auth_id`. On PostgreSQL the tracking tables live in the `public` schema; on SQL Server they are created in the login's default schema (normally `dbo`).

### Database Schema Overview[​](#database-schema-overview "Direct link to Database Schema Overview")

![Migration Database Schema](/assets/images/migration_db_schema-1520c7e05cb5f53e7ca90bf75c7e471c.png)

Primary keys are marked with key symbols and relationships show cardinality (1<!-- -->:N<!-- -->). Since 0.7.0, `run_id` is part of the primary key of the catalog tables (`sources`, `sourcecolumns`, `sourceconstraints`, `targets`, `targetcolumns`): every run keeps its own metadata snapshot.

### Key Tables[​](#key-tables "Direct link to Key Tables")

#### sources[​](#sources "Direct link to sources")

One row per discovered source table and run: `databasename`, `schemaname`, `tablename`, `run_id`, `datediscovery`, `nbrows`, `nbrows_estimate`, `nbcolumns`, `lasttransferstatus`, and the incremental watermarks `nz_last_xid` (Netezza) and `or_max_rowid` (Oracle).

#### targets[​](#targets "Direct link to targets")

One row per target table and run (with a PostgreSQL target, schema and table names are stored in lower case): `databasename`, `schemaname`, `tablename`, `run_id`, `nbrows`, `nbrows_estimate`, `nbcolumns`, `diff_count`.

#### sourcecolumns / targetcolumns[​](#sourcecolumns--targetcolumns "Direct link to sourcecolumns / targetcolumns")

Column-level metadata per table and run: `columnname`, `coldatatype`, `collength`, `colprecision`, `colscale`, `isnullable`, `ordinalposition`, and profiling statistics (`countdistinct`, `valmin`, `valmax`, `valavg`, `valcountnull`). `targetcolumns` holds the translated (target) data types.

#### loadsteps[​](#loadsteps "Direct link to loadsteps")

Reference list of steps (`id_step`, `desc_step`): `0` source\_table\_discovery, `1` source\_data\_types\_translation, `2` target\_table\_creation, `3` data\_transfer, `4` source\_target\_tables\_comparison, `5` apply\_constrainsts\_pk, `6` apply\_constrainsts\_ak, `7` apply\_constrainsts\_fk.

#### sourcetargetloads[​](#sourcetargetloads "Direct link to sourcetargetloads")

One job per table and task: `id_load`, `id_step`, `run_id`, `project`, `src_databasename`, `src_schemaname`, `src_tablename`, `tar_databasename`, `tar_schemaname`, `tar_tablename`, and `status` (`NULL`/`NOT STARTED` before the job runs, then `STARTED`, `DONE`, or `FAILED`). `--resume` re-processes the jobs of a run that are not `DONE`.

#### eventlog[​](#eventlog "Direct link to eventlog")

Event log for migration activity: `eventtimestamp`, `eventrunid`, `eventloglevel` (`info`, `error`, ...), `id_step`, `eventstatus` (`STARTED`, `DONE`, `FAILED`), `elapsedtimeseconds`, source and target database/schema/table names, `eventmessage` (error text on failure), and `project`.

#### sourcetargetdiff[​](#sourcetargetdiff "Direct link to sourcetargetdiff")

Results of the `diff` task, one row per compared item: `id_load`, source and target table and column names, `diff_timestamp`, `diff_type`, `diff_outcome` (true when source and target match), `run_id`, `project`. The `v_sourcetargetdiff` view joins it with the source and target statistics.

#### sourceconstraints[​](#sourceconstraints "Direct link to sourceconstraints")

Constraint metadata read from the source (Oracle, PostgreSQL or SQL Server) for `copy_pk`/`copy_ak`/`copy_fk`: `constraintname`, `constrainttype`, `columnlist`, `constraintdefinition`, `refschemaname`, `reftablename`, `refcolumnlist`, `run_id`.

## File-Based Logging[​](#file-based-logging "Direct link to File-Based Logging")

Each migration run creates a log file for detailed operational tracing.

### Naming Pattern[​](#naming-pattern "Direct link to Naming Pattern")

```
mig_YYYYMMDD_HHMMSS_<run_id>.log
```

The date and time are the local start time; `<run_id>` has the format `YYYYMMDD-<uuid4>`, for example `mig_20260115_093012_20260115-0f8c4a8e-6c1f-4f5e-9b55-7d6f1c2e9a10.log`. A resumed run writes a new file with the original run ID.

The file is opened as soon as the run ID is known (after the tracking database setup), so the first messages of a run (banner, license and configuration) appear on the console only.

### Log Format[​](#log-format "Direct link to Log Format")

Each line contains a timestamp, the log level, the process ID and the process name:

```
[YYYY-MM-DD HH:mm:ss.SSS+TZ :: LEVEL :: PID :: ProcessName] Message
```

### Sample Output[​](#sample-output "Direct link to Sample Output")

```
[2026-01-15 09:30:12.145+01:00 :: INFO :: 8421 :: MainProcess] Log file path: /var/log/migratorxpress/mig_20260115_093012_20260115-0f8c4a8e-6c1f-4f5e-9b55-7d6f1c2e9a10.log
[2026-01-15 09:30:12.385+01:00 :: INFO :: 8421 :: MainProcess] *** Source table selection ***
[2026-01-15 09:30:13.102+01:00 :: INFO :: 8421 :: MainProcess] ========== Step 'translate' across all schemas ==========
[2026-01-15 09:31:40.556+01:00 :: INFO :: 8421 :: MainProcess] ===========================================================================
[2026-01-15 09:31:40.556+01:00 :: INFO :: 8421 :: MainProcess] RUN SUMMARY: 41/42 tables succeeded
[2026-01-15 09:31:40.556+01:00 :: INFO :: 8421 :: MainProcess] ===========================================================================
[2026-01-15 09:31:40.556+01:00 :: INFO :: 8421 :: MainProcess] Failed tables:
[2026-01-15 09:31:40.556+01:00 :: INFO :: 8421 :: MainProcess]   - SALES.ORDERS_ARCHIVE                     [transfer]
```

The `RUN SUMMARY` block at the end of a run lists the tables that failed and the task(s) where they failed. When tables failed, the run then logs `run <run_id> finished with failed tables, exit code 40; use --resume <run_id> to retry them` (exit code `41` when every table failed). See [Exit Codes](/latest/reference/cli-reference.md#exit-codes).

### FastTransfer command[​](#fasttransfer-command "Direct link to FastTransfer command")

For each table, the `fasttransfer command` line logs the FastTransfer call. Since 0.7.2 it starts with the absolute path of the FastTransfer executable and is rendered with shell quoting (POSIX quoting on Linux, Windows command-line quoting on Windows), instead of the former `./FastTransfer --option "value"` string. Update log parsers written for 0.7.1.

Passwords and connection strings of the source and target entries are replaced by `**********` in this line, in every logged line of FastTransfer's output, in connection error messages and in the event log (`eventlog.eventmessage`).

## Log Levels[​](#log-levels "Direct link to Log Levels")

Set via `--log_level` (case-insensitive):

| Level      | Description                                              |
| ---------- | -------------------------------------------------------- |
| `DEBUG`    | SQL queries, FastTransfer commands, detailed diagnostics |
| `INFO`     | Progress, row counts, task completion (default)          |
| `WARNING`  | Non-critical issues                                      |
| `ERROR`    | Failures preventing a table from migrating               |
| `CRITICAL` | Errors that stop the run or a step                       |

The same level applies to the console and to the log file.

## Log Location[​](#log-location "Direct link to Log Location")

Defaults to the current working directory. Override with `--log_dir` (the directory is created if it does not exist):

```
./MigratorXpress --log_dir /var/log/migratorxpress \
  --auth ./credentials.json \
  ...
```

## Terminal Output[​](#terminal-output "Direct link to Terminal Output")

Logs are mirrored to the terminal (stdout) with the same format; the timestamp, level, process ID and process name fields are colorized. Use `--quiet_ft` to hide FastTransfer's own output from the console (it is still written to the log file), `--no_progress` to disable the progress lines, and `--no_banner` to suppress the startup banner.

## Monitoring Best Practices[​](#monitoring-best-practices "Direct link to Monitoring Best Practices")

### During migration[​](#during-migration "Direct link to During migration")

* Watch the terminal for real-time progress on each table.
* Use `--n_jobs 1` for initial test runs so log output is sequential and easier to follow.
* Set `--log_level DEBUG` to capture SQL statements when diagnosing issues.

### After migration[​](#after-migration "Direct link to After migration")

* Read the `RUN SUMMARY` block at the end of the log.
* Query the `sourcetargetloads` table for per-table job status.
* Query the `eventlog` table for error messages and elapsed times.
* Query `sourcetargetdiff` / `v_sourcetargetdiff` for the `diff` results.

### Resuming failed runs[​](#resuming-failed-runs "Direct link to Resuming failed runs")

If a migration is interrupted or some tables failed, the tracking database preserves the state of each job. Use `--resume` with the run ID to finish it -- only jobs that are not `DONE` are reprocessed:

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --target_db_auth_id mssql_target \
  --migration_db_auth_id ms_mig_log \
  --resume 20260115-0f8c4a8e-6c1f-4f5e-9b55-7d6f1c2e9a10
```

## Integration with Monitoring Tools[​](#integration-with-monitoring-tools "Direct link to Integration with Monitoring Tools")

### Log file ingestion[​](#log-file-ingestion "Direct link to Log file ingestion")

MigratorXpress log files use a structured format that can be parsed by log aggregation tools:

* **Filebeat / Logstash** -- configure a file input pointing to `mig_*.log` with a grok pattern for the bracket-delimited format.
* **Fluentd** -- use a regexp parser matching `\[(?<time>[^\]]+) :: (?<level>\w+) :: (?<pid>\d+) :: (?<context>[^\]]+)\] (?<message>.*)`.
* **Splunk** -- index the log directory and create field extractions for timestamp, level, PID, and process name.

### Database queries for dashboards[​](#database-queries-for-dashboards "Direct link to Database queries for dashboards")

Connect your monitoring tool (Grafana, Power BI, etc.) directly to the migration tracking database. These queries work on both SQL Server and PostgreSQL.

```
-- Failed jobs of a run, with their error message
SELECT e.src_schemaname, e.src_tablename, l.desc_step, e.eventmessage, e.eventtimestamp
FROM eventlog AS e
JOIN loadsteps AS l ON l.id_step = e.id_step
WHERE e.eventrunid = 'YOUR_RUN_ID'
  AND e.eventstatus = 'FAILED'
ORDER BY e.eventtimestamp DESC;

-- Transfer duration and throughput per table
SELECT e.src_schemaname, e.src_tablename, s.nbrows_estimate, e.elapsedtimeseconds,
       s.nbrows_estimate / NULLIF(e.elapsedtimeseconds, 0) AS est_rows_per_second
FROM eventlog AS e
JOIN sources AS s
  ON s.databasename = e.src_databasename
 AND s.schemaname = e.src_schemaname
 AND s.tablename = e.src_tablename
 AND s.run_id = e.eventrunid
WHERE e.eventrunid = 'YOUR_RUN_ID'
  AND e.id_step = 3
  AND e.eventstatus = 'DONE'
ORDER BY e.elapsedtimeseconds DESC;

-- Columns whose diff failed
SELECT src_schemaname, src_tablename, src_columnname, diff_type
FROM sourcetargetdiff
WHERE run_id = 'YOUR_RUN_ID'
  AND diff_outcome = 0;   -- PostgreSQL: diff_outcome = false
```

## See Also[​](#see-also "Direct link to See Also")

* [CLI Reference](/latest/reference/cli-reference.md) -- `--log_level`, `--log_dir`, and other options
* [Troubleshooting](/latest/reference/troubleshooting.md) -- common issues and solutions


---

# MigratorXpress SBOM Downloads

SBOMs for 0.7.x

Since v0.6.33, the CycloneDX SBOMs (JSON and XML, with SHA-256 checksums) ship **inside each release zip** -- this includes all 0.7.x releases. The files below are the last SBOMs published on this site (v0.6.29); they do not describe the current release.

## Last Published SBOM: 0.6.29[​](#last-published-sbom-0629 "Direct link to Last Published SBOM: 0.6.29")

Last updated: 2026-04-16

### Download Files[​](#download-files "Direct link to Download Files")

#### JSON Format (CycloneDX 1.5)[​](#json-format-cyclonedx-15 "Direct link to JSON Format (CycloneDX 1.5)")

* **Download**: [migratorxpress-v0.6.29-sbom.json](/assets/files/migratorxpress-v0.6.29-sbom-ad9a5841736c8f1adf36f9aac5a127df.json)
* **SHA256**: *(available after release)*
* **Checksum file**: [migratorxpress-v0.6.29-sbom.json.sha256](/assets/files/migratorxpress-v0.6.29-sbom.json-1171f66966b0e14e4533d78ac2778d20.sha256)

#### XML Format (CycloneDX 1.5)[​](#xml-format-cyclonedx-15 "Direct link to XML Format (CycloneDX 1.5)")

* **Download**: [migratorxpress-v0.6.29-sbom.xml](/assets/files/migratorxpress-v0.6.29-sbom-f0de12f64d3412a1ee339d090779f659.xml)
* **SHA256**: *(available after release)*
* **Checksum file**: [migratorxpress-v0.6.29-sbom.xml.sha256](/assets/files/migratorxpress-v0.6.29-sbom.xml-8b92f4a3b90b7ec4e8c6f168f8b38a8d.sha256)

### All Checksums[​](#all-checksums "Direct link to All Checksums")

* **Combined checksums**: [checksums.txt](/assets/files/checksums-7fbdbf4613e80ff7dae1182b7a65c814.txt)

### Verification Instructions[​](#verification-instructions "Direct link to Verification Instructions")

To verify the integrity of downloaded SBOM files:

```
# Download SBOM and checksum
wget https://migratorxpress.arpe.io/sboms/latest/migratorxpress-v0.6.29-sbom.json
wget https://migratorxpress.arpe.io/sboms/latest/migratorxpress-v0.6.29-sbom.json.sha256

# Verify
sha256sum -c migratorxpress-v0.6.29-sbom.json.sha256
```

### Quick Download Script[​](#quick-download-script "Direct link to Quick Download Script")

Save this as `download-sbom.sh`:

```
#!/bin/bash
# Download and verify MigratorXpress SBOM

BASE_URL="https://migratorxpress.arpe.io/sboms/latest"
VERSION="v0.6.29"

# Download JSON SBOM and verify
echo "Downloading JSON SBOM..."
wget "${BASE_URL}/migratorxpress-${VERSION}-sbom.json"
wget "${BASE_URL}/migratorxpress-${VERSION}-sbom.json.sha256"
sha256sum -c "migratorxpress-${VERSION}-sbom.json.sha256" || exit 1

# Download XML SBOM and verify
echo "Downloading XML SBOM..."
wget "${BASE_URL}/migratorxpress-${VERSION}-sbom.xml"
wget "${BASE_URL}/migratorxpress-${VERSION}-sbom.xml.sha256"
sha256sum -c "migratorxpress-${VERSION}-sbom.xml.sha256" || exit 1

echo "SBOMs downloaded and verified!"
```

### Version History[​](#version-history "Direct link to Version History")

SBOMs of previous releases are kept under `https://migratorxpress-docs.arpe.io/sboms/v<version>/` (for example `/sboms/v0.6.29/`), with the same file names as above for that version.

### About These SBOMs[​](#about-these-sboms "Direct link to About These SBOMs")

The Software Bill of Materials (SBOM) provides a complete inventory of all components in MigratorXpress:

* All direct dependencies with exact versions
* Package URLs (PURLs) for each component
* License information where available
* CycloneDX 1.5 format compatible with security scanning tools

### Integration with Security Tools[​](#integration-with-security-tools "Direct link to Integration with Security Tools")

Use these SBOMs with:

* **Grype**: `grype sbom:migratorxpress-v0.6.29-sbom.json`
* **Trivy**: `trivy sbom migratorxpress-v0.6.29-sbom.json`
* **OWASP Dependency-Track**: Import via UI or API

***

*For current releases, use the SBOM files included in the release zip.*


---

# Troubleshooting

Common issues encountered during MigratorXpress migrations and how to resolve them.

## Connection Issues[​](#connection-issues "Direct link to Connection Issues")

### Cannot connect to source database[​](#cannot-connect-to-source-database "Direct link to Cannot connect to source database")

**Symptoms:** Connection timeout or authentication error when MigratorXpress starts.

**Solutions:**

1. Verify that the credentials file is valid JSON and that the `--source_db_auth_id` matches a key in the file. An auth ID that is not in the file stops the run with exit code `10`; the message lists the available entry names.
2. Check the entry format. For `auth_mode` `"classic"`, `info` must contain non-empty `username`, `password`, `server`, `database` and an integer `port` (for example `1521`, not `"1521"`), and nothing else (except `lib_dir` for Oracle). An invalid entry stops the run at startup with exit code `10` (`INVALID_AUTH_ENTRY`, `AUTH_MODE_NOT_SUPPORTED` or `INVALID_CONNECTION_STRING`) and a message naming the entry and the key. See [Authentication modes](/latest/configuration/database-configuration.md#authentication-modes).
3. Values are used literally: `$env{...}` references are **not** expanded.
4. Test connectivity independently (e.g., `psql`, `sqlplus`, `sqlcmd`) before running MigratorXpress.
5. Confirm the server hostname, port, and database name are correct (Oracle: service name).

A connection failure stops the run with a `CONNECTION FAILED` summary and exit code `12`.

```
# Test Oracle connectivity (host:port/service_name)
sqlplus migrator@//oracle-host:1521/ORCLPDB1

# Test PostgreSQL connectivity
psql -h pg-host -p 5432 -U migrator -d analytics

# Test SQL Server connectivity
sqlcmd -S sql-host,1433 -U migrator -d target_db
```

### Migration database not accessible[​](#migration-database-not-accessible "Direct link to Migration database not accessible")

**Symptoms:** Error connecting to the migration tracking database or error creating tables.

**Solutions:**

1. The migration tracking database must be **SQL Server** (`ds_type: "mssql"`) or **PostgreSQL** (`ds_type: "postgres"`).
2. Verify the `--migration_db_auth_id` references a valid entry of one of these types in the credentials file.
3. The connecting user must be able to create and alter tables in the tracking database (and own the `public` schema on PostgreSQL, see [PostgreSQL as Migration Tracking](/latest/configuration/databases/postgresql-as-tracking.md)).
4. On SQL Server, a `classic` entry uses SQL Server authentication, which needs **mixed-mode authentication**. Otherwise use a `trusted` entry (integrated authentication).

SQL Server example:

```
-- Grant CREATE TABLE permission
USE migration_log;
GRANT CREATE TABLE TO your_migration_user;
GRANT ALTER ON SCHEMA::dbo TO your_migration_user;
GRANT INSERT, UPDATE, DELETE, SELECT ON SCHEMA::dbo TO your_migration_user;
```

## PostgreSQL Issues[​](#postgresql-issues "Direct link to PostgreSQL Issues")

### Connection refused[​](#connection-refused "Direct link to Connection refused")

**Symptoms:** `could not connect to server: Connection refused`

**Solutions:**

* Verify PostgreSQL is running:
  <!-- -->
  ```
  systemctl status postgresql
  ```

* Check that `pg_hba.conf` allows connections from your IP address. Add a line such as:

  <!-- -->

  ```
  host    all    all    10.0.0.0/8    md5
  ```

  <!-- -->

  Then reload the configuration:

  <!-- -->

  ```
  sudo systemctl reload postgresql
  ```

* Check firewall rules:
  <!-- -->
  ```
  sudo ufw allow 5432/tcp
  ```

* Confirm PostgreSQL is listening on the correct interface. Check `listen_addresses` in `postgresql.conf`:
  <!-- -->
  ```
  listen_addresses = '*'
  ```

### Authentication failed[​](#authentication-failed "Direct link to Authentication failed")

**Symptoms:** `FATAL: password authentication failed for user`

**Solutions:**

* Verify the username and password are correct.
* Check the password encryption method in `pg_hba.conf` (`md5` vs `scram-sha-256`).
* Confirm the user exists:
  <!-- -->
  ```
  SELECT * FROM pg_user WHERE usename = 'your_user';
  ```
* Check that the password in the credentials file is exactly the database password (it is used as written; JSON escaping rules apply to `\` and `"`).

## Oracle Issues[​](#oracle-issues "Direct link to Oracle Issues")

### ORA-12154: TNS could not resolve connect identifier[​](#ora-12154-tns-could-not-resolve-connect-identifier "Direct link to ORA-12154: TNS could not resolve connect identifier")

**Symptoms:** Connection fails with TNS resolution error.

**Solutions:**

* Verify that the `database` value in the credentials file is the **service name** registered with the listener (`lsnrctl services`). MigratorXpress connects with `host:port/service_name`; SIDs and TNS aliases are not supported.
* Try using the IP address instead of the hostname.
* Confirm the Oracle listener is running:
  <!-- -->
  ```
  lsnrctl status
  ```

### ORA-28000: account is locked[​](#ora-28000-account-is-locked "Direct link to ORA-28000: account is locked")

**Symptoms:** Login fails because the Oracle account is locked.

**Solutions:**

* Unlock the account as a DBA:
  <!-- -->
  ```
  ALTER USER your_username ACCOUNT UNLOCK;
  ```
* Check if the account was locked due to too many failed login attempts. Review the account profile:
  <!-- -->
  ```
  SELECT profile FROM dba_users WHERE username = 'YOUR_USER';
  SELECT resource_name, limit FROM dba_profiles WHERE profile = 'DEFAULT' AND resource_name = 'FAILED_LOGIN_ATTEMPTS';
  ```

### Thick mode library not found[​](#thick-mode-library-not-found "Direct link to Thick mode library not found")

**Symptoms:** Error loading Oracle client libraries, typically `DPI-1047: Cannot locate a 64-bit Oracle Client library`.

**Solutions:**

* Verify the `lib_dir` path in the credentials file points to a valid Oracle Instant Client directory.
* Confirm the Instant Client version matches the platform (64-bit required).
* Check file permissions on the Instant Client directory.
* On Linux, set `LD_LIBRARY_PATH`:
  <!-- -->
  ```
  export LD_LIBRARY_PATH=/opt/oracle/instantclient_19_8:$LD_LIBRARY_PATH
  ```
* On Linux, you may also need `libaio`:
  <!-- -->
  ```
  sudo apt-get install libaio1    # Debian/Ubuntu
  sudo yum install libaio         # RHEL/CentOS
  ```

## SQL Server Issues[​](#sql-server-issues "Direct link to SQL Server Issues")

### Login failed for user[​](#login-failed-for-user "Direct link to Login failed for user")

**Symptoms:** `Login failed for user 'username'`

**Solutions:**

* For a `classic` entry, confirm SQL Server is configured for **SQL Server Authentication** (mixed mode), not Windows Authentication only, or switch to a `trusted` entry (integrated authentication).
* Verify the username and password are correct.
* Check that the user exists and is not disabled:
  <!-- -->
  ```
  SELECT name, is_disabled FROM sys.sql_logins WHERE name = 'your_user';
  ```
* Check for IP restrictions or firewall rules blocking the connection.

### Integrated authentication fails on Linux[​](#integrated-authentication-fails-on-linux "Direct link to Integrated authentication fails on Linux")

**Symptoms:** a `trusted` entry (or a connection string with `Integrated Security=true`) cannot log in from Linux.

**Solutions:**

* Check that the account running MigratorXpress has a valid Kerberos ticket for the whole run (`klist`; renew with `kinit`, or `kinit -kt` with a keytab).
* Check that `/etc/krb5.conf` declares the realm and its KDC.
* Give the server by its fully qualified domain name, not an IP address or a CNAME alias.
* Check that the service principal `MSSQLSvc/<fqdn>:<port>` is registered for the SQL Server service account.
* Install the system GSSAPI library (`libgssapi_krb5`), needed by FastTransfer.

### ODBC entry rejected at startup[​](#odbc-entry-rejected-at-startup "Direct link to ODBC entry rejected at startup")

**Symptoms:** an `odbc` entry stops the run with exit code `10`.

**Solutions:**

* `odbc` is accepted for a SQL Server source or tracking database only, never for the target.
* Install the ODBC prerequisites, which are not bundled: on Linux the unixODBC driver manager (`libodbc.so.2`), on every platform the Microsoft ODBC Driver 18 for SQL Server, and declare the DSN (`/etc/odbc.ini`, `~/.odbc.ini`, or the Windows ODBC Data Source Administrator).

### Cannot define PRIMARY KEY constraint on nullable column[​](#cannot-define-primary-key-constraint-on-nullable-column "Direct link to Cannot define PRIMARY KEY constraint on nullable column")

**Symptoms:** `copy_pk` fails on a SQL Server target with `Cannot define PRIMARY KEY constraint on nullable column`.

**Solutions:**

* Up to 0.7.2, every column of a PostgreSQL source was created nullable on the target. Since 0.7.3 the source `NOT NULL` is kept: recreate the tables (`--task_list translate create` with `--drop_tables_if_exists true`, then reload them) before running `copy_pk`.

### Cannot open database requested by the login[​](#cannot-open-database-requested-by-the-login "Direct link to Cannot open database requested by the login")

**Symptoms:** `Cannot open database "dbname" requested by the login. The login failed.`

**Solutions:**

* Verify the database name in the credentials file is spelled correctly (case-sensitive on Linux-hosted SQL Server).
* Confirm the user has access to the database:
  <!-- -->
  ```
  USE your_database;
  SELECT * FROM sys.database_principals WHERE name = 'your_user';
  ```
* Check the database is online:
  <!-- -->
  ```
  SELECT name, state_desc FROM sys.databases WHERE name = 'your_database';
  ```

## Netezza Issues[​](#netezza-issues "Direct link to Netezza Issues")

### Connection refused[​](#connection-refused-1 "Direct link to Connection refused")

**Symptoms:** `could not connect to server: Connection refused` on port 5480.

**Solutions:**

* Verify the Netezza appliance is powered on and the NPS service is running.
* Confirm the correct port (default: **5480**, not 5432).
* Check network connectivity:
  <!-- -->
  ```
  telnet nz-host 5480
  ```
* Verify firewall rules allow traffic to port 5480.

### Authentication failed[​](#authentication-failed-1 "Direct link to Authentication failed")

**Symptoms:** `FATAL: password authentication failed`

**Solutions:**

* Verify the username and password.
* Confirm the user exists in the Netezza system:
  <!-- -->
  ```
  SELECT username FROM _v_user WHERE username = 'YOUR_USER';
  ```
* Check that the user has access to the target database:
  <!-- -->
  ```
  SELECT * FROM _v_object_data WHERE objname = 'YOUR_DATABASE';
  ```

## General Tips[​](#general-tips "Direct link to General Tips")

### Exit codes[​](#exit-codes "Direct link to Exit codes")

| Code | Meaning                                                                                                                                                                                                                                        |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | Every table succeeded every task (differences found by `diff` do not fail a table)                                                                                                                                                             |
| `1`  | Other error (migration error, invalid `--migration_db_mode`, unexpected exception)                                                                                                                                                             |
| `2`  | Command-line parsing error (missing required argument, invalid value)                                                                                                                                                                          |
| `10` | Configuration error detected at startup: invalid auth entry, auth ID not found, unsupported target or tracking database type, unsupported source/target pair, `copy_*` with a Netezza source, `copy_fk` with a PostgreSQL target, ODBC problem |
| `12` | Database connection failure (source, target, or tracking database)                                                                                                                                                                             |
| `13` | License error (missing, invalid, expired, or not yet active)                                                                                                                                                                                   |
| `20` | Validation error: invalid task options, invalid `--fk_mode`, `--target_db_name` not matching the target auth entry                                                                                                                             |
| `40` | Some tables failed a task: fix the cause and `--resume <run_id>`                                                                                                                                                                               |
| `41` | Every table failed a task                                                                                                                                                                                                                      |

See [Exit Codes](/latest/reference/cli-reference.md#exit-codes) for the details.

### "the following arguments are required"[​](#the-following-arguments-are-required "Direct link to \"the following arguments are required\"")

`--auth`, `--source_db_auth_id`, `--target_db_auth_id` and `--migration_db_auth_id` are mandatory for every run, including `--resume`. Only `--upgrade_migdb` relaxes the source and target arguments. `--source_db_name` and `--target_db_name` are optional since 0.7.2.

### Target database name mismatch[​](#target-database-name-mismatch "Direct link to Target database name mismatch")

**Symptoms:** the run stops with exit code `20` and `--target_db_name '...' does not match the database '...' of the target auth entry`.

`--target_db_name` must match the database of the target auth entry (case-insensitively for SQL Server, exactly for PostgreSQL). Remove the option, or fix the auth entry. `--source_db_name` is ignored: the source database is always the one of the source auth entry.

### Task list rejected[​](#task-list-rejected "Direct link to Task list rejected")

`incorrect task sequence` means the task combination is not one of the accepted sequences (for example `translate transfer` without `create`). `Either 'task_list' or 'resume' should be given` means both or neither were given. See [Migration Tasks](/latest/configuration/migration-tasks.md#accepted-combinations). These errors exit with code `20`.

### Unsupported combination rejected at startup[​](#unsupported-combination-rejected-at-startup "Direct link to Unsupported combination rejected at startup")

Exit code `10` with `UNSUPPORTED_SOURCE_TARGET_PAIR` (Netezza to PostgreSQL), `CONSTRAINT_COPY_UNSUPPORTED_SOURCE` (`copy_*` with a Netezza source) or `COPY_FK_UNSUPPORTED_TARGET` (`copy_fk`, or `--task_list all`, with a PostgreSQL target). Remove the unsupported tasks from `--task_list`, for example `--task_list translate create transfer diff copy_pk copy_ak` for a PostgreSQL target. See [Compatibility](/latest/compatibility.md#supported-migration-paths).

### Table not created with a PostgreSQL target[​](#table-not-created-with-a-postgresql-target "Direct link to Table not created with a PostgreSQL target")

SQL Server `GEOGRAPHY` / `GEOMETRY` columns and PostgreSQL `ARRAY` / user-defined columns cannot be translated for a PostgreSQL target: `translate` fails for the table, and `create` reports it as failed without creating it. Exclude these tables (`--exclude_tables`) and migrate them separately.

### `--drop_tables_if_exists` value rejected[​](#--drop_tables_if_exists-value-rejected "Direct link to --drop_tables_if_exists-value-rejected")

`--drop_tables_if_exists` accepts `true`/`yes`/`1` (or no value) and `false`/`no`/`0`. Any other value is rejected by the argument parser (exit code `2`). Up to 0.7.1, any value enabled the option, including `false`.

### Tracking database on the old schema[​](#tracking-database-on-the-old-schema "Direct link to Tracking database on the old schema")

On the first 0.7 run against a tracking database created by 0.6.x, MigratorXpress logs `metadata DB is on the old schema; upgrading in place` and upgrades it. You can also run the upgrade separately with `--upgrade_migdb` (see [Upgrading the tracking database](/latest/reference/cli-reference.md#upgrading-the-tracking-database)). Back up the tracking database first.

### License errors[​](#license-errors "Direct link to License errors")

The license is searched in this order: `MIGRATORXPRESS_LICENSE` environment variable, `--license`, `--license_file`, `~/.migratorxpress/license.lic` (Linux) or `%APPDATA%\MigratorXpress\license.lic` (Windows), then `./license.lic`. Without a valid license (missing, invalid or expired), the run stops with exit code `13`. The free 30-day trial is a license file from [arpe.io](https://arpe.io/get-trial?product=MigratorXpress).

### Enable debug logging[​](#enable-debug-logging "Direct link to Enable debug logging")

Set `--log_level DEBUG` to capture detailed diagnostics including SQL statements, FastTransfer commands, and connection details:

```
./MigratorXpress --auth ./credentials.json \
  --log_level DEBUG \
  --log_dir /tmp/mig_debug \
  ...
```

### Check the log file[​](#check-the-log-file "Direct link to Check the log file")

Every migration run creates a log file named `mig_YYYYMMDD_HHMMSS_<run_id>.log` in `--log_dir` (default: current directory). Review the full log for error context that may not appear in the terminal summary.

### Resume after failure[​](#resume-after-failure "Direct link to Resume after failure")

If a migration fails partway through, or the `RUN SUMMARY` lists failed tables (exit code `40` or `41`), use `--resume` with the run ID to process only the jobs that are not `DONE` rather than starting over. The run ID is part of the log file name:

```
./MigratorXpress --auth ./credentials.json \
  --source_db_auth_id oracle_prod \
  --target_db_auth_id mssql_target \
  --migration_db_auth_id ms_mig_log \
  --resume 20260203-cf5be0ac-159f-4dad-861e-8b2b6f3868d7
```

### Verify FastTransfer binary[​](#verify-fasttransfer-binary "Direct link to Verify FastTransfer binary")

MigratorXpress uses the FastTransfer found in `--fasttransfer_dir_path`, or in the `engine/` directory next to its binary when the flag is omitted. FastTransfer 0.15.0 or later is required. Confirm the binary is executable and check its version (printed in the banner when run without arguments):

```
ls -la ./FastTransfer_linux-x64_v0.15.0/
./FastTransfer_linux-x64_v0.15.0/FastTransfer
```

## See Also[​](#see-also "Direct link to See Also")

* [CLI Reference](/latest/reference/cli-reference.md) -- all command-line options
* [Logging and Monitoring](/latest/reference/logging.md) -- log format and database tracking
* [Database Configuration](/latest/configuration/database-configuration.md) -- connection setup
* [PostgreSQL](/latest/configuration/databases/postgresql.md) -- PostgreSQL-specific configuration
* [Oracle](/latest/configuration/databases/oracle.md) -- Oracle-specific configuration
* [SQL Server](/latest/configuration/databases/sql-server.md) -- SQL Server-specific configuration


---

# Command Builder

Build your MigratorXpress command step by step using the interactive wizard below.

<!-- -->

Expand All\[ ]

### Platform <!-- -->Linux

Linux

Windows (PowerShell)

### Source Database

| Authentication File:           | credentials.json                                                                                                                   |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Source Database ID (required): | e.g., ds\_08\_oracleID from your credentials JSON file                                                                             |
| Source Schema Name:            | e.g., SALES or APP\_%Supports SQL LIKE patterns (%, \_). Comma-separated for multiple. Omit for all schemas. Not used with Resume. |

### Target Database

| Target Database ID (required):                   | e.g., ds\_05\_msID from your credentials JSON file. SQL Server or PostgreSQL target (PostgreSQL: names are lower-cased, no copy\_fk; not from a Netezza source)            |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Target Database Name (<!-- -->optional<!-- -->): | e.g., tpchDefaults to the database of the target entry in the credentials file. If set, it must match it.                                                                  |
| Target Schema Name:                              | e.g., tpch\_1\_copyLeave empty to keep the source schema name(s). If set with a pattern/list (or no source schema), all source schemas are loaded into this single schema. |

### Migration Tracking Database

| Migration DB ID (required): | e.g., ds\_02\_msSQL Server or PostgreSQL database for migration tracking and logging                                                                  |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Migration DB Mode:          | preservetruncatedroppreserve: keep tracking data (enables resume). truncate: delete all tracking data (all runs). drop: recreate all tracking tables. |

### Migration Tasks <!-- -->translate, create, transfer, diff

|                                                                                                                                                                                              |   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| \[x]`translate` — <!-- -->Translate source column types to target types                                                                                                                      |   |
| \[x]`create` — <!-- -->Create tables in target database                                                                                                                                      |   |
| \[x]`transfer` — <!-- -->Copy data (requires FastTransfer)                                                                                                                                   |   |
| \[x]`diff` — <!-- -->Validate data integrity                                                                                                                                                 |   |
| \[ ]`copy_pk` — <!-- -->Copy primary key constraints                                                                                                                                         |   |
| \[ ]`copy_ak` — <!-- -->Copy alternate key constraints                                                                                                                                       |   |
| \[ ]`copy_fk` — <!-- -->Copy foreign key constraints                                                                                                                                         |   |
| Tasks always run in this order.<!-- --> <!-- -->copy\_pk/copy\_ak/copy\_fk need an Oracle, PostgreSQL or SQL Server source (not Netezza). copy\_fk, and so "all", needs a SQL Server target. |   |

### FastTransfer Configuration

### Table Filtering

### Migration Options

### Oracle Source Options

### Logging & Output

### Resume

### License

### Generated Command

Multi-line\[x]

```
./MigratorXpress \
  --auth credentials.json \
  --source_db_auth_id <source_db_auth_id> \
  --target_db_auth_id <target_db_auth_id> \
  --migration_db_auth_id <migration_db_auth_id> \
  --task_list translate create transfer diff
```

copy


---