// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
= Connection String and DSN

== Connection String Format

The ODBC Driver supports standard connection string format. Here is the formal syntax:

[source,text]
----
connection-string ::= empty-string[;] | attribute[;] | attribute; connection-string
empty-string ::=
attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]
attribute-keyword ::= identifier
attribute-value ::= character-string
----


In simple terms, an ODBC connection URL is a string with parameters of the choice separated by semicolon.

== Supported Arguments

The ODBC driver supports and uses several connection string/DSN arguments. All parameter names are case-insensitive - `ADDRESS`, `Address`, and `address` all are valid parameter names and refer to the same parameter. If an argument is not specified, the default value is used. The exception to this rule is the `ADDRESS` attribute. If it is not specified, `SERVER` and `PORT` attributes are used instead.

[width="100%",cols="20%,60%,20%"]
|=======================================================================
|Attribute keyword |Description |Default Value

|`ADDRESS`
|Address of the remote node to connect to. The format is: `<host>[:<port>]`. For example: `localhost`, `example.com:12345`, `127.0.0.1`, `192.168.3.80:5893`.
If this attribute is specified, then `SERVER` and `PORT` arguments are ignored.
|None.

|`SERVER`
|Address of the node to connect to.
This argument value is ignored if ADDRESS argument is specified.
|None.

|`PORT`
|Port on which `OdbcProcessor` of the node is listening.
This argument value is ignored if `ADDRESS` argument is specified.
|`10800`

|`USER`
|Username for SQL Connection. This parameter is required if authentication is enabled on the server.
See link:security/authentication[Authentication] and link:sql-reference/ddl#create-user[CREATE] user docs for more details on how to enable authentication and create user, respectively.
|Empty string

|`PASSWORD`
|Password for SQL Connection. This parameter is required if authentication is enabled on the server.
See link:security/authentication[Authentication] and link:sql-reference/ddl#create-user[CREATE] user docs for more details on how to enable authentication and create user, respectively.
|Empty string

|`SCHEMA`
|Schema name.
|`PUBLIC`

|`DSN`
|DSN name to connect to.
| None.

|`PAGE_SIZE`
|Number of rows returned in response to a fetching request to the data source. Default value should be fine in most cases. Setting a low value can result in slow data fetching while setting a high value can result in additional memory usage by the driver, and additional delay when the next page is being retrieved.
|`1024`

|`DISTRIBUTED_JOINS`
|Enables the link:SQL/distributed-joins#non-colocated-joins[non-colocated distributed joins] feature for all queries that are executed over the ODBC connection.
|`false`

|`ENFORCE_JOIN_ORDER`
|Enforces a join order of tables in SQL queries. If set to `true`, the query optimizer does not reorder tables in the join.
|`false`

|`PROTOCOL_VERSION`
|Used to specify ODBC protocol version to use. Currently, there are following versions: `2.1.0`, `2.1.5`, `2.3.0`, `2.3.2`, `2.5.0`. You can use earlier versions of the protocol for backward compatibility.
|`2.3.0`

|`REPLICATED_ONLY`
|Set this property to `true` if the query is to be executed over fully replicated tables. This can enforce execution optimizations.
|`false`

|`COLLOCATED`
| Set this parameter to `true` if your SQL statement includes a GROUP BY clause that groups the results by either primary
or affinity key. When Ignite executes a distributed query, it sends sub-queries to individual cluster members. If
you know in advance that the elements of your query selection are colocated together on the same node and you group by
a primary or affinity key, then Ignite makes significant performance and network optimizations by grouping data locally
 on each node participating in the query.
|`false`

|`LAZY`
|Lazy query execution.
By default, Ignite attempts to fetch the whole query result set to memory and send it to the client. For small and medium result sets, this provides optimal performance and minimize duration of internal database locks, thus increasing concurrency.
However, if the result set is too big to fit in the available memory, then it can lead to excessive GC pauses and even `OutOfMemoryError` errors. Use this flag to tell Ignite to fetch the result set lazily, thus minimizing memory consumption at the cost of a moderate performance hit.
|`false`

