ODBC DSN connection properties

The following tables list the connection properties you can set in the DSNs for use with Vertica's ODBC driver.

The following tables list the connection properties you can set in the DSNs for use with Vertica's ODBC driver. To set these parameters, see Setting DSN connection properties.

Required connection properties

These connection properties are the minimum required to create a functioning DSN.

Property Description
Driver The file path and name of the driver used.
Database The name of the database running on the server.

The host name or IP address of any active node in a Vertica cluster.

You can provide an IPv4 address, IPv6 address, or host name.

In mixed IPv4/IPv6 networks, the DNS server configuration determines which IP version address is sent first. Use the PreferredAddressFamily option to force the connection to use either IPv4 or IPv6.

You can also use the aliases "server" and "host" for this property.

UID The database username.

Optional properties

Property Description

The port number on which Vertica listens for ODBC connections.

Default: 5433


The password for the specified user name. You may insert an empty string to leave this property blank.

Default: None, login only succeeds if the user does not have a password set.


The IP version to use if the client and server have both IPv4 and IPv6 addresses and you have provided a host name, one of the following:

  • ipv4: Connect to the server using IPv4.

  • ipv6: Connect to the server using IPv6.

  • none: Use the IP address provided by the DNS server.

Default: none

Advanced settings

Property Description

A Boolean value that controls whether the driver automatically commits transactions after executing a DML statement.

Default: true


A string containing the host name or IP address that client libraries can try to connect to if the host specified in ServerName is unreachable. Connection attempts continue until successful or until the list of server nodes is exhausted.

Valid values: Comma-separated list of servers optionally followed by a colon and port number.


A Boolean value that indicates whether the connection can be redirected to a host in the database other than the ServerNode.

This affects the connection only if the load balancing. is set to something other than "none". When the node differs from the node the client is connected to, the client disconnects and reconnects to the targeted node. See About Native Connection Load Balancing in the Administration Guide.

Default: false


A string containing SQL commands that the driver should execute immediately after connecting to the server. You can use this property to configure the connection, such as setting a schema search path.

Reserved symbol: In the connection string semicolon (;) is a reserved symbol. To set multiple properties as part of ConnSettings properties, use %3B as the comma delimiter, and + (plus) for spaces.


The number of seconds to wait for a request to complete before returning to the client application. This is equivalent to the SQL_ATTR_CONNECTION_TIMEOUT parameter in the ODBC API.

Default: 0 (no timeout)


Controls whether square-bracket query identifiers are converted to a double quote identifier for compatibility when making queries to a Vertica database.

Default: false

DirectBatchInsert Deprecated, always set to true.

Controls whether the ODBC driver performs type conversions on strings sent between the ODBC driver and the database. Possible values are:

  • NONE: No conversion in either direction. This results in the highest performance.

  • INPUT: Strings sent from the client to the server are converted, but strings sent from the server to the client are not.

  • OUTPUT: Strings sent by the server to the client are converted, but strings sent from the client to the server are not.

  • BOTH: Strings are converted in both directions.

Default: OUTPUT


The locale used for the session. Specify the locale as an ICU Locale.

**See **the ICU User Guide for a complete list of properties that can be used to specify a locale.

Default: en_US@collation=binary


[Windows only] Controls whether users are prompted to enter a password, if none is supplied by the connection string or DSN used to connect to Vertica. See Prompting windows users for passwords.

Default: false


A true or false value that controls whether the connection can read data only from Vertica.

Default: false


Size of memory buffer for the large result sets in streaming mode. A value of 0 means ResultBufferSize is turned off.

Default: 131072 (128KB)


Sets the transaction isolation for the connection, one of the following:

  • Read Committed

  • Serializable

  • Server Default

See Changing Transaction Isolation Levels for an explanation of transaction isolation.

Default: Server Default


Property Description Standard/ Vertica

Description for the DSN entry.

Required? No

Insert an empty string to leave the description empty.

Label / SessionLabel

Sets a label for the connection on the server. This value appears in the client_label column of the V_MONITOR.SESSIONS system table.

Label and SessionLabel are synonyms and can be used interchangeably.


OAuth connection properties

The following connection properties pertain to OAuth in ODBC.

Property Description
OAuthAccessToken Required if oauthrefreshtoken is unspecified, an OAuth token that authorizes a user to the database.

Required if oauthaccesstoken is unspecified, allows a user to refresh and obtain a new oauthaccesstoken when their old one expires.

If you set this parameter, you must also set the following refresh properties in oauthjsonconfig:

  • oauthrefreshtoken

  • oauthdiscoveryurl or oauthtokenurl

  • oauthclientid

  • oauthclientsecret

In cases where introspection fails (e.g. when the access token expires), Vertica responds to the request with an error. If introspection fails and OAuthRefreshToken is specified, the driver attempts to refresh and silently retrieve a new access token. Otherwise, the driver passes error to the client application.


