Update jdbc driver version to 42.7.3-yb-1 (#24481)

* Update jdbc driver version to 42.7.3-yb-1 * Apply suggestions from code review * fix tabs * Improve details on the node selection logic * Have consistent messaging across preview/stable/v2.20 * Update Hikari version. Minor wording changes * edits * backport * minor edit --------- Co-authored-by: Dwight Hodge <[email protected]> Co-authored-by: Dwight Hodge <[email protected]>
yugabyte · Oct 30, 2024 · 06e596b · 06e596b
1 parent 52181a1
commit 06e596b
Show file tree

Hide file tree

Showing 32 changed files with 223 additions and 202 deletions.
diff --git a/docs/content/preview/drivers-orms/include-drivers-orms-list.md b/docs/content/preview/drivers-orms/include-drivers-orms-list.md
@@ -11,7 +11,7 @@ private = true
 |            | Version | Support Level | Example apps |
 | :--------- | :------ | :------------ | :----------- |
 | **Drivers** | | | |
-| YugabyteDB JDBC Smart Driver<br/>[Recommended] | [42.3.5-yb-8](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.3.5-yb-8) | Full | [CRUD](/preview/drivers-orms/java/yugabyte-jdbc/) |
+| YugabyteDB JDBC Smart Driver<br/>[Recommended] | [42.7.3-yb-1](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.7.3-yb-1) | Full | [CRUD](/preview/drivers-orms/java/yugabyte-jdbc/) |
 | YugabyteDB R2DBC Smart Driver | [1.1.0-yb-1-ea](https://mvnrepository.com/artifact/com.yugabyte/r2dbc-postgresql) | Full | [CRUD](/preview/drivers-orms/java/yb-r2dbc/) |
 | PostgreSQL JDBC Driver  | [42.3.4](https://mvnrepository.com/artifact/org.postgresql/postgresql/42.3.4) | Full | [CRUD](/preview/drivers-orms/java/postgres-jdbc/) |
 | Vert.x Pg Client       | [4.3.2](https://mvnrepository.com/artifact/io.vertx/vertx-core/4.3.2) | Full | [CRUD](/preview/drivers-orms/java/ysql-vertx-pg-client/) |

diff --git a/docs/content/preview/drivers-orms/java/_index.md b/docs/content/preview/drivers-orms/java/_index.md
@@ -21,7 +21,7 @@ The following projects can be used to implement Java applications using the Yuga
 
 | Driver | Documentation and Guides | Latest Driver Version | Supported YugabyteDB Version |
 | ------- | ------------------------ | ------------------------ | ---------------------|
-| YugabyteDB JDBC Driver [Recommended] | [Documentation](yugabyte-jdbc/)<br />[Reference](yugabyte-jdbc-reference/)<br />[Blog](https://dev.to/yugabyte/yugabytedb-jdbc-smart-driver-for-proxyless-halb-2k8a/) | [42.3.5-yb-8](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.3.5-yb-8) | 2.8 and above |
+| YugabyteDB JDBC Driver [Recommended] | [Documentation](yugabyte-jdbc/)<br />[Reference](yugabyte-jdbc-reference/)<br />[Blog](https://dev.to/yugabyte/yugabytedb-jdbc-smart-driver-for-proxyless-halb-2k8a/) | [42.7.3-yb-1](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.7.3-yb-1)<br/>(Supports Java 21) | 2.8 and above |
 | YugabyteDB R2DBC Driver | [Documentation](yb-r2dbc/) | [1.1.0-yb-1-ea](https://mvnrepository.com/artifact/com.yugabyte/r2dbc-postgresql) | 2.18 and above |
 | PostgreSQL JDBC Driver | [Documentation](postgres-jdbc/)<br /> [Reference](postgres-jdbc-reference/) | [42.3.4](https://mvnrepository.com/artifact/org.postgresql/postgresql/42.3.4) | 2.4 and above |
 | Vert.x Pg Client | [Documentation](ysql-vertx-pg-client/) | [4.3.2](https://mvnrepository.com/artifact/io.vertx/vertx-core/4.3.2) | |

diff --git a/docs/content/preview/drivers-orms/java/ebean.md b/docs/content/preview/drivers-orms/java/ebean.md
@@ -110,7 +110,7 @@ To begin using Ebean in the application, do the following:
 1. Add the following dependency for the YugabyteDB JDBC driver to the `build.sbt` file.
 
     ```sbt
-    libraryDependencies += "com.yugabyte" % "jdbc-yugabytedb" % "42.3.5-yb-8"
+    libraryDependencies += "com.yugabyte" % "jdbc-yugabytedb" % "42.7.3-yb-1"
     ```
 
 1. Enable the PlayEbean plugin in the `build.sbt` file by adding `PlayEbean` as follows:

diff --git a/docs/content/preview/drivers-orms/java/yugabyte-jdbc-reference.md b/docs/content/preview/drivers-orms/java/yugabyte-jdbc-reference.md
@@ -57,14 +57,14 @@ To get the driver and HikariPool from Maven, add the following dependencies to t
 <dependency>
   <groupId>com.yugabyte</groupId>
   <artifactId>jdbc-yugabytedb</artifactId>
-  <version>42.3.5-yb-8</version>
+  <version>42.7.3-yb-1</version>
 </dependency>
 
 <!-- https://mvnrepository.com/artifact/com.zaxxer/HikariCP -->
 <dependency>
   <groupId>com.zaxxer</groupId>
   <artifactId>HikariCP</artifactId>
-  <version>4.0.3</version>
+  <version>5.0.1</version>
 </dependency>
 ```
 
@@ -74,8 +74,8 @@ To get the driver and HikariPool, add the following dependencies to the Gradle p
 
 ```java
 // https://mvnrepository.com/artifact/org.postgresql/postgresql
-implementation 'com.yugabyte:jdbc-yugabytedb:42.3.5-yb-8'
-implementation 'com.zaxxer:HikariCP:4.0.3'
+implementation 'com.yugabyte:jdbc-yugabytedb:42.7.3-yb-1'
+implementation 'com.zaxxer:HikariCP:5.0.1'
 ```
 
 Note that v4 of HikariCP is required because the YugabyteDB JDBC Driver requires Java 8.

diff --git a/docs/content/preview/drivers-orms/java/yugabyte-jdbc.md b/docs/content/preview/drivers-orms/java/yugabyte-jdbc.md
@@ -89,14 +89,14 @@ If you are using [Maven](https://maven.apache.org/guides/development/guide-build
 <dependency>
   <groupId>com.yugabyte</groupId>
   <artifactId>jdbc-yugabytedb</artifactId>
-  <version>42.3.5-yb-8</version>
+  <version>42.7.3-yb-1</version>
 </dependency>
 
 <!-- https://mvnrepository.com/artifact/com.zaxxer/HikariCP -->
 <dependency>
   <groupId>com.zaxxer</groupId>
   <artifactId>HikariCP</artifactId>
-  <version>4.0.3</version>
+  <version>5.0.1</version>
 </dependency>
 ```
 
@@ -109,8 +109,8 @@ Install the added dependency using `mvn install`.
 If you are using [Gradle](https://docs.gradle.org/current/samples/sample_building_java_applications.html), add the following dependencies to your `build.gradle` file:
 
 ```java
-implementation 'com.yugabyte:jdbc-yugabytedb:42.3.5-yb-8'
-implementation 'com.zaxxer:HikariCP:4.0.3'
+implementation 'com.yugabyte:jdbc-yugabytedb:42.7.3-yb-1'
+implementation 'com.zaxxer:HikariCP:5.0.1'
 ```
 
 ### Step 2: Set up the database connection
@@ -125,18 +125,18 @@ The following table describes the connection parameters required to connect, inc
 
 | JDBC Parameter | Description | Default |
 | :------------- | :---------- | :------ |
-| hostname  | Host name of the YugabyteDB instance. You can also enter [multiple addresses](#use-multiple-addresses). | localhost |
-| port |  Listen port for YSQL | 5433 |
-| database | Database name | yugabyte |
-| user | User connecting to the database | yugabyte |
-| password | User password | yugabyte |
-| `load-balance` | [Uniform load balancing](../../smart-drivers/#cluster-aware-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-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` | If `topology-keys` are specified, the driver only tries to connect to nodes specified in `topology-keys` | Empty |
-| `failed-host-reconnect-delay-secs` | When the driver is unable to connect to a node, it marks the node as failed using a timestamp. When refreshing the server list via yb_servers(), if the driver sees a failed node in the response, it marks the server as UP only if the time specified via this property has elapsed from the time it was last marked as failed. | 5 |
-
-In v42.3.5-yb-8 and later, the `load_balance` property supports the following additional properties: any (alias for 'true'), only-primary, only-rr, prefer-primary, and prefer-rr. See [Node type-aware load balancing](../../smart-drivers/#node-type-aware-load-balancing).
+| `hostname`  | Host name of the YugabyteDB instance. You can also enter [multiple addresses](#use-multiple-addresses). | localhost |
+| `port` |  Listen port for YSQL | 5433 |
+| `database` | Database name | yugabyte |
+| `user` | User connecting to the database | yugabyte |
+| `password` | User password | yugabyte |
+| `load-balance` | Enables [Uniform load balancing](../../smart-drivers/#cluster-aware-load-balancing) | false (Disabled) |
+| `yb-servers-refresh-interval` | The interval in seconds to refresh the servers list; ignored if `load-balance` is false | 300 |
+| `topology-keys` | Enables [Topology-aware load balancing](../../smart-drivers/#topology-aware-load-balancing). It can be set to comma-separated geo-locations in the form `cloud.region.zone:priority`. Ignored if `load-balance` is false | Empty |
+| `fallback-to-topology-keys-only` | If set to true and `topology-keys` are specified, the driver only tries to connect to nodes specified in `topology-keys` | false |
+| `failed-host-reconnect-delay-secs` | Time, in seconds, to wait before trying to connect to failed nodes. When the driver is unable to connect to a node, it marks the node as failed using a timestamp, and ignores the node when trying new connections until this time elapses. | 5 |
+
+In v42.7.3-yb-1 and later, the `load-balance` property supports the following additional properties: any (alias for 'true'), only-primary, only-rr, prefer-primary, and prefer-rr. See [Node type-aware load balancing](../../smart-drivers/#node-type-aware-load-balancing).
 
 The following is an example JDBC URL for connecting to YugabyteDB:
 

diff --git a/docs/content/preview/drivers-orms/orms/java/ysql-ebean.md b/docs/content/preview/drivers-orms/orms/java/ysql-ebean.md
@@ -71,7 +71,7 @@ $ git clone https://github.com/YugabyteDB-Samples/orm-examples.git && cd orm-exa
 - Add a dependency in `build.sbt` for the YugabyteDB JDBC driver.
 
   ```sh
-  libraryDependencies += "com.yugabyte" % "jdbc-yugabytedb" % "42.3.5-yb-8"
+  libraryDependencies += "com.yugabyte" % "jdbc-yugabytedb" % "42.7.3-yb-1"
   ```
 
 - From your local YugabyteDB installation directory, connect to the [YSQL](../../../../api/ysqlsh/) shell using:

diff --git a/docs/content/preview/drivers-orms/smart-drivers.md b/docs/content/preview/drivers-orms/smart-drivers.md
@@ -42,7 +42,7 @@ YugabyteDB smart drivers have the following key features.
 | [Cluster aware](#cluster-aware-load-balancing) | Smart drivers perform automatic uniform connection load balancing<br/>After the driver establishes an initial connection, it fetches the list of available servers from the cluster and distributes connections evenly across these servers. |
 | [Node type aware](#node-type-aware-load-balancing) | If your cluster has read replicas, distribute connections based on the node type (primary or read replica). (Not supported by all smart drivers.) |
 | [Topology aware](#topology-aware-load-balancing) | If you want to restrict connections to particular geographies to achieve lower latency, you can target specific regions, zones, and fallback zones across which to balance connections. |
-| [Configurable refresh interval](#servers-refresh-interval) | By default, the driver refreshes the list of available servers every five minutes. The interval is configurable (with the exception of Python). |
+| [Configurable&nbsp;refresh interval](#servers-refresh-interval) | By default, the driver refreshes the list of available servers every five minutes. The interval is configurable (with the exception of Python). |
 | [Connection pooling](#connection-pooling) | Like the upstream driver, smart drivers support popular connection pooling solutions. |
 
 ## Overview
@@ -97,7 +97,7 @@ A connection works as follows:
 
 #### Enable load balancing
 
-To enable cluster-aware load balancing, you set the load balance connection parameter to `true` in the connection URL or the connection string (DSN style).
+To enable cluster-aware load balancing, you set the load balance connection parameter to `true` or `any` (the default is false) in the connection URL or the connection string (DSN style).
 
 For example, using the Go smart driver, you would enable load balancing as follows:
 
@@ -115,7 +115,7 @@ Note that, for load balancing, the nodes in the universe must be accessible. If,
 
 #### Node type-aware load balancing
 
-If your cluster has read replicas, smart drivers can distribute connections based on the node type - primary or read replica. If a cluster has read replicas, you may want to load balance connections to the read replica nodes, or exclude them.
+If your cluster has read replicas, smart drivers can distribute (or exclude) connections based on the node type - primary or read replica.
 
 To support this, the load balance property accepts the following additional values.
 
@@ -127,7 +127,7 @@ To support this, the load balance property accepts the following additional valu
 | prefer&#8209;primary | Create connections equally across primary nodes. If none are available, create them equally across the available read replica nodes. |
 | prefer-rr | Create connections equally across read replica nodes. If none are available, create them equally across the available primary nodes. |
 
-The default value for the load balance property remains `false`.
+To see how nodes would be selected for connections using these values, see [Order of node selection for new connections](#order-of-node-selection-for-new-connections).
 
 ### Servers refresh interval
 
@@ -179,54 +179,61 @@ To specify fallback locations if a location is unavailable, add `:n` to the topo
 
 Not specifying a priority is the equivalent of setting priority to 1.
 
-If you specify topology keys, you can additionally specify that connections only fall back to those nodes using the `fallback-to-topology-keys-only` property (JDBC smart driver only).
+If you specify topology keys, you can additionally specify that connections only fall back to the nodes specified using the topology keys by setting the `fallback-to-topology-keys-only` property (JDBC smart driver only).
+
+The property `fallback-to-topology-keys-only` is ignored when either `topology-keys` is empty, or when `load-balance` is set to `prefer-primary` or `prefer-rr`.
 
 If no servers are available, the request may return with a failure.
 
 ### Order of node selection for new connections
 
-Consider a cluster with three primary nodes across three zones (zoneA, zoneB, and zoneC); and three read replica nodes in zoneB, zoneC, and zoneD.
+Consider a hypothetical setup where a YugabyteDB cluster has nodes in a single region _region1_ of cloud _cloud1_ with three primary nodes across three zones (_zoneA_, _zoneB_, and _zoneC_); and three read replica nodes across zones _zoneB_, _zoneC_, and _zoneD_.
 
 The following shows how nodes are selected for new connections, depending on the load balance and topology key settings.
 
-{{<tabpane text=true >}}
-{{% tab header="No topology keys" lang="no-keys" %}}
+(The property names used in the example are for the JDBC smart driver; use the equivalent for your preferred language.)
 
-When no topology keys are specified, nodes are selected as follows.
+#### No topology keys
+
+When `topology-keys` is not specified, nodes are selected as follows.
 
 | Load balance setting | Connect to |
 | :--- | :--- |
-| true / any | Any node in all zones |
-| only-primary | Primary nodes in all zones |
-| only-rr | Read replica nodes in all zones |
-| prefer-primary | Primary nodes in all zones, with fallback to read replica nodes |
-| prefer-rr | Read replica nodes in all zones, with fallback to primary nodes |
+| true / any | Any nodes in entire cluster |
+| only-primary | <ol><li>Primary nodes in entire cluster</li><li>Else, fail</li> |
+| only-rr | <ol><li>Read Replica nodes in entire cluster</li><li>Else, fail</li> |
+| prefer-primary | <ol><li>Primary nodes in entire cluster</li><li>Else, read replica nodes in entire cluster</li> |
+| prefer-rr | <ol><li>Read Replica nodes in entire cluster</li><li>Else, primary nodes in entire cluster</li> |
 
-{{% /tab %}}
-{{% tab header="Topology keys" lang="100-wh" %}}
+#### Topology keys
+
+When `topology-keys` is specified as `cloud1.region1.zoneA:1,cloud1.region1.zoneB:2`, nodes are selected as follows.
+
+{{<tabpane text=true >}}
+{{% tab header="Default" lang="fallback-false" %}}
 
-When topology keys are specified as zoneA:1, zoneB:2, nodes are selected as follows.
+If topology keys are specified, by default (that is, `fallback-to-topology-keys-only` is false), nodes are selected as follows.
 
 | Load balance setting | Connect to |
 | :--- | :--- |
-| true / any | <ol><li>Any nodes in zoneA</li><li>If none, then any nodes in zoneB</li><li>If none, then any nodes in entire cluster (all zones) |
-| only-primary | <ol><li>Primary nodes in zoneA</li><li>If none, then primary nodes in zoneB</li><li>If none, then primary nodes in entire cluster (all zones)</li><li>If none, fail |
-| only-rr | <ol><li>Read replica nodes in zoneB</li><li>If none, read replica nodes in entire cluster (all zones)</li><li>If none, fail |
-| prefer-primary | <ol><li>Primary nodes in zoneA</li><li>If none, primary nodes in zoneB</li><li>If none, then primary nodes in entire cluster</li><li>If none, then read replica nodes in entire cluster |
-| prefer-rr | <ol><li>Read replica nodes in zoneB</li><li>If none, read replica nodes in entire cluster</li><li>If none, then primary nodes in entire cluster |
+| true / any | <ol><li>Any nodes in zoneA</li><li>Else, any nodes in zoneB</li><li>Else, any nodes in entire cluster |
+| only-primary | <ol><li>Primary nodes in zoneA</li><li>Else, primary nodes in zoneB</li><li>Else, primary nodes in entire cluster</li><li>Else, fail |
+| only-rr | <ol><li>Read replica nodes in zoneB</li><li>Else, read replica nodes in entire cluster</li><li>Else, fail |
+| prefer-primary | <ol><li>Primary nodes in zoneA</li><li>Else, primary nodes in zoneB</li><li>Else, primary nodes in entire cluster</li><li>Else, read replica nodes in entire cluster |
+| prefer-rr | <ol><li>Read replica nodes in zoneB</li><li>Else, read replica nodes in entire cluster</li><li>Else, primary nodes in entire cluster |
 
 {{% /tab %}}
-{{% tab header="Fall back to topology keys" lang="100-wh" %}}
+{{% tab header="Fall back to topology keys only" lang="fallback-true" %}}
 
-When topology keys are specified as zoneA:1, zoneB:2, and fallback to topology keys only is true, nodes are selected as follows.
+If topology keys are specified, and `fallback-to-topology-keys-only` is true, nodes are selected as follows.
 
 | Load balance setting | Connect to |
 | :--- | :--- |
-| true / any | <ol><li>Any nodes in zoneA</li><li>If none, then any nodes in zoneB</li><li>If none, then fail |
-| only-primary | <ol><li>Primary nodes in zoneA</li><li>If none, then primary nodes in zoneB</li><li>If none, fail |
-| only-rr | <ol><li>Read replica nodes in zoneB</li><li>If none, fail |
-| prefer-primary | <ol><li>Primary nodes in zoneA</li><li>If none, primary nodes in zoneB</li><li>If none, then primary nodes in entire cluster</li><li>If none, then read replica nodes in entire cluster |
-| prefer-rr | <ol><li>Read replica nodes in zoneB</li><li>If none, read replica nodes in entire cluster</li><li>If none, then primary nodes in entire cluster |
+| true / any | <ol><li>Any nodes in zoneA</li><li>Else, any nodes in zoneB</li><li>Else, fail |
+| only-primary | <ol><li>Primary nodes in zoneA</li><li>Else, primary nodes in zoneB</li><li>Else, fail |
+| only-rr | <ol><li>Read replica nodes in zoneB</li><li>Else, fail |
+| prefer-primary | fallback-to-topology-keys-only is ignored:<ol><li>Primary nodes in zoneA</li><li>Else, primary nodes in zoneB</li><li>Else, primary nodes in entire cluster</li><li>Else, read replica nodes in entire cluster |
+| prefer-rr | fallback-to-topology-keys-only is ignored:<ol><li>Read replica nodes in zoneB</li><li>Else, read replica nodes in entire cluster</li><li>Else, primary nodes in entire cluster |
 
 {{% /tab %}}
 {{</tabpane >}}
@@ -281,6 +288,6 @@ For more information on using TLS/SSL in YugabyteDB Aeon, refer to [Encryption i
 ## Learn more
 
 - YugabyteDB Friday Tech Talk: [PostgreSQL Smart Drivers](https://youtu.be/FbXrRdB_4u0)
-- [Smart driver FAQ](../../faq/smart-drivers-faq/)
+- [Smart driver FAQ](/preview/faq/smart-drivers-faq/)
 - Smart driver [architecture documentation](https://github.com/yugabyte/yugabyte-db/blob/master/architecture/design/smart-driver.md)
 - Blog: [Node.js Smart Drivers for YugabyteDB: Why You Should Care](https://www.yugabyte.com/blog/node-js-smart-drivers-for-yugabytedb/)
diff --git a/docs/content/preview/integrations/apache-spark/java-ysql.md b/docs/content/preview/integrations/apache-spark/java-ysql.md
@@ -101,7 +101,7 @@ Create the database and table you will read and write to as follows:
     <dependency>
         <groupId> com.yugabyte</groupId>
         <artifactId>jdbc-yugabytedb</artifactId>
-        <version>42.3.5-yb-8</version>
+        <version>42.7.3-yb-1</version>
     </dependency>
     ```
 

diff --git a/docs/content/preview/integrations/apache-spark/python-ysql.md b/docs/content/preview/integrations/apache-spark/python-ysql.md
@@ -57,7 +57,7 @@ This tutorial assumes that you have:
 From your spark installation directory, use the following command to start `pyspark` shell, and pass the YugabyteDB driver package with the `--packages` parameter. The command fetches the YugabyteDB driver from local cache (if present), or installs the driver from [maven central](https://search.maven.org/).
 
 ```sh
-./bin/pyspark --packages com.yugabyte:jdbc-yugabytedb:42.3.5-yb-8
+./bin/pyspark --packages com.yugabyte:jdbc-yugabytedb:42.7.3-yb-1
 ```
 
 The Spark session should be available as follows: