OpenSearch - JDBC

This is the driver for JDBC connectivity to a cluster running with OpenSearch SQL support.

JDBC Driver

Build

Specifications

The driver is compatible with JDBC 4.2 specification and requires a minimum of Java 8.

BI Tool Connectors

• Tableau Desktop

Download and Installation

The driver is available for download from Maven, from Artifacts page on OpenSearch.org at the very bottom and from automated CI workflow.

Using the driver

The driver comes in the form of a single jar file. To use it, simply place it on the classpath of the Java application that needs to use it.

If using with JDBC compatible BI tools, refer to the tool documentation on configuring a new JDBC driver. Typically, all that's required is to make the tool aware of the location of the driver jar and then use it to setup database (i.e OpenSearch) connections.

Connection URL and other settings

To setup a connection, the driver requires a JDBC connection URL. The connection URL is of the form:

    jdbc:opensearch://[scheme://][host][:port][/context-path]?[property-key=value]&[property-key2=value2]..&[property-keyN=valueN]

• scheme

  Can be one of http or https. Default is http.

• host

  Hostname or IP address of the target cluster. Default is localhost.

• port

  Port number on which the cluster's REST interface is listening. Default value depends on the scheme selected. For http, the default is 9200. For https, the default is 443.

• context-path

  The context path at which the cluster REST interface is rooted. Not needed if the REST interface is simply available on the '/' context path.

• property key=value

  The query string portion of the connection URL can contain desired connection settings in the form of one or more property-key=value pairs. The possible configuration properties are provided in the table below. The property keys and values are case insensitive and values unless otherwise indicated.

  Note that JDBC provides multiple APIs for specifying connection properties of which specifying them in the connection URL is just one. When directly coding with the driver you can choose any of the other options (refer sample code below). If you are setting up a connection via a tool, it is likely the tool will allow you to specify the connection URL (with just the scheme, host, port and context-path components) while the the connection properties are provided separately. For example, you may not wish to place the user and password in the connection URL. Check the tool you are using for such support.

  The configurable connection properties are:

  Property Key	Description	Accepted Value(s)	Default value
  user	Connection username. mandatory if auth property selects a authentication scheme that mandates a username value	any string	null
  password	Connection password. mandatory if auth property selects a authentication scheme that mandates a password value	any string	null
  fetchSize	Cursor page size	positive integer value. Max value is limited by index.max_result_window OpenSearch setting	0 (for non-paginated response)
  logOutput	Location where driver logs should be emitted	a valid file path	null (logs are disabled)
  logLevel	Severity level for which driver logs should be emitted	in order from highest (least logging) to lowest (most logging): OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL	OFF (logs are disabled)
  auth	Authentication mechanism to use	NONE (no auth), BASIC (HTTP Basic), AWS_SIGV4 (AWS SIGV4)	basic if username and/or password is specified, NONE otherwise
  awsCredentialsProvider	The AWS credential provider to be used when authentication mechanism is AWS_SIGV4 (AWS SIGV4). If not set, the driver will use DefaultAWSCredentialsProviderChain to sign the request. The value has to be an instance of com.amazonaws.auth.AWSCredentialsProvider	instance of an AWSCredentialProvider	DefaultAWSCredentialsProviderChain
  region	If authentication type is aws_sigv4, then this is the region value to use when signing requests. Only needed if the driver can not determine the region for the host endpoint. The driver will detect the region if the host endpoint matches a known url pattern.	a valid AWS region value e.g. us-east-1	null (auto-detected if possible from the host endpoint)
  requestCompression	Whether to indicate acceptance of compressed (gzip) responses when making server requests	true or false	false
  useSSL	Whether to establish the connection over SSL/TLS	true or false	false if scheme is http, true if scheme is https
  trustStoreLocation	Location of the SSL/TLS truststore to use	file path or URL as appropriate to the type of truststore	null
  trustStoreType	Type of the truststore	valid truststore type recognized by available Java security providers	JKS
  trustStorePassword	Password to access the Trust Store	any string	null
  keyStoreLocation	Location of the SSL/TLS keystore to use	file path or URL as appropriate to the type of keystore	null
  keyStoreType	Type of the keystore	valid keystore type recognized by available Java security providers	JKS
  keyStorePassword	Password to access the keystore	any string	null
  trustSelfSigned	Shortcut way to indicate that any self-signed certificate should be accepted. A truststore is not required to be configured.	true or false	false
  hostnameVerification	Indicate whether certificate hostname verification should be performed when using SSL/TLS	true or false	true
  tunnelHost	VPC endpoint hostname if connected through a tunnel or proxy and AWS_SIGV4 authentication is used	any string	null

