Configuration

For DSN management, ODBC provides the ODBC Data Source Administrator application, readily installed on all recent desktop Windows operating systems.

To launch it, open the search menu - Win + S - and type "ODBC Data Sources (64-bit)" or "ODBC Data Sources (32-bit)" and press Enter:

Launching ODBC Data Source Administrator

Once launched, you can verify that the driver was installed correctly by clicking on the Drivers tab of the ODBC Data Source Administrator and checking that Elasticsearch Driver is present in the list of installed drivers.

You should also see the version number of the installed driver.

Drivers tab

The next step is to configure a DSN. You can choose between the following options mapped on the first three tabs of the Administrator application:

The configuration steps are similar for all the above points. Following is an example of configuring a System DSN.

Click on the System DSN tab, then on the Add…​ button:

Add a new DSN

A new window will open, listing all available installed drivers. Click on Elasticsearch Driver, to highlight it, then on the Finish button:

Launch the DSN Editor

This action closes the previously opened second window and open a new one instead, Elasticsearch SQL ODBC Driver’s DSN Editor:

Elasticsearch SQL ODBC Driver DSN Editor

This new window has three tabs, each responsible for a set of configuration parameters, as follows.

This tab allows configuration for the following items:

At a minimum, the Name and Hostname fields must be provisioned, before the DSN can be saved.

One of the following SSL options can be chosen:

For troubleshooting purposes, the Elasticsearch SQL ODBC Driver offers functionality to log the API calls that an application makes; this is enabled in the Administrator application:

Enable Application ODBC API logging

However, this only logs the ODBC API calls made by the application into the Driver Manager and not those made by the Driver Manager into the driver itself. To enable logging of the calls that the driver receives, as well as internal driver processing events, you can enable driver’s logging on Editor’s Logging tab:

Once the Hostname, the Port (if different from implicit default) and the SSL options are configured, you can test if the provided parameters are correct by pressing the Test Connection button. This will instruct the driver to connect to the Elasticsearch instance and perform a simple SQL test query. (This will thus require a running Elasticsearch instance with the SQL plugin enabled.)

Connection testing

See Alternative logging configuration section further for an alternative way of configuring the logging.

Once everything is in place, pressing the Save button will store the configuration into the chosen destination (Registry or file).

Before saving a DSN configuration the provided file/directory paths are verified to be valid on the current system. The DSN editor will however not verify in any way the validity or reachability of the configured Hostname : Port. See 2.5 Testing the connection for an exhaustive check.

If everything is correct, the name of the newly created DSN will be listed as available to use:

Connection added

Due to the specification of the ODBC API, the driver will receive the configured DSN parameters - including the logging ones - only once a connection API is invoked (such as SQLConnect or SQLDriverConnect). The Driver Manager will however always make a set of API calls into the driver before attempting to establish a connection. To capture those calls as well, one needs to pass logging configuration parameters in an alternative way. The Elasticsearch SQL ODBC Driver will use an environment variable for this purpose.

Configuring an environment variable is OS specific and not detailed in this guide. Whether the variable should be configured system-wide or user-specific depends on the way the ODBC-enabled application is being run and if logging should affect the current user only or not.

The definition of the environment variable needs to be done as follows:

Logging environment variable

Both ways of configuring the logging can coexist and both can use the same destination logging directory. However, one logging message will only be logged once, the connection logging taking precedence over the environment variable logging.

The following is a list of additional parameters that can be configured for a particular connection, in case the default behavior of the driver is not suitable. For earlier versions of the driver, this needs to be done within the client application, in a manner particular to that application, generally in a free text input box (sometimes named "Connection string", "String extras", or similar). The format of the string is Attribute1=Value1. Multiple attributes can be specified, separated by a semicolon Attribute1=Value1;Attribute2=Value2;. The attribute names are given below.