From 2eedabd6fa9fa4748fd0adad5aef613047f31291 Mon Sep 17 00:00:00 2001 From: Amogh Shetkar Date: Wed, 2 Oct 2024 03:00:18 +0530 Subject: [PATCH] [doc] Read replica connection load balancing support in JDBC Smart driver (#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 --- .../drivers-orms/include-drivers-orms-list.md | 2 +- .../preview/drivers-orms/java/_index.md | 2 +- .../preview/drivers-orms/java/ebean.md | 2 +- .../java/yugabyte-jdbc-reference.md | 4 +- .../drivers-orms/java/yugabyte-jdbc.md | 38 +++++--- .../preview/drivers-orms/nodejs/ycql.md | 2 +- .../drivers-orms/orms/java/ysql-ebean.md | 2 +- .../drivers-orms/smart-drivers-ycql.md | 2 +- .../preview/drivers-orms/smart-drivers.md | 89 +++++++++++++++--- .../integrations/apache-spark/java-ysql.md | 2 +- .../integrations/apache-spark/python-ysql.md | 2 +- .../integrations/apache-spark/scala-ysql.md | 2 +- .../integrations/apache-spark/spark-sql.md | 2 +- docs/content/preview/integrations/camunda.md | 2 +- docs/content/preview/integrations/flyway.md | 3 +- .../integrations/spring-framework/sd-jpa.md | 2 +- .../integrations/spring-framework/sdyb.md | 2 +- docs/content/preview/quick-start/docker.md | 2 +- .../content/preview/quick-start/kubernetes.md | 2 +- .../chapter3-tolerating-outages.md | 2 +- .../drivers-orms/include-drivers-orms-list.md | 2 +- .../stable/drivers-orms/java/_index.md | 2 +- .../content/stable/drivers-orms/java/ebean.md | 2 +- .../java/yugabyte-jdbc-reference.md | 4 +- .../stable/drivers-orms/java/yugabyte-jdbc.md | 35 ++++--- .../stable/drivers-orms/nodejs/ycql.md | 2 +- .../drivers-orms/orms/java/ysql-ebean.md | 2 +- .../stable/drivers-orms/smart-drivers-ycql.md | 2 +- .../stable/drivers-orms/smart-drivers.md | 91 ++++++++++++++++--- .../transactions/transactions-retries-ysql.md | 2 +- .../content/v2.18/drivers-orms/java/_index.md | 2 +- .../v2.18/drivers-orms/smart-drivers.md | 26 ++++-- .../transactions/transactions-retries-ysql.md | 2 +- .../drivers-orms/include-drivers-orms-list.md | 2 +- .../content/v2.20/drivers-orms/java/_index.md | 2 +- .../v2.20/drivers-orms/java/yugabyte-jdbc.md | 28 ++++-- .../content/v2.20/drivers-orms/nodejs/ycql.md | 2 +- .../v2.20/drivers-orms/smart-drivers-ycql.md | 2 +- .../v2.20/drivers-orms/smart-drivers.md | 87 ++++++++++++++++-- 39 files changed, 348 insertions(+), 115 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 index fead512a3adc..430c30208097 100644 --- 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
[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
[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/) | diff --git a/docs/content/preview/drivers-orms/java/_index.md b/docs/content/preview/drivers-orms/java/_index.md index 2444974428c2..8d0413b7d5fb 100644 --- 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/)
[Reference](yugabyte-jdbc-reference/)
[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/)
[Reference](yugabyte-jdbc-reference/)
[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/)
[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 index d4376fff581a..a8ee30e1dadf 100644 --- 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-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: diff --git a/docs/content/preview/drivers-orms/java/yugabyte-jdbc-reference.md b/docs/content/preview/drivers-orms/java/yugabyte-jdbc-reference.md index e549e88e16dd..c8e88e8cae3d 100644 --- a/docs/content/preview/drivers-orms/java/yugabyte-jdbc-reference.md +++ b/docs/content/preview/drivers-orms/java/yugabyte-jdbc-reference.md @@ -56,7 +56,7 @@ To get the driver and HikariPool from Maven, add the following dependencies to t com.yugabyte jdbc-yugabytedb - 42.3.5-yb-5 + 42.3.5-yb-7 @@ -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' ``` diff --git a/docs/content/preview/drivers-orms/java/yugabyte-jdbc.md b/docs/content/preview/drivers-orms/java/yugabyte-jdbc.md index 56e2063312f8..b8525c6bf6e2 100644 --- a/docs/content/preview/drivers-orms/java/yugabyte-jdbc.md +++ b/docs/content/preview/drivers-orms/java/yugabyte-jdbc.md @@ -88,7 +88,7 @@ If you are using [Maven](https://maven.apache.org/guides/development/guide-build com.yugabyte jdbc-yugabytedb - 42.3.5-yb-5 + 42.3.5-yb-7 @@ -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' ``` @@ -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: @@ -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 @@ -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. @@ -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 { diff --git a/docs/content/preview/drivers-orms/nodejs/ycql.md b/docs/content/preview/drivers-orms/nodejs/ycql.md index 82dd441e24eb..bbd9c64dfc2a 100644 --- a/docs/content/preview/drivers-orms/nodejs/ycql.md +++ b/docs/content/preview/drivers-orms/nodejs/ycql.md @@ -33,7 +33,7 @@ type: docs -[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" >}} diff --git a/docs/content/preview/drivers-orms/orms/java/ysql-ebean.md b/docs/content/preview/drivers-orms/orms/java/ysql-ebean.md index c9f964543f08..2bad348d0fa1 100644 --- 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-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: diff --git a/docs/content/preview/drivers-orms/smart-drivers-ycql.md b/docs/content/preview/drivers-orms/smart-drivers-ycql.md index e645f3ee44ac..5cead2f8ac84 100644 --- a/docs/content/preview/drivers-orms/smart-drivers-ycql.md +++ b/docs/content/preview/drivers-orms/smart-drivers-ycql.md @@ -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 diff --git a/docs/content/preview/drivers-orms/smart-drivers.md b/docs/content/preview/drivers-orms/smart-drivers.md index 3e0cd891b5cd..3945f6833400 100644 --- a/docs/content/preview/drivers-orms/smart-drivers.md +++ b/docs/content/preview/drivers-orms/smart-drivers.md @@ -39,14 +39,15 @@ YugabyteDB smart drivers have the following key features. | Feature | Notes | | :--- | :--- | | Multiple hosts | As with the upstream driver (with the exception of node.js), you can specify multiple hosts for the initial connection, to avoid dropping connections in the case where the primary host is unavailable. | -| [Cluster aware](#cluster-aware-connection-load-balancing) | Smart drivers perform automatic uniform connection load balancing
After the driver establishes an initial connection, it fetches the list of available servers from the cluster and distributes connections evenly across these servers. | -| [Topology aware](#topology-aware-connection-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. | +| [Cluster aware](#cluster-aware-load-balancing) | Smart drivers perform automatic uniform connection load balancing
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). | | [Connection pooling](#connection-pooling) | Like the upstream driver, smart drivers support popular connection pooling solutions. | ## Overview -YugabyteDB is a distributed, fault tolerant, and highly available database with low latencies for reads and writes. Data in YugabyteDB is automatically sharded, replicated, and balanced across multiple nodes that can potentially be in different availability zones and regions. For better performance and fault tolerance, you can also balance application traffic (database connections) across the nodes in the universe to avoid excessive CPU and memory load on any single node. +YugabyteDB is distributed, fault tolerant, and highly available. YugabyteDB automatically shards, replicates, and balances data across multiple nodes, which can be in different availability zones and regions. For better performance and fault tolerance, you can also balance application traffic (database connections) across the nodes in the universe to avoid excessive CPU and memory load on any single node. You can load balance application connections to the database in the following ways: @@ -82,11 +83,11 @@ Developers can use smart driver connection load balancing in two configurations: In both cases, the driver attempts to connect to the least loaded server from the available group of servers. For topology-aware load balancing, this group is determined by geo-locations specified using the topology keys connection parameter. -### Cluster-aware connection load balancing +### Cluster-aware load balancing With cluster-aware (also referred to as uniform) connection load balancing, connections are distributed uniformly across all the YB-TServers in the cluster, irrespective of their placement. -For example, if a client application creates a hundred connections to a YugabyteDB universe consisting of ten nodes, then the driver creates ten connections to each node. If the number of connections is not exactly divisible by the number of servers, then some servers may have one less or one more connection than the others. This is the client view of the load, so the servers may not be well-balanced if other client applications are not using a smart driver +For example, if a client application creates a hundred connections to a YugabyteDB universe consisting of ten nodes, then the driver creates ten connections to each node. If the number of connections is not exactly divisible by the number of servers, then some servers may have one less or one more connection than the others. This is the client view of the load, so the servers may not be well-balanced if other client applications are not using a smart driver. A connection works as follows: @@ -124,7 +125,23 @@ For example, using the Go smart driver, you can change the interval to four minu (Note that currently this feature is not available in the YugabyteDB Python Smart Driver.) -### Topology-aware connection load balancing +### 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. + +To support this, the load balance property accepts the following additional values. + +| Value | Description | +| :--- | :--- | +| any | Distribute connections equally across all nodes in the cluster, irrespective of type (primary or read replica). This is an alias for value _true_. | +| only-primary | Create connections equally across only primary nodes. If none are available, fail. | +| only-rr | Create connections equally across only read replica nodes. If none are available, fail. | +| prefer‑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`. + +### Topology-aware load balancing For a database deployment that spans multiple regions, evenly distributing requests across all database nodes may not be optimal. With topology-aware connection load balancing, you can target nodes in specified geo-locations. The driver then distributes connections uniformly among the nodes in the specified locations. This is beneficial in the following situations: @@ -162,9 +179,59 @@ 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 no servers are available, the request may return with a failure. -### Connection pooling +### 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. + +The following shows how nodes are selected for new connections, depending on the load balance and topology key settings. + +{{}} +{{% tab header="No topology keys" lang="no-keys" %}} + +When no topology keys are 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 | + +{{% /tab %}} +{{% tab header="Topology keys" lang="100-wh" %}} + +When topology keys are specified as zoneA:1, zoneB:2, nodes are selected as follows. + +| Load balance setting | Connect to | +| :--- | :--- | +| true / any |
  1. Any nodes in zoneA
  2. If none, then any nodes in zoneB
  3. If none, then any nodes in entire cluster (all zones) | +| only-primary |
    1. Primary nodes in zoneA
    2. If none, then primary nodes in zoneB
    3. If none, then primary nodes in entire cluster (all zones)
    4. If none, fail | +| only-rr |
      1. Read replica nodes in zoneB
      2. If none, read replica nodes in entire cluster (all zones)
      3. If none, fail | +| prefer-primary |
        1. Primary nodes in zoneA
        2. If none, primary nodes in zoneB
        3. If none, then primary nodes in entire cluster
        4. If none, then read replica nodes in entire cluster | +| prefer-rr |
          1. Read replica nodes in zoneB
          2. If none, read replica nodes in entire cluster
          3. If none, then primary nodes in entire cluster | + +{{% /tab %}} +{{% tab header="Fall back to topology keys" lang="100-wh" %}} + +When topology keys are specified as zoneA:1, zoneB:2, and fallback to topology keys only is true, nodes are selected as follows. + +| Load balance setting | Connect to | +| :--- | :--- | +| true / any |
            1. Any nodes in zoneA
            2. If none, then any nodes in zoneB
            3. If none, then fail | +| only-primary |
              1. Primary nodes in zoneA
              2. If none, then primary nodes in zoneB
              3. If none, fail | +| only-rr |
                1. Read replica nodes in zoneB
                2. If none, fail | +| prefer-primary |
                  1. Primary nodes in zoneA
                  2. If none, primary nodes in zoneB
                  3. If none, then primary nodes in entire cluster
                  4. If none, then read replica nodes in entire cluster | +| prefer-rr |
                    1. Read replica nodes in zoneB
                    2. If none, read replica nodes in entire cluster
                    3. If none, then primary nodes in entire cluster | + +{{% /tab %}} +{{}} + +## Connection pooling Smart drivers can be configured with popular pooling solutions such as Hikari and Tomcat. Different pools can be configured with different load balancing policies if required. For example, an application can configure one pool with topology awareness for one region and its availability zones, and configure another pool to communicate with a completely different region. @@ -176,17 +243,17 @@ For an example of how connection pooling reduces latencies, see [Database Connec ## Using smart drivers with YugabyteDB Aeon -[YugabyteDB Aeon](../../yugabyte-cloud/) clusters automatically use the uniform load balancing provided by the cloud provider where the cluster is provisioned. YugabyteDB Aeon creates an external load balancer to distribute the load across the nodes in a particular region. For multi-region clusters, each region has its own external load balancer. +[YugabyteDB Aeon](/preview/yugabyte-cloud/) clusters automatically use the uniform load balancing provided by the cloud provider where the cluster is provisioned. YugabyteDB Aeon creates an external load balancer to distribute the load across the nodes in a particular region. For multi-region clusters, each region has its own external load balancer. When connecting using an upstream driver, you connect to the region of choice, and application connections are then uniformly distributed across the region without the need for any special coding. If you are using a smart driver, you can connect to any region and the load balancer acts as a discovery endpoint, allowing the application to use connections to nodes in all regions. -YugabyteDB Aeon clusters also support topology-aware load balancing. If the cluster has a [preferred region](../../yugabyte-cloud/cloud-basics/create-clusters/create-clusters-multisync/#preferred-region), set the topology keys to a zone in that region for best performance. +YugabyteDB Aeon clusters also support topology-aware load balancing. If the cluster has a [preferred region](/preview/yugabyte-cloud/cloud-basics/create-clusters/create-clusters-multisync/#preferred-region), set the topology keys to a zone in that region for best performance. ### Deploying applications -To take advantage of smart driver load balancing features when connecting to clusters in YugabyteDB Aeon, applications using smart drivers must be deployed in a VPC that has been [peered with the cluster VPC](../../yugabyte-cloud/cloud-basics/cloud-vpcs/cloud-add-peering/). For applications that access the cluster from outside the peered network or using private endpoints via a private link, set the load balance connection parameter to `false`; in this case, the cluster performs the load balancing. +To take advantage of smart driver load balancing features when connecting to clusters in YugabyteDB Aeon, applications using smart drivers must be deployed in a VPC that has been [peered with the cluster VPC](/preview/yugabyte-cloud/cloud-basics/cloud-vpcs/cloud-add-peering/). For applications that access the cluster from outside the peered network or using private endpoints via a private link, set the load balance connection parameter to `false`; in this case, the cluster performs the load balancing. Applications that use smart drivers from outside the peered network with load balance on will try to connect to the inaccessible nodes before falling back to the upstream driver behavior. You may see a warning similar to the following: @@ -196,7 +263,7 @@ WARNING [com.yug.Driver] (agroal-11) Failed to apply load balance. Trying normal This indicates that the smart driver was unable to perform smart load balancing. To avoid the added latency incurred, turn load balance off. -For information on VPC peering in YugabyteDB Aeon, refer to [VPC network](../../yugabyte-cloud/cloud-basics/cloud-vpcs/). +For information on VPC peering in YugabyteDB Aeon, refer to [VPC network](/preview/yugabyte-cloud/cloud-basics/cloud-vpcs/). ### SSL/TLS verify-full support diff --git a/docs/content/preview/integrations/apache-spark/java-ysql.md b/docs/content/preview/integrations/apache-spark/java-ysql.md index ec895b43680a..4850eee5f761 100644 --- 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: com.yugabyte jdbc-yugabytedb - 42.3.5-yb-5 + 42.3.5-yb-7 ``` diff --git a/docs/content/preview/integrations/apache-spark/python-ysql.md b/docs/content/preview/integrations/apache-spark/python-ysql.md index a76e48d71ee6..942fc29f8c37 100644 --- 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-5 +./bin/pyspark --packages com.yugabyte:jdbc-yugabytedb:42.3.5-yb-7 ``` The Spark session should be available as follows: diff --git a/docs/content/preview/integrations/apache-spark/scala-ysql.md b/docs/content/preview/integrations/apache-spark/scala-ysql.md index 7fc1bdf055f0..ec4a167268c0 100644 --- a/docs/content/preview/integrations/apache-spark/scala-ysql.md +++ b/docs/content/preview/integrations/apache-spark/scala-ysql.md @@ -57,7 +57,7 @@ This tutorial assumes that you have: From your Spark installation directory, use the following command to start `spark-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/spark-shell --packages com.yugabyte:jdbc-yugabytedb:42.3.5-yb-5 +./bin/spark-shell --packages com.yugabyte:jdbc-yugabytedb:42.3.5-yb-7 ``` The Scala prompt should be available as follows: diff --git a/docs/content/preview/integrations/apache-spark/spark-sql.md b/docs/content/preview/integrations/apache-spark/spark-sql.md index e3dd7efe5a6f..fc16aa1d9c8a 100644 --- a/docs/content/preview/integrations/apache-spark/spark-sql.md +++ b/docs/content/preview/integrations/apache-spark/spark-sql.md @@ -58,7 +58,7 @@ This tutorial assumes that you have: From your Spark installation directory, use the following command to start `spark-sql`, 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/spark-sql --packages com.yugabyte:jdbc-yugabytedb:42.3.5-yb-5 +./bin/spark-sql --packages com.yugabyte:jdbc-yugabytedb:42.3.5-yb-7 ``` The Spark prompt should be available as `spark-sql>`. diff --git a/docs/content/preview/integrations/camunda.md b/docs/content/preview/integrations/camunda.md index 29fbf76ceec2..40b44f33dd0f 100644 --- a/docs/content/preview/integrations/camunda.md +++ b/docs/content/preview/integrations/camunda.md @@ -56,7 +56,7 @@ This tutorial assumes that: password: yugabyte ``` - Then, download the YugabyteDB JDBC driver [JAR file](https://repo1.maven.org/maven2/com/yugabyte/jdbc-yugabytedb/42.3.5-yb-5/jdbc-yugabytedb-42.3.5-yb-5.jar) and place it in the `camunda-bpm-run-7.17.0/configuration/userlib` directory. Read more about the [YugabyteDB JDBC driver](../../drivers-orms/java/yugabyte-jdbc-reference/). + Then, download the YugabyteDB JDBC driver [JAR file](https://repo1.maven.org/maven2/com/yugabyte/jdbc-yugabytedb/42.3.5-yb-7/jdbc-yugabytedb-42.3.5-yb-7.jar) and place it in the `camunda-bpm-run-7.17.0/configuration/userlib` directory. Read more about the [YugabyteDB JDBC driver](../../drivers-orms/java/yugabyte-jdbc-reference/). 1. Start the Camunda Platform server using `./start.sh` on Linux or macOS, or `./start.bat` on Windows. diff --git a/docs/content/preview/integrations/flyway.md b/docs/content/preview/integrations/flyway.md index d77bead9cc19..6e5d957f2ce8 100644 --- a/docs/content/preview/integrations/flyway.md +++ b/docs/content/preview/integrations/flyway.md @@ -44,8 +44,7 @@ To use Flyway with YugabyteDB, you need the following: com.yugabyte jdbc-yugabytedb - 42.3.5-yb-5 - test + 42.3.5-yb-7 ``` diff --git a/docs/content/preview/integrations/spring-framework/sd-jpa.md b/docs/content/preview/integrations/spring-framework/sd-jpa.md index dd783bdc6cdf..33e947f71193 100644 --- a/docs/content/preview/integrations/spring-framework/sd-jpa.md +++ b/docs/content/preview/integrations/spring-framework/sd-jpa.md @@ -39,7 +39,7 @@ Add the following dependencies for Spring Data JPA with [YugabyteDB JDBC Driver] com.yugabyte jdbc-yugabytedb - 42.3.5-yb-5 + 42.3.5-yb-7 ``` diff --git a/docs/content/preview/integrations/spring-framework/sdyb.md b/docs/content/preview/integrations/spring-framework/sdyb.md index ae3dce8f4413..f92ea32d276b 100644 --- a/docs/content/preview/integrations/spring-framework/sdyb.md +++ b/docs/content/preview/integrations/spring-framework/sdyb.md @@ -48,7 +48,7 @@ The project definition includes the following dependencies: com.yugabyte jdbc-yugabytedb - 42.3.5-yb-5 + 42.3.5-yb-7 ``` diff --git a/docs/content/preview/quick-start/docker.md b/docs/content/preview/quick-start/docker.md index 826b0b043787..ac6ef0676571 100644 --- a/docs/content/preview/quick-start/docker.md +++ b/docs/content/preview/quick-start/docker.md @@ -232,7 +232,7 @@ Perform the following to create a sample Java project: com.yugabyte jdbc-yugabytedb - 42.3.5-yb-5 + 42.3.5-yb-7 diff --git a/docs/content/preview/quick-start/kubernetes.md b/docs/content/preview/quick-start/kubernetes.md index add43e772ca2..863ab18183dc 100644 --- a/docs/content/preview/quick-start/kubernetes.md +++ b/docs/content/preview/quick-start/kubernetes.md @@ -300,7 +300,7 @@ Perform the following to create a sample Java project: com.yugabyte jdbc-yugabytedb - 42.3.5-yb-5 + 42.3.5-yb-7 diff --git a/docs/content/preview/tutorials/build-and-learn/chapter3-tolerating-outages.md b/docs/content/preview/tutorials/build-and-learn/chapter3-tolerating-outages.md index 524af9ef3ac7..d76f28e924e8 100644 --- a/docs/content/preview/tutorials/build-and-learn/chapter3-tolerating-outages.md +++ b/docs/content/preview/tutorials/build-and-learn/chapter3-tolerating-outages.md @@ -245,7 +245,7 @@ The YugaPlus movies recommendation service, written in Java, already includes th com.yugabyte jdbc-yugabytedb - 42.3.5-yb-5 + 42.3.5-yb-7 ``` diff --git a/docs/content/stable/drivers-orms/include-drivers-orms-list.md b/docs/content/stable/drivers-orms/include-drivers-orms-list.md index bbce055d265c..11ee44cd9550 100644 --- a/docs/content/stable/drivers-orms/include-drivers-orms-list.md +++ b/docs/content/stable/drivers-orms/include-drivers-orms-list.md @@ -11,7 +11,7 @@ private = true | | Version | Support Level | Example apps | | :--------- | :------ | :------------ | :----------- | | **Drivers** | | | | -| YugabyteDB JDBC Smart Driver
                      [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
                      [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/) | diff --git a/docs/content/stable/drivers-orms/java/_index.md b/docs/content/stable/drivers-orms/java/_index.md index 35d57632c42b..fb78d0ddd88f 100644 --- a/docs/content/stable/drivers-orms/java/_index.md +++ b/docs/content/stable/drivers-orms/java/_index.md @@ -19,7 +19,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/)
                      [Reference](yugabyte-jdbc-reference/)
                      [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/)
                      [Reference](yugabyte-jdbc-reference/)
                      [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/)
                      [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/stable/drivers-orms/java/ebean.md b/docs/content/stable/drivers-orms/java/ebean.md index 85e94367dbe5..61e52b06ec67 100644 --- a/docs/content/stable/drivers-orms/java/ebean.md +++ b/docs/content/stable/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-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: diff --git a/docs/content/stable/drivers-orms/java/yugabyte-jdbc-reference.md b/docs/content/stable/drivers-orms/java/yugabyte-jdbc-reference.md index adf82799b3d9..733cd19f7364 100644 --- a/docs/content/stable/drivers-orms/java/yugabyte-jdbc-reference.md +++ b/docs/content/stable/drivers-orms/java/yugabyte-jdbc-reference.md @@ -54,7 +54,7 @@ To get the driver and HikariPool from Maven, add the following dependencies to t com.yugabyte jdbc-yugabytedb - 42.3.5-yb-5 + 42.3.5-yb-7 @@ -71,7 +71,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' ``` diff --git a/docs/content/stable/drivers-orms/java/yugabyte-jdbc.md b/docs/content/stable/drivers-orms/java/yugabyte-jdbc.md index 2751e8649e2e..3062d227026b 100644 --- a/docs/content/stable/drivers-orms/java/yugabyte-jdbc.md +++ b/docs/content/stable/drivers-orms/java/yugabyte-jdbc.md @@ -81,7 +81,7 @@ If you are using [Maven](https://maven.apache.org/guides/development/guide-build com.yugabyte jdbc-yugabytedb - 42.3.5-yb-5 + 42.3.5-yb-7 @@ -99,7 +99,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' ``` @@ -115,14 +115,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 | + +Starting with version 42.3.5-yb-7, 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 JDBC URL for connecting to YugabyteDB: @@ -157,10 +161,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. @@ -199,6 +203,9 @@ 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 your connections to be load-balanced across only the read-replica nodes, + // set the load-balance property to 'only-rr' as shown below. + // 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 { diff --git a/docs/content/stable/drivers-orms/nodejs/ycql.md b/docs/content/stable/drivers-orms/nodejs/ycql.md index b2df65b07b32..b47c592fea1a 100644 --- a/docs/content/stable/drivers-orms/nodejs/ycql.md +++ b/docs/content/stable/drivers-orms/nodejs/ycql.md @@ -33,7 +33,7 @@ type: docs
                      4. -[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" >}} diff --git a/docs/content/stable/drivers-orms/orms/java/ysql-ebean.md b/docs/content/stable/drivers-orms/orms/java/ysql-ebean.md index 637054bbbd9e..b0d6dc54e5cf 100644 --- a/docs/content/stable/drivers-orms/orms/java/ysql-ebean.md +++ b/docs/content/stable/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-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: diff --git a/docs/content/stable/drivers-orms/smart-drivers-ycql.md b/docs/content/stable/drivers-orms/smart-drivers-ycql.md index 91982a500372..464c36fc966e 100644 --- a/docs/content/stable/drivers-orms/smart-drivers-ycql.md +++ b/docs/content/stable/drivers-orms/smart-drivers-ycql.md @@ -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 diff --git a/docs/content/stable/drivers-orms/smart-drivers.md b/docs/content/stable/drivers-orms/smart-drivers.md index 0ece1b27a61a..c2e06fa5840d 100644 --- a/docs/content/stable/drivers-orms/smart-drivers.md +++ b/docs/content/stable/drivers-orms/smart-drivers.md @@ -39,14 +39,15 @@ YugabyteDB smart drivers have the following key features. | Feature | Notes | | :--- | :--- | | Multiple hosts | As with the upstream driver (with the exception of node.js), you can specify multiple hosts for the initial connection, to avoid dropping connections in the case where the primary host is unavailable. | -| [Cluster aware](#cluster-aware-connection-load-balancing) | Smart drivers perform automatic uniform connection load balancing
                      After the driver establishes an initial connection, it fetches the list of available servers from the cluster and distributes connections evenly across these servers. | -| [Topology aware](#topology-aware-connection-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. | +| [Cluster aware](#cluster-aware-load-balancing) | Smart drivers perform automatic uniform connection load balancing
                      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). | | [Connection pooling](#connection-pooling) | Like the upstream driver, smart drivers support popular connection pooling solutions. | ## Overview -YugabyteDB is a distributed, fault tolerant, and highly available database with low latencies for reads and writes. Data in YugabyteDB is automatically sharded, replicated, and balanced across multiple nodes that can potentially be in different availability zones and regions. For better performance and fault tolerance, you can also balance application traffic (database connections) across the nodes in the universe to avoid excessive CPU and memory load on any single node. +YugabyteDB is distributed, fault tolerant, and highly available. YugabyteDB automatically shards, replicates, and balances data across multiple nodes, which can be in different availability zones and regions. For better performance and fault tolerance, you can also balance application traffic (database connections) across the nodes in the universe to avoid excessive CPU and memory load on any single node. You can load balance application connections to the database in the following ways: @@ -82,11 +83,11 @@ Developers can use smart driver connection load balancing in two configurations: In both cases, the driver attempts to connect to the least loaded server from the available group of servers. For topology-aware load balancing, this group is determined by geo-locations specified using the topology keys connection parameter. -### Cluster-aware connection load balancing +### Cluster-aware load balancing With cluster-aware (also referred to as uniform) connection load balancing, connections are distributed uniformly across all the YB-TServers in the cluster, irrespective of their placement. -For example, if a client application creates a hundred connections to a YugabyteDB universe consisting of ten nodes, then the driver creates ten connections to each node. If the number of connections is not exactly divisible by the number of servers, then some servers may have one less or one more connection than the others. This is the client view of the load, so the servers may not be well-balanced if other client applications are not using a smart driver +For example, if a client application creates a hundred connections to a YugabyteDB universe consisting of ten nodes, then the driver creates ten connections to each node. If the number of connections is not exactly divisible by the number of servers, then some servers may have one less or one more connection than the others. This is the client view of the load, so the servers may not be well-balanced if other client applications are not using a smart driver. A connection works as follows: @@ -124,7 +125,23 @@ For example, using the Go smart driver, you can change the interval to four minu (Note that currently this feature is not available in the YugabyteDB Python Smart Driver.) -### Topology-aware connection load balancing +### 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. + +To support this, the load balance property accepts the following additional values. + +| Value | Description | +| :--- | :--- | +| any | Distribute connections equally across all nodes in the cluster, irrespective of type (primary or read replica). This is an alias for value _true_. | +| only-primary | Create connections equally across only primary nodes. If none are available, fail. | +| only-rr | Create connections equally across only read replica nodes. If none are available, fail. | +| prefer‑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`. + +### Topology-aware load balancing For a database deployment that spans multiple regions, evenly distributing requests across all database nodes may not be optimal. With topology-aware connection load balancing, you can target nodes in specified geo-locations. The driver then distributes connections uniformly among the nodes in the specified locations. This is beneficial in the following situations: @@ -162,8 +179,58 @@ 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 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. + +The following shows how nodes are selected for new connections, depending on the load balance and topology key settings. + +{{}} +{{% tab header="No topology keys" lang="no-keys" %}} + +When no topology keys are 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 | + +{{% /tab %}} +{{% tab header="Topology keys" lang="100-wh" %}} + +When topology keys are specified as zoneA:1, zoneB:2, nodes are selected as follows. + +| Load balance setting | Connect to | +| :--- | :--- | +| true / any |
                      1. Any nodes in zoneA
                      2. If none, then any nodes in zoneB
                      3. If none, then any nodes in entire cluster (all zones) | +| only-primary |
                        1. Primary nodes in zoneA
                        2. If none, then primary nodes in zoneB
                        3. If none, then primary nodes in entire cluster (all zones)
                        4. If none, fail | +| only-rr |
                          1. Read replica nodes in zoneB
                          2. If none, read replica nodes in entire cluster (all zones)
                          3. If none, fail | +| prefer-primary |
                            1. Primary nodes in zoneA
                            2. If none, primary nodes in zoneB
                            3. If none, then primary nodes in entire cluster
                            4. If none, then read replica nodes in entire cluster | +| prefer-rr |
                              1. Read replica nodes in zoneB
                              2. If none, read replica nodes in entire cluster
                              3. If none, then primary nodes in entire cluster | + +{{% /tab %}} +{{% tab header="Fall back to topology keys" lang="100-wh" %}} + +When topology keys are specified as zoneA:1, zoneB:2, and fallback to topology keys only is true, nodes are selected as follows. + +| Load balance setting | Connect to | +| :--- | :--- | +| true / any |
                                1. Any nodes in zoneA
                                2. If none, then any nodes in zoneB
                                3. If none, then fail | +| only-primary |
                                  1. Primary nodes in zoneA
                                  2. If none, then primary nodes in zoneB
                                  3. If none, fail | +| only-rr |
                                    1. Read replica nodes in zoneB
                                    2. If none, fail | +| prefer-primary |
                                      1. Primary nodes in zoneA
                                      2. If none, primary nodes in zoneB
                                      3. If none, then primary nodes in entire cluster
                                      4. If none, then read replica nodes in entire cluster | +| prefer-rr |
                                        1. Read replica nodes in zoneB
                                        2. If none, read replica nodes in entire cluster
                                        3. If none, then primary nodes in entire cluster | + +{{% /tab %}} +{{}} + ### Connection pooling Smart drivers can be configured with popular pooling solutions such as Hikari and Tomcat. Different pools can be configured with different load balancing policies if required. For example, an application can configure one pool with topology awareness for one region and its availability zones, and configure another pool to communicate with a completely different region. @@ -176,27 +243,27 @@ For an example of how connection pooling reduces latencies, see [Database Connec ## Using smart drivers with YugabyteDB Aeon -[YugabyteDB Aeon](../../yugabyte-cloud/) clusters automatically use the uniform load balancing provided by the cloud provider where the cluster is provisioned. YugabyteDB Aeon creates an external load balancer to distribute the load across the nodes in a particular region. For multi-region clusters, each region has its own external load balancer. +[YugabyteDB Aeon](/preview/yugabyte-cloud/) clusters automatically use the uniform load balancing provided by the cloud provider where the cluster is provisioned. YugabyteDB Aeon creates an external load balancer to distribute the load across the nodes in a particular region. For multi-region clusters, each region has its own external load balancer. When connecting using an upstream driver, you connect to the region of choice, and application connections are then uniformly distributed across the region without the need for any special coding. If you are using a smart driver, you can connect to any region and the load balancer acts as a discovery endpoint, allowing the application to use connections to nodes in all regions. -YugabyteDB Aeon clusters also support topology-aware load balancing. If the cluster has a [preferred region](../../yugabyte-cloud/cloud-basics/create-clusters/create-clusters-multisync/#preferred-region), set the topology keys to a zone in that region for best performance. +YugabyteDB Aeon clusters also support topology-aware load balancing. If the cluster has a [preferred region](/preview/yugabyte-cloud/cloud-basics/create-clusters/create-clusters-multisync/#preferred-region), set the topology keys to a zone in that region for best performance. ### Deploying applications -To take advantage of smart driver load balancing features when connecting to clusters in YugabyteDB Aeon, applications using smart drivers must be deployed in a VPC that has been peered with the cluster VPC. For information on VPC peering in YugabyteDB Aeon, refer to [VPC network](../../yugabyte-cloud/cloud-basics/cloud-vpcs/). +To take advantage of smart driver load balancing features when connecting to clusters in YugabyteDB Aeon, applications using smart drivers must be deployed in a VPC that has been [peered with the cluster VPC](/preview/yugabyte-cloud/cloud-basics/cloud-vpcs/cloud-add-peering/). For applications that access the cluster from outside the peered network or using private endpoints via a private link, set the load balance connection parameter to `false`; in this case, the cluster performs the load balancing. -Applications that use smart drivers from outside the peered network fall back to the upstream driver behavior automatically. You may see a warning similar to the following: +Applications that use smart drivers from outside the peered network with load balance on will try to connect to the inaccessible nodes before falling back to the upstream driver behavior. You may see a warning similar to the following: ```output WARNING [com.yug.Driver] (agroal-11) Failed to apply load balance. Trying normal connection ``` -This indicates that the smart driver was unable to perform smart load balancing, and will fall back to the upstream behavior. +This indicates that the smart driver was unable to perform smart load balancing. To avoid the added latency incurred, turn load balance off. -For applications that access the cluster from outside the peered network or using private endpoints via a private link, use the upstream PostgreSQL driver instead; in this case, the cluster performs the load balancing. +For information on VPC peering in YugabyteDB Aeon, refer to [VPC network](/preview/yugabyte-cloud/cloud-basics/cloud-vpcs/). ### SSL/TLS verify-full support diff --git a/docs/content/v2.18/develop/learn/transactions/transactions-retries-ysql.md b/docs/content/v2.18/develop/learn/transactions/transactions-retries-ysql.md index ad3aadecb2d3..a7226a87516e 100644 --- a/docs/content/v2.18/develop/learn/transactions/transactions-retries-ysql.md +++ b/docs/content/v2.18/develop/learn/transactions/transactions-retries-ysql.md @@ -82,7 +82,7 @@ SerializationFailure errors happen when multiple transactions are updating the s ERROR: 40001: All transparent retries exhausted. ``` -- All transactions are given a dynamic priority. When a deadlock is detected, the transaction with lower priority is automatically killed. For this scenario, the client might receive a message similar to the following: +- All transactions are given a dynamic priority. If another higher priority transaction aborts the current transaction, the client might receive a message similar to the following: ```output ERROR: 40001: Operation expired: Heartbeat: Transaction XXXX expired or aborted by a conflict diff --git a/docs/content/v2.18/drivers-orms/java/_index.md b/docs/content/v2.18/drivers-orms/java/_index.md index c5eee71369f9..41dd62e2246e 100644 --- a/docs/content/v2.18/drivers-orms/java/_index.md +++ b/docs/content/v2.18/drivers-orms/java/_index.md @@ -19,7 +19,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/)
                                          [Blog](https://dev.to/yugabyte/yugabytedb-jdbc-smart-driver-for-proxyless-halb-2k8a/)
                                          [Reference](../../reference/drivers/java/yugabyte-jdbc-reference/) | [42.3.5-yb-1](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.3.5-yb-1) | 2.8 and above +| YugabyteDB JDBC Driver [Recommended] | [Documentation](yugabyte-jdbc/)
                                          [Blog](https://dev.to/yugabyte/yugabytedb-jdbc-smart-driver-for-proxyless-halb-2k8a/)
                                          [Reference](../../reference/drivers/java/yugabyte-jdbc-reference/) | [42.3.5-yb-7](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.3.5-yb-7) | 2.8 and above | PostgreSQL JDBC Driver | [Documentation](postgres-jdbc/)
                                          [Reference](../../reference/drivers/java/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) | | YugabyteDB YCQL (3.10) Driver | [Documentation](ycql)
                                          [Reference](../../reference/drivers/ycql-client-drivers/#yugabyte-java-driver-for-ycql-3-10) | [3.10.3-yb-2](https://mvnrepository.com/artifact/com.yugabyte/cassandra-driver-core/3.10.3-yb-2) | | diff --git a/docs/content/v2.18/drivers-orms/smart-drivers.md b/docs/content/v2.18/drivers-orms/smart-drivers.md index 4c121a1458e6..5970938c9064 100644 --- a/docs/content/v2.18/drivers-orms/smart-drivers.md +++ b/docs/content/v2.18/drivers-orms/smart-drivers.md @@ -32,8 +32,8 @@ YugabyteDB smart drivers have the following key features. | Feature | Notes | | :--- | :--- | | Multiple hosts | As with the upstream driver (with the exception of node.js), you can specify multiple hosts for the initial connection, to avoid dropping connections in the case where the primary host is unavailable. | -| [Cluster aware](#cluster-aware-connection-load-balancing) | Smart drivers perform automatic uniform connection load balancing
                                          After the driver establishes an initial connection, it fetches the list of available servers from the cluster and distributes connections evenly across these servers. | -| [Topology aware](#topology-aware-connection-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. | +| [Cluster aware](#cluster-aware-load-balancing) | Smart drivers perform automatic uniform connection load balancing
                                          After the driver establishes an initial connection, it fetches the list of available servers from the cluster and distributes connections evenly across these servers. | +| [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). | | [Connection pooling](#connection-pooling) | Like the upstream driver, smart drivers support popular connection pooling solutions. | @@ -75,7 +75,7 @@ Developers can use smart driver connection load balancing in two configurations: In both cases, the driver attempts to connect to the least loaded server from the available group of servers. For topology-aware load balancing, this group is determined by geo-locations specified using the topology keys connection parameter. -### Cluster-aware connection load balancing +### Cluster-aware load balancing With cluster-aware (also referred to as uniform) connection load balancing, connections are distributed uniformly across all the YB-TServers in the cluster, irrespective of their placement. @@ -117,7 +117,7 @@ For example, using the Go smart driver, you can change the interval to four minu (Note that currently this feature is not available in the YugabyteDB Python Smart Driver.) -### Topology-aware connection load balancing +### Topology-aware load balancing For a database deployment that spans multiple regions, evenly distributing requests across all database nodes may not be optimal. With topology-aware connection load balancing, you can target nodes in specified geo-locations. The driver then distributes connections uniformly among the nodes in the specified locations. This is beneficial in the following situations: @@ -169,17 +169,27 @@ For an example of how connection pooling reduces latencies, see [Database Connec ## Using smart drivers with YugabyteDB Aeon -[YugabyteDB Aeon](../../yugabyte-cloud/) clusters automatically use the uniform load balancing provided by the cloud provider where the cluster is provisioned. YugabyteDB Aeon creates an external load balancer to distribute the load across the nodes in a particular region. For multi-region clusters, each region has its own external load balancer. +[YugabyteDB Aeon](/preview/yugabyte-cloud/) clusters automatically use the uniform load balancing provided by the cloud provider where the cluster is provisioned. YugabyteDB Aeon creates an external load balancer to distribute the load across the nodes in a particular region. For multi-region clusters, each region has its own external load balancer. When connecting using an upstream driver, you connect to the region of choice, and application connections are then uniformly distributed across the region without the need for any special coding. If you are using a smart driver, you can connect to any region and the load balancer acts as a discovery endpoint, allowing the application to use connections to nodes in all regions. -YugabyteDB Aeon clusters also support topology-aware load balancing. If the cluster has a [preferred region](../../yugabyte-cloud/cloud-basics/create-clusters/create-clusters-multisync/#preferred-region), set the topology keys to a zone in that region for best performance. +YugabyteDB Aeon clusters also support topology-aware load balancing. If the cluster has a [preferred region](/preview/yugabyte-cloud/cloud-basics/create-clusters/create-clusters-multisync/#preferred-region), set the topology keys to a zone in that region for best performance. -Applications using smart drivers must be deployed in a VPC that has been peered with the cluster VPC. For information on VPC networking in YugabyteDB Aeon, refer to [VPC network](../../yugabyte-cloud/cloud-basics/cloud-vpcs/). +### Deploying applications -For applications that access the cluster from a non-peered network, use the upstream PostgreSQL driver instead; in this case, the cluster performs the load balancing. Applications that use smart drivers from non-peered networks fall back to the upstream driver behavior automatically. +To take advantage of smart driver load balancing features when connecting to clusters in YugabyteDB Aeon, applications using smart drivers must be deployed in a VPC that has been [peered with the cluster VPC](/preview/yugabyte-cloud/cloud-basics/cloud-vpcs/cloud-add-peering/). For applications that access the cluster from outside the peered network or using private endpoints via a private link, set the load balance connection parameter to `false`; in this case, the cluster performs the load balancing. + +Applications that use smart drivers from outside the peered network with load balance on will try to connect to the inaccessible nodes before falling back to the upstream driver behavior. You may see a warning similar to the following: + +```output +WARNING [com.yug.Driver] (agroal-11) Failed to apply load balance. Trying normal connection +``` + +This indicates that the smart driver was unable to perform smart load balancing. To avoid the added latency incurred, turn load balance off. + +For information on VPC peering in YugabyteDB Aeon, refer to [VPC network](/preview/yugabyte-cloud/cloud-basics/cloud-vpcs/). ### SSL/TLS verify-full support diff --git a/docs/content/v2.20/develop/learn/transactions/transactions-retries-ysql.md b/docs/content/v2.20/develop/learn/transactions/transactions-retries-ysql.md index eb6291a430d9..694dd1b51e24 100644 --- a/docs/content/v2.20/develop/learn/transactions/transactions-retries-ysql.md +++ b/docs/content/v2.20/develop/learn/transactions/transactions-retries-ysql.md @@ -82,7 +82,7 @@ SerializationFailure errors happen when multiple transactions are updating the s ERROR: 40001: All transparent retries exhausted. ``` -- All transactions are given a dynamic priority. When a deadlock is detected, the transaction with lower priority is automatically killed. For this scenario, the client might receive a message similar to the following: +- All transactions are given a dynamic priority. If another higher priority transaction aborts the current transaction, the client might receive a message similar to the following: ```output ERROR: 40001: Operation expired: Heartbeat: Transaction XXXX expired or aborted by a conflict diff --git a/docs/content/v2.20/drivers-orms/include-drivers-orms-list.md b/docs/content/v2.20/drivers-orms/include-drivers-orms-list.md index 624c8605438c..4a3cb4cffee1 100644 --- a/docs/content/v2.20/drivers-orms/include-drivers-orms-list.md +++ b/docs/content/v2.20/drivers-orms/include-drivers-orms-list.md @@ -11,7 +11,7 @@ private = true | | Version | Support Level | Example apps | | :--------- | :------ | :------------ | :----------- | | **Drivers** | | | | -| YugabyteDB JDBC Smart Driver
                                          [Recommended] | [42.3.5-yb-3](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.3.5-yb-3) | Full | [CRUD](/preview/drivers-orms/java/yugabyte-jdbc/) | +| YugabyteDB JDBC Smart Driver
                                          [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/) | | 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/) | | YugabyteDB Java Driver for YCQL | [3.10.3-yb-2](https://mvnrepository.com/artifact/com.yugabyte/cassandra-driver-core/3.10.3-yb-2) | Full | [CRUD](/preview/drivers-orms/java/ycql) | diff --git a/docs/content/v2.20/drivers-orms/java/_index.md b/docs/content/v2.20/drivers-orms/java/_index.md index 627383205e6c..895ec0a26ccf 100644 --- a/docs/content/v2.20/drivers-orms/java/_index.md +++ b/docs/content/v2.20/drivers-orms/java/_index.md @@ -19,7 +19,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/)
                                          [Blog](https://dev.to/yugabyte/yugabytedb-jdbc-smart-driver-for-proxyless-halb-2k8a/)
                                          [Reference](../../reference/drivers/java/yugabyte-jdbc-reference/) | [42.3.5-yb-1](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.3.5-yb-1) | 2.8 and above +| YugabyteDB JDBC Driver [Recommended] | [Documentation](yugabyte-jdbc/)
                                          [Blog](https://dev.to/yugabyte/yugabytedb-jdbc-smart-driver-for-proxyless-halb-2k8a/)
                                          [Reference](../../reference/drivers/java/yugabyte-jdbc-reference/) | [42.3.5-yb-7](https://mvnrepository.com/artifact/com.yugabyte/jdbc-yugabytedb/42.3.5-yb-7) | 2.8 and above | PostgreSQL JDBC Driver | [Documentation](postgres-jdbc/)
                                          [Reference](../../reference/drivers/java/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) | | YugabyteDB YCQL (3.10) Driver | [Documentation](ycql)
                                          [Reference](../../reference/drivers/ycql-client-drivers/#java) | [3.10.3-yb-2](https://mvnrepository.com/artifact/com.yugabyte/cassandra-driver-core/3.10.3-yb-2) | | diff --git a/docs/content/v2.20/drivers-orms/java/yugabyte-jdbc.md b/docs/content/v2.20/drivers-orms/java/yugabyte-jdbc.md index 31f719b477fc..f51a5b9b3f5e 100644 --- a/docs/content/v2.20/drivers-orms/java/yugabyte-jdbc.md +++ b/docs/content/v2.20/drivers-orms/java/yugabyte-jdbc.md @@ -74,7 +74,7 @@ If you are using [Maven](https://maven.apache.org/guides/development/guide-build com.yugabyte jdbc-yugabytedb - 42.3.0 + 42.3.5-yb-7 @@ -92,7 +92,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.0' +implementation 'com.yugabyte:jdbc-yugabytedb:42.3.5-yb-7' implementation 'com.zaxxer:HikariCP:4.0.3' ``` @@ -108,14 +108,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: @@ -192,6 +196,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 { diff --git a/docs/content/v2.20/drivers-orms/nodejs/ycql.md b/docs/content/v2.20/drivers-orms/nodejs/ycql.md index e6df272f69a8..064bb9ea4fd3 100644 --- a/docs/content/v2.20/drivers-orms/nodejs/ycql.md +++ b/docs/content/v2.20/drivers-orms/nodejs/ycql.md @@ -33,7 +33,7 @@ type: docs
                                          4. -[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" >}} diff --git a/docs/content/v2.20/drivers-orms/smart-drivers-ycql.md b/docs/content/v2.20/drivers-orms/smart-drivers-ycql.md index 1c1bbd191ec2..979c83b82f4b 100644 --- a/docs/content/v2.20/drivers-orms/smart-drivers-ycql.md +++ b/docs/content/v2.20/drivers-orms/smart-drivers-ycql.md @@ -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 diff --git a/docs/content/v2.20/drivers-orms/smart-drivers.md b/docs/content/v2.20/drivers-orms/smart-drivers.md index 88e9c749957e..87a920e08f14 100644 --- a/docs/content/v2.20/drivers-orms/smart-drivers.md +++ b/docs/content/v2.20/drivers-orms/smart-drivers.md @@ -38,14 +38,15 @@ YugabyteDB smart drivers have the following key features. | Feature | Notes | | :--- | :--- | | Multiple hosts | As with the upstream driver (with the exception of node.js), you can specify multiple hosts for the initial connection, to avoid dropping connections in the case where the primary host is unavailable. | -| [Cluster aware](#cluster-aware-connection-load-balancing) | Smart drivers perform automatic uniform connection load balancing
                                          After the driver establishes an initial connection, it fetches the list of available servers from the cluster and distributes connections evenly across these servers. | -| [Topology aware](#topology-aware-connection-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. | +| [Cluster aware](#cluster-aware-load-balancing) | Smart drivers perform automatic uniform connection load balancing
                                          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). | | [Connection pooling](#connection-pooling) | Like the upstream driver, smart drivers support popular connection pooling solutions. | ## Overview -YugabyteDB is a distributed, fault tolerant, and highly available database with low latencies for reads and writes. Data in YugabyteDB is automatically sharded, replicated, and balanced across multiple nodes that can potentially be in different availability zones and regions. For better performance and fault tolerance, you can also balance application traffic (database connections) across the nodes in the universe to avoid excessive CPU and memory load on any single node. +YugabyteDB is distributed, fault tolerant, and highly available. YugabyteDB automatically shards, replicates, and balances data across multiple nodes, which can be in different availability zones and regions. For better performance and fault tolerance, you can also balance application traffic (database connections) across the nodes in the universe to avoid excessive CPU and memory load on any single node. You can load balance application connections to the database in the following ways: @@ -81,11 +82,11 @@ Developers can use smart driver connection load balancing in two configurations: In both cases, the driver attempts to connect to the least loaded server from the available group of servers. For topology-aware load balancing, this group is determined by geo-locations specified using the topology keys connection parameter. -### Cluster-aware connection load balancing +### Cluster-aware load balancing With cluster-aware (also referred to as uniform) connection load balancing, connections are distributed uniformly across all the YB-TServers in the cluster, irrespective of their placement. -For example, if a client application creates a hundred connections to a YugabyteDB universe consisting of ten nodes, then the driver creates ten connections to each node. If the number of connections is not exactly divisible by the number of servers, then some servers may have one less or one more connection than the others. This is the client view of the load, so the servers may not be well-balanced if other client applications are not using a smart driver +For example, if a client application creates a hundred connections to a YugabyteDB universe consisting of ten nodes, then the driver creates ten connections to each node. If the number of connections is not exactly divisible by the number of servers, then some servers may have one less or one more connection than the others. This is the client view of the load, so the servers may not be well-balanced if other client applications are not using a smart driver. A connection works as follows: @@ -123,7 +124,23 @@ For example, using the Go smart driver, you can change the interval to four minu (Note that currently this feature is not available in the YugabyteDB Python Smart Driver.) -### Topology-aware connection load balancing +### 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. + +To support this, the load balance property accepts the following additional values. + +| Value | Description | +| :--- | :--- | +| any | Distribute connections equally across all nodes in the cluster, irrespective of type (primary or read replica). This is an alias for value _true_. | +| only-primary | Create connections equally across only primary nodes. If none are available, fail. | +| only-rr | Create connections equally across only read replica nodes. If none are available, fail. | +| prefer‑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`. + +### Topology-aware load balancing For a database deployment that spans multiple regions, evenly distributing requests across all database nodes may not be optimal. With topology-aware connection load balancing, you can target nodes in specified geo-locations. The driver then distributes connections uniformly among the nodes in the specified locations. This is beneficial in the following situations: @@ -161,8 +178,58 @@ 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 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. + +The following shows how nodes are selected for new connections, depending on the load balance and topology key settings. + +{{}} +{{% tab header="No topology keys" lang="no-keys" %}} + +When no topology keys are 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 | + +{{% /tab %}} +{{% tab header="Topology keys" lang="100-wh" %}} + +When topology keys are specified as zoneA:1, zoneB:2, nodes are selected as follows. + +| Load balance setting | Connect to | +| :--- | :--- | +| true / any |
                                          1. Any nodes in zoneA
                                          2. If none, then any nodes in zoneB
                                          3. If none, then any nodes in entire cluster (all zones) | +| only-primary |
                                            1. Primary nodes in zoneA
                                            2. If none, then primary nodes in zoneB
                                            3. If none, then primary nodes in entire cluster (all zones)
                                            4. If none, fail | +| only-rr |
                                              1. Read replica nodes in zoneB
                                              2. If none, read replica nodes in entire cluster (all zones)
                                              3. If none, fail | +| prefer-primary |
                                                1. Primary nodes in zoneA
                                                2. If none, primary nodes in zoneB
                                                3. If none, then primary nodes in entire cluster
                                                4. If none, then read replica nodes in entire cluster | +| prefer-rr |
                                                  1. Read replica nodes in zoneB
                                                  2. If none, read replica nodes in entire cluster
                                                  3. If none, then primary nodes in entire cluster | + +{{% /tab %}} +{{% tab header="Fall back to topology keys" lang="100-wh" %}} + +When topology keys are specified as zoneA:1, zoneB:2, and fallback to topology keys only is true, nodes are selected as follows. + +| Load balance setting | Connect to | +| :--- | :--- | +| true / any |
                                                    1. Any nodes in zoneA
                                                    2. If none, then any nodes in zoneB
                                                    3. If none, then fail | +| only-primary |
                                                      1. Primary nodes in zoneA
                                                      2. If none, then primary nodes in zoneB
                                                      3. If none, fail | +| only-rr |
                                                        1. Read replica nodes in zoneB
                                                        2. If none, fail | +| prefer-primary |
                                                          1. Primary nodes in zoneA
                                                          2. If none, primary nodes in zoneB
                                                          3. If none, then primary nodes in entire cluster
                                                          4. If none, then read replica nodes in entire cluster | +| prefer-rr |
                                                            1. Read replica nodes in zoneB
                                                            2. If none, read replica nodes in entire cluster
                                                            3. If none, then primary nodes in entire cluster | + +{{% /tab %}} +{{}} + ### Connection pooling Smart drivers can be configured with popular pooling solutions such as Hikari and Tomcat. Different pools can be configured with different load balancing policies if required. For example, an application can configure one pool with topology awareness for one region and its availability zones, and configure another pool to communicate with a completely different region. @@ -185,17 +252,17 @@ YugabyteDB Aeon clusters also support topology-aware load balancing. If the clus ### Deploying applications -To take advantage of smart driver load balancing features when connecting to clusters in YugabyteDB Aeon, applications using smart drivers must be deployed in a VPC that has been peered with the cluster VPC. For information on VPC peering in YugabyteDB Aeon, refer to [VPC network](/preview/yugabyte-cloud/cloud-basics/cloud-vpcs/). +To take advantage of smart driver load balancing features when connecting to clusters in YugabyteDB Aeon, applications using smart drivers must be deployed in a VPC that has been [peered with the cluster VPC](/preview/yugabyte-cloud/cloud-basics/cloud-vpcs/cloud-add-peering/). For applications that access the cluster from outside the peered network or using private endpoints via a private link, set the load balance connection parameter to `false`; in this case, the cluster performs the load balancing. -Applications that use smart drivers from outside the peered network fall back to the upstream driver behavior automatically. You may see a warning similar to the following: +Applications that use smart drivers from outside the peered network with load balance on will try to connect to the inaccessible nodes before falling back to the upstream driver behavior. You may see a warning similar to the following: ```output WARNING [com.yug.Driver] (agroal-11) Failed to apply load balance. Trying normal connection ``` -This indicates that the smart driver was unable to perform smart load balancing, and will fall back to the upstream behavior. +This indicates that the smart driver was unable to perform smart load balancing. To avoid the added latency incurred, turn load balance off. -For applications that access the cluster from outside the peered network or using private endpoints via a private link, use the upstream PostgreSQL driver instead; in this case, the cluster performs the load balancing. +For information on VPC peering in YugabyteDB Aeon, refer to [VPC network](/preview/yugabyte-cloud/cloud-basics/cloud-vpcs/). ### SSL/TLS verify-full support