docs/content/stable/yugabyte-voyager/release-notes.md
What follows are the release notes for the YugabyteDB Voyager v1 release series. Content will be added as new notable features and changes are available in the patch releases of the YugabyteDB v1 series.
Voyager releases (starting with v2025.5.2) use the numbering format YYYY.M.N, where YYYY is the release year, M is the month, and N is the number of the release in that month.
Improved the archive changes command for live migration fallback workflows with multiple iterations. When run from the parent migration export directory, the command now continues archiving change segments across all iterations.
Improved import data error reporting when a batch fails with unique-constraint (SQLSTATE 23505) or foreign-key (SQLSTATE 23503) errors. Voyager now classifies these failures and suggests a more appropriate next step (for example, distinguishing primary-key conflicts, other unique violations, and foreign-key failures that often relate to permissions such as session_replication_role) instead of defaulting to generic error reporting.
{{< note title="Important: Breaking change" >}}
This release includes breaking changes for Voyager migrations. Migrations started with earlier Voyager versions cannot be continued with this version. To proceed, either continue the migration using the same Voyager version you started with, or start a new migration using v2026.3.3.
{{< /note >}}
Improved the archive changes command configuration options with explicit policies and flags. You must set the --policy flag to delete or archive. For archive, set the --archive-dir flag to the directory where processed change segments are copied before the originals are removed.
The export-data processing step of the cutover process is resumable. If export-data fails before cutover is marked as processed, it can be retried by re-running the command.
import-data.assess-migration with --assessment-metadata-dir for offline assessments that do not require source database connectivity.import-schema to only appear when the assessment has recommended colocated tables, rather than whenever the target database is non-colocated.--adaptive-parallelism-max from total N/2 to N total cores. This change enables better CPU utilization during data migration, with improved core detection for load-balanced and managed clusters.export schema could hang while fetching redundant index information during schema export.use-yb-grpc-connector parameter in configuration templates from true to false.{{< note title="Important: Breaking change" >}}
This release includes breaking changes for Voyager migrations. Migrations started with earlier Voyager versions cannot be continued with this version. To proceed, either continue the migration using the same Voyager version you started with, or start a new migration using v2026.2.1.
{{< /note >}}
"pg-schema", "Schema") are now correctly handled in all migration workflows: assessment, export schema, export data, live migration, and also the grant-migration-permissions script. The --source-db-schema or schema_list parameter accepts schema names with or without quotes. Quoted names are preserved and matched correctly.--start-clean flag if the assess-migration command was skipped. This ensures metadata remains in sync after a clean start and avoids stale assessment data.Improved assessment validation. When replica endpoints are provided during a migration assessment, Voyager now validates that they belong to the same cluster as the primary by comparing the system identifier. Misconfigurations are detected and flagged early in the migration process.
When importing snapshot data to the target YugabyteDB cluster, import-data now schedules sharded table imports in descending order of size (as opposed to a random order). This ensures that the import of larger tables starts sooner, avoiding the scenario where the largest tables are imported towards the end, which can cause an uneven load on the cluster and become a bottleneck during snapshot import.
Fixed an issue in live migration (fall-back or fall-forward) where INTERVAL columns were not being handled correctly during value conversion, causing import-data to error out.
Fixed an issue in live migration where prepared statement name collisions occurred when schema or table identifiers exceeded PostgreSQL's 63 character limit. The fix ensures distinct statement names are generated for different tables and operations, even those with long identifiers.
--primary-only flag to the assess-migration command for PostgreSQL sources. When specified, the assessment skips read replica discovery and assessment, allowing you to assess only the primary database.2025.2.0.0.{{< note title="Important: Breaking change" >}}
This release introduces breaking changes for Voyager migrations. Migrations started with previous Voyager versions cannot continue with this version. To proceed, either continue the migration using an older Voyager version, or restart the migration using the new version.
{{< /note >}}
When importing data to YugabyteDB, batches are now ingested in random order. This helps avoid hotspots and ensures writes are distributed uniformly across cluster nodes, particularly when importing sequentially-ordered data into range-sharded tables.
Auto-discovery of read replicas during assessment. When assessing the migration for PostgreSQL databases, physical read replicas are automatically detected and incorporated into the various aspects of assessment (sizing, detecting incompatibilities in queries, detecting object usage when reporting performance issues, comparing performance, and so on).
Aggregate query statistics from all source nodes. The compare-performance command now aggregates query statistics from all source database nodes (primary and replicas) when PostgreSQL read replicas are used. This provides a more comprehensive and accurate workload performance comparison by merging execution counts, total execution times, and preserving minimum or maximum execution times across all nodes.
--source-read-replica-endpoints argument. This provides a more comprehensive and accurate workload assessment by aggregating metrics across both primary and replica nodes.Added an Object Usage column in the Performance optimization section of the assessment report to categorize objects involved in optimizations as FREQUENT, MODERATE, RARE, or UNUSED based on workload usage.
Optimized per-table queries involved in startup (for export data from target) and post-processing (for import data to target), cutting database round trips from N (number of tables) to 1, reducing cutover-to-target time.
The YugabyteDB Logical Replication Connector is now the default for cutover to target in fall-forward and fall-back workflows. Set --use-yb-grpc-connector=true to use the gRPC connector instead.
Removed unsupported datatype issues for hstore, tsvector, and array of enum datatypes from the assessment report, as these are now supported with the default YugabyteDB Logical Replication Connector.
Enhanced export schema console output with improved UI/UX, including color-coded messages.
Improved performance of sizing calculations in assess-migration.
assess-migration was not fetching read IOPS for tables without an index or primary key.tsvector, array of ENUMs when the YugabyteDB Connector is used in export-data-from-target in the fall-forward/fall-back workflows of live migration.--allow-oracle-clob-data-export flag for the support of CLOB datatype export.--start-clean flag, after creating missing tables following guardrail failures.pg_stat_statements having zero calls.{{<tags/feature/tp>}} Added the ability to analyze, compare, and summarize workload query performance between the source database and the target YugabyteDB database using the compare-performance command. The command generates both HTML and JSON reports for easy query comparison.
Note that this feature is supported for YugabyteDB release {{<release "2025.1">}} and later.
pgx driver identifies as non‑retryable, enhancing stability.--adaptive-parallelism flag. Options include disabled, balanced (default), or aggressive. Replaces the --enable-adaptive-parallelism flag.--output-format flag to the export data status, import data status, and get data-migration-report commands to generate structured JSON reports. end migration now saves the JSON versions of these reports as well.failed to prepare table to column.import data command.Enhanced primary key recommendation logic to consider both unique constraints and unique indexes when suggesting primary keys, and added support for generating recommendations for partitioned tables that don't have primary keys.
Enhanced assessment report:
Added console messages to show resumption progress when importing from large files, keeping users informed during long resumption processes.
Introduced a flag --max-retries-streaming in the import data commands to configure the number of retries for the streaming phase in live migration.
The assessment report now includes primary key recommendations for tables having no primary key but with UNIQUE NOT NULL columns, improving schema optimization guidance.
Improved the estimated time for import calculations in the assessment report by additionally estimating the time without considering redundant indexes, which are now automatically excluded in the export schema step.
End migration now backs up the schema optimization report produced by export schema.
Modified flag names in export schema from "skip-performance-optimizations" to "skip-performance-recommendations" and from "skip-recommendations" to "skip-colocation-recommendations" for consistency and clarity.
--allow-oracle-clob-data-export flag for the export data command, to enable exporting data from CLOB datatype columns in Oracle offline migrations.assess-migration by factoring in throughput gains based on the recommended number of nodes for more accurate import time estimation.assess-migration report as export schema now automatically removes redundant indexes.export schema to list all recommendations, whether they are applied or skipped, even when the --skip-performance-recommendations / --skip-colocation-recommendations flags are used.--skip-performance-recommendations flag in the export schema command to true.import data and import-data-file commands by using the flags error-policy-snapshot or error-policy.import data by increasing the max CPU threshold for adaptive parallelism to 80.assess-migration command to honor auto‑analyze settings and gracefully handle user prompts.end migration when the database configuration is not set, preventing unexpected errors during migration processes.import data with --on-primary-key-conflict ignore failed if import to source replica started earlier.Introduced the --on-primary-key-conflict flag for the import data to target and import data file command, supporting two modes:
assess-migration is aborted via a prompt, eliminating the need to rerun with --start-clean.export data from source and export data from target commands to prevent multiple internal processes from running concurrently in cases where a previous run may have left an orphaned process.DEFAULT CURRENT_TIMESTAMP AT TIME ZONE clauses were generated with a syntax error during export schema.assess-migration command that caused it to fail with an error in scenarios where the source database had a column of an array of any unsupported YugabyteDB datatype.import-data command for a live migration scenario that prevented resuming import-data if a failure occurred after cutover was initiated.int32 range).Added support for the YugabyteDB Connector in live migration with fall-forward and fall-back workflows. The cutover to target command now includes a mandatory flag to specify whether to use YugabyteDB gRPC Connector or YugabyteDB Connector for these workflows.
This is required for YugabyteDB Aeon or restricted environments where only the YugabyteDB Connector is supported.
CONTROL_PLANE_TYPE is provided, avoiding stack traces on the console.ALLOW was supported but incorrectly flagged as invalid by import commands.yb-voyager.export schema without first running assess-migration, Voyager will now automatically run assess the migration before exporting the schema for PostgreSQL source databases.BOOLEAN or ENUM)NULL valuesimport-data command now monitors replication (CDC/xCluster) only for the target database specified in the migration. This avoids false positives caused by replication streams on other databases.BIT VARYING columns were incorrectly omitted during live migration.finalize-schema-post-data-import
This command is used to re-add NOT VALID constraints and refresh materialized views after import, and replaces the use of import schema with the --post-snapshot-import true and --refresh-mviews flags; both of these flags are now deprecated in import schema.target-db-version specified during the assess-migration command.Parallel jobs recommendations as the Adaptive Parallelism feature now dynamically adjusts parallelism based on cluster load.assess-migration command now features a cleaner, more user-friendly design for better readability and usability.--skip-replication-checks flag.--continue-on-error and ignore-exist flags.yb-voyager-pg-grant-migration-permissions.sql script for live migrations to notify users about the change in table ownership.--pg-only, --oracle-only, and --mysql-only flags to the airgapped installation script to check/install dependencies for a specific database.yb-voyager-pg-grant-migration-permissions.sql.import data resumption process to correctly recognize an earlier initiated cutover to target .export data from source / export data from target for live migration workflow when the tables that are not being migrated and existed in only one of the source or target databases.end-migration where deleting the CDC stream ID on the target failed if the ssl-root-cert was only provided during export data from target phase.iops-capture-interval flag in the assess-migration command did not honor the user-defined value and always defaulted to its preset.seq_tup_read for read statistics.session_replication_role to source-db-user. This eliminates the need for you to disable Foreign Keys and triggers on the source database before running import-data-to-source.gcc on the client machine running yb-voyager.hstore datatype in live migration from source PostgreSQL was failing with errors and causing panics during the import-data step.import schema where SQL bodies in FUNCTION DDL statements were not being parsed correctly.import data command, where the command fails with error failed to connect to target-host server error (FATAL: password authentication failed for user (SQLSTATE 28P01).--target-db-version. The default is the latest stable release (currently {{<yb-version version="stable">}}).pg_stat_statements that belong to the schemas provided by the user will be processed for detecting and reporting issues.import data file and import data to source replica now accept a new flag truncate-tables (in addition to import data), which, when used with start-clean true, truncates all the tables in the target/source-replica database before importing data into the tables.pg_stat_statements is not loaded via shared_preloaded_libraries.analyze-schema and import data when export-dir is empty.assess-migration and analyze-schema commands to accept the target database version (--target-db-version flag) as input and use it for reporting issues not supported in that target version for the source schema.yb-voyager-pg-grant-migration-permissions.sql) by internally detecting table owners, eliminating the need to specify the original_owner_of_tables flag.assess-migration command by filtering queries to include only those that match user-specified schemas, provided schema information is present in the query.assess-migration and analyze-schema commands to report issues in Functions or Procedures for variables declared with reference types (%TYPE) in the "Unsupported PL/pgSQL Objects" section.assess-migration and analyze-schema commands.assess-migration command to verify that the pg_stat_statements extension is properly loaded in the source database.--table-list and --exclude-table-list in guardrails now checks for PostgreSQL export to determine which tables require permission checks.schema_list and if the migration user has access to queries in the pg_stat_statements view. This is part of the guardrails for assess-migration for PostgreSQL.--version flag in the voyager installer script, which can be used to specify the version to install.XMLTABLE() function under unsupported query constructs.yb-voyager-pg-grant-migration-permissions.sql) and new checks are added for replication slots, foreign keys, and triggers in PostgreSQL guardrails.REPORT_UNSUPPORTED_QUERY_CONSTRUCTS=false, which disables the "Unsupported Query Constructs" feature and proceeds with the command execution.Adaptive parallelism. Introduced the ability to dynamically adjust the number of parallel jobs in the import data command based on real-time CPU and memory use of the YugabyteDB cluster. This prevents resource under- and over-utilization, optimizes import speeds, and enhances efficiency. It also ensures stability across both snapshot and live migration phases without the need for manual intervention. Available in YugabyteDB versions {{<release "2.20.8.0">}}, v2024.1.4.0, v2024.2.0.0, or later.
Detect unsupported query constructs. The assess-migration command can now detect and report SQL queries containing unsupported features and constructs, such as advisory locks, system columns, and XML functions. This helps identify potential issues early in the migration process.
Guardrails for YugabyteDB Voyager commands. Added checks to validate source/target database permissions, verify binary dependencies, and check database version compatibility for PostgreSQL in all yb-voyager commands. This feature is currently disabled by default; to enable it, use the --run-guardrails-checks flag during assess-migration, export data, and import data phases.
import data file commands to ensure batches created from data files don't exceed the default batch size limit (200MB), preventing "RPC message too long" errors with large rows. Also, added an immediate check to error out for single row size over 200MB.analyze-schema where partitioned tables were incorrectly reported as having insufficient columns in the primary key constraint due to a regex misidentifying the CONSTRAINT clause before primary key definition.assess-migration and analyze-schema reports, and renamed the INDEX, TRIGGER, and POLICY objects by appending the table name to the objects for unique identification (using the format <object_name> ON <table_name>).The assess-migration and analyze schema commands now report issues with indexes on UDT columns under the Index on complex data types PostgreSQL unsupported feature.
Improved logic for cluster sizing recommendations in assessment reports:
The analyze-schema command now generates both HTML and JSON format reports by default unless the output-format flag is used, in which case only the specified format will be generated.
Voyager's diagnostic service (callhome) now uses a secure port for enhanced data security.
The installer script now installs the jq package on all supported operating systems and verifies that the installed Java version is between 17 and 19 (inclusive).
ALTER TABLE CLUSTER ON.assess-migration-bulk) for Oracle which allows you to assess multiple schemas in one or more database instances simultaneously.failed.sql file for all failed SQL statements in import schema.export-dir is not provided.pg_sequences table was not found.In all migration workflows, indexes and triggers will now be imported to the target YugabyteDB by default during the import-schema step, as opposed to import-schema --post-snapshot-import true. This is because experiments have shown that pre-creating indexes and then importing data is faster than importing data and then backfilling the indexes.
Modified and enhanced the call-home diagnostic functionality. More details are collected, such as source database size, migration type (offline/live), assessment report details (unsupported features/datatypes, source index/table statistics, and so on). Furthermore, call-home diagnostic details are also sent in bulk data import and live migration workflows.
More details are being sent to yugabyted control plane from voyager. For example, source database size details (such as total database size, total index size, total table size, total table row count), assessment report target recommendations (total colocated size, total sharded size), analyze-schema issues, and so on.
Enhanced the cluster sizing recommendation logic in the assessment report:
Optimized execution time of get data-migration-report by 90% for large databases.
import-schema --continue-on-error true could miss listing certain failed statements in failed.sql.--table-list argument.DATE:date to DATE:timestamp in Oracle to avoid time data loss for such columns.The live migration workflow has been optimized for Importing indexes and triggers on the target YugabyteDB. Instead of creating indexes on target after cutover, they can now be created concurrently with the CDC phase of import-data-to-target. This ensures that the time consuming task of creating indexes on the target YugabyteDB is completed before the cutover process.
The --post-import-data flag of import schema has been renamed to --post-snapshot-import to incorporate live migration workflows.
Enhanced analyze schema to report the unsupported extensions on YugabyteDB.
Improved UX of yb-voyager get data-migration-report for large set of tables by adding pagination.
The YugabyteDB Debezium connector version is upgraded to v1.9.5.y.33.2 to leverage support for precise decimal type handling with YugabyteDB versions 2.20.1.1 and later.
Enhanced export data status command to report number of rows exported for each table in case of offline migration.
Reduced default value of --parallel-jobs for import data to target YugabyteDB to 0.25 of total cores (from 0.5), to improve stability of target YugabyteDB.
Fixed a bug in the CDC phase of import data where parallel ingestion of events with different primary keys having same unique keys was leading to unique constraint errors.
Fixed an issue in yb-voyager initiate cutover to target where fallback intent is stored even if you decide to abort the process in the confirmation prompt.
Fixed an issue in yb-voyager end migration where the source database is not cleaned up if --save-migration-reports flag is set to false.
yb-voyager now gracefully shuts down all child processes on exit, to prevent orphan processes.
Fixed a bug in live migration where "\r\n" in text data was silently converted to "\n". This was affecting snapshot phase of live migration as well as offline migration with BETA_FAST_DATA_EXPORT.
--table-list argument.Live migration
Support for live migration from Oracle databases (with the option of fall-back) {{<tags/feature/tp>}}, using which you can fall back to the original source database if an issue arises during live migration.
Various commands that are used in live migration workflows (including fall-forward) have been modified. YugabyteDB Voyager is transitioning from the use of the term "fall-forward database" to the more preferred "source-replica database" terminology. The following table includes the list of modified commands.
| Old command | New command |
|---|---|
| yb-voyager fall-forward setup ... | yb-voyager import data to source-replica ... |
| yb-voyager fall-forward synchronize ... | yb-voyager export data from target ... |
| yb-voyager fall-forward switchover ... | yb-voyager initiate cutover to source-replica ... |
| yb-voyager cutover initiate ... | yb-voyager initiate cutover to target ... |
A new command yb-voyager get data-migration-report has been added to display table-wise statistics during and post live migration.
End migration
A new command yb-voyager end migration has been added to complete migration by cleaning up metadata on all databases involved in migration, and backing up migration reports, schema, data, and log files.
= while setting boolean flags to false; a white-space would work (just like arguments of other types). As a side effect of this action, you cannot use boolean flag names without any value. For example, use --send-diagnostics true instead of --send-diagnostics. The boolean values can now be specified as true/false, yes/no, 1/0.--table-list can now be provided via a file using the arguments --table-list-file-path or exclude-table-list-file-path. The table-list arguments now support glob wildcard characters ? (matches one character) and * (matches zero or more characters). Furthermore, the table-list and exclude-table-list arguments can be used together in a command, which can be beneficial with glob support.yb-voyager export schema can now be filtered via the arguments --object-type-list or --exclude-object-type-list.table-list argument are now by default, case-insensitive. To make it case-sensitive, enclose each name in double quotes.--verbose argument has been removed from all yb-voyager commands.--delete argument in yb-voyager archive-changes has been renamed to --delete-changes-without-archiving.yb-voyager analyze-schema now provides additional details in the report, indicating indices that don't get exported, such as reverse indexes, which are unsupported in YugabyteDB.Removed redundant ALTER COLUMN DDLs present in the exported schema for certain cases.
Compared to earlier releases, Voyager v1.6 uses a different and incompatible structure to represent the import data state. As a result, Voyager v1.6 can't "continue" a data import operation that was started using Voyager v1.5 or earlier.
If you are using dockerized yb-voyager:
export schema and export data from Oracle database with SSL (via --oracle-tns-alias) fails. Use a non-docker version of yb-voyager to work around this limitation.
end migration command fails. This issue will be addressed in an upcoming release.
Note that as the feature in Tech Preview, there are some known limitations. For details, refer to Live migration limitations, and Live migration with fall-forward limitations.
{{< youtube id="TJX7OlgPyUM" title="YugabyteDB Voyager 1.5 Demo" >}}
pg_dump arguments internally. The arguments are present at /etc/yb-voyager/pg_dump-args.ini. Any additions or modifications to this file will be honoured by yb-voyager.SOURCE_DB_PASSWORD and TARGET_DB_PASSWORD. This addresses the security concern of a password being leaked via the ps command output. In addition, the password will not be present in any configuration or log files on the disk.The import data file command now supports importing multiple files to the same table. Moreover, glob expressions can be provided in the --file-table-map argument to specify multiple files to be imported into the same table.
In addition to AWS S3, import data file now supports directly importing objects (CSV/TEXT files) stored in GCS and Azure Blob Storage. You can specify GCS and Azure Blob Storage "directories" by prefixing them with gs:// and https://.
When using the accelerated data export, Voyager can now connect to the source databases using SSL.
The analyze-schema command now reports unsupported data types.
The --file-opts CLI argument is now deprecated. Use the new --escape-char and --quote-char options.
Fixed the issue where, if a CSV file had empty lines, import data status would continue reporting the import status as MIGRATING even though the import was completed and successful.
yb-voyager now explicitly closes the source/target database connections when exiting.
The import data file command now uses tab (\t) instead of comma (,) as the default delimiter when importing TEXT formatted files.
Export data for MySQL and Oracle is now 2-4x faster. To leverage this performance improvement, set the environment variable BETA_FAST_DATA_EXPORT=1. Most features, such as migrating partitioned tables, sequences, and so on, are supported in this mode. Refer to Export data for more details.
Added support for characters such as backspace(\b) in quote and escape character with --file-opts in import data file.
Added ability to specify null value string in import data file.
During export data, yb-voyager can now explicitly inform you of any unsupported data types, and requests for permission to ignore them.
yb-voyager can now parse CREATE TABLE statements that have complex check constraints.
Import data file with AWS S3 now works when yb-voyager is installed via Docker.
When using the import data file command with the --data-dir option, you can provide an AWS S3 bucket as a path to the data directory.
Added support for rotation of log files in a new logs directory found in export-dir/logs.
import data file command may not recognise the data directory being provided, causing the step to fail for Dockerized yb-voyager.When using the import data file command with CSV files, YB Voyager now supports any character as an escape character and a quote character in the --file-opts flag, such as single quote (') as a quote_char and backslash (\) as an escape_char, and so on. Previously, YB Voyager only supported double quotes (") as a quote character and an escape character.
Creating the Orafce extension on the target database for Oracle migrations is now available by default.
User creation for Oracle no longer requires EXECUTE permissions on PROCEDURE, FUNCTION, PACKAGE, and PACKAGE BODY objects.
The precision and scale of numeric data types from Oracle are migrated to the target database.
For PostgreSQL migrations, YB Voyager no longer uses a password in the pg_dump command running in the background. Instead, the password is internally set as an environment variable to be used by pg_dump.
For any syntax error in the data file or CSV file, complete error details such as line number, column, and data are displayed in the output of the import data or import data file commands.
For the export data command, the list of table names passed in the --table-list and --exclude-table-list are, by default, case insensitive. Enclose each name in double quotes to make it case-sensitive.
In the 1.0 release, the schema details in the report generated via analyze-schema are sent with diagnostics when the --send-diagnostics flag is on. These schema details are now removed before sending diagnostics.
The object types which YB Voyager can't categorize are placed in a separate file as uncategorized.sql, and the information regarding this file is available as a note under the Notes section in the report generated via analyze-schema.