SQL: ODBC: document extra connection string parameters (#40476)
* document ODBC's extra connection string parameters Document the connection string parameters that are currently not configurable from the GUI. Add a note about SmartScreen possible warning on driver MSI installation. Add a note about the TLS certificate file not being supported as bundled or password-protected. * rephrasing and restructuring the list of params - addressing PR review notes * rephrasings and reference linking - addressing PR review notes (cherry picked from commit ca90190226c0a8c63f51c2603b27df299ce8d503)
This commit is contained in:
Bogdan Pintea
parent
6efe748e2e
commit
6182b464a3
|
|
@ -9,9 +9,12 @@
|
|||
[float]
|
||||
=== Overview
|
||||
|
||||
{odbc} is a feature-rich 3.80 ODBC driver for {es}.
|
||||
It is a core level driver, exposing all of the functionality accessible through the {es}'s SQL ODBC API, converting ODBC calls into
|
||||
{es-sql}.
|
||||
{odbc} is a 3.80 compliant ODBC driver for {es}.
|
||||
It is a core level driver, exposing all of the functionality accessible through
|
||||
the {es}'s SQL API, converting ODBC calls into {es-sql}.
|
||||
|
||||
In order to make use of the driver, the server must have {es-sql} installed and
|
||||
running with the valid license.
|
||||
|
||||
* <<sql-odbc-installation, Driver installation>>
|
||||
* <<sql-odbc-setup, Configuration>>
|
||||
|
|
|
|||
|
|
@ -162,6 +162,8 @@ In case the server uses a certificate that is not part of the PKI, for example u
|
|||
+
|
||||
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:
|
||||
+
|
||||
|
|
@ -260,7 +262,95 @@ 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.
|
||||
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]]
|
||||
[float]
|
||||
==== 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. This can 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.
|
||||
|
||||
|
||||
`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.
|
||||
|
||||
|
||||
`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.
|
||||
|
||||
|
||||
`VersionChecking` (default: `strict`)::
|
||||
By default, the version of the driver and that of the server must be the same.
|
||||
This parameter will allow a driver to connect to a server of different version.
|
||||
The variation however can only be of the minor version, both endpoints must be
|
||||
of same major version number.
|
||||
Possible values:
|
||||
|
||||
* `strict`: the versions must be in sync;
|
||||
|
||||
* `major`: the versions must have the same major number.
|
||||
|
||||
WARNING: This parameter can only be used for troubleshooting purposes. Running
|
||||
with versions out of sync is not supported.
|
||||
|
||||
|
||||
`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>>).
|
||||
|
||||
// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138
|
||||
|
|
|
|||
|
|
@ -21,6 +21,11 @@ If you fail to meet any of the prerequisites the installer will show an error me
|
|||
|
||||
NOTE: It is not possible to inline upgrade using the MSI. In order to upgrade, you will first have to uninstall the old driver and then install the new driver.
|
||||
|
||||
NOTE: When installing the MSI, the Windows Defender SmartScreen might warn
|
||||
about running an unrecognized app. If the MSI has been downloaded from
|
||||
Elastic's web site, it is safe to acknowledge the message by allowing the
|
||||
installation to continue (`Run anyway`).
|
||||
|
||||
[[download]]
|
||||
==== Download the `.msi` package(s)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue