Skip to content

Commit

Permalink
[doc] Read replica connection load balancing support in JDBC Smart dr…
Browse files Browse the repository at this point in the history 
…iver (#24006)

* Add docs content for readreplica support in JDBC smart driver

* Add read replica support content. Update JDBC Smart driver version

* Removed unintentional formatting changes

* Update missing files

* Provide more details on new values of load-balance

* Update docs under stable/ and for 2.20

* Update a missing line in v2.20 docs

* edits

* review comments and backport

* Minor fix

* fix

* port more changes

* minor fixes

* fix links

* fix

---------

Co-authored-by: Dwight Hodge <[email protected]>
  • Loading branch information
@ashetkar @ddhodge
ashetkar and ddhodge authored Oct 1, 2024
1 parent 037fac0 commit 2eedabd
Show file tree
Hide file tree
Showing 39 changed files with 348 additions and 115 deletions.
2 changes: 1 addition & 1 deletion docs/content/preview/drivers-orms/include-drivers-orms-list.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ private = true
| | Version | Support Level | Example apps |
| :--------- | :------ | :------------ | :----------- |
| **Drivers** | | | |
| YugabyteDB JDBC Smart Driver<br/>[Recommended] | [42.3.5-yb-5](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.3.5-yb-5) | Full | [CRUD](/preview/drivers-orms/java/yugabyte-jdbc/) |
| YugabyteDB JDBC Smart Driver<br/>[Recommended] | [42.3.5-yb-7](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.3.5-yb-7) | 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/) |
Expand Down
2 changes: 1 addition & 1 deletion docs/content/preview/drivers-orms/java/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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-5](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.3.5-yb-5) | 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.3.5-yb-7](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.3.5-yb-7) | 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) | |
Expand Down
2 changes: 1 addition & 1 deletion docs/content/preview/drivers-orms/java/ebean.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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-5"
libraryDependencies += "com.yugabyte" % "jdbc-yugabytedb" % "42.3.5-yb-7"
```
1. Enable the PlayEbean plugin in the `build.sbt` file by adding `PlayEbean` as follows:
Expand Down
4 changes: 2 additions & 2 deletions docs/content/preview/drivers-orms/java/yugabyte-jdbc-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ 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-5</version>
<version>42.3.5-yb-7</version>
</dependency>

<!-- https://mvnrepository.com/artifact/com.zaxxer/HikariCP -->
Expand All @@ -73,7 +73,7 @@ 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-5'
implementation 'com.yugabyte:jdbc-yugabytedb:42.3.5-yb-7'
implementation 'com.zaxxer:HikariCP:4.0.3'
```

Expand Down
38 changes: 23 additions & 15 deletions docs/content/preview/drivers-orms/java/yugabyte-jdbc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ 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-5</version>
<version>42.3.5-yb-7</version>
</dependency>

