Quick start

Get started with YugabyteDB Voyager migration in minutes

This quick start guide describes the steps to perform an offline migration of a PostgreSQL database to YugabyteDB using YugabyteDB Voyager with your target database in YugabyteDB Aeon.

Prerequisites

Before you start, ensure that you have the following:

  • Java 17 installed
  • 2+ CPU cores and 4GB+ RAM
  • Network access to both source and target databases
  • Sudo access on the machine where you'll run Voyager
  • A PostgreSQL database to migrate (source)

Create a YugabyteDB Aeon cluster

  1. Sign up for YugabyteDB Aeon.

  2. Create a cluster:

    • Log in to your YugabyteDB Aeon account.
    • Click Create a Free cluster on the welcome screen, or click Add Cluster on the Clusters page to open the Create Cluster wizard.
    • Select Sandbox for testing or Dedicated for production.
    • Enter a cluster name, choose your cloud provider (AWS or GCP) and region in which to deploy the cluster, then click Next.
    • Click Add Current IP Address to allow connections from your machine, and click Next.
    • Click Download credentials. The default credentials are for a database user named "admin". You'll use these credentials when connecting to your YugabyteDB database.
    • Click Create Cluster.

Install YugabyteDB Voyager

Install YugabyteDB Voyager on your machine as follows:

  1. In your YugabyteDB Aeon cluster page, click Migrations, and select Migrate Database.
  2. In Prepare Voyager, choose your operating system, run the installation commands on your machine, and verify the installation.

Prepare source and target databases

Prepare source PostgreSQL database

Create a database user and provide the user with READ access to all the resources which need to be migrated. Run the following commands in a psql session:

  1. Create a new user named ybvoyager.

    CREATE USER ybvoyager PASSWORD 'password';

  2. Grant permissions for migration. Use the yb-voyager-pg-grant-migration-permissions.sql script (in /opt/yb-voyager/guardrails-scripts/ or, for brew, check in $(brew --cellar)/yb-voyager@<voyagerversion>/<voyagerversion>) to grant the required permissions as follows:

    psql -h <host> \
     -d <database> \
     -U <username> \ # A superuser or a privileged user with enough permissions to grant privileges
     -v voyager_user='ybvoyager' \
     -v schema_list='<comma_separated_schema_list>' \
     -v is_live_migration=0 \
     -v is_live_migration_fall_back=0 \
     -f <path_to_the_script>

    The ybvoyager user can now be used for migration.

Prepare target YugabyteDB Aeon database

  1. Connect to your YugabyteDB Aeon cluster via Cloud shell.

  2. In the ysqlsh prompt, create a target database (optional - you can use the default yugabyte database):

    -- Connect to your YugabyteDB Aeon cluster
psql -h <your-cluster-host> -p 5433 -U admin -d yugabyte

-- Create target database
CREATE DATABASE target_db;

  3. Create a user with yb_superuser role using the following commands:

    CREATE USER ybvoyager PASSWORD 'password';
GRANT yb_superuser TO ybvoyager;

  4. Create an API key to enable authentication.

  5. Download SSL certificates to have Voyager connect to the target YugabyteDB database over SSL.

Create an export directory and configuration file for Voyager

  1. Create an export directory for yb-voyager as follows:

    mkdir -p $HOME/<migration-name>/export-dir

  2. Copy the offline configuration template file to the export directory:

    cp /opt/yb-voyager/config-templates/offline-migration.yaml export-dir/migration-config.yaml

  3. Edit the configuration file migration-config.yaml to include only the export-dir, source, and target arguments:

    # Global settings
export-dir: <absolute-path-to-export-dir>

# Source database (PostgreSQL)
source:
  db-type: postgresql
  db-host: <your-postgresql-host>
  db-port: 5432
  db-name: <your-source-database>
  db-schema: public
  db-user: ybvoyager
  db-password: 'your_postgresql_password'

# Target database (YugabyteDB Aeon)
target:
  db-host: <your-cluster-host>
  db-port: 5433
  db-name: target_db
  db-user: ybvoyager
  db-password: 'your_yugabytedb_password'
  ssl-mode: require
  ssl-cert: /path/to/yugabyte.crt
  ssl-key: /path/to/yugabyte.key
  ssl-root-cert: /path/to/ca.crt

Run migration assessment

Execute the migration assessment to get recommendations:

yb-voyager assess-migration --config-file migration-config.yaml

The assess-migration command generates a detailed assessment report with:

  • Schema complexity analysis
  • Data distribution recommendations
  • Cluster sizing suggestions
  • Performance optimization tips

Review and address assessment recommendations

  1. Review the assessment report:

    • The report is saved in your export directory
    • Open the HTML report in your browser - Review recommendations for your specific workload

  2. Address recommendations in YugabyteDB Aeon:

    • If the assessment suggests cluster resizing, adjust your cluster in Aeon
    • Enable any recommended features in your cluster settings
    • Note any schema changes recommended for optimal performance

Migrate to a YugabyteDB Aeon cluster

Proceed with schema and data migration using the following steps:

Export schema

Export the schema from the source database:

yb-voyager export schema --config-file migration-config.yaml

Analyze schema

  1. Analyze the PostgreSQL schema dumped in the export schema step:

    yb-voyager analyze-schema --config-file migration-config.yaml

  2. Review schema analysis report in YugabyteDB Aeon:

    • Open the generated HTML report
    • Review any manual changes recommended
    • Make necessary modifications to the exported schema files if needed

Import schema

Import the schema to your target YugabyteDB Aeon cluster:

yb-voyager import schema --config-file migration-config.yaml

Export data

Export data from source:

yb-voyager export data --config-file migration-config.yaml

Import data

  1. Import data to target:

    yb-voyager import data --config-file migration-config.yaml

  2. Monitor import progress:

    yb-voyager import data status --config-file migration-config.yaml

  3. Finalize schema (if needed):

    yb-voyager finalize-schema-post-data-import --config-file migration-config.yaml

Review import status in YugabyteDB Aeon

  1. In your YugabyteDB Aeon cluster page, click the Migrations tab.
  2. Review the import data status report and verify that all tables and data have been imported successfully

Validate migration

  1. Connect to your target YugabyteDB Aeon cluster via Cloud shell.

  2. In the ysqlsh prompt, connect to your target database:

     psql -h <your-cluster-host> -p 5433 -U ybvoyager -d target_db

  3. Verify data integrity:

    -- Check table count
SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public';

-- Verify row counts for key tables
SELECT COUNT(*) FROM your_table_name;

-- Sample data verification
SELECT * FROM your_table_name LIMIT 10;

  4. Test application connectivity:

    • Update your application connection strings
    • Test basic CRUD operations
    • Verify application functionality

End migration

Complete the migration as follows:

yb-voyager end migration --config-file migration-config.yaml \
  --backup-schema-files true \
  --backup-data-files true \
  --backup-log-files true \
  --save-migration-reports true

What's next?

Additional resources