217 lines
7.1 KiB
Plaintext
217 lines
7.1 KiB
Plaintext
[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"]
|
|
----
|
|
<dependency>
|
|
<groupId>org.elasticsearch.plugin</groupId>
|
|
<artifactId>x-pack-sql-jdbc</artifactId>
|
|
<version>{version}</version>
|
|
</dependency>
|
|
----
|
|
|
|
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"]
|
|
----
|
|
<repositories>
|
|
<repository>
|
|
<id>elastic.co</id>
|
|
<url>https://artifacts.elastic.co/maven</url>
|
|
</repository>
|
|
</repositories>
|
|
----
|
|
|
|
[[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 <<frozen-indices, frozen-indices>> 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.
|