<!-- https://mvnrepository.com/artifact/com.zaxxer/HikariCP -->
Expand All @@ -106,7 +106,7 @@ 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-5'
implementation 'com.yugabyte:jdbc-yugabytedb:42.3.5-yb-7'
implementation 'com.zaxxer:HikariCP:4.0.3'
```

Expand All @@ -122,14 +122,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-connection-load-balancing) | Defaults to upstream driver behavior unless set to 'true'
| `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`.
| 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-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` | 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-7 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 [Read replica-aware load balancing](../../smart-drivers/#read-replica-cluster-aware).

The following is an example JDBC URL for connecting to YugabyteDB:

Expand All @@ -139,7 +143,7 @@ jdbc:yugabytedb://hostname:port/database?user=yugabyte&password=yugabyte&load-ba
topology-keys=cloud.region.zone1,cloud.region.zone2
```

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.
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.

#### Use multiple addresses

Expand All @@ -164,10 +168,10 @@ The following table describes the connection parameters required to connect usin

| JDBC Parameter | Description | Default |
| :---------- | :---------- | :------ |
| ssl | Enable SSL client connection | false
| sslmode | SSL mode | require
| sslrootcert | Path to the root certificate on your computer | ~/.postgresql/
| sslhostnameverifier | Address of host name verifier; only used for YugabyteDB Aeon clusters where sslmode is verify-full. Driver v42.3.5-yb-2 and later only. | com.yugabyte.ysql.YBManagedHostnameVerifier
| ssl | Enable SSL client connection | false |
| sslmode | SSL mode | require |
| sslrootcert | Path to the root certificate on your computer | ~/.postgresql/ |
| sslhostnameverifier | Address of host name verifier; only used for YugabyteDB Aeon clusters where sslmode is verify-full. Driver v42.3.5-yb-2 and later only. | com.yugabyte.ysql.YBManagedHostnameVerifier |

The following is an example JDBC URL for connecting to a YugabyteDB cluster with SSL encryption enabled.

Expand Down Expand Up @@ -206,6 +210,10 @@ public class QuickStartApp {
public static void main(String[] args) throws ClassNotFoundException, SQLException {
Class.forName("com.yugabyte.Driver");
String yburl = "jdbc:yugabytedb://127.0.0.1:5433/yugabyte?user=yugabyte&password=yugabyte&load-balance=true";
// If you have a read replica cluster and want to balance
// connections across only read replica nodes,
// set the load-balance property to 'only-rr' as follows:
// String yburl = "jdbc:yugabytedb://127.0.0.1:5433/yugabyte?user=yugabyte&password=yugabyte&load-balance=only-rr";
Connection conn = DriverManager.getConnection(yburl);
Statement stmt = conn.createStatement();
try {
Expand Down
2 changes: 1 addition & 1 deletion docs/content/preview/drivers-orms/nodejs/ycql.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ type: docs
</li>
</ul>

[Yugabyte Node.js Driver for YCQL](https://github.com/yugabyte/cassandra-java-driver/tree/4.15.x) is based on [DataStax Node.js Driver](https://github.com/datastax/nodejs-driver) for [YCQL](../../../api/ycql/) with additional [smart driver](../../smart-drivers-ycql/) features.
[YugabyteDB Node.js Driver for YCQL](https://github.com/yugabyte/cassandra-nodejs-driver) is based on [DataStax Node.js Driver](https://github.com/datastax/nodejs-driver) for [YCQL](../../../api/ycql/) with additional [smart driver](../../smart-drivers-ycql/) features.

{{< note title="YugabyteDB Aeon" >}}

Expand Down
2 changes: 1 addition & 1 deletion docs/content/preview/drivers-orms/orms/java/ysql-ebean.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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-5"
libraryDependencies += "com.yugabyte" % "jdbc-yugabytedb" % "42.3.5-yb-7"
```

- From your local YugabyteDB installation directory, connect to the [YSQL](../../../../admin/ysqlsh/) shell using:
Expand Down
2 changes: 1 addition & 1 deletion docs/content/preview/drivers-orms/smart-drivers-ycql.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Yugabyte has extended the upstream Cassandra drivers with specific changes to le
| [YugabyteDB Node.js Driver for YCQL](https://github.com/yugabyte/cassandra-nodejs-driver) | [DataStax Node.js Driver](https://github.com/datastax/nodejs-driver) | [Documentation](../nodejs/ycql/) |
| [YugabyteDB C++ Driver for YCQL](https://github.com/yugabyte/cassandra-cpp-driver) | [DataStax C++ Driver](https://github.com/datastax/cpp-driver) | [Documentation](../cpp/ycql/) |
| [YugabyteDB C# Driver for YCQL](https://github.com/yugabyte/cassandra-csharp-driver) | [DataStax C# Driver](https://github.com/datastax/csharp-driver) | [Documentation](../csharp/ycql/) |
| [YugabyteDB Ruby Driver for YCQL](https://github.com/yugabyte/cassandra-ruby-driver) | [DataStax Ruby Driver](https://github.com/datastax/ruby-driver) | [Documentation](../rust/yb-rust-postgres) |
| [YugabyteDB Ruby Driver for YCQL](https://github.com/yugabyte/cassandra-ruby-driver) | [DataStax Ruby Driver](https://github.com/datastax/ruby-driver) | [Documentation](../ruby/ycql) |

## Key features

Expand Down
Loading

0 comments on commit 2eedabd

Please sign in to comment.