yb-voyager CLI reference

yb-voyager is a command line executable for migrating databases from PostgreSQL, Oracle, and MySQL to a YugabyteDB database.

Syntax

yb-voyager [ <migration-step>... ] [ <arguments> ... ]

• migration-step: See Commands
• arguments: See Arguments

Command line help

To display the available online help, run:

yb-voyager --help

To display the available online help for any migration step, run:

yb-voyager [ <migration-step>... ] --help

Version check

To verify the version of yb-voyager installed on your machine, run:

yb-voyager version

Commands

The following command line options specify the migration steps.

export schema

Export the schema from the source database.

Syntax

yb-voyager export schema [ <arguments> ... ]

The valid arguments for export schema are described in the following table:

Example

yb-voyager export schema --export-dir /path/to/yb/export/dir \
        --source-db-type sourceDB \
        --source-db-host localhost \
        --source-db-port port \
        --source-db-user username \
        --source-db-password password \ # Enclose the password in single quotes if it contains special characters.
        --source-db-name dbname \
        --source-db-schema schemaName \ # Not applicable for MySQL
        --start-clean

analyze-schema

Analyse the PostgreSQL schema dumped in the export schema step.

Syntax

yb-voyager analyze-schema [ <arguments> ... ]

The valid arguments for analyze schema are described in the following table:

Example

yb-voyager analyze-schema --export-dir /path/to/yb/export/dir --output-format txt

export data

Dump the source database to the machine where yb-voyager is installed.

Syntax

yb-voyager export data [ <arguments> ... ]

The valid arguments for export data are described in the following table:

Example

yb-voyager export data --export-dir /path/to/yb/export/dir \
        --source-db-type sourceDB \
        --source-db-host hostname \
        --source-db-port port \
        --source-db-user username \
        --source-db-password password \ # Enclose the password in single quotes if it contains special characters.
        --source-db-name dbname \
        --source-db-schema schemaName # Not applicable for MySQL

export data status

Get the status report of an ongoing or completed data export operation.

Syntax

yb-voyager export data status [ <arguments> ... ]

The valid arguments for export data status are described in the following table:

Example

yb-voyager export data status --export-dir /path/to/yb/export/dir

import schema

Import the schema to the target YugabyteDB.

During migration, run the import schema command twice, first without the --post-import-data argument and then with the argument. The second invocation creates indexes and triggers in the target schema, and must be done after import data is complete.

Syntax

yb-voyager import schema [ <arguments> ... ]

The valid arguments for import schema are described in the following table:

Example

yb-voyager import schema --export-dir /path/to/yb/export/dir \
        --target-db-host hostname \
        --target-db-user username \
        --target-db-password password \ # Enclose the password in single quotes if it contains special characters.
        --target-db-name dbname \
        --target-db-schema schemaName # MySQL and Oracle only

import data

Import the data to the target YugabyteDB.

Syntax

yb-voyager import data [ <arguments> ... ]

The valid arguments for import data are described in the following table:

Example

yb-voyager import data --export-dir /path/to/yb/export/dir \
        --target-db-host hostname \
        --target-db-user username \
        --target-db-password password \ # Enclose the password in single quotes if it contains special characters.
        --target-db-name dbname \
        --target-db-schema schemaName \ # MySQL and Oracle only
        --parallel-jobs connectionCount

import data file

Load all your data files in CSV or text format directly to the target YugabyteDB. These data files can be located either on a local filesystem or an AWS S3 bucket.

Syntax

yb-voyager import data file [ <arguments> ... ]

The valid arguments for import data file are described in the following table:

Example

yb-voyager import data file --export-dir /path/to/yb/export/dir \
        --target-db-host hostname \
        --target-db-port port \
        --target-db-user username \
        --target-db-password password \ # Enclose the password in single quotes if it contains special characters.
        --target-db-name dbname \
        --target-db-schema schemaName \ # MySQL and Oracle only
        --data-dir "/path/to/files/dir/" \
        --file-table-map "filename1:table1,filename2:table2" \
        --delimiter "|" \
        --has-header \
        --file-opts "escape_char=\",quote_char=\"" \
        --format format

import data status

Get the status report of an ongoing or completed data import operation. The report contains migration status of tables, number of rows or bytes imported, and percentage completion.

Syntax

yb-voyager import data status [ <arguments> ... ]

The valid arguments for import data status are described in the following table:

Example

yb-voyager import data status --export-dir /path/to/yb/export/dir

Arguments

--export-dir

Specifies the path to the directory containing the data files to export.

An export directory is a workspace used by yb-voyager to store the following:

• exported schema DDL files
• export data files
• migration state
• log file

--source-db-type

Specifies the source database type (postgresql, mysql, or oracle).

--source-db-host

Specifies the domain name or IP address of the machine on which the source database server is running.

--source-db-port

Specifies the port number of the machine on which the source database server is running.

Default: 5432 (PostgreSQL), 3306 (MySQL), and 1521 (Oracle)

--source-db-user

Specifies the username of the source database.

--source-db-password

Specifies the password of the source database.

If you don't provide a password via the CLI during any migration phase, yb-voyager will prompt you at runtime for a password.

