ODBC Configuration and Connection Parameters

The Snowflake ODBC driver utilizes configuration and connection parameters. The procedures for setting the parameters are different depending on the platform in which the driver is installed.

In this Topic:

Setting Parameters in Windows

In Windows:

  • Configuration parameters are set in the Windows registry using regedit and the following registry path:

    [HKEY_LOCAL_MACHINE\SOFTWARE\Snowflake\Driver]
    
  • Connection parameters are set in Data Source Names (DSNs):

    • DSNs are typically created and edited using the Windows Data Source Administration tool.

    • If you wish, the registry keys for DSNs can be edited directly in the Windows registry using regedit. The registry path to the keys is different depending on whether you’re using 64-bit and 32-bit Windows and whether you’re editing a user or system DSN:

      • 64-bit Windows:

        [HKEY_CURRENT_USER\SOFTWARE\ODBC\ODBC.INI\<DSN_NAME>]
        
        [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\<DSN_NAME>]
        
      • 32-bit Windows:

        [HKEY_CURRENT_USER\SOFTWARE\WOW6432NODE\ODBC\ODBC.INI\<DSN_NAME>]
        
        [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432NODE\ODBC\ODBC.INI\<DSN_NAME>]
        

      To add a connection parameter using regedit, add a new String Value, double-click on the value you created, then enter the ODBC parameter as the Value name and the parameter value as the Value data.

Setting Parameters in Mac OS/Linux

In Mac OS or Linux:

  • Configuration parameters are set in the configuration file (simba.snowflake.ini).
  • Connection parameters are set in the DSN file (odbc.ini).

Configuration Parameters

LogLevel
Specifies the level of detail logged for clients that use the ODBC driver.
LogPath
Specifies the location of the Snowflake log files for clients that use the ODBC driver.
CURLVerboseMode
Set to true to enable cURL verbose logging. The log file snowflake_odbc_curl.dmp is created and updated. The Snowflake ODBC driver uses cURL as the HTTP and SSL library. This parameter is useful for diagnosing network issues.
Proxy

Specifies a proxy server in the form of <host>:<port> for clients that use the ODBC driver.

Note

In Windows, entries for LogLevel and LogPath are created and populated with default values when the ODBC driver is installed; however, an entry for Proxy is not created during install. To specify a proxy to use with the driver, you must manually add the entry to the driver registry key.

To bypass the proxy for one or more IP addresses or URLs, add the following configuration parameter:

NoProxy

Specifies the hostname patterns to bypass the proxy server, e.g. no_proxy=.amazonaws.com to bypass AWS S3 access.

Note

The Snowflake ODBC driver passes the NoProxy value to the curl option CURLOPT_NOPROXY. The format of the NoProxy value can be found here.

CABundleFile

Set the location of the Certificate Authority (CA) bundle file. Must reference a file that includes a valid list of CA certificates.

For Linux, the RPM and DEB installers automatically copy the file and set this parameter.

For Mac, the PKG installer copies the file and sets this parameter.

For Windows, the MSI installer copies the file and sets this parameter.

A manual installation requires you to download the file from https://curl.haxx.se/docs/caextract.html and set the location of the file.

DisableOCSPCheck
Set to true to disable the TLS/SSL certificate revocation status check by the Online Certificate Status Protocol (OCSP). In normal circumstances, this flag should not set. But if the OCSP availablility problem persists, the application may temporarily set this parameter in order to unblock connectivity issues and remove it when the OCSP availability problem is addressed.
KeepLeadingTrailingZeros

Determines how leading or trailing zeros in numbers formatted as string values are handled. By default, the parameter is set to true, which means the driver retains any leading or trailing zeros. Set the parameter to false to remove leading or trailing zeros, e.g.:

  • 0.23 is changed to .23
  • 7.00 is changed to 7

Connection Parameters

Required Connection Parameters

<name> (Data Source)
Specifies the name of your DSN.
uid (User)
Specifies the login name of the Snowflake user to authenticate.
pwd (Password)

A password is required to connect to Snowflake; however, for security and authentication reasons, Snowflake strongly discourages storing password credentials directly within any DSN definition.

Typically, the credentials are passed to the driver programmatically by the client application that is attempting to connect to Snowflake.

Note

In Windows, the ODBC driver displays a Password field in the Data Source Administration tool; however, the driver does not store any values entered in the field. Instead, the driver requires login credentials to be provided at connection time.

