OpenSearch/docs/reference/sql/endpoints/odbc/configuration.asciidoc

[role="xpack"]
[testenv="platinum"]
[[sql-odbc-setup]]
=== Configuration

Once the driver has been installed, in order for an application to be able to connect to {es} through ODBC, a set of configuration parameters must be provided to the driver. Depending on the application, there are generally three ways of providing these parameters:

* through a connection string;
* using a User DSN or System DSN;
* through a File DSN.

DSN (_data source name_) is a generic name given to the set of parameters an ODBC driver needs to connect to a database.

We will refer to these parameters as _connection parameters_ or _DSN_ (despite some of these parameters configuring some other aspects of a driver's functions; e.g. logging, buffer sizes...).

Using a DSN is the most widely used, simplest and safest way of performing the driver configuration. Constructing a connection string, on the other hand, is the most crude way and consequently the least common method.

We will focus on DSN usage only.

[[data-source-administrator]]
==== 1. Launching ODBC Data Source Administrator

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

- The 32-bit version of the Odbcad32.exe file is located in the `%systemdrive%\Windows\SysWoW64` folder.
- The 64-bit version of the Odbcad32.exe file is located in the `%systemdrive%\Windows\System32` folder.

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_:

[[launch_administrator]]
.Launching ODBC Data Source Administrator
image:images/sql/odbc/launch_administrator.png[]

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.

[[administrator_drivers]]
.Drivers tab
image:images/sql/odbc/administrator_drivers.png[]

[[dsn-configuration]]
==== 2. Configure a DSN
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:

* User DSN
+
The connections configured under this tab are only available to the currently logged in user. Each of these DSNs are referred to by a chosen arbitrary name (typically a host or cluster name).
+
The actual set of parameters making up the DSN is stored through the driver in the system registry. Thus, a user will later only need to provide an application with the DSN name in order to connect to the configured {es} instance.
+
* System DSN
+
Similar to a User DSN, except that the connections configured under this tab will be available to all the users configured on the system.
* File DSN
+
This tab contains functionality that will allow to have one set of connection parameters written into a file, rather then the Registry.
+
Such a file can be then shared among multiple systems and the user will need to specify the path to it, in order to have the application connect to the configured {es} instance.

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

[discrete]
===== 2.1 Launch {odbc} DSN Editor
Click on the _System DSN_ tab, then on the _Add..._ button:

[[system_add]]
.Add a new DSN
image:images/sql/odbc/administrator_system_add.png[]

A new window will open, listing all available installed drivers. Click on _{es} Driver_, to highlight it, then on the _Finish_ button:

[[launch_editor]]
.Launch the DSN Editor
image:images/sql/odbc/administrator_launch_editor.png[]

This action closes the previously opened second window and open a new one instead, {odbc}'s DSN Editor:

[[dsn_editor]]
.{odbc} DSN Editor
image:images/sql/odbc/dsn_editor_basic.png[]

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

[discrete]
===== 2.2 Connection parameters
This tab allows configuration for the following items:

* Name
+
This is the name the DSN will be referred by.
+
NOTE: The characters available for this field are limited to the set permitted for a Registry key.
+
Example: _localhost_
+
* Description
+
This field allows a arbitrary text; generally used for short notes about the configured connection.
+
Example: _Clear-text connection to the local [::1]:9200._
+
* Cloud ID
+
The _Cloud ID_ is a string that simplifies the configuration when connecting to
Elastic's Cloud {ess}; it is obtained from within the Cloud console of each
{es} cluster and encodes the connection parameters to that cluster.
+
NOTE: When this field is provisioned, the _Hostname_, _Port_ and the security
settings are provisioned as well and their respective inputs disabled.
+
* Hostname
+
This field requires an IP address or a resolvable DNS name of the {es} instance that the driver will connect to.
+
Example: _::1_
+
* Port
+
The port on which the {es} listens on.
+
NOTE: If left empty, the default *9200* port number will be used.
+
* Username, Password
+
If security is enabled, these fields will need to contain the credentials of the access user.

At a minimum, the _Name_ and _Hostname_ fields must be provisioned, before the DSN can be saved.

WARNING: Connection encryption is enabled by default. This will need to be changed if connecting to an {es} node with no encryption.

[discrete]
===== 2.3 Cryptography parameters
One of the following SSL options can be chosen:

* Disabled. All communications unencrypted.
+
The communication between the driver and the {es} instance is performed over a clear-text connection.
+
WARNING: This setting can expose the access credentials to a 3rd party intercepting the network traffic and is not recommended.
+
* Enabled. Certificate not validated.
+
The connection encryption is enabled, but the certificate of the server is not validated.
+
This is currently the default setting.
+
NOTE: This setting allows a 3rd party to act with ease as a man-in-the-middle and thus intercept all communications.
+
* Enabled. Certificate is validated; hostname not validated.
+
The connection encryption is enabled and the driver verifies that server's certificate is valid, but it does *not* verify if the
certificate is running on the server it was meant for.
+
NOTE: This setting allows a 3rd party that had access to server's certificate to act as a man-in-the-middle and thus intercept all the
communications.
+
* Enabled. Certificate is validated; hostname validated.
+
The connection encryption is enabled and the driver verifies that both the certificate is valid, as well as that it is being deployed on
the server that the certificate was meant for.
+
* Enabled. Certificate identity chain validated.
+
This setting is equivalent to the previous one, with one additional check against certificate's revocation. This offers the strongest
security option and is the recommended setting for production deployments.
+
* Certificate File
+
In case the server uses a certificate that is not part of the PKI, for example using a self-signed certificate, you can configure the path to a X.509 certificate file that will be used by the driver to validate server's offered certificate.
+
The driver will only read the contents of the file just before a connection is attempted. See <<connection_testing>> section further on how to check the validity of the provided parameters.
+
NOTE: The certificate file can not be bundled or password protected since the driver will not prompt for a password.
+
If using the file browser to locate the certificate - by pressing the _Browse..._ button - only files with _.pem_ and _.der_ extensions
will be considered by default. Choose _All Files (\*.*)_ from the drop down, if your file ends with a different extension:
+
[[dsn_editor_cert]]
.Certificate file browser
image:images/sql/odbc/dsn_editor_security_cert.png[]

[discrete]
===== 2.4 Connection parameters
The connection configuration can further be tweaked by the following parameters.

* Request timeout (s)
+
The maximum number of seconds for a request to the server. The value 0 disables the timeout.
This corresponds to the `Timeout` setting in <<odbc-cfg-dsnparams>>.
+
* Max page size (rows)
+
The maximum number of rows that Elasticsearch SQL server should send the driver for one page.
This corresponds to the `MaxFetchSize` setting in <<odbc-cfg-dsnparams>>.
+
* Max page length (MB)
+
The maximum number of megabytes that the driver will accept for one page.
This corresponds to the `MaxBodySizeMB` setting in <<odbc-cfg-dsnparams>>.
+
* Varchar limit
+
The maximum character length of the string type columns.
this correspeonds to the `VarcharLimit` setting in <<odbc-cfg-dsnparams>>.
+
* Floats format
+
How should the floating point numbers be printed, when these are converted to string by the driver.
This corresponds to the `ScientificFloats` setting in <<odbc-cfg-dsnparams>>.
+
* Data encoding
+
How should the data between the server and the driver be encoded as.
This corresponds to the `Packing` setting in <<odbc-cfg-dsnparams>>.
+
* Data compression
+
Should the data between the server and the driver be compressed?
This corresponds to the `Compression` setting in <<odbc-cfg-dsnparams>>.
+
* Follow HTTP redirects
+
Should the driver follow HTTP redirects of the requests to the server?
This corresponds to the `Follow` setting in <<odbc-cfg-dsnparams>>.
+
* Use local timezone
+
Should the driver use machine's local timezone? The default is UTC.
This corresponds to the `ApplyTZ` setting in <<odbc-cfg-dsnparams>>.
+
* Auto-escape PVAs
+
Should the driver auto-escape the pattern-value arguments?
This corresponds to the `AutoEscapePVA` setting in <<odbc-cfg-dsnparams>>.
+
* Multi value field lenient
+
Should the server return one value out of a multi-value field (instead of rejecting the request)?
This corresponds to the `MultiFieldLenient` setting in <<odbc-cfg-dsnparams>>.
+
* Include frozen indices
+
Should the server consider the frozen indices when servicing a request?
This corresponds to the `IndexIncludeFrozen` setting in <<odbc-cfg-dsnparams>>.
+
* Early query execution
+
Should the driver execute a non-parameterized query as soon as it's submitted
for preparation?
This corresponds to the `EarlyExecution` setting in <<odbc-cfg-dsnparams>>.


[[dsn_editor_misc]]
.Connection parameters
image:images/sql/odbc/dsn_editor_misc.png[]

[discrete]
===== 2.5 Logging parameters
For troubleshooting purposes, the {odbc} offers functionality to log the API calls that an application makes; this is enabled in the Administrator application:

[[administrator_tracing]]
.Enable Application ODBC API logging
image:images/sql/odbc/administrator_tracing.png[]

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:

* Enable Logging?
+
Ticking this will enable driver's logging. A logging directory is also mandatory when this option is enabled (see the next option).
However the specified logging directory will be saved in the DSN if provided, even if logging is disabled.
+
* Log Directory
+
Here is to specify which directory to write the log files in.
+
NOTE: The driver will create *one log file per connection*, for those connections that generate logging messages.
+
* Log Level
+
Configure the verbosity of the logs.
+
[[administrator_logging]]
.Enable driver logging
image:images/sql/odbc/dsn_editor_logging.png[]
+
When authentication is enabled, the password will be redacted from the logs.

NOTE: Debug-logging can quickly lead to the creation of many very large files and generate significant processing overhead. Only enable if
instructed so and preferably only when fetching low volumes of data.

[discrete]
[[connection_testing]]
===== 2.5 Testing the connection
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 {es} instance and perform
a simple SQL test query. (This will thus require a running {es} instance with the SQL plugin enabled.)

[[dsn_editor_conntest]]
.Connection testing
image:images/sql/odbc/dsn_editor_conntest.png[]

NOTE: When connection testing, all the configured parameters are taken into account, including the logging configuration. This will allow
early detection of potential file/directory access rights conflicts.

See <<alternative_logging>> section further for an alternative way of configuring the logging.

[[available-dsn]]
==== 3. DSN is available
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 <<connection_testing>>
for an exhaustive check.

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

[[system_added]]
.Connection added
image:images/sql/odbc/administrator_system_added.png[]

[[alternative_logging]]
==== Alternative logging configuration

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 {odbc} 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:

* Name: _ESODBC_LOG_DIR_

* Value: [path](?[level]), where:
+
[path] is the path to the directory where the log files will be written into;
+
[level] is optional and can take one of the following values: _debug_, _info_, _warn_, _error_; if not provided, _debug_ is assumed.

[[env_var_logging]]
.Logging environment variable
image:images/sql/odbc/env_var_log.png[]

NOTE: When enabling the logging through the environment variable, the driver will create *one log file per process*.

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.

[[odbc-cfg-dsnparams]]
[discrete]
==== Connection string parameters

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.

`Timeout` (default: `0`)::
The maximum time (in seconds) a request to the server can take. This can be
overridden by a larger statement-level timeout setting. The value 0 means no
timeout.


`Follow` (default: `yes`)::
A boolean value (`yes`|`no` / `true`|`false` / `0`|`1`) controlling if the
driver will follow HTTP redirects.


`Packing` (default: `CBOR`)::
This value controls which data format to encode the REST content in. Possible
values are:

* `CBOR`: use the Concise Binary Object Representation format. This is the
preferred encoding, given its more compact format.

* `JSON`: use the JavaScript Object Notation format. This format is more
verbose, but easier to read, useful in debugging cases.


`Compression` (default: `auto`)::
This value controls if and when the REST content - encoded in one of the above
formats -  is going to be compressed. The possible values are:

* `on`: enables the compression;

* `off`: disables the compression;

* `auto`: enables the compression, except for the case when the data flows
through a secure connection; since in this case the encryption layer employs
its own data compression and there can be security implications when an
additional compression is enabled, the setting should be kept to this value.


`MaxFetchSize` (default: `0`)::
The maximum number of rows that {es-sql} server should send the driver for one
page. This corresponds to {es-sql}'s request parameter `fetch_size` (see
<<sql-rest-fields>>). The value 0 means server default.


