Java JDBC driver

The Kubling JDBC driver is the recommended client for Java applications that require JDBC. It connects through the Engine’s nativeProtocol transport and supports standard JDBC connections, statements, result sets, metadata and transactions.

New non-Java applications should use the gRPC client interface. The PostgreSQL wire protocol is a compatibility option for existing clients and tools.

The driver is open source in the Kubling Core repository and published with the other Kubling Core releases .

Install the driver


<dependency>
    <groupId>com.kubling</groupId>
    <artifactId>kubling-client</artifactId>
    <version>26.4</version>
</dependency>

Connect

The driver class is com.kubling.jdbc.KublingDriver. The dependency registers it with DriverManager automatically.

Connection URL:


jdbc:kubling:<vdb-name>[@mm[s]://<host>:<port>][;prop-name=prop-value]*

<vdb-name> is the VDB to connect to. It can include the version, for example myvdb.2, or the version can be supplied with the version property. Do not use both forms in the same URL.
mm selects the native protocol and mms selects its TLS variant.
<host> is the Kubling address. Place an IPv6 address in square brackets, for example [::1].
<port> is the configured native transport port.
Additional properties use name=value pairs separated by semicolons. URL-encode values that contain reserved characters.

Connection Properties

Property Name	Type	Description
`ApplicationName`	`string`	Name of the client application; allows the administrator to identify the connections
`FetchSize`	`int`	Size of the `resultset`; The default size if `500`. `0` indicates that the default should be used.
`partialResultsMode`	`boolean`	Accept valid incomplete rows from providers that support partial results. Default `false`.
`user`	`string`	User name
`password`	`string`	User credential
`version`	`integer`	VDB version
`resultSetCacheMode`	`boolean`	`ResultSet` caching is turned on/off. Default `false`.
`queryTimeout`	`integer`	Query timeout in seconds. Must be >= `0`, while `0` indicates no timeout. Can be overridden by `Statement.setQueryTimeout`. Default `0`.
`encryptRequests`	`boolean`	Only applies to non-SSL socket connections. When `true`, request messages and their payloads are encrypted using the connection cryptor. Default `false`.
`disableResultSetFetchSize`	`boolean`	In some situations, the client may choose undesirable fetch sizes for processing results. Set to `true` to disable honoring `ResultSet.setFetchSize`. Default `false`.
`loginTimeout`	`integer`	The login timeout in seconds. Must be >= `0`, while `0` indicates no specific timeout, but other timeouts may apply. If a connection cannot be created in approximately the `timeout` number of seconds, connection attempt will fail and the session closed by Kubling. A default value `0` does not mean that the login will wait indefinitely, instead it is up the Session Manager to close the sessions when in login (authentication) phase.
`reportAsViews`	`boolean`	Indicates whether `DatabaseMetaData` must report views as `VIEW` table type. If `false` then views will be reported as `TABLE`. Default `true`.
`connectionPropsFilePath`	`string`	Path to the client connection properties file, also known as client settings. These properties are related to networking and transport, so please do not confuse with connection string (URL) properties listed in this table.

Create a Connection


import java.sql.Connection;
import java.sql.DriverManager;
import java.util.Properties;
 
var props = new Properties();
props.setProperty("user", "sa");
props.setProperty("password", "mypass");
 
try (Connection connection = DriverManager.getConnection(
        "jdbc:kubling:EmptyVDB@mm://localhost:35482",
        props)) {
    connection.setAutoCommit(true);
    // Execute JDBC operations.
}

Partial query results v26.6+

JDBC connections are strict by default. Set partialResultsMode=true only when the application can use an incomplete answer and will inspect the statement warning chain:


import com.kubling.jdbc.PartialResultsWarning;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.SQLWarning;
import java.util.Properties;
 
var props = new Properties();
props.setProperty("user", "sa");
props.setProperty("password", "mypass");
props.setProperty("partialResultsMode", "true");
 
try (var connection = DriverManager.getConnection(jdbcUrl, props);
     var statement = connection.createStatement();
     var rows = statement.executeQuery(sql)) {
 
    while (rows.next()) {
        // Consume valid rows.
    }
 
    for (SQLWarning warning = statement.getWarnings();
         warning != null;
         warning = warning.getNextWarning()) {
        if (warning instanceof PartialResultsWarning partial) {
            for (String source : partial.getFailedConnectors()) {
                SQLException cause = partial.getConnectorException(source);
                // Report the incomplete source and its cause.
            }
        } else {
            // Handle a general KublingSQLWarning.
        }
    }
}

PartialResultsWarning identifies the sources that did not contribute rows and exposes their associated exceptions. Other provider diagnostics appear as general KublingSQLWarning entries. Do not parse message text to decide whether the result is partial.

When partialResultsMode is absent or false, a provider that cannot complete the query causes the execution to fail instead of returning an incomplete result. See Partial query results for the end-to-end policy.

Client networking properties file v26.5+

The driver loads /kubling-client-settings.properties from the classpath by default. Set connectionPropsFilePath in the JDBC URL when the settings are stored in an external file.

Kubling 26.5 no longer reads the previous org.teiid.ssl.* and org.teiid.sockets.* keys. Rename them to the com.kubling.* forms shown below. See the complete 26.5 naming migration.


########################################
# SSL Settings
########################################
 
#
# The key store type.  default = PKCS12
#
 
com.kubling.ssl.keyStoreType=PKCS12
 
#
# The key store algorithm, defaults to
# the system property "ssl.TrustManagerFactory.algorithm"
#
 
#com.kubling.ssl.algorithm=
 
#
# Path to the key store.
#
# This property is required only if performing mTLS authentication that requires a specific private key.
#
 
com.kubling.ssl.keyStore=/sample/path/client.p12
 
#
# The key store password
#
 
com.kubling.ssl.keyStorePassword=mypass
 
#
# The key alias(not required, if given named certificate is used)
#
 
#com.kubling.ssl.keyAlias=
 
#
# The key password(not required, used if the key password is different than the keystore password)
#
 
#com.kubling.ssl.keyPassword=
 
#
# Path to the trust store, required when com.kubling.ssl.trustAll is set to false
#
 
com.kubling.ssl.trustStore=/sample/path/client-truststore.ks
 
#
# The trust store password. It is always required when certificates were generated using kdv
#
 
com.kubling.ssl.trustStorePassword=mypass
 
#
# The cipher protocol. 
# Earlier versions (TLS 1.0, 1.1, and 1.2) are considered vulnerable, so try to avoid them as much as possible.
#
 
com.kubling.ssl.protocol=TLSv1.3
 
#
# Indicates whether to allow anonymous SSL (the TLS_DH_anon_WITH_AES_128_CBC_SHA cipher suite)
# THIS CIPHER SUITE IS INSECURE! See https://ciphersuite.info/cs/TLS_DH_anon_WITH_AES_128_CBC_SHA/
#
 
com.kubling.ssl.allowAnon=false
 
#
# Indicates whether to trust all server certificates. When false,
# com.kubling.ssl.trustStore must point to a valid trust store.
# default = false
#
 
com.kubling.ssl.trustAll=false
 
#
# Indicates whether the client must check expired server certificates
# (skipped when com.kubling.ssl.trustAll is set to true)
# default = false
#
 
com.kubling.ssl.checkExpired=false
 
########################################
# Misc Socket Configuration
########################################
 
#
# The time in milliseconds for socket timeouts.
# Timeouts during the initialization, handshake, or
# a server ping may be treated as an error.
#
# This is the lower bound for all other timeouts
# the JDBC login timeout.
#
# Typically this should be left at the default of 1000
# (1 second). Setting this value too low may cause read
# errors.
#
 
com.kubling.sockets.soTimeout=1000
 
#
# Set the max time to live (in milliseconds) for non-execution
# synchronous calls.
#
 
com.kubling.sockets.synchronousttl=240000
 
#
# Set the socket receive buffer size (in bytes)
# 0 indicates that the default socket setting will be used.
#
 
com.kubling.sockets.receiveBufferSize=0
 
#
# Set the socket send buffer size (in bytes)
# 0 indicates that the default socket setting will be used.
#
 
com.kubling.sockets.sendBufferSize=0
 
#
# Set to true to enable Nagle's algorithm to conserve bandwidth
# by minimizing the number of segments that are sent.
#
 
com.kubling.sockets.conserveBandwidth=false
 
#
# Maximum number of bytes per server message.
# May need to be increased when using custom types and/or large batch sizes.
#
 
com.kubling.sockets.maxObjectSize=33554432