This is a distributed JDBC driver for YugabyteDB SQL. This driver is based on the PostgreSQL JDBC Driver.
This JDBC driver has the following features:
This driver adds a YBClusterAwareDataSource
that requires only an initial contact point for the YugabyteDB cluster, using which it discovers the rest of the nodes. Additionally, it automatically learns about the nodes being started/added or stopped/removed. Internally the driver keeps track of number of connections it has created to each server endpoint and every new connection request is connected to the least loaded server as per the driver's view.
This is similar to 'Cluster Awareness' but uses those servers which are part of a given set of geo-locations specified by topology-keys.
NOTE: This feature is still in the design phase.
- load-balance - It takes 'true' or 'false' as valid values. By default it is 'false' for now.
- topology-keys - It takes a comma separated geo-location values. The geo-location can be given as 'cloud:region:zone'.
Please refer to the [Use the Driver](#Use the Driver) section for examples.
Either add the following lines to your maven project in pom.xml file.
<dependency>
<groupId>com.yugabyte</groupId>
<artifactId>jdbc-yugabytedb</artifactId>
<version>42.2.7-yb-5-beta.5</version>
</dependency>
or you can visit to this link for the latest version of dependency: https://search.maven.org/artifact/com.yugabyte/jdbc-yugabytedb
-
Build environment
gpgsuite needs to be present on the machine where build is performed.
https://gpgtools.org/
Please install gpg and create a key.
-
Clone this repository.
git clone https://github.com/yugabyte/jdbc-yugabytedb.git && cd jdbc-yugabytedb
-
Build and install into your local maven folder.
mvn clean install -DskipTests
-
Finally, use it by adding the lines below to your project.
<dependency> <groupId>com.yugabyte</groupId> <artifactId>jdbc-yugabytedb</artifactId> <version>42.2.7-yb-6-SNAPSHOT</version> </dependency>
####Note: You need to have installed 2.7.2.0-b0 or above version of YugabyteDB on your system for load balancing to work.
-
Passing new connection properties for load balancing in connection url or properties bag
For uniform load balancing across all the server you just need to specify the load-balance=true property in the url.
String yburl = "jdbc:postgresql://127.0.0.1:5433/yugabyte?user=yugabyte&password=yugabyte&load-balance=true"; DriverManager.getConnection(yburl);
For specifying topology keys you need to set the additional property with a valid comma separated value, for example topology-keys=region1.zone1,region1.zone2.
String yburl = "jdbc:postgresql://127.0.0.1:5433/yugabyte?user=yugabyte&password=yugabyte&load-balance=true&topology-keys=region1.zone1,region1.zone2"; DriverManager.getConnection(yburl);
-
Create and setup the DataSource for uniform load balancing A datasource for Yugabyte has been added. It can be configured like this for load balancing behaviour.
String jdbcUrl = "jdbc:postgresql://127.0.0.1:5433/yugabyte"; YBClusterAwareDataSource ds = new YBClusterAwareDataSource(); ds.setUrl(jdbcUrl); ds.setLoadBalance("true"); // If topology aware distribution to be enabled then ds.setTopologyKeys("region1.zone1,region2.zone2"); // If you want to provide more endpoints to safeguard against even first connection failure due to the possible unavailability of initial contact point. ds.setAdditionalEndpoints("127.0.0.2:5433,127.0.0.3:5433"); Connection conn = ds.getConnection();
-
Create and setup the DataSource with a popular pooling solution like Hikari
Properties poolProperties = new Properties(); poolProperties.setProperty("dataSourceClassName", "com.yugabyte.ysql.YBClusterAwareDataSource"); poolProperties.setProperty("maximumPoolSize", 10); poolProperties.setProperty("dataSource.serverName", "127.0.0.1"); poolProperties.setProperty("dataSource.portNumber", "5433"); poolProperties.setProperty("dataSource.databaseName", "yugabyte"); poolProperties.setProperty("dataSource.user", "yugabyte"); poolProperties.setProperty("dataSource.password", "yugabyte"); poolProperties.setProperty("dataSource.loadBalance", "true"); // If you want to provide additional end points String additionalEndpoints = "127.0.0.2:5433,127.0.0.3:5433,127.0.0.4:5433,127.0.0.5:5433"; poolProperties.setProperty("dataSource.additionalEndpoints", additionalEndpoints); // If you want to load balance between specific geo locations using topology keys String geoLocations = "region1.zone1,region2.zone2"; poolProperties.setProperty("dataSource.topologyKeys", geoLocations); poolProperties.setProperty("poolName", name); HikariConfig config = new HikariConfig(poolProperties); config.validate(); HikariDataSource ds = new HikariDataSource(config); Connection conn = ds.getConnection();