`MaxBodySizeMB` (default: `100`)::
The maximum size (in megabytes) that an answer can grow to, before being
rejected as too large by the driver.
This is concerning the HTTP answer body of one page, not the cumulated data
volume that a query might generate.


`VarcharLimit` (default: `0`)::
The maximum width of the string columns.
If this setting is greater than zero, the driver will advertise all the string
type columns as having a maximum character length equal to this value and will
truncate any longer string to it. The string types are textual fields
(TEXT, KEYWORD etc.) and some specialized fields (IP, the GEOs etc.). Note that
no interpretation of the value is performed before trunctation, which can lead
to invalid values if the limit is set too low.
This is required for those applications that do not support column lengths as
large as {es} fields can be.


`ApplyTZ` (default: `no`)::
A boolean value controlling the timezone of:

* the context in which the query will execute (especially relevant for functions dealing with timestamp components);

* the timestamps received from / sent to the server.
If disabled, the UTC timezone will apply; otherwise, the local machine's set
timezone.


`ScientificFloats` (default: `default`)::
Controls how the floating point numbers will be printed, when these are
converted to string by the driver. Possible values given to this parameter:

* `scientific`: the exponential notation (ex.: 1.23E01);

* `default`: the default notation (ex.: 12.3);

* `auto`: the driver will choose one of the above depending on the value to be
printed.
Note that the number of decimals is dependent on the precision (or ODBC scale)
of the value being printed and varies with the different floating point types
supported by {es-sql}.
This setting is not effective when the application fetches from the driver the
values as numbers and then does the conversion subsequently itself.


