Installing and Configuring the ODBC Driver for Linux

Similar to Windows, Linux utilizes named data sources (DSNs) for connecting ODBC-based client applications to Snowflake. You can choose to install the ODBC driver using the TGZ file, RPM package, or DEB package provided in the Snowflake web interface.

In this Topic:

Prerequisites

Driver Manager: iODBC or unixODBC

A driver manager is required to manage communication between Snowflake and the ODBC driver. The driver supports using either iODBC or unixODBC as the driver manager.

iODBC

If iODBC is not installed on CentOS, as sudo, execute the following command:

$ yum install libiodbc

unixODBC

unixODBC provides the odbcinst and isql command line utilities used to install, configure, and test the driver. To verify whether unixODBC is installed, execute the following commands:

$ which odbcinst

$ which isql

If unixODBC is not installed:

  1. As sudo, execute the following commands:

    $ yum search unixODBC
    
    $ yum install unixODBC.x86_64
    
  2. Verify the directory where odbcinst expects the odbcinst.ini and odbc.ini files to be located:

    $ odbcinst -j
    

    The location should be /etc.

Step 1: Verify the Package Signature (RPM or DEB only) — Optional

Note

If you are installing the ODBC driver using the TGZ file, skip this step.

If you are installing the ODBC driver using the RPM or DEB package and wish to verify the package signature before installation, perform the following tasks:

1.1: Download and Import the Latest Snowflake Public Key

Download and import the Snowflake GPG public key from either the Snowflake web interface or the public keyserver.

Web Interface

  1. In the Snowflake web interface, go to Help > Download... to display the Downloads dialog.

  2. Select ODBC Driver on the left, then click the Snowflake GPG Public Key icon on the right.

  3. Import the public key:

    $ gpg --import snowflakeKey.asc
    

Public Keyserver

To download and import the key from the public keyserver:

$ gpg --keyserver hkp://keys.gnupg.net --recv-keys 69BE019A

1.2: Download the RPM or DEB Driver Package

Download the package from the Snowflake web interface. For details, see Downloading the ODBC Driver.

1.3: Verify the Signature for the RPM or DEB Driver Package

RPM Package Signature

  1. Verify the key was imported successfully:

    $ gpg --list-keys
    

    The command should display the Snowflake key.

  2. Verify the signature:

    $ rpm -K snowflake-odbc-<version>.x86_64.rpm
    

DEB Package Signature

  1. Install the package signature verification tool:

    $ sudo apt-get install debsig-verify
    
  2. Import the public key to the keyring:

    $ mkdir /usr/share/debsig/keyrings/69BE019A
    $ gpg --no-default-keyring --keyring /usr/share/debsig/kerings/69BE019A/debsig.gpg --import snowflakeKey.asc
    
  3. Configure a policy for the key. For details, see /usr/share/doc/debsig-verify. The policy must be stored in the following directory:

    /etc/debsig/policies/69BE019A
    

    Store the policy in a file named <policy_name>.pol, where policy_name is your name for the policy. For the policy name, you can use any text string, however the string cannot contain blank spaces.

    Here is a sample policy file:

    <?xml version="1.0"?>
    <!DOCTYPE Policy SYSTEM "http://www.debian.org/debsig/1.0/policy.dtd">
    <Policy xmlns="http://www.debian.org/debsig/1.0/">
    <Origin Name="Snowflake Computing" id="69BE019A"
    Description="Snowflake ODBC Driver DEB package"/>
    
    <Selection>
    <Required Type="origin" File="debsig.gpg" id="69BE019A"/>
    </Selection>
    
    <Verification MinOptional="0">
    <Required Type="origin" File="debsig.gpg" id="69BE019A"/>
    </Verification>
    
    </Policy>
    
  4. Verify the signature:

    $ sudo debsig-verify snowflake-odbc-<version>.x86_64.deb
    

Note

By default, the dpkg package signature verification tool does not check the signature when you install the package. If you want to verify the signature every time you run dpkg, remove the --no-debsig line in the /etc/dpkg/dpkg.cfg file.

1.4: Delete the Old Snowflake Public Key — Optional

Your local environment can contain multiple GPG keys; however, for security reasons, Snowflake periodically rotates the public GPG key. As a best practice, we recommend deleting the existing public key after confirming that the latest key works with the latest signed package.

