[DOC-1088] Docs for Voyager v2025.11.2

docs/content/stable/yugabyte-voyager/migrate/assess-migration.md

@@ -155,19 +155,24 @@ To be able to view the assessment report in the yugabyted UI, do the following:
   1. Set the following configuration parameters before starting the migration:
 
         ```yaml
+        ### *********** Control Plane Configuration ************
+        ### To see the Voyager migration workflow details in the UI, set the following parameters.
+
         ### Control plane type refers to the deployment type of YugabyteDB
+        ### Accepted values: yugabyted
+        ### Optional (if not set, no visualization will be available)
         control-plane-type: yugabyted
 
-        ### YSQL connection string
-        ### Provide the standard PostgreSQL connection parameters, including user name, host name, and port. For example, postgresql://yugabyte:[email protected]:5433
-        yugabyted-db-conn-string: postgresql://yugabyte:[email protected]:5433
+        ### Yugabyted Control Plane Configuration (for local yugabyted clusters)
+        ### Uncomment the section below if control-plane-type is 'yugabyted'
+        yugabyted-control-plane:
+          ### YSQL connection string to yugabyted database
+          ### Provide standard PostgreSQL connection parameters: user name, host name, and port
+          ### Example: postgresql://yugabyte:[email protected]:5433
+          ### Note: Don't include the dbname parameter; the default 'yugabyte' database is used for metadata
+          db-conn-string: postgresql://yugabyte:[email protected]:5433
         ```
 
-        {{< note title="Note" >}}
-
-Don't include the `dbname` parameter in the connection string; the default `yugabyte` database is used to store the meta information for showing the migration in the yugabyted UI.
-        {{< /note >}}
-
 ## Assess migration
 
 Assess your migration using the following steps:
@@ -205,12 +210,59 @@ You can perform the following steps with these scripts:
 
 1. On a machine which has access to the source database, copy the scripts and install dependencies psql and pg_dump version 14 or later. Alternatively, you can install yb-voyager on the machine to automatically get the dependencies.
 
-1. Run the `yb-voyager-pg-gather-assessment-metadata.sh` script by providing the source connection string, the schema names, path to a directory where metadata will be saved, and an optional argument of an interval to capture the IOPS metadata of the source (in seconds with a default value of 120). For example:
+1. Run the `yb-voyager-pg-gather-assessment-metadata.sh` script by providing the source connection string, the schema names, path to a directory where metadata will be saved, and additional optional arguments.
+
+    | <div style="width:150px">Argument</div> | Description/valid options |
+    | :------- | :------------------------ |
+    | pgss_enabled (required) | Whether pg_stat_statements is correctly installed and enabled. <br>Accepted parameters: true, false |
+    | iops_capture_interval (optional) |  Interval in seconds to capture IOPS metadata .<br>Default: 120|
+    | yes (optional) | Answer "yes" to interactive questions. <br>Default: false <br>Accepted parameters: true, false |
+    | source_node_name (optional) | Logical name of the node from which you are collecting data. If omitted, it defaults to primary. Use distinct values (for example, primary, replica1, replica2) when collecting from multiple nodes. |
+    | skip_checks (optional) | When true, skips pre-flight checks already performed by guardrails <br>Default: false <br>Accepted parameters: true, false |
+
+    For example, on a single-node PostgreSQL deployment:
+
+    ```sh
+      /path/to/yb-voyager-pg-gather-assessment-metadata.sh \
+        'postgresql://ybvoyager@host:port/dbname' \
+        'schema1|schema2' \
+        '/path/to/assessment_metadata_dir' \
+        'true' \
+        '120'\
+    ```
+
+    **Note: For primary–replica setups and source_node_name option**<br/>
+    If you have read replicas, run the script once on each node that you want to include in the assessment, using the same directory, `assessment_metadata_dir` but a different `source_node_name` for each node. The primary node must use `source_node_name=primary` (or omit it to accept the default), and replicas should use unique names such as replica1, replica2, and so on. This ensures that Voyager tags and analyzes the collected metrics separately for each node. For example,
+
+    On the primary node:
+    ```sh
+      /path/to/yb-voyager-pg-gather-assessment-metadata.sh \
+        'postgresql://ybvoyager@primary-host:5432/dbname' \
+        'public|sales' \
+        '/path/to/assessment_metadata_dir' \
+        'true' \
+        '120' \
+        'false' \
+        'primary'
+    ```
+
+    On a read replica:
 
     ```sh
-    /path/to/yb-voyager-pg-gather-assessment-metadata.sh 'postgresql://ybvoyager@host:port/dbname' 'schema1|schema2' '/path/to/assessment_metadata_dir' '60'
+    /path/to/yb-voyager-pg-gather-assessment-metadata.sh \
+      'postgresql://ybvoyager@replica1-host:5432/dbname' \
+      'public|sales' \
+      '/path/to/assessment_metadata_dir' \
+      'true' \
+      '120' \
+      'false' \
+      'replica1'
     ```
 