Connecting using the DriverManager interface

The main Driver class is org.opensearch.jdbc.Driver. If the driver jar is on the application classpath, no other configuration is required.

Code samples to open a connection for some typical scenarios are given below:

• Connect to localhost on port 9200 with no authentication over a plain connection

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

String url = "jdbc:opensearch://localhost:9200";

Connection con = DriverManager.getConnection(url);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

• Connect to a remote host on default SSL port with no authentication

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

String url = "jdbc:opensearch://https://remote-host-name";

Connection con = DriverManager.getConnection(url);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

or,

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

String url = "jdbc:opensearch://remote-host-name";

Properties properties = new Properties();
properties.put("useSSL", "true");

Connection con = DriverManager.getConnection(url, properties);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

• Connect to a remote host with HTTP Basic authentication over an SSL/TLS connection on the default SSL/TLS port. Note - if a username and password are provided and auth property is not provided, basic auth is implicitly used.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

String url = "jdbc:opensearch://https://remote-host-name";
String user = "username";
String password = "password";

Connection con = DriverManager.getConnection(url, user, password);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

or,

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

String url = "jdbc:opensearch://remote-host-name";

Properties properties = new Properties();
properties.put("useSSL", "true");
properties.put("user", "username");
properties.put("password", "password");

Connection con = DriverManager.getConnection(url, properties);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

• Connect to a remote host with HTTP Basic authentication over an SSL/TLS connection, allowing any self-signed certificate and optionally turning off hostname verification. This may be useful for a dev/test setup.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

String url = "jdbc:opensearch://remote-host-name";

Properties properties = new Properties();
properties.put("useSSL", "true");
properties.put("trustSelfSigned", "true");

// uncomment below to turn off hostname verification
// properties.put("hostnameVerification", "false");

properties.put("user", "username");
properties.put("password", "password");

Connection con = DriverManager.getConnection(url, properties);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

• Connect to a remote host on default SSL port with AWS Sig V4 authentication. The driver will determine the credentials used to sign the request just like the standard aws-sdk i.e. in standard directories, environment variables etc.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

String url = "jdbc:opensearch://https://remote-host-name?auth=aws_sigv4";

Connection con = DriverManager.getConnection(url);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

or,

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

String url = "jdbc:opensearch://https://remote-host-name";

Properties properties = new Properties();
properties.put("auth", "aws_sigv4");

Connection con = DriverManager.getConnection(url, properties);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

• Connect to a remote host on default SSL port with AWS Sig V4 authentication, explicitly specifying the AWSCredentialProvider to use

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

String url = "jdbc:opensearch://https://remote-host-name";

Properties properties = new Properties();
properties.put("awsCredentialsProvider", new EnvironmentVariableCredentialsProvider());

Connection con = DriverManager.getConnection(url, properties);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

• Connect to a remote host on default SSL port with AWS Sig V4 authentication, explicitly specifying the region to use in the request signing.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

String url = "jdbc:opensearch://https://remote-host-name?auth=aws_sigv4&region=us-west-1";

Connection con = DriverManager.getConnection(url);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

or,

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.Statement;

String url = "jdbc:opensearch://https://remote-host-name";

Properties properties = new Properties();
properties.put("auth", "aws_sigv4");
properties.put("region", "us-west-2");

Connection con = DriverManager.getConnection(url, properties);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

Connecting using the DataSource interface