If the connecting application does not provide the required credentials, the driver interactively prompts for the information.

server (Server)

Specifies the full domain name for your account (provided by Snowflake).

The format of the URL domain is different depending on the Snowflake Region where your account is located:

US West:<account_name>.snowflakecomputing.com
Other regions:<account_name>.<region_id>.snowflakecomputing.com

Where <account_name> is the name of your account (provided by Snowflake) and <region_id> is:

Region ID Snowflake Region
us-east-1 US East
eu-west-1 EU (Dublin)
eu-central-1 EU (Frankfurt)
ap-southeast-2 Asia Pacific (Sydney)

For example, if your account name is abc123:

  • In US West, the URL would be abc123.snowflakecomputing.com.
  • In US East, the URL would be abc123.us-east-1.snowflakecomputing.com.
  • In EU (Frankfurt), the URL would be abc123.eu-central-1.snowflakecomputing.com.

Note

There is no need to change the default Port value of 443.

Optional Connection Parameters

database (Database)
Specifies the default database to use for sessions initiated by the driver.
schema (Schema)

Specifies the default schema to use for sessions initiated by the driver.

Default is public.

warehouse (Warehouse)
Specifies the default warehouse to use for sessions initiated by the driver.
role (Role)
Specifies the default role to use for sessions initiated by the driver. The specified role should be a role that has been assigned to the specified user for the driver. If the specified role does not match any of the roles assigned to the user, sessions initiated by the driver have no role initially; however, a role can always be specified from within the session.
tracing (Tracing)

The level of detail to be logged in the driver trace files:

0 = Disable tracing

1 = Fatal only error tracing

2 = Error tracing

3 = Warning tracing

4 = Info tracing

5 = Debug tracing

6 = Detailed tracing

Additional Connection Parameters

Note

In Windows, these additional connection parameters can only be set in the Windows Registry using regedit.

In Mac OS or Linux, they are set in the odbc.ini file, similar to the rest of the connection parameters.

authenticator

Specifies the authenticator to use for verifying user login credentials:

  • snowflake (Default) to use the internal Snowflake authenticator.
  • externalbrowser to authenticate using your web browser and Okta, ADFS, or any other SAML 2.0-compliant identify provider (IdP) that has been defined for your account.
  • https://<your_okta_account_name>.okta.com (i.e. the URL endpoint for Okta) to authenticate through native Okta (only supported if your IdP is Okta).

Default is snowflake.

Note

The externalbrowser authenticator is only supported in terminal windows that have web browser access. For example, a terminal window on a remote machine accessed through a SSH (Secure Shell) session may require additional setup to open a web browser.