+
+
+
+
 1. Copy the metadata directory to the client machine on which voyager is installed, and run the `assess-migration` command by specifying the path to the metadata directory as follows:
 
     ```sh
@@ -256,6 +308,66 @@ Depending on the recommendations in the assessment report, do the following when
     - [Live migration with fall-forward](../../migrate/live-fall-forward/)
     - [Live migration with fall-back](../../migrate/live-fall-back/)
 
+## Assess with read replicas (PostgreSQL only)
+
+Voyager can collect assessment metadata from [read replicas](/stable/architecture/docdb-replication/read-replicas/) in addition to the primary node, providing a comprehensive view of your workload distribution.
+
+Two ways to use read replicas:
+
+-  Automatic discovery (Default): By default, Voyager attempts to discover replicas via [pg_stat_replication](/stable/additional-features/change-data-capture/using-logical-replication/monitor/#pg-stat-replication) and validate them by connecting to the primary as follows:
+
+    ```sh
+    yb-voyager assess-migration --source-db-type postgresql \
+        --source-db-host primary-host \
+        --source-db-user ybvoyager \
+        --source-db-password password \
+        --source-db-name dbname \
+        --export-dir /path/to/export/dir
+    ```
+
+    Voyager discovers replicas from the primary, attempts best-effort validation, and prompts you to include them. If validation fails (common in RDS, Aurora, Kubernetes, or when using internal IPs), you can either continue with primary-only assessment or manually specify replica endpoints.
+
+- Manual specification: Explicitly provide the read replica endpoints when automatic discovery fails, or if you want precise control.
+
+    Run the command as follows:
+
+    {{< tabpane text=true >}}
+  {{% tab header="CLI" lang="cli" %}}
+
+  ```sh
+  yb-voyager assess-migration --source-db-type postgresql \
+      --source-db-host primary-host \
+      --source-db-user ybvoyager \
+      --source-db-password password \
+      --source-db-name dbname \
+      --source-read-replica-endpoints "replica1:5432,replica2:5432" \
+      --export-dir /path/to/export/dir
+  ```
+
+  {{% /tab %}}
+  {{% tab header="Config file" lang="config" %}}
+
+```sh
+yb-voyager assess-migration --config-file <path-to-config-file>
+```
+
+A sample source database configuration is as follows:
+
+```yaml
+source:
+  host: primary-host
+  port: 5432
+  user: ybvoyager
+  password: password
+  db-name: dbname
+  read-replica-endpoints: "replica1:5432,replica2:5432"
+```
+
+  {{% /tab %}}
+    {{< /tabpane >}}
+
+  Ensure that all provided endpoints are accessible as they are strictly validated.
+
 ## Assess a fleet of databases (Oracle only)
 
 Use the Bulk Assessment command ([assess-migration-bulk](../../reference/assess-migration/#assess-migration-bulk)) to assess multiple schemas across one or more database instances simultaneously. It offers:

docs/content/stable/yugabyte-voyager/migrate/live-fall-back.md

@@ -734,19 +734,24 @@ Configure the yugabyted UI as follows:
   1. To see the Voyager migration workflow details in the UI, set the following configuration parameters before starting the migration:
 
         ```yaml
+        ### *********** Control Plane Configuration ************
+        ### To see the Voyager migration workflow details in the UI, set the following parameters.
+
         ### Control plane type refers to the deployment type of YugabyteDB
+        ### Accepted values: yugabyted
+        ### Optional (if not set, no visualization will be available)
         control-plane-type: yugabyted
 
-        ### YSQL connection string
-        ### Provide the standard PostgreSQL connection parameters, including user name, host name, and port. For example, postgresql://yugabyte:[email protected]:5433
-        yugabyted-db-conn-string: postgresql://yugabyte:[email protected]:5433
+        ### Yugabyted Control Plane Configuration (for local yugabyted clusters)
+        ### Uncomment the section below if control-plane-type is 'yugabyted'
+        yugabyted-control-plane:
+          ### YSQL connection string to yugabyted database
+          ### Provide standard PostgreSQL connection parameters: user name, host name, and port
+          ### Example: postgresql://yugabyte:[email protected]:5433
+          ### Note: Don't include the dbname parameter; the default 'yugabyte' database is used for metadata
+          db-conn-string: postgresql://yugabyte:[email protected]:5433
         ```
 
-        {{< note title="Note" >}}
-
-Don't include the `dbname` parameter in the connection string; the default `yugabyte` database is used to store the meta information for showing the migration in the yugabyted UI.
-        {{< /note >}}
-
 ## Assess migration
 
 This step applies to PostgreSQL and Oracle migrations only.

docs/content/stable/yugabyte-voyager/migrate/live-fall-forward.md

@@ -760,19 +760,24 @@ Configure the yugabyted UI as follows:
   1. To see the Voyager migration workflow details in the UI, set the following configuration parameters before starting the migration:
 
         ```yaml
