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

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

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

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

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

Full Migration

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

--task_list translate create transfer diff

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

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

--task_list transfer

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

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

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. Also forces --without_xid
(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_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

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

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

• FastTransfer Configuration -- Parallel transfer tuning and performance
• Database Connections -- Auth file configuration
• Quick Start Guide -- Getting started with MigratorXpress
• CLI Reference -- Full command-line reference