Skip to content

Commit 8e19fe6

Browse files
costincostin
committed
[DOCS] Fix version in SQL JDBC Maven template
[DOCS] Improve install and setup section for SQL JDBC
1 parent 889091a commit 8e19fe6

File tree

1 file changed

+129
-4
lines changed

1 file changed

+129
-4
lines changed

‎x-pack/docs/en/sql/endpoints/jdbc.asciidoc‎

Lines changed: 129 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,133 @@ Elasticsearch's SQL jdbc driver is a rich, fully featured JDBC driver for Elasti
66
It is Type 4 driver, meaning it is a platform independent, stand-alone, Direct to Database,
77
pure Java driver that converts JDBC calls to Elasticsearch SQL.
88

9-
// TODO add example of resolving the artifact in maven and gradle.
9+
[float]
10+
=== Installation
1011

11-
You can connect to it using the two APIs offered
12-
by JDBC, namely `java.sql.Driver` and `DriverManager`:
12+
The JDBC driver can be obtained either by downloading it from the https://www.elastic.co/downloads/jdbc-client[elastic.co] site or by using a http://maven.apache.org/[Maven]-compatible tool with the following dependency:
13+
14+
["source","xml",subs="attributes"]
15+
----
16+
<dependency>
17+
<groupId>org.elasticsearch.plugin.jdbc</groupId>
18+
<artifactId>jdbc</artifactId>
19+
<version>{version}</version>
20+
</dependency>
21+
----
22+
23+
from `artifacts.elastic.co/maven` by adding it to the repositories list:
24+
25+
["source","xml",subs="attributes"]
26+
----
27+
<repositories>
28+
<repository>
29+
<id>elastic.co</id>
30+
<url>https://artifacts.elastic.co/maven</url>
31+
</repository>
32+
</repositories>
33+
----
34+
35+
[[jdbc-setup]]
36+
[float]
37+
=== Setup
38+
39+
The driver main class is `org.elasticsearch.xpack.sql.jdbc.jdbc.JdbcDriver`. Note the driver
40+
also implements the JDBC 4.0 +Service Provider+ mechanism meaning it is registerd automatically
41+
as long as its available in the classpath.
42+
43+
Once registered, the driver expects the following syntax as an URL:
44+
45+
["source","text",subs="attributes"]
46+
----
47+
jdbc:es://<1>[http|https]?<2>[host[:port]]*<3>/[prefix]*<4>[?[option=value]&<5>]*
48+
----
49+
50+
<1> `jdbc:es://` prefix. Mandatory.
51+
<2> type of HTTP connection to make - `http` (default) or `https`. Optional.
52+
<3> host (`localhost` by default) and port (`9200` by default). Optional.
53+
<4> prefix (empty by default). Typically used when hosting {es} under a certain path. Optional.
54+
<5> Parameters for the JDBC driver. Empty by default. Optional.
55+
56+
The driver recognized the following parameters:
57+
58+
[[jdbc-cfg]]
59+
[float]
60+
===== Essential
61+
62+
`timezone` (default JVM timezone)::
63+
Timezone used by the driver _per connection_ indicated by its `ID`.
64+
*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.
65+
66+
[[jdbc-cfg-network]]
67+
[float]
68+
===== Network
69+
70+
`connect.timeout` (default 30s)::
71+
Connection timeout (in seconds). That is the maximum amount of time waiting to make a connection to the server.
72+
73+
`network.timeout` (default 60s)::
74+
Network timeout (in seconds). That is the maximum amount of time waiting for the network.
75+
76+
`page.timeout` (default 45s)::
77+
Page timeout (in seconds). That is the maximum amount of time waiting for a page.
78+
79+
`page.size` (default 1000)::
80+
Page size (in entries). The number of results returned per page by the server.
81+
82+
`query.timeout` (default 90s)::
83+
Query timeout (in seconds). That is the maximum amount of time waiting for a query to return.
84+
85+
[[jdbc-cfg-auth]]
86+
[float]
87+
==== Basic Authentication
88+
89+
`user`:: Basic Authentication user name
90+
91+
`password`:: Basic Authentication password
92+
93+
[[jdbc-cfg-ssl]]
94+
[float]
95+
==== SSL
96+
97+
`ssl` (default false):: Enable SSL
98+
99+
`ssl.keystore.location`:: key store (if used) location
100+
101+
`ssl.keystore.pass`:: key store password
102+
103+
`ssl.keystore.type` (default `JKS`):: key store type. `PKCS12` is a common, alternative format
104+
105+
`ssl.truststore.location`:: trust store location
106+
107+
`ssl.truststore.pass`:: trust store password
108+
109+
`ssl.cert.allow.self.signed` (default `false`):: Whether or not to allow self signed certificates
110+
111+
`ssl.protocol`(default `TLS`):: SSL protocol to be used
112+
113+
[float]
114+
==== Proxy
115+
116+
`proxy.http`:: Http proxy host name
117+
118+
`proxy.socks`:: SOCKS proxy host name
119+
120+
121+
To put all of it together, the following URL:
122+
123+
["source","text",subs="attributes"]
124+
----
125+
jdbc:es://http://server:3456/timezone=UTC&page.size=250
126+
----
127+
128+
Opens up a {es-jdbc} connection to `server` on port `3456`, setting the JDBC timezone to `UTC` and its pagesize to `250` entries.
129+
130+
=== API usage
131+
132+
One can use JDBC through the official `java.sql` and `javax.sql` packages:
133+
134+
==== `java.sql`
135+
The former through `java.sql.Driver` and `DriverManager`:
13136

14137
["source","java",subs="attributes,callouts,macros"]
15138
--------------------------------------------------
@@ -20,7 +143,9 @@ HTTP traffic. The port is by default 9200.
20143
<2> Properties for connecting to Elasticsearch. An empty `Properties`
21144
instance is fine for unsecured Elasticsearch.
22145

23-
or `javax.sql.DataSource` through
146+
==== `javax.sql`
147+
148+
Accessible through the `javax.sql.DataSource` API:
24149
["source","java",subs="attributes,callouts,macros"]
25150
--------------------------------------------------
26151
include-tagged::{jdbc-tests}/JdbcIntegrationTestCase.java[connect-ds]

0 commit comments

Comments
 (0)