Install
Prerequisites
The following sections describe the prerequisites for installing YugabyteDB Voyager.
Operating system
You can install YugabyteDB Voyager on the following:
- RHEL 7/8
- CentOS 7/8
- Ubuntu 18.04, 20.04, 22.04
- macOS (For MySQL/Oracle source databases on macOS, install yb-voyager using the Docker option.)
Hardware requirements
- Disk space of at least 1.5 times the estimated size of the source database
- 2 cores minimum (recommended)
Software requirement
- Java 11 or later. For better performance, the recommended version is Java 17.
Prepare the host
The node where you'll run the yb-voyager command should:
- connect to both the source and the target database.
- have sudo access.
Install yb-voyager
YugabyteDB Voyager consists of the yb-voyager command line executable.
Install yb-voyager on a machine which satisfies the Prerequisites using one of the following options:
Perform the following steps to install yb-voyager using yum for RHEL 7/8 and CentOS 7/8:
-
Update the yum package manager, and all the packages and repositories installed on your machine using the following command:
sudo yum update
-
Install the
yugabyte
yum repository using the following command:sudo yum install https://s3.us-west-2.amazonaws.com/downloads.yugabyte.com/repos/reporpms/yb-yum-repo-1.1-0.noarch.rpm
This repository contains the yb-voyager rpm and other dependencies required to run
yb-voyager
. -
Install the
epel-release
repository using the following command:# For RHEL 7 or CentOS 7 sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
# For RHEL 8 or Centos 8 sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
-
Install the Oracle instant client repositories using the following command:
sudo yum install oracle-instant-clients-repo
-
Install the PostgreSQL repositories using the following command:
# For RHEL 7 sudo yum --disablerepo=* -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# For RHEL 8 sudo yum --disablerepo=* -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
These repositories contain the rest of the dependencies required to run
yb-voyager
.Note that if you're using RHEL 8 or CentOS 8, perform the following two steps before proceeding to step 6.
-
Disable the default
PostgreSQL
yum module on your machine using the following command:sudo dnf -qy module disable postgresql
-
Install
perl-open
on your machine using the following command:sudo yum install perl-open.noarch
-
-
Update the yum package manager and all the packages and repositories installed on your machine using the following command:
sudo yum update
-
Install
yb-voyager
and its dependencies using the following command:sudo yum install yb-voyager
Install a specific version of
yb-voyager
on your machine using the following command:sudo yum install yb-voyager-<VERSION>
-
Check that yb-voyager is installed using the following command:
yb-voyager version
Perform the following steps to install yb-voyager using apt for Ubuntu:
Note
apt
installation is only supported for Ubuntu 22. For other versions such as 18 and 20, use the install script via the Source installation option.
-
Install the Yugabyte apt repository on your machine using the following command:
wget https://s3.us-west-2.amazonaws.com/downloads.yugabyte.com/repos/reporpms/yb-apt-repo_1.0.0_all.deb sudo apt-get install ./yb-apt-repo_1.0.0_all.deb
This repository contains the
yb-voyager
debian package and the dependencies required to runyb-voyager
. -
Clean the
apt-get
cache and package lists using the following commands::sudo apt-get clean sudo apt-get update
-
Install yb-voyager and its dependencies using the following command:
sudo apt-get install yb-voyager
-
Check that yb-voyager is installed using the following command:
yb-voyager version
Note on migrating from MySQL/Oracle on macOS
To migrate from MySQL/Oracle source databases on macOS to YugabyteDB, install yb-voyager using docker-based instructions.Perform the following steps to install yb-voyager using brew for macOS:
-
Tap the
yugabyte
Homebrew repository using the following command:brew tap yugabyte/tap
The repository contains the formula to build and install
yb-voyager
on your macOS device.Note that the tap
yugabyte/yugabytedb
has been updated toyugabyte/tap
. If you have previously installed yb-voyager using the tapyugabyte/yugabytedb
, untap the entry usingbrew untap yugabyte/yugabytedb
, and then tap using the preceding command. -
Install
yb-voyager
and its dependencies using the following command:brew install yb-voyager
Install a specific version of
yb-voyager
using the following command:brew install yb-voyager@<VERSION>
-
Check that yb-voyager is installed using the following command:
yb-voyager version
You can perform an airgapped installation on RHEL 7/8 and CentOS 7/8.
Install yb-voyager using a Docker image in an airgapped environment using the following steps:
-
From a machine connected to the internet, run the following commands to pull and save the latest yb-voyager docker image (Pull the version from docker.io):
docker pull yugabytedb/yb-voyager docker save -o yb-voyager-image.tar yugabytedb/yb-voyager:latest gzip yb-voyager-image.tar
-
Download the yb-voyager wrapper script on the same machine using the following command:
wget -O ./yb-voyager https://raw.githubusercontent.com/yugabyte/yb-voyager/main/docker/yb-voyager-docker
-
Copy the
yb-voyager-image.tar.gz
andyb-voyager
files to the airgapped machine. -
Load the docker image using the following command:
gunzip yb-voyager-image.tar.gz docker load --input yb-voyager-image.tar
-
Make the wrapper script executable and move it to the
bin
directory using the following commands:chmod +x yb-voyager sudo mv yb-voyager /usr/local/bin
-
Check that yb-voyager is installed using the following command:
yb-voyager version
Package dependencies
To resolve package dependencies, yum takes into account the list of packages (and their versions) already installed on a machine.
For yum to download all the required dependencies, ensure that the list of all packages (and their versions) already installed on the airgapped machine and the connected machine are exactly the same. For example, it will not work if you prepare the installer bundle on RHEL 7.5 and try to install it on RHEL 7.2.
-
Download rpm files for
yb-voyager
and its dependencies on a machine with internet connection using the following steps:-
Install the
yugabyte
yum repository on your machine using the following command:sudo yum install https://s3.us-west-2.amazonaws.com/downloads.yugabyte.com/repos/reporpms/yb-yum-repo-1.1-0.noarch.rpm
This repository contains the yb-voyager rpm and other dependencies required to run
yb-voyager
. -
Install the
epel-release
repository using the following command:# For RHEL 7 or CentOS 7 sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
# For RHEL 8 or CentOS 8 sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
-
Install the Oracle instant client repositories using the following command:
sudo yum install oracle-instant-clients-repo
-
Install the PostgreSQL repositories using the following command:
# For RHEL 7 sudo yum --disablerepo=* -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# For RHEL 8 sudo yum --disablerepo=* -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
These repositories contain the rest of the dependencies required to run
yb-voyager
. -
If you're using RHEL 8 or CentOS 8, do the following:
-
Disable the default
PostgreSQL
yum module on your machine using the following command:sudo dnf -qy module disable postgresql
-
Download rpm files for
perl-open
on your machine using the following command:sudo yum install --downloadonly --downloaddir=<path_to_directory> perl-open.noarch
-
-
Download the rpm files for
yb-voyager
and its dependencies using the following command:sudo yum install --downloadonly --downloaddir=<path_to_directory> yb-voyager
-
-
Transfer the downloaded files to your airgapped machine.
-
Navigate to the folder containing all the files and install the rpm files using the following command:
sudo yum --disablerepo=* install *
-
Check that yb-voyager is installed using the following command:
yb-voyager version
Before installing yb-voyager, ensure that you have the Docker runtime installed on your machine.
-
Pull the docker image from YugabyteDB's docker hub (Pull the version from docker.io) as follows:
docker pull yugabytedb/yb-voyager
-
Download the script to run yb-voyager using the docker image from yb-voyager's GitHub repository, and move it to your machine's bin directory using the following commands:
wget -O ./yb-voyager https://raw.githubusercontent.com/yugabyte/yb-voyager/main/docker/yb-voyager-docker && chmod +x ./yb-voyager && sudo mv yb-voyager /usr/local/bin/yb-voyager
Use yb-voyager docker script withoutsudo
to run Voyager commands. -
Check that yb-voyager is installed using the following command:
yb-voyager version
Perform the following steps to install yb_voyager
using an installer script:
-
Clone the yb-voyager repository.
git clone https://github.com/yugabyte/yb-voyager.git
-
Change the directory to
yb-voyager/installer_scripts
.cd yb-voyager/installer_scripts
-
Install yb-voyager using the following script:
./install-yb-voyager
It is safe to execute the script multiple times. If the script fails, check the
/tmp/install-yb-voyager.log
file. -
The script generates a
.yb-voyager.rc
file in the home directory. Source the file to ensure that the environment variables are set using the following command:source ~/.yb-voyager.rc
-
Check that yb-voyager is installed using the following command:
yb-voyager version
Collect diagnostics
By default, yb-voyager captures a diagnostics report using the YugabyteDB diagnostics service that runs each time you use the yb-voyager command. If you don't want to send diagnostics when you run yb-voyager, set the --send-diagnostics flag to false.