[DOC-476] Enable load balancing for read replica clusters

docs/content/preview/drivers-orms/go/yb-pgx-reference.md

@@ -69,16 +69,30 @@ Learn how to perform common tasks required for Go application development using
 
 The following connection properties need to be added to enable load balancing:
 
-- `load_balance` - enable cluster-aware load balancing by setting this property to `true`; disabled by default.
+- `load_balance` - enable cluster-aware load balancing by setting this property to one of the allowed values descrived below other than `false`; disabled by default.
 - `topology_keys` - provide comma-separated geo-location values to enable topology-aware load balancing. Geo-locations can be provided as `cloud.region.zone`. Specify all zones in a region as `cloud.region.*`. To designate fallback locations for when the primary location is unreachable, specify a priority in the form `:n`, where `n` is the order of precedence. For example, `cloud1.datacenter1.rack1:1,cloud1.datacenter1.rack2:2`.
 
 By default, the driver refreshes the list of nodes every 300 seconds (5 minutes). You can change this value by including the `yb_servers_refresh_interval` connection parameter.
 
+#### Load balancing for read replica clusters
+
+YugabyteDB PGX smart driver also enables load balancing across nodes in primary clusters which have an associated read replica cluster.
+
+The connection property `load-balance` allows the five values as described in the following table, using which you can distribute connections among different combination of nodes as per their requirements:
+
+| Values | Description |
+| :----- | :---------- |
+| `only-rr` | Create connections only on read replica nodes. |
+| `only-primary` | Create connections only on primary cluster nodes. |
+| `prefer-rr` | Create connections on read replica nodes. If none available, create on any node in the cluster including primary cluster nodes. |
+| `prefer-primary` | Create connections on primary cluster nodes. If none available, create on any node in the cluster including read replica nodes. |
+| `any` or `true` | Equivalent to value true. Create connections on any node in the primary or read replica cluster. |
+
 ### Use the driver
 
 To use the driver, pass new connection properties for load balancing in the connection URL or properties pool.
 
-To enable uniform load balancing across all servers, you set the `load_balance` property to `true` in the URL, as per the following example:
+To enable uniform load balancing across all servers, you set the `load_balance` property to one of the allowed values other than `false` in the URL, as per the following example:
 
 ```go
 baseUrl := fmt.Sprintf("postgres://%s:%s@%s:%d/%s",

docs/content/preview/drivers-orms/go/yb-pgx.md

@@ -98,9 +98,13 @@ The following table describes the connection parameters required to connect, inc
 | user | User connecting to the database | yugabyte |
 | password | User password | yugabyte |
 | dbname | Database name | yugabyte |
-| `load_balance` | [Uniform load balancing](../../smart-drivers/#cluster-aware-connection-load-balancing) | Defaults to upstream driver behavior unless set to 'true' |
+| `load_balance` | [Uniform load balancing](../../smart-drivers/#cluster-aware-connection-load-balancing) |  Defaults to upstream driver behavior unless set to one of the allowed values other than 'false' |
 | `yb_servers_refresh_interval` | If `load_balance` is true, the interval in seconds to refresh the servers list | 300 |
 | `topology_keys` | [Topology-aware load balancing](../../smart-drivers/#topology-aware-connection-load-balancing) | If `load_balance` is true, uses uniform load balancing unless set to comma-separated geo-locations in the form `cloud.region.zone`. |
+| `fallback_to_topology_keys_only` | Applicable only when `topology_keys` are specified. Ensures that the driver attempts connections to nodes within only the placement values specified in `topology_keys` | Empty
+| `failed_host_reconnect_delay_secs` | The driver marks a server as failed with a timestamp, when it cannot connect to it. Later, whenever it refreshes the server list via yb_servers(), if it sees the failed server in the response, it marks the server as UP only if the time specified via this property has elapsed since the time it was last marked as a failed host. | 5 
+
+Starting with version v5.5.3-yb-4, 5 new values are allowed for the property `load_balance` to support read replica nodes: 'any' (alias for 'true'), 'only-primary', 'only-rr', 'prefer-primary' and 'prefer-rr'. See the [smart driver page](../smart-drivers.md#read-replica-cluster-aware) for usage of these values.
 
 The following is an example connection string for connecting to YugabyteDB with uniform load balancing:
 
@@ -135,6 +139,8 @@ conn, err := pgx.Connect(context.Background(), url)
 
 After the driver establishes the initial connection, it fetches the list of available servers from the cluster, and load-balances subsequent connection requests across these servers.
 
+To enable load balancing for primary cluster nodes that have a read replica cluster, see [Load balancing read replica clusters](../yb-pgx-reference/#load-balancing-for-read-replica-clusters).
+
 #### Use multiple addresses
 
 You can specify multiple hosts in the connection string to provide alternative options during the initial connection in case the primary address fails.
@@ -225,6 +231,9 @@ var baseUrl string = fmt.Sprintf("postgres://%s:%s@%s:%d/%s",
 func main() {
  // Create a table and insert a row
  url := fmt.Sprintf("%s?load_balance=true", baseUrl)
+ // If you have a read-replica cluster and want your connections to be load-balanced across only the read-replica nodes,
+ // set the load-balance property to 'only-rr' as shown below.
+ // url := fmt.Sprintf("%s?load_balance=only-rr", baseUrl)
  fmt.Printf("Connection url: %s\n", url)
  createTable(url)
  printAZInfo()