If you want to prove (fast) that the YugabyteDB JDBC Smart Driver actually routes connections to the right YugabyteDB nodes, without fiddling with external load balancers, this mini app does the trick. It connects to the database, runs a single query, and shows exactly which node you landed on, along with its cloud / region / zone, using built-in geo-partitioning helper functions.
Why this works
The YugabyteDB JDBC Smart Driver is both cluster-aware and topology-aware:
• It learns the list of tablet servers (
yb_servers()) at startup and refreshes it periodically.• It can balance new connections evenly across the cluster.
• It can route connections according to topology preferences you define.
The geo-partitioning helper functions:
•
yb_server_cloud()•
yb_server_region()•
yb_server_zone()
…make it trivial to see where your current session is connected, without having to query and filter yb_servers() yourself.
Project layout
yb-smart-driver-test/
├─ pom.xml
└─ src/
└─ main/
└─ java/
└─ com/
└─ yb/
└─ smart/
└─ App.java
The Java program (App.java)
package com.yb.smart;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;
public class App {
public static void main(String[] args) {
if (args.length < 1) {
System.err.println("❌ Usage: java -jar yb-smart-driver-test.jar <JDBC_URL>");
System.exit(1);
}
String url = args[0];
try (Connection conn = DriverManager.getConnection(url);
Statement stmt = conn.createStatement()) {
String sql = "SELECT host(inet_server_addr()) AS host, " +
"yb_server_cloud() AS cloud, " +
"yb_server_region() AS region, " +
"yb_server_zone() AS zone";
ResultSet rs = stmt.executeQuery(sql);
while (rs.next()) {
System.out.printf("%nhost=%s / cloud=%s / region=%s / zone=%s%n",
rs.getString("host"),
rs.getString("cloud"),
rs.getString("region"),
rs.getString("zone"));
}
} catch (Exception e) {
e.printStackTrace();
System.err.println("❌ Failed to connect or execute query.");
}
}
}
Maven configuration (pom.xml) – builds a single runnable JAR
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.yb.smart</groupId>
<artifactId>yb-smart-driver-test</artifactId>
<version>1.0-SNAPSHOT</version>
<name>yb-smart-driver-test</name>
<properties>
<maven.compiler.release>17</maven.compiler.release>
</properties>
<dependencies>
<!-- Yugabyte JDBC Smart Driver -->
<dependency>
<groupId>com.yugabyte</groupId>
<artifactId>jdbc-yugabytedb</artifactId>
<version>42.7.3-yb-4</version>
</dependency>
</dependencies>
<build>
<plugins>
<!-- Ensure correct Java release -->
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<release>${maven.compiler.release}</release>
</configuration>
</plugin>
<!-- Create one fat JAR with all dependencies -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.5.0</version>
<executions>
<execution>
<phase>package</phase>
<goals><goal>shade</goal></goals>
<configuration>
<!-- Force the exact filename you want -->
<finalName>yb-smart-driver-test-1.0-SNAPSHOT-jar-with-dependencies</finalName>
<createDependencyReducedPom>false</createDependencyReducedPom>
<transformers>
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>com.yb.smart.App</mainClass>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
Note: Prefer Java 17+; if you’re on 11, set <maven.compiler.release>11</maven.compiler.release>.
Also, update the Yugabyte-enhanced pgJDBC driver version as needed.
Build
From the project root:
mvn -q -DskipTests package
Result:
target/yb-smart-driver-test-1.0-SNAPSHOT-jar-with-dependencies.jar
Running the test
The JDBC URL includes your username and password, so you can connect without prompting for credentials:
# Local 3-node cluster with topology preferences
java -jar yb-smart-driver-test-1.0-SNAPSHOT-jar-with-dependencies.jar \
"jdbc:yugabytedb://127.0.0.1:5433,127.0.0.2:5433,127.0.0.3:5433/yugabyte?user=yugabyte&password=yugabyte&load-balance=true&reWriteBatchedInserts&topology-keys=onprem.EAST2.*:1,onprem.CENTRAL.*:2,onprem.SCENTRAL.*:3"
# Single seed endpoint
java -jar yb-smart-driver-test-1.0-SNAPSHOT-jar-with-dependencies.jar \
"jdbc:yugabytedb://yugabytedb.tech:5433/yugabyte?user=yugabyte&password=yugabyte&load-balance=true&reWriteBatchedInserts&topology-keys=onprem.EAST2.*:1,onprem.CENTRAL.*:2,onprem.SCENTRAL.*:3"
Note: If your environment uses trust authentication, you can omit the user and password parameters entirely.
What you’ll see
Each run prints something like:
host=10.0.1.42 / cloud=onprem / region=EAST2 / zone=EAST2a
Smart driver features you can verify
• Multiple hosts in the URL for resilient bootstrap… just comma-separate them.
• Cluster-aware load balancing with
load-balance=true.• Topology-aware routing with
topology-keys=cloud.region.zone[:priority].• Node type awareness (
only-primary,prefer-rr, etc.).• Automatic server list refresh (
yb-servers-refresh-interval).
Why this is useful
This tiny test shows, without any extra tooling:
• The driver is aware of your cluster topology.
• Load balancing is actually happening.
• Topology keys are working as expected.
It’s the fastest way to get visual proof that the YugabyteDB JDBC Smart Driver is doing its job.
Have Fu n!
