mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-05 20:48:22 +00:00
3d96d91efb
SQL: fix handling of escaped chars in JDBC connection string (#58429) This commit fixes an issue emerging when the connection string URI contains escaped characters. The original URI is pre-parsed in order to re-assemble a new URI having the optional elements filled in with defaults. The new URI has been using however the unescaped query and fragment parts. So if these contained any escaped `&` or `=` (such as in the password option value), the unescaping would reveal them and make them later interfere with the options parsing. The commit changes that, so that the new URI be built from the unescaped "raw" parts of the original URI. (cherry picked from commit 94eb5a05e79c6e203de548d05b13e00295bd4489)
216 lines
7.0 KiB
Plaintext
216 lines
7.0 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]]
|
|
[float]
|
|
=== 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::
|
|
http://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 `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]]
|
|
[float]
|
|
=== 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]]
|
|
[float]
|
|
===== 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]]
|
|
[float]
|
|
===== 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]]
|
|
[float]
|
|
==== Basic Authentication
|
|
|
|
`user`:: Basic Authentication user name
|
|
|
|
`password`:: Basic Authentication password
|
|
|
|
[[jdbc-cfg-ssl]]
|
|
[float]
|
|
==== 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
|
|
|
|
[float]
|
|
==== Proxy
|
|
|
|
`proxy.http`:: Http proxy host name
|
|
|
|
`proxy.socks`:: SOCKS proxy host name
|
|
|
|
[float]
|
|
==== 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.
|
|
|
|
[float]
|
|
==== Index
|
|
`index.include.frozen` (default `false`):: Whether to include <<frozen-indices, frozen-indices>> in the query execution or not (default).
|
|
|
|
[float]
|
|
==== 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.
|