From 6182b464a36813d1f6b5d82d3b0de6e82d75b06d Mon Sep 17 00:00:00 2001 From: Bogdan Pintea Date: Wed, 27 Mar 2019 14:11:59 +0100 Subject: [PATCH] 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) --- docs/reference/sql/endpoints/odbc.asciidoc | 9 +- .../sql/endpoints/odbc/configuration.asciidoc | 96 ++++++++++++++++++- .../sql/endpoints/odbc/installation.asciidoc | 5 + 3 files changed, 104 insertions(+), 6 deletions(-) diff --git a/docs/reference/sql/endpoints/odbc.asciidoc b/docs/reference/sql/endpoints/odbc.asciidoc index 1a7dd974281..fd92a37dca6 100644 --- a/docs/reference/sql/endpoints/odbc.asciidoc +++ b/docs/reference/sql/endpoints/odbc.asciidoc @@ -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. * <> * <> diff --git a/docs/reference/sql/endpoints/odbc/configuration.asciidoc b/docs/reference/sql/endpoints/odbc/configuration.asciidoc index 8bda67ce063..70ba437b648 100644 --- a/docs/reference/sql/endpoints/odbc/configuration.asciidoc +++ b/docs/reference/sql/endpoints/odbc/configuration.asciidoc @@ -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 <> 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 +<>). 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 <>). -// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138 diff --git a/docs/reference/sql/endpoints/odbc/installation.asciidoc b/docs/reference/sql/endpoints/odbc/installation.asciidoc index 08f0c66ee2a..3a024e443d7 100644 --- a/docs/reference/sql/endpoints/odbc/installation.asciidoc +++ b/docs/reference/sql/endpoints/odbc/installation.asciidoc @@ -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)