+        ### *********** Control Plane Configuration ************
+        ### To see the Voyager migration workflow details in the UI, set the following parameters.
+
         ### Control plane type refers to the deployment type of YugabyteDB
+        ### Accepted values: yugabyted
+        ### Optional (if not set, no visualization will be available)
         control-plane-type: yugabyted
 
-        ### YSQL connection string
-        ### Provide the standard PostgreSQL connection parameters, including user name, host name, and port. For example, postgresql://yugabyte:[email protected]:5433
-        yugabyted-db-conn-string: postgresql://yugabyte:[email protected]:5433
+        ### Yugabyted Control Plane Configuration (for local yugabyted clusters)
+        ### Uncomment the section below if control-plane-type is 'yugabyted'
+        yugabyted-control-plane:
+          ### YSQL connection string to yugabyted database
+          ### Provide standard PostgreSQL connection parameters: user name, host name, and port
+          ### Example: postgresql://yugabyte:[email protected]:5433
+          ### Note: Don't include the dbname parameter; the default 'yugabyte' database is used for metadata
+          db-conn-string: postgresql://yugabyte:[email protected]:5433
         ```
 
-        {{< note title="Note" >}}
-
-Don't include the `dbname` parameter in the connection string; the default `yugabyte` database is used to store the meta information for showing the migration in the yugabyted UI.
-        {{< /note >}}
-
 ## Assess migration
 
 This step applies to PostgreSQL and Oracle migrations only.

docs/content/stable/yugabyte-voyager/migrate/live-migrate.md

@@ -596,19 +596,24 @@ Configure the yugabyted UI as follows:
   1. To see the Voyager migration workflow details in the UI, set the following configuration parameters before starting the migration:
 
         ```yaml
+        ### *********** Control Plane Configuration ************
+        ### To see the Voyager migration workflow details in the UI, set the following parameters.
+
         ### Control plane type refers to the deployment type of YugabyteDB
+        ### Accepted values: yugabyted
+        ### Optional (if not set, no visualization will be available)
         control-plane-type: yugabyted
 
-        ### YSQL connection string
-        ### Provide the standard PostgreSQL connection parameters, including user name, host name, and port. For example, postgresql://yugabyte:[email protected]:5433
-        yugabyted-db-conn-string: postgresql://yugabyte:[email protected]:5433
+        ### Yugabyted Control Plane Configuration (for local yugabyted clusters)
+        ### Uncomment the section below if control-plane-type is 'yugabyted'
+        yugabyted-control-plane:
+          ### YSQL connection string to yugabyted database
+          ### Provide standard PostgreSQL connection parameters: user name, host name, and port
+          ### Example: postgresql://yugabyte:[email protected]:5433
+          ### Note: Don't include the dbname parameter; the default 'yugabyte' database is used for metadata
+          db-conn-string: postgresql://yugabyte:[email protected]:5433
         ```
 
-        {{< note title="Note" >}}
-
-Don't include the `dbname` parameter in the connection string; the default `yugabyte` database is used to store the meta information for showing the migration in the yugabyted UI.
-        {{< /note >}}
-
 ## Assess migration
 
 This step applies to PostgreSQL and Oracle migrations only.

docs/content/stable/yugabyte-voyager/migrate/migrate-steps.md

@@ -204,19 +204,24 @@ Configure the yugabyted UI as follows:
   1. To see the Voyager migration workflow details in the UI, set the following configuration parameters before starting the migration:
 
         ```yaml
+        ### *********** Control Plane Configuration ************
+        ### To see the Voyager migration workflow details in the UI, set the following parameters.
+
         ### Control plane type refers to the deployment type of YugabyteDB
+        ### Accepted values: yugabyted
+        ### Optional (if not set, no visualization will be available)
         control-plane-type: yugabyted
 
