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

Source Databases

Database	Parallel Transfer Method	Notes
PostgreSQL	Ctid	No key column required
Oracle	Rowid	Thin and thick client modes; requires SELECT_CATALOG_ROLE for parallel transfers
SQL Server	None (table-level parallelism only)	Also usable as target and migration tracking
Netezza	NZDataSlice	Source-only; default port 5480

Target Databases

Database	Notes
SQL Server	Supported target; columnstore index options (cci_threshold, aci_threshold)
PostgreSQL	From Oracle, PostgreSQL and SQL Server sources; lower-case names; no copy_fk

Migration Tracking Database

Database	Notes
SQL Server	ds_type: "mssql"; tables in the default schema (dbo)
PostgreSQL	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

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 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

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

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)

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)

{
  "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

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

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

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

• 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

• 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

• 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

• PostgreSQL -- Source, target, and tracking configuration
• Oracle -- Source configuration with thin/thick modes
• SQL Server -- Source, target, and migration tracking configuration
• Netezza -- Source configuration
• Quick Start Guide -- Getting started with MigratorXpress
• CLI Reference -- Command-line options