|`SKIP_REDUCER_ON_UPDATE`
|Enables server side update feature.
When Ignite executes a DML operation, first, it fetches all the affected intermediate rows for analysis to the query initiator (also known as reducer), and only then prepares batches of updated values that will be sent to remote nodes.
This approach might affect performance, and saturate the network if a DML operation has to move many entries over it.
Use this flag to tell Ignite to do all intermediate rows analysis and updates "in-place" on corresponding remote data nodes.
Defaults to `false`, meaning that intermediate results will be fetched to the query initiator first.
|`false`

|`SSL_MODE`
|Determines whether the SSL connection should be negotiated with the server. Use `require` or `disable` mode as needed.
| None.

|`SSL_KEY_FILE`
|Specifies the name of the file containing the SSL server private key.
| None.

|`SSL_CERT_FILE`
|Specifies the name of the file containing the SSL server certificate.
| None.

|`SSL_CA_FILE`
|Specifies the name of the file containing the SSL server certificate authority (CA).
| None.
|=======================================================================

== Connection String Samples
You can find samples of the connection string below. These strings can be used with `SQLDriverConnect` ODBC call to establish connection with a node.


[tabs]
--
tab:Authentication[]
[source,text]
----
DRIVER={Apache Ignite};
ADDRESS=localhost:10800;
SCHEMA=somecachename;
USER=yourusername;
PASSWORD=yourpassword;
SSL_MODE=[require|disable];
SSL_KEY_FILE=<path_to_private_key>;
SSL_CERT_FILE=<path_to_client_certificate>;
SSL_CA_FILE=<path_to_trusted_certificates>
----

tab:Specific Cache[]
[source,text]
----
DRIVER={Apache Ignite};ADDRESS=localhost:10800;CACHE=yourCacheName
----

tab:Default cache[]
[source,text]
----
DRIVER={Apache Ignite};ADDRESS=localhost:10800
----

tab:DSN[]
[source,text]
----
DSN=MyIgniteDSN
----

tab:Custom page size[]
[source,text]
----
DRIVER={Apache Ignite};ADDRESS=example.com:12901;CACHE=MyCache;PAGE_SIZE=4096
----
--


== Configuring DSN
The same arguments apply if you prefer to use link:https://en.wikipedia.org/wiki/Data_source_name[DSN] (Data Source Name) for connection purposes.

To configure DSN on Windows, you should use a system tool called `odbcad32` (for 32-bit [x86] systems) or `odbc64` (for 64-bit systems) which is an ODBC Data Source Administrator.

When installing the DSN tool, _if you use the pre-built msi file_, make sure you've installed Microsoft Visual C++ 2010 (https://www.microsoft.com/en-ie/download/details.aspx?id=5555[32-bit/x86] or https://www.microsoft.com/en-us/download/details.aspx?id=14632[64-bit/x64]).

Launch this tool, via `Control panel->Administrative Tools->Data Sources (ODBC)`. Once the ODBC Data Source Administrator is launched, select `Add...->Apache Ignite` and configure your DSN.


image::images/odbc_dsn_configuration.png[Configuring DSN]


To do the same on Linux, you have to locate the `odbc.ini` file. The file location varies among Linux distributions and depends on a specific Driver Manager used by the Linux distribution. As an example, if you are using unixODBC then you can run the following command which will print system wide ODBC related details:


[source,text]
----
odbcinst -j
----


Use the `SYSTEM DATA SOURCES` and `USER DATA SOURCES` properties to locate the `odbc.ini` file.

Once you locate the `odbc.ini` file, open it with the editor of your choice and add the DSN section to it, as shown below:

[source,text]
----
[DSN Name]
description=<Insert your description here>
driver=Apache Ignite
<Other arguments here...>
----