Client Reference

Avatica provides a reference-implementation client in the form of a Java JDBC client that interacts with the Avatica server over HTTP. This client can be used just as any other JDBC driver. There are a number of options that are available for clients to specify via the JDBC connection URL.

As a reminder, the JDBC connection URL for Avatica is:

jdbc:avatica:remote:[option=value[;option=value]]

The following are a list of supported options:

url: Description: This property is a URL which refers to the location of the Avatica Server which the driver will communicate with.; Default: This property’s default value is null. It is required that the user provides a value for this property.; Required: Yes.
serialization: Description: Avatica supports multiple types of serialization mechanisms to format data between the client and server. This property is used to ensure that the client and server both use the same serialization mechanism. Valid values presently include json and protobuf.; Default: json is the default value.; Required: No.
authentication: Description: Avatica clients can specify the means in which it authenticates with the Avatica server. Clients who want to use a specific form of authentication should specify the appropriate value in this property. Valid values for this property are presently: NONE, BASIC, DIGEST, and SPNEGO.; Default: null (implying “no authentication”, equivalent to NONE).; Required: No.
timeZone: Description: The timezone that will be used for dates and times. Valid values for this property are defined by RFC 822, for example: GMT, GMT-3, EST or PDT.; Default: This property’s default value is null which will cause the Avatica Driver to use the default timezone as specified by the JVM, commonly overriden by the user.timezone system property.; Required: No.
httpclient_factory: Description: The Avatica client is a “fancy” HTTP client. As such, there are many libraries and APIs available for making HTTP calls. To determine which implementation should be used, there is an interface AvaticaHttpClientFactory which can be provided to control how the AvaticaHttpClient implementation is chosen.; Default: AvaticaHttpClientFactoryImpl.; Required: No.
httpclient_impl: Description: When using the default AvaticaHttpClientFactoryImpl HTTP client factory implementation, this factory should choose the correct client implementation for the given client configuration. This property can be used to override the specific HTTP client implementation. If it is not provided, the AvaticaHttpClientFactoryImpl will automatically choose the HTTP client implementation.; Default: null.; Required: No.
avatica_user: Description: This is the username used by an Avatica client to identify itself to the Avatica server. It is unique to the traditional “user” JDBC property. It is only necessary if Avatica is configured for HTTP Basic or Digest authentication.; Default: null.; Required: No.
avatica_password: Description: This is the password used by an Avatica client to identify itself to the Avatica server. It is unique to the traditional “password” JDBC property. It is only necessary if Avatica is configured for HTTP Basic or Digest authentication.; Default: null.; Required: No.
principal: Description: The Kerberos principal which can be used by the Avatica JDBC Driver to automatically perform a Kerberos login before attempting to contact the Avatica server. If this property is provided, it is also expected that keytab is provided and that the Avatica server is configured for SPNEGO authentication. Users can perform their own Kerberos login; this option is provided only as a convenience.; Default: null.; Required: No.
keytab: Description: The Kerberos keytab which contains the secret material to perform a Kerberos login with the principal. The value should be a path on the local filesystem to a regular file.; Default: null.; Required: No.
truststore: Description: A path to a Java KeyStore (JKS) file on the local filesystem which contains the certificate authority to trust in a TLS handshake. Only necessary when using HTTPS.; Default: null.; Required: No.
truststore_password: Description: The password for the Java KeyStore file specified by truststore.; Default: null.; Required: Only if truststore was provided.
keystore_type: Description: The format of the truststore file specified by truststore. This needs to be specified if non JKS format keystores are used (i.e. BCFKS). This setting applies both to keystore and truststore files. For formats not included in the default JVM the corresponding security provider must be installed and configured into the JVM, or added to the application classpath and configured.; Default: null.; Required: No.
fetch_size: Description: The number of rows to fetch. If Statement:setFetchSize is set, that value overrides fetch_size.; Default: 100.; Required: No.
transparent_reconnection: Description: The Java client versions between 1.5.0 and 1.20.0 transparently re-created the Connection object on the client side if it expired from the server cache. This behaviour broke JDBC compliance and could cause data loss for transactional write workloads, and has been removed in 1.21.0. Setting this property to true restores the 1.20.0 behaviour.; Default: false.; Required: No.
use_client_side_lb: Description: Enables the client side load-balancing.; Default: false.; Required: No.
lb_urls: Description: List of URLs in a comma separated format, for example “URL1,URL2…URLn”, to be used by the client side load balancer. Depending on the load balancing strategy, load balancer selects one of the URLs from the list.; Default: null.; Required: No.
lb_strategy: Description: The load balancing strategy to be used by the client side load balancer. It must be a fully qualified Java class name which implements org.apache.calcite.avatica.ha.LBStrategy. Three implementations are provided org.apache.calcite.avatica.ha.RandomSelectLBStrategy, org.apache.calcite.avatica.ha.RoundRobinLBStrategy and org.apache.calcite.avatica.ha.ShuffledRoundRobinLBStrategy; Default: org.apache.calcite.avatica.ha.ShuffledRoundRobinLBStrategy.; Required: No.
lb_connection_failover_retries: Description: Number of times that the load balancer tries to retry the connection with another URL (fail-over). When the connection fails, load balancer retries the connection with another URL, chosen by the load balancing strategy.; Default: 3.; Required: No.
lb_connection_failover_sleep_time: Description: The amount of time in milliseconds that the load balancer sleeps before attempting the next connection failover retry.; Default: 1000.; Required: No.
http_connection_timeout: Description: Timeout in milliseconds for establishing the connection between the Avatica HTTP client and server.; Default: 180000 (3 minutes).; Required: No.
http_response_timeout: Description: Socket Timeout in milliseconds for the connection between the Avatica HTTP client and server.; Default: 180000 (3 minutes).; Required: No.