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 run yb-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
```
Note: If you see a failure in the install step similar to the following:
```
Depends: ora2pg (= 23.2-yb.2) but 24.3-1.pgdg22.04+1 is to be installed
```
Try installing ora2pg using the following command:
```
sudo apt-get install ora2pg=23.2-yb.2
```
And then, try installing yb-voyager 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 to yugabyte/tap. If you have previously installed yb-voyager using the tap yugabyte/yugabytedb, untap the entry using brew 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 and yb-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 without sudo 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.

Next step

Migrate