`MultiFieldLenient` (default: `true`)::
This boolean parameter controls the behavior of the server in case a
multi-value field is queried. In case this is set and the server encounters
such a field, it will pick a value in the set - without any guarantees of what
that will be, but typically the first in natural ascending order - and return
it as the value for the column. If not set, the server will return an error.
This corresponds to {es-sql}'s request parameter `field_multi_value_leniency`
(see <<sql-rest-fields>>).


`AutoEscapePVA` (default: `true`)::
The pattern-value arguments make use of `_` and `%` as special characters to
build patern matching values. Some applications however use these chars as
regular ones, which can lead to {es-sql} returning more data than the app
intended. With the auto escaping, the driver will inspect the arguments and
will escape these special characters if not already done by the application.


`IndexIncludeFrozen` (default: `false`)::
If this parameter is `true`, the server will include the frozen indices in the
query execution.
This corresponds to {es-sql}'s request parameter `index_include_frozen`


`EarlyExecution` (default: `true`)::
If this parameter is `true`, the driver will execute a statement as soon as the
application submits it for preparation, i.e. early and is functionally
equivalent to a direct execution. This will only happen if the query lacks
parameters. Early execution is useful with those applications that inspect the
result before actually executing the query. {es-sql} lacks a preparation API,
so early execution is required for interoperability with these applications.