To delete the key:

$ gpg --delete-key "Snowflake Computing"

Step 2: Install the ODBC Driver

Install the driver using one of the distribution packages:

  • TGZ (TAR file compressed using .GZIP)
  • RPM
  • DEB

Installing the TGZ File

To install the Snowflake ODBC driver for Linux using the TGZ file:

  1. Download the file from the Snowflake web interface. For details, see Downloading the ODBC Driver.

  2. Copy the downloaded file (snowflake_linux_x8664_odbc.tgz) to a working directory.

  3. Unzip the file:

    $ gunzip snowflake_linux_x8664_odbc-<version>.tgz
    
  4. Extract the files from the .tar file:

    $ tar -xvf snowflake_linux_x8664_odbc-<version>.tar
    
  5. Copy the resulting snowflake_odbc folder to the directory where you want to install the driver. Make note of this directory. You’ll need the location later in the instructions.

Installing the RPM Package

Note

The RPM package requires unixODBC as the driver manager.

To install the Snowflake ODBC driver for Linux using the RPM package, after optionally verifying the package signature, run the following command:

$ yum install snowflake-odbc-<version>.x86_64.rpm

Note

The installation directory is /usr/lib64/snowflake/odbc/. You’ll need the location later in the instructions.

Installing the DEB Package

Note

The DEB package requires unixODBC as the driver manager.

To install the Snowflake ODBC driver for Linux using the DEB package, after optionally verifying the package signature, run the following command:

$ sudo dpkg -i snowflake-odbc-<version>.x86_64.deb

The command may fail if any required dependencies for the package manager are not installed. If that happens, install them now:

$ sudo apt-get install -f

Note

The installation directory is /usr/lib/snowflake/odbc/. You’ll need the location later in the instructions.

Step 3: Configure the Environment (TGZ Only)

Note

If you installed the ODBC driver using the RPM or DEB package file, skip this step.

If you installed using the TGZ file, configure the environment using the installed driver manager (either iODBC or unixODBC).

Configuring with iODBC

In a terminal window, change to the /snowflake_odbc/ directory, and run the following command to install Snowflake ODBC:

$ ./iodbc_setup.sh

This script completes the following steps:

  • Adds one Snowflake connection to your system-level /etc/odbc.ini file.
  • Adds the Snowflake driver information to your system-level /etc/odbcinst.ini file.
  • Merges all certificates needed by the Snowflake ODBC Driver to your system-default /etc/pki/nssdb file.

By running iodbc_setup.sh, you don’t need to set any environment variables.

Alternatively, if you don’t want Snowflake to change your system configurations, add the following environment variables to your shell configuration file (e.g. .profile, .bash_profile):

  • ODBCINI = /<path>/snowflake_odbc/conf/odbc.ini
  • ODBCINSTINI = /<path>/snowflake_odbc/conf/odbcinst.ini
  • SSL_DIR = /<path>/snowflake_odbc/SSLCertificates/nssdb

Where path is the location of the snowflake_odbc directory. If you have configured other ODBC drivers in your system and plan to add the Snowflake ODBC entries to your existing odbc.ini and odbcinst.ini files in the next step, then point ODBCINI and ODBCINSTINI to the location of those files.

Configuring with unixODBC

In a terminal window, change to the /snowflake_odbc/ directory, and run the following command to install Snowflake ODBC:

$ ./unixodbc_setup.sh

This script completes the following steps:

  • Adds a Snowflake connection to your system-level /etc/odbc.ini file.
  • Adds the Snowflake driver information to your system-level /etc/odbcinst.ini file.
  • Merges all certificates needed by the Snowflake ODBC Driver to your system-default /etc/pki/nssdb file.

By running unixodbc_setup.sh, you don’t need to set any environment variables.

Alternatively, if you don’t want Snowflake change your system configurations, add the following environment variables to your shell configuration file, e.g. .profile, .bash_profile:

  • ODBCSYSINI = /<path>/snowflake_odbc/conf/
  • SSL_DIR = /<path>/snowflake_odbc/SSLCertificates/nssdb

