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