// 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


== 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`

|IDENTITY
|Identity to use for authentication. Depending on the authenticator used on the server side, it can be a user name or another unique identifier. See the link:administrators-guide/security/authentication[Authentication] topic for details.
|None.

|SECRET
|Secret to use for authentication. Depending on the authenticator used on the server side, it can be a user password or another type of user-specific secret. See the link:administrators-guide/security/authentication[Authentication] topic for details.
|None.

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

|`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`

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

|`SSL_KEY_FILE`
|Specifies the path to the file containing the SSL server private key.
|None.

|`SSL_CERT_FILE`
|Specifies the path to the file containing the SSL server certificate.
|None.

|`SSL_CA_FILE`
|Specifies the path to 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:Specific schema[]
[source,text]
----
DRIVER={Apache Ignite 3};ADDRESS=localhost:10800;SCHEMA=yourSchemaName
----

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

tab:Authentication[]
[source,text]
----
DRIVER={Apache Ignite 3};ADDRESS=localhost:10800;IDENTITY=yourid;SECRET=yoursecret
----

tab:Custom page size[]
[source,text]
----
DRIVER={Apache Ignite 3};ADDRESS=localhost:10800;SCHEMA=yourSchemaName;PAGE_SIZE=4096
----
--