If you don’t have access to a web browser, but your IdP is Okta, you can use native Okta (i.e. set the authenticator to https://<your_okta_account_name>.okta.com).

For more information, see Managing/Using Federated Authentication.

CLIENT_SESSION_KEEP_ALIVE

Specifies whether to keep the current session active after a period of inactivity, or to force the user to login again. If the value is true, Snowflake keeps the session active indefinitely, even if there is no activity from the user. If the value is false, the user must log in again after four hours of inactivity.

  • true specifies to keep the session active indefinitely.
  • false specifies to log out after four hours of inactivity.

Default is false.

passcode

Specifies the passcode to use for multi-factor authentication.

For more information about multi-factor authentication, see Multi-Factor Authentication (MFA).

passcodeInPassword

Specifies whether the passcode for multi-factor authentication is appended to the password:

  • on (or true) specifies the passcode is appended.
  • off (or false) or any other value specifies the passcode is not appended.

The default value is off.

login_timeout

Specifies how long to wait for a response when connecting to the Snowflake service before returning a login failure error.

Default is 60 seconds.

network_timeout

Specifies how long to wait for a response when interacting with the Snowflake service before returning an error. Zero (0) indicates no network timeout is set.

Default is 0 seconds.

query_timeout

Specifies how long to wait for a query to complete before returning an error. Zero (0) indicates to wait indefinitely.

Default is 0 seconds.

proxy

Specifies the proxy server URL in the format http://<hostname>:<port>/ or <hostname>:<port_number> so that all communications from ODBC use the proxy server.

Note

This parameter is applied to the process. If another connection shares the same process, the proxy setting must be identical or the behavior is not predictable.

no_proxy

Specifies the hostname patterns to bypass the proxy server, e.g. no_proxy=.amazonaws.com to bypass AWS S3 access.

Note

This parameter is applied to the process. If another connection shares the same process, the proxy setting must be identical or the behavior is not predictable.

Connecting Through a Proxy Server

The instructions for configuring a proxy server connection depend on your operating system and driver version:

Operating System Driver Version Supported Instructions
Linux 2.16.0 (released May 3, 2018) or higher
2.13.18 (released February 7, 2018) - 2.15.0 (released April 30, 2018) Using Environment Variables
2.13.17 or lower Using Configuration Parameters
Mac OS 2.16.0 (released May 3, 2018) or higher
2.14.0 (released March 28, 2018) - 2.15.0 (released April 30, 2018) Using Environment Variables
2.13.21 or lower Using Configuration Parameters
Windows 2.16.0 (released May 3, 2018) or higher
2.15.0 (released April 30, 2018) Using Environment Variables
2.14.0 or lower Using Configuration Parameters

Note

The latest versions of ODBC driver, indicated above, support any of the listed configuration options. The options are listed in the order of precedence. If more than one option is defined, the setting with the highest precedence is applied.

Using Connection Parameters

To connect through a proxy server, add the following connection parameters to the DSN:

  • proxy
  • no_proxy

For example:

[connection]
Description = SnowflakeDB
Driver      = SnowflakeDSIIDriver
Locale      = en-US
server      = account.snowflakecomputing.com
proxy       = http://proxyserver.company:80
no_proxy    = .amazonaws.com

See Connection Parameters for parameter descriptions.

Using Configuration Parameters

Note

These parameters are obsoleted (i.e. no longer supported) in recent ODBC driver versions. See the table of supported options in Connecting Through a Proxy Server. As you upgrade your driver, configure your proxy server settings using the environment variables or connection parameters.

To connect through a proxy server, add the following configuration parameters:

  • Proxy
  • NoProxy

See Configuration Parameters for parameter descriptions.

Using Environment Variables

To connect through a proxy server, configure the following environment variables:

  • http_proxy
  • https_proxy
  • no_proxy

Note

These environment variables are case-sensitive for Linux and Mac OS, and must be set in lower-case. For Windows, the environment variables are case-insensitive.

For example:

  • Linux or Mac OS X:

    export http_proxy=http://proxyserver.company.com:80
    export https_proxy=http://proxyserver.company.com:80
    

    If the proxy server requires a user name and password, include the credentials, e.g.:

    export https_proxy=http://username:password@proxyserver.company.com:80
    
  • Windows:

    set http_proxy=http://proxyserver.company.com:80
    set https_proxy=http://proxyserver.company.com:80
    

    If the proxy server requires a user name and password, include the credentials, e.g.:

    set https_proxy=http://username:password@proxyserver.company.com:80
    

Optionally, you can set no_proxy to bypass the proxy for specific communications, e.g. no_proxy=.amazonaws.com to bypass AWS S3 access.

OCSP Response Cache Server

Note

The OCSP response cache server is currently supported by the Snowflake ODBC Driver 2.15.0 and higher.

Snowflake clients initiate every connection to a Snowflake service endpoint with a “handshake” that establishes a secure connection before actually transferring data. As part of the handshake, a client authenticates the TLS/SSL certificate for the service endpoint. The revocation status of the certificate is checked by sending a client certificate request to one of the certificate authority’s (CA) Certificate revocation list (CRL) or Online Certificate Status Protocol (OCSP) servers.

A connection failure occurs when the response from the CRL/OCSP server is delayed beyond a reasonable time. The following levels of cache persist the revocation status, helping alleviate these issues:

  • Memory cache, which persists for the life of the process.

  • File cache, which persists until the cache directory, e.g., ~/.cache/snowflake or ~/.snowsql/ocsp_response_cache is purged.

  • Snowflake OCSP response cache server, which fetches OCSP responses from the CA’s OCSP servers hourly and stores them for 24 hours. Clients can then request the validation status of a given Snowflake certificate from this server cache.

    Important

    If your server policy denies access to most or all external IP addresses and web sites, you must whitelist the cache server address to allow normal service operation. The cache server URL is ocsp*.snowflakecomputing.com:80.

    If you need to disable the cache server for any reason, set the SF_OCSP_RESPONSE_CACHE_SERVER_ENABLED environment variable to false. Note that the value is case-sensitive and must be in lower-case.

If none of the three layers of cache contain the OCSP response, the client attempts to fetch the validation status from the CA’s OCSP server.