OpenSearch/docs/en/sql/endpoints/jdbc.asciidoc

[role="xpack"]
[[sql-jdbc]]
== SQL JDBC

Elasticsearch's SQL jdbc driver is a rich, fully featured JDBC driver for Elasticsearch.
It is Type 4 driver, meaning it is a platform independent, stand-alone, Direct to Database,
pure Java driver that converts JDBC calls to Elasticsearch SQL.

// TODO add example of resolving the artifact in maven and gradle.

You can connect to it using the two APIs offered
by JDBC, namely `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.

or `javax.sql.DataSource` through
["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 parameters 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 parameters.

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]
--------------------------------------------------

[[sql-jdbc-permissions]]
[NOTE]
===============================
If you are using Security you need to add a few permissions to
users so they can run SQL. To run SQL a user needs `read` and
`indices:admin/get`. Some parts of the API require
`cluster:monitor/main`. The following example configures a
role that can run SQL in JDBC querying the `test` and `bort`
indices:

["source","yaml",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-tests}/security/roles.yml[cli_jdbc]
--------------------------------------------------
===============================