-        ### YSQL connection string
-        ### Provide the standard PostgreSQL connection parameters, including user name, host name, and port. For example, postgresql://yugabyte:[email protected]:5433
-        yugabyted-db-conn-string: postgresql://yugabyte:[email protected]:5433
+        ### Yugabyted Control Plane Configuration (for local yugabyted clusters)
+        ### Uncomment the section below if control-plane-type is 'yugabyted'
+        yugabyted-control-plane:
+          ### YSQL connection string to yugabyted database
+          ### Provide standard PostgreSQL connection parameters: user name, host name, and port
+          ### Example: postgresql://yugabyte:[email protected]:5433
+          ### Note: Don't include the dbname parameter; the default 'yugabyte' database is used for metadata
+          db-conn-string: postgresql://yugabyte:[email protected]:5433
         ```
 
-        {{< note title="Note" >}}
-
-Don't include the `dbname` parameter in the connection string; the default `yugabyte` database is used to store the meta information for showing the migration in the yugabyted UI.
-        {{< /note >}}
-
 ## Assess migration
 
 This step applies to PostgreSQL and Oracle migrations only.

docs/content/stable/yugabyte-voyager/reference/assess-migration.md

@@ -201,6 +201,13 @@ source:
 ```
 
 | Path of the file containing source SSL Root Certificate. |
+| --source-read-replica-endpoints |
+
+```yaml{.nocopy}
+source:
+      read-replica-endpoints:
+```
+| (PostgreSQL only) Comma-separated list of read replica endpoints. Each endpoint format is host:port. <br/>Default port: 5432 <br/>Example: "host1:5432, host2:5433". |
 | -e, --export-dir |
 
 ```yaml{.nocopy}

docs/content/stable/yugabyte-voyager/reference/configuration-file.md

@@ -71,15 +71,22 @@ log-level: info
 # Default : true
 send-diagnostics: true
 
-# Control plane type refers to the deployment type of YugabyteDB.
-# Accepted value - (yugabyted)
-# Optional
+# *********** Control Plane Configuration ************
+# To see the Voyager migration workflow details in the UI, set the following parameters.
+
+# Control plane type refers to the deployment type of YugabyteDB
+# Accepted values: yugabyted
+# Optional (if not set, no visualization will be available)
 control-plane-type: yugabyted
 
-# YSQL connection string
-# Provide the standard PostgreSQL connection parameters, excluding dbname.
-# Required if control-plane-type is set to yugabyted
-yugabyted-db-conn-string: <ysql-connection-parameters>
+# Yugabyted Control Plane Configuration (for local yugabyted clusters)
+# Uncomment the section below if control-plane-type is 'yugabyted'
+yugabyted-control-plane:
+  # YSQL connection string to yugabyted database
+  # Provide standard PostgreSQL connection parameters: user name, host name, and port
+  # Example: postgresql://yugabyte:[email protected]:5433
+  # Note: Don't include the dbname parameter; the default 'yugabyte' database is used for metadata
+  db-conn-string: postgresql://yugabyte:[email protected]:5433
 ```
 
 ### Source database configuration
@@ -112,6 +119,12 @@ source:
   # Can be specified via SOURCE_DB_PASSWORD environmental variable
   db-password: test_password
 
+  # Comma-separated list of read replica endpoints.
+  # Default port: 5432
+  # Example: "host1:5432, host2:5433"
+  # Note - Valid only for PostgreSQL
+  read-replica-endpoints: host:port
+
   # Path to source SSL Certificate
   ssl-cert: /path/to/cert
 

docs/content/stable/yugabyte-voyager/release-notes.md

@@ -17,6 +17,23 @@ What follows are the release notes for the YugabyteDB Voyager v1 release 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.
 
+## v2025.11.2 - November 25, 2025
+
+### New feature
+
+- Assess migration now supports fetching metadata from PostgreSQL read replicas in addition to the primary source database. This provides a more comprehensive and accurate workload assessment by aggregating metrics across both primary and replica nodes.
+
+### Enhancement
+
+- Added sorting functionality to the "Object Usage" column in the Performance Optimizations table of the assessment report for a better user experience.
+
+### Bug fixes
+
+- Fixed a nil pointer error when a table was missing in the target database during live migration.
+- Fixed a bug in the Schema Optimization Report to exclude parent partitioned tables from "Colocated" recommendations, as colocation applies only to leaf partitions.
+- Fixed a bug in the Schema Optimization Report where Colocation Recommendations were incorrectly marked as "Applied" when assess-migration could not provide sizing recommendations.
+- Fixed an issue with sorting options in the "Assessment Issues" and "Performance Optimizations" sections of the Assessment Report.
+
 ## v2025.11.1 - November 11, 2025
 
 ### Enhancements

docs/layouts/shortcodes/yb-voyager-release.html

@@ -9,7 +9,7 @@
     You will need to update this line for each new release.
     Example: for v2025.6.1, use "yb-voyager/v2025.6.1"
 */ -}}
-{{- $version := "yb-voyager/v2025.11.1" -}}
+{{- $version := "yb-voyager/v2025.11.2" -}}
 
 {{- /* Output only the version string */ -}}
 {{- $version -}}