A JSON string or file that lets you set the following:

  • oauthclientid: The client ID of the client application registered in the identity provider.

  • oauthclientsecret: The client secret of the client application registered in the identity provider.

  • oauthtokenurl: The endpoint to which token refresh requests are sent. The format for this depends on your provider. For examples, see the Keycloak and Okta documentation.

    If oauthdiscoveryurl is not set: this parameter is only required for IDP valdiation if oauthdiscoveryurl, but should also be set for JWT validation to support token refresh.

  • oauthauthurl: The authorization endpoint used for single sign-on. For examples, see the Keycloak and Okta documentation.

  • oauthdiscoveryurl: Also known as the OpenID Provider Configuration Document, this endpoint contains a list of all other endpoints supported by the IDP. If set, the other endpoints (such as oauthtokenurl and oauthauthurl) do not need to be specified. This parameter is only supported for Keycloak. For other identity providers like Okta, the endpoints must be set manually.

    If you set both oauthdiscoveryurl and another endpoint (like oauthtokenurl), oauthdiscoveryurl takes precedence.

    This parameter is only required for IDP valdiation, but should also be set for JWT validation to support token refresh.

  • oauthscope: The requested OAuth scopes, delimited with spaces. These scopes define the extent of access to the resource server (in this case, Vertica) granted to the client by the access token. For details, see the OAuth documentation.

  • oauthvalidatehostname: Boolean, whether to verify the subjectAltName of the identity provider host. If enabled, the IP address or hostname must be set as the subjectAltName in its certificate. Hostname verification is enabled by default.

Unlike oauthaccesstoken or oauthrefreshtoken, which must be set programmatically by the client when they attempt to connect, the same oauthjsonconfig can be reused between connections to the database.

For example, to set it as a JSON string in ODBC.ini as part of the DSN:

OAuthJsonConfig = {
    "oauthdiscoveryurl": "",
    "oauthtokenurl": "",
    "oauthclientid": "vertica",
    "oauthclientsecret": "eba23135-834f-1341-aa34-bf9345713dfc",
    "oauthscope": "offline_access openid",
    "oauthvalidatehostname": "false"

To set it inside separate a JSON configuration file:

  1. Create oauth_config.json:

        "oauthdiscoveryurl": "",
        "oauthtokenurl": "",
        "oauthclientid": "vertica",
        "oauthclientsecret": "eba23135-834f-1341-aa34-bf9345713dfc",
        "oauthscope": "offline_access openid",
        "oauthvalidatehostname": "false"
  2. Specify oauth_config.json inside ODBC.ini:

    OAuthJsonconfig = {"oauthjsonfile": "/path/to/oauth_config.json"}


Property Description Standard/ Vertica

Controls whether the connection to the database uses SSL encryption, one of the following. For information on using these parameters to configure TLS, see Configuring TLS for ODBC Clients:

  • require: Requires that the server use TLS. If the TLS connection attempt fails, the client rejects the connection.
  • prefer: Prefers that the server use TLS. The client first attempts to connect using TLS. If that attempt fails, the client attempts to connect again in plaintext.
  • allow: Makes a connection to the server whether the server uses TLS or not. The first connection attempt to the database is attempted over a clear channel. If that fails, a second connection is attempted over TLS.
  • verify_ca: The client verifies that the server's certificate was issued by a trusted certificate authority (CA).
  • verify_full: The client verifies that the following conditions are met:
  • The server's certificate was issued by a trusted CA.
  • One of the following:
    • The server's hostname matches the common name specified in the server's certificate.
    • The server's hostname or IP address appears in the Subject Alternative Name (SAN) field of the server's certificate.
  • disable: Never connect to the server using TLS. This setting is typically used for troubleshooting.

Default: prefer

SSLCertFile The absolute path of the client's public certificate file. This file can reside anywhere on the system. Vertica
SSLKeyFile The absolute path to the client's private key file. This file can reside anywhere on the system. Vertica

Third-party compatibility

Property Description Default Standard/ Vertica

Specifies how character column types are reported when the driver is in Unicode mode. When set to false, the ODBC driver reports the data type of character columns as WCHAR. If you set ColumnsAsChar to true, the driver identifies character column as CHAR.

You typically use this setting for compatibility with some third-party clients.

Default: false

false Vertica

A Boolean value that controls how catalog names are interpreted by the driver. When this value is false, the driver reports that catalog names are not supported. When catalog names are not supported, they cannot be used as a filter in database metadata API calls. In this case, the driver returns NULL as the catalog name in all driver metadata results.

When this value is true, catalog names can be used as a filter in database metadata API calls. In this case, the driver returns the database name as the catalog name in metadata results. Some third-party applications assume a certain catalog behavior and do not work properly with the default values. Enable this option if your client software expects to get the catalog name from the database metadata and use it as part of a three-part name reference.

Default: false for UNIX, true for Windows

false (UNIX)

true (Window)


Prevents NULL values from being loaded into columns with a NOT NULL constraint during batch inserts. When this value is set to true, batch inserts roll back when NULL values are inserted in to columns with NOT NULL constraints. When this value is set to false, batch insert behavior is unchanged.

Vertica recommends only using this property with SAP Data Services as it could negatively impact database performance.

false Vertica

Kerberos connection properties

Use the following properties for client authentication using Kerberos.

Property Description Standard/ Vertica

Provides the service name portion of the Vertica Kerberos principal; for example: vertichost@EXAMPLE.COM

Default: vertica


Provides the instance or host name portion of the Vertica Kerberos principal; for example: verticaosEXAMPLE.COM

Default: Value specified in the servername connection string property


See also

ODBC driver settings