If the password contains special characters that are interpreted by the shell (for example, # and $), enclose it in single quotes.

--source-db-name

Specifies the name of the source database.

--source-db-schema

Specifies the schema of the source database. Not applicable for MySQL.

For Oracle, you can specify only one schema name using this option.

For PostgreSQL, you can specify a list of comma-separated schema names.

Case-sensitive schema names are not yet supported. Refer to Import issue with case-sensitive schema names for more details.

--output-format

Specifies the format in which the report file is generated. It can be in html, txt, json, or xml.

--target-db-host

Specifies the domain name or IP address of the machine on which target database server is running.

--target-db-port

Specifies the port number of the machine on which the target database server is running.

Default: 5433

--target-db-user

Specifies the username in the target database to be used for the migration.

--target-db-password

Specifies the password for the target database user to be used for the migration.

If you don't provide a password via the CLI during any migration phase, yb-voyager will prompt you at runtime for a password.

If the password contains special characters that are interpreted by the shell (for example, # and $), enclose the password in single quotes.

--target-db-name

Specifies the name of the target database.

Default: yugabyte

--target-db-schema

Specifies the schema of the target database. MySQL and Oracle migrations only.

--parallel-jobs

For export data

Specifies the number of tables to be exported in parallel from the source database at a time.

Default: 4; exports 4 tables at a time by default.

If you use BETA_FAST_DATA_EXPORT to accelerate data export, yb-voyager exports only one table at a time and the --parallel-jobs argument is ignored.

For import data

Specifies the number of parallel COPY commands issued to the target database.

Depending on the target YugabyteDB configuration, the value of --parallel-jobs should be tweaked such that at most 50% of target cores are utilised.

Default: If yb-voyager can determine the total number of cores N in the target YugabyteDB cluster, it uses N/2 as the default. Otherwise, it defaults to twice the number of nodes in the cluster.

--batch-size

Specifies the size of batches generated for ingestion during import data.

Default: 20,000

--data-dir

Path to the directory containing the data files to import. You can also provide an AWS S3 bucket as a path to the data directory. For example,

yb-voyager import data file .... \
--data-dir s3://voyager-data

The authentication mechanism for accessing an S3 bucket using yb-voyager is the same as that used by the AWS CLI.

Refer to Configuring the AWS CLI for additional details to set up your S3 bucket.

--file-table-map

Comma-separated mapping between the files in data-dir to the corresponding table in the database.

Default: If this flag isn't used, the import data file command imports files from the --data-dir directory matching the PREFIX_data.csv pattern, where PREFIX is the name of the table into which the file data is imported.

Example : filename1:tablename1,filename2:tablename2[,...]

--delimiter

Default: comma (,); can be changed to '\t' (tab), pipe(|), or any other character.

--has-header

This argument is to be specified only for CSV file type.

Default: false; change to true if the CSV file contains column names as a header.

Note: Boolean flags take arguments in the format --flag-name=[true|false], and not --flag-name [true|false].

--file-opts

Comma-separated string options for CSV file format. The options can include the following:

• escape_char: escape character

• quote_char: character used to quote the values

Default: double quotes (") for both escape and quote characters

Note that escape_char and quote_char are only valid and required for CSV file format.

Example: --file-opts "escape_char=\",quote_char=\"" or --file-opts 'escape_char=",quote_char="'

--null-string

String that represents null value in the data file.

Default: ""(empty string) for CSV, and '\N' for text.

--format

Specifies the format of your data file with CSV or text as the supported formats.

Default: CSV

--post-import-data

Run this argument with import schema command to import indexes and triggers in the target YugabyteDB database after data import is complete. The --post-import-data argument assumes that data import is already done and imports only indexes and triggers in the target YugabyteDB database.

--oracle-db-sid

Oracle System Identifier (SID) you can use while exporting data from Oracle instances. Oracle migrations only.

--oracle-home

Path to set $ORACLE_HOME environment variable. tnsnames.ora is found in $ORACLE_HOME/network/admin. Not applicable during import phases or analyze schema. Oracle migrations only.

--use-orafce

Enable using orafce extension in export schema. Oracle migrations only.

Default: true

--yes

By default, answer yes to all questions during migration.

--start-clean

Cleans the data directories for already existing files and is applicable during all phases of migration, except analyze-schema. For the export phase, this implies cleaning the schema or data directories depending on the current phase of migration. For the import phase, it implies cleaning the contents of the target YugabyteDB database.

--table-list

Comma-separated list of the tables for which data needs to be migrated. Do not use in conjunction with --exclude-table-list.

--exclude-table-list

Comma-separated list of tables to exclude while migrating data.

--send-diagnostics

Controls whether to send diagnostics information to Yugabyte.

Default: true

--verbose

Displays extra information in the output.

Default: false

--disable-pb

Use this argument to not display progress bars.

Default: false

SSL Connectivity

You can instruct yb-voyager to connect to the source or target database over an SSL connection. Connecting securely to PostgreSQL, MySQL, and YugabyteDB requires you to pass a similar set of arguments to yb-voyager. Oracle requires a different set of arguments.

Note that the SSL arguments are unsupported with BETA_FAST_DATA_EXPORT.

The following table summarizes the arguments and options you can pass to yb-voyager to establish an SSL connection.