The driver also provides a javax.sql.DataSource implementation via the org.opensearch.jdbc.OpenSearchDataSource class that can be used to obtain a connection. Here are some typical code samples:

• Connect to localhost on port 9200 with no authentication over a plain connection

import java.sql.Connection;
import java.sql.Statement;
import javax.sql.DataSource;

import org.opensearch.jdbc.OpenSearchDataSource;

String url = "jdbc:opensearch://localhost:9200";

OpenSearchDataSource ds = new OpenSearchDataSource();
ds.setUrl(url);

Connection con = ds.getConnection(url);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

• Connect to a remote host on default SSL port with no authentication

import java.sql.Connection;
import java.sql.Statement;
import javax.sql.DataSource;

import org.opensearch.jdbc.OpenSearchDataSource;

String url = "jdbc:opensearch://https://remote-host-name";

OpenSearchDataSource ds = new OpenSearchDataSource();
ds.setUrl(url);

Connection con = ds.getConnection(url);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

• Connect to a remote host with HTTP Basic authentication over an SSL/TLS connection on the default SSL/TLS port.

import java.sql.Connection;
import java.sql.Statement;
import javax.sql.DataSource;

import org.opensearch.jdbc.OpenSearchDataSource;

String url = "jdbc:opensearch://https://remote-host-name";

OpenSearchDataSource ds = new OpenSearchDataSource();
ds.setUrl(url);

Connection con = ds.getConnection(url, "user", "password");
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

• Connect to a remote host on default SSL port with AWS Sig V4 authentication. The driver will determine the credentials used to sign the request just like the standard aws-sdk i.e. in standard directories, environment variables etc.

import java.sql.Connection;
import java.sql.Statement;
import javax.sql.DataSource;

import org.opensearch.jdbc.OpenSearchDataSource;

String url = "jdbc:opensearch://https://remote-host-name?auth=aws_sigv4";

OpenSearchDataSource ds = new OpenSearchDataSource();
ds.setUrl(url);

Connection con = ds.getConnection(url);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

• Connect to a remote host on default SSL port with AWS Sig V4 authentication, explicitly specifying the AWSCredentialProvider to use

import java.sql.Connection;
import java.sql.Statement;
import javax.sql.DataSource;

import org.opensearch.jdbc.OpenSearchDataSource;

String url = "jdbc:opensearch://https://remote-host-name?auth=aws_sigv4&region=us-west-1";

OpenSearchDataSource ds = new OpenSearchDataSource();
ds.setUrl(url);
ds.setAwsCredentialProvider(new EnvironmentVariableCredentialsProvider());

Connection con = ds.getConnection(url);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

• Connect to a remote host on default SSL port with AWS Sig V4 authentication, explicitly specifying the region to use in the request signing.

import java.sql.Connection;
import java.sql.Statement;
import javax.sql.DataSource;

import org.opensearch.jdbc.OpenSearchDataSource;

String url = "jdbc:opensearch://https://remote-host-name?auth=aws_sigv4&region=us-west-1";

OpenSearchDataSource ds = new OpenSearchDataSource();
ds.setUrl(url);

Connection con = ds.getConnection(url);
Statement st = con.createStatement();

// use the connection

// close connection
con.close();

Building from source

The driver is built as a shadow jar so that its dependencies are bundled within itself. This way no additional libraries besides the driver jar need to be placed on an application classpath for the driver to be used. The namespaces of the bundled dependencies are modified to ensure they do not conflict with other classes on the application classpath.

Run unit tests and build the driver jar

./gradlew clean test shadowJar

Build the driver jar without unit tests

./gradlew shadowJar

Publish the built driver jar to local maven repo

./gradlew publishToMavenLocal

Documentation

Please refer to the documentation for detailed information on installing and configuring OpenSearch.

Code of Conduct

This project has adopted an Open Source Code of Conduct.

Security issue notifications

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public GitHub issue.

Licensing

See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.

Copyright

Copyright OpenSearch Contributors. See NOTICE for details.