[role="xpack"] [testenv="platinum"] [[sql-jdbc]] == SQL JDBC {es}'s SQL jdbc driver is a rich, fully featured JDBC driver for {es}. It is Type 4 driver, meaning it is a platform independent, stand-alone, Direct to Database, pure Java driver that converts JDBC calls to {es-sql}. [[sql-jdbc-installation]] [discrete] === Installation The JDBC driver can be obtained from: Dedicated page:: https://www.elastic.co/downloads/jdbc-client[elastic.co] provides links, typically for manual downloads. Maven dependency:: https://maven.apache.org/[Maven]-compatible tools can retrieve it automatically as a dependency: ["source","xml",subs="attributes"] ---- org.elasticsearch.plugin x-pack-sql-jdbc {version} ---- from https://search.maven.org/artifact/org.elasticsearch.plugin/x-pack-sql-jdbc[Maven Central Repository], or from `artifacts.elastic.co/maven` by adding it to the repositories list: ["source","xml",subs="attributes"] ---- elastic.co https://artifacts.elastic.co/maven ---- [[jdbc-setup]] [discrete] === Setup The driver main class is `org.elasticsearch.xpack.sql.jdbc.EsDriver`. Note the driver implements the JDBC 4.0 +Service Provider+ mechanism meaning it is registered automatically as long as it is available in the classpath. Once registered, the driver understands the following syntax as an URL: ["source","text",subs="attributes"] ---- jdbc:[es|elasticsearch]://[[http|https]://]?[host[:port]]?/[prefix]?[\?[option=value]&]* ---- `jdbc:[es|elasticsearch]://`:: Prefix. Mandatory. `[[http|https]://]`:: Type of HTTP connection to make. Possible values are `http` (default) or `https`. Optional. `[host[:port]]`:: Host (`localhost` by default) and port (`9200` by default). Optional. `[prefix]`:: Prefix (empty by default). Typically used when hosting {es} under a certain path. Optional. `[option=value]`:: Properties for the JDBC driver. Empty by default. Optional. The driver recognized the following properties: [[jdbc-cfg]] [discrete] ===== Essential [[jdbc-cfg-timezone]] `timezone` (default JVM timezone):: Timezone used by the driver _per connection_ indicated by its `ID`. *Highly* recommended to set it (to, say, `UTC`) as the JVM timezone can vary, is global for the entire JVM and can't be changed easily when running under a security manager. [[jdbc-cfg-network]] [discrete] ===== Network `connect.timeout` (default 30s):: Connection timeout (in seconds). That is the maximum amount of time waiting to make a connection to the server. `network.timeout` (default 60s):: Network timeout (in seconds). That is the maximum amount of time waiting for the network. `page.timeout` (default 45s):: Page timeout (in seconds). That is the maximum amount of time waiting for a page. `page.size` (default 1000):: Page size (in entries). The number of results returned per page by the server. `query.timeout` (default 90s):: Query timeout (in seconds). That is the maximum amount of time waiting for a query to return. [[jdbc-cfg-auth]] [discrete] ==== Basic Authentication `user`:: Basic Authentication user name `password`:: Basic Authentication password [[jdbc-cfg-ssl]] [discrete] ==== SSL `ssl` (default false):: Enable SSL `ssl.keystore.location`:: key store (if used) location `ssl.keystore.pass`:: key store password `ssl.keystore.type` (default `JKS`):: key store type. `PKCS12` is a common, alternative format `ssl.truststore.location`:: trust store location `ssl.truststore.pass`:: trust store password `ssl.truststore.type` (default `JKS`):: trust store type. `PKCS12` is a common, alternative format `ssl.protocol`(default `TLS`):: SSL protocol to be used [discrete] ==== Proxy `proxy.http`:: Http proxy host name `proxy.socks`:: SOCKS proxy host name [discrete] ==== Mapping `field.multi.value.leniency` (default `true`):: Whether to be lenient and return the first value (without any guarantees of what that will be - typically the first in natural ascending order) for fields with multiple values (true) or throw an exception. [discrete] ==== Index `index.include.frozen` (default `false`):: Whether to include <> in the query execution or not (default). [discrete] ==== Additional `validate.properties` (default true):: If disabled, it will ignore any misspellings or unrecognizable properties. When enabled, an exception will be thrown if the provided property cannot be recognized. To put all of it together, the following URL: ["source","text"] ---- jdbc:es://http://server:3456/?timezone=UTC&page.size=250 ---- opens up a {es-sql} connection to `server` on port `3456`, setting the JDBC connection timezone to `UTC` and its pagesize to `250` entries. === API usage One can use JDBC through the official `java.sql` and `javax.sql` packages: [[java-sql]] ==== `java.sql` The former through `java.sql.Driver` and `DriverManager`: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{jdbc-tests}/JdbcIntegrationTestCase.java[connect-dm] -------------------------------------------------- <1> The server and port on which Elasticsearch is listening for HTTP traffic. The port is by default 9200. <2> Properties for connecting to Elasticsearch. An empty `Properties` instance is fine for unsecured Elasticsearch. [[javax-sql]] ==== `javax.sql` Accessible through the `javax.sql.DataSource` API: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{jdbc-tests}/JdbcIntegrationTestCase.java[connect-ds] -------------------------------------------------- <1> The server and port on which Elasticsearch is listening for HTTP traffic. By default 9200. <2> Properties for connecting to Elasticsearch. An empty `Properties` instance is fine for unsecured Elasticsearch. Which one to use? Typically client applications that provide most configuration properties in the URL rely on the `DriverManager`-style while `DataSource` is preferred when being _passed_ around since it can be configured in one place and the consumer only has to call `getConnection` without having to worry about any other properties. To connect to a secured Elasticsearch server the `Properties` should look like: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{security-tests}/JdbcSecurityIT.java[admin_properties] -------------------------------------------------- Once you have the connection you can use it like any other JDBC connection. For example: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{jdbc-tests}/SimpleExampleTestCase.java[simple_example] -------------------------------------------------- [NOTE] {es-sql} doesn't provide a connection pooling mechanism, thus the connections the JDBC driver creates are not pooled. In order to achieve pooled connections, a third-party connection pooling mechanism is required. Configuring and setting up the third-party provider is outside the scope of this documentation.