Where path is the location of the snowflake_odbc directory. If you have configured other ODBC drivers in your system and plan to add the Snowflake ODBC entries to your existing odbc.ini and odbcinst.ini files in the next step, then point ODBCSYSINI to the location of those files.

Step 4: Configure the ODBC Driver

Configuring the ODBC driver requires adding entries to the following files:

  • snowflake_odbc/lib/simba.snowflake.ini
  • /etc/odbcinst.ini (or snowflake_odbc/conf/odbc.ini, if you are using environment variables)
  • /etc/odbc.ini (or snowflake_odbc/conf/odbcinst.ini, if you are using environment variables)

4.1: simba.snowflake.ini File (Driver Manager and Logging)

Add the following entries to the simba.snowflake.ini file:

ErrorMessagesPath=<path>/snowflake_odbc/ErrorMessages/
LogPath=/tmp/
ODBCInstLib=<driver_manager_path>

Where:

  • path is the location of the snowflake_odbc directory.

  • driver_manager_path is the location of your driver manager directory:

    • iODBC: ODBCInstLib=libiodbcinst.so.2
    • unixODBC: ODBCInstLib=libodbcinst.so

    Note

    If your driver manager directory is not included in the LD_LIBRARY_PATH environment variable, specify the full path to the driver manager library here.

Verify that you have write permissions on the log path.

4.2: odbcinst.ini File (Driver Registration)

Add the following entries to the odbcinst.ini file:

[ODBC Drivers]
SnowflakeDSIIDriver=Installed

[SnowflakeDSIIDriver]
APILevel=1
ConnectFunctions=YYY
Description=Snowflake DSII
Driver=/<path>/snowflake_odbc/lib/libSnowflake.so
DriverODBCVer=03.52
SQLLevel=1

Where path is the location of the snowflake_odbc directory.

4.3: odbc.ini File (DSN Entries)

For each DSN, add the following entries to the odbc.ini file:

  • DSN Name and driver name (SnowflakeDSIIDriver), in the form of <dsn_name> = <driver_name>.

  • Parameters:

    • Required connection parameters, such as server.
    • Any additional, optional parameters, such as default role, database, and warehouse.

    Parameters are specified in the form of <parameter_name> = <value>. For details about the parameters that can be set for each DSN, see ODBC Configuration and Connection Parameters.

The following example illustrates an odbc.ini file containing two drivers, testodbc1 and testodbc2:

[ODBC Data Sources]
testodbc1 = SnowflakeDSIIDriver
testodbc2 = SnowflakeDSIIDriver


[testodbc1]
Driver      = /usr/jsmith/snowflake_odbc/lib/libSnowflake.so
Description =
server      = abc123.snowflakecomputing.com
role        = sysadmin


[testodbc2]
Driver      = /usr/jsmith/snowflake_odbc/lib/libSnowflake.so
Description =
server      = abc123.snowflakecomputing.com
role        = analyst
database    = sales
warehouse   = analysis

Note the following:

  • Both drivers in the example have default roles.
  • testodbc2 also has a default database and warehouse.

Step 5: Test the ODBC Driver

Test the driver using the installed driver manager (either iODBC or unixODBC).

Testing with iODBC

Test the DSNs you created. On the command line, specify the DSN name, user login name, and password, using the following format:

iodbctest "DSN=<dsn_name>;UID=<user_name>;PWD=<password>"

For example:

$ iodbctest "DSN=testodbc2;UID=mary;PWD=password"
iODBC Demonstration program
This program shows an interactive SQL processor
Driver Manager: 03.52.0709.0909
Driver: 2.12.70 (Snowflake)

SQL>

Testing with unixODBC

Test the DSNs you created using the isql command line utility provided with unixODBC.

On the command line, specify the DSN name, user login name, and password.

For example:

$ isql -v testodbc2 mary <password>

Dec 14 22:57:50 INFO  2022078208 Driver::LogVersions: SDK Version: 09.04.09.1013
Dec 14 22:57:50 INFO  2022078208 Driver::LogVersions: DSII Version: 2.12.36
Dec 14 22:57:50 INFO  2022078208 SFConnection::connect: Tracing level: 4

+---------------------------------------+
| Connected!                            |
|                                       |
| sql-statement                         |
| help [tablename]                      |
| quit                                  |
|                                       |
+---------------------------------------+
SQL>