Linux DSN Configuration

This section shows how to connect to Cassandra and execute SQL queries from several Linux distributions: Debian-based systems, like Ubuntu, and Red Hat Linux platforms, like Red Hat Enterprise Linux (RHEL), CentOS, and Fedora.

Using a Driver Manager

Before installing the CData ODBC Driver for Cassandra 2016 on Linux, you will need to install a driver manager. ODBC-compliant applications connect to the driver through a driver manager. After you connect, the driver manager loads the driver and passes function calls from the application to the driver. The driver manager also implements some functions for discovering the registered drivers and DSNs. DSNs can be defined for a specific user or system wide.

Installing unixODBC

Precompiled binaries for the unixODBC driver manager are available for many operating systems.

On Debian-based systems like Ubuntu, you can install unixODBC by running the following command as root or with sudo:

apt-get install unixODBC unixODBC-dev

On Red Hat Enterprise Linux, CentOS, and Fedora, you can install unixODBC with YUM or DNF. For example, run the following command as root or with sudo:

yum install unixODBC unixODBC-devel

If binaries are not available for your operating system, you will need to compile unixODBC yourself. Please refer to the unixODBC website for more information about obtaining binaries or compiling unixODBC on your operating system.

Installing the Driver Dependencies

Minimum Linux Versions

Below are the minimum supported versions for Red Hat-based and Debian-based systems:


OS	Min. Version
Ubuntu	11
Debian	7
RHEL	6
CentOS	6
Fedora	13

Required Libraries and Packages

Below are the libraries required by the driver and their corresponding packages:


Debian/Ubuntu Package	RHEL/CentOS/Fedora Package	File
libc6	glibc	linux-vdso.1
libc6	glibc	libm.so.6
libc6	glibc	librt.so.1
libc6	glibc	libdl.so.2
libc6	glibc	libpthread.so.0
libc6	glibc	libc.so.6
libc6	glibc	ld-linux-x86-64.so.2
libstdc++6	libstdc++	libstdc++.so.6
zlib1g	zlib	libz.so.1
libgcc1	libgcc	libgcc_s.so.1

Installing the Packages

You can install the necessary dependencies with the following commands:

Debian/Ubuntu:

apt-get install libc6 libstdc++6 zlib1g libgcc1

RHEL/CentOS/Fedora:
```
yum install glibc libstdc++ zlib libgcc
```

Installing the Driver

You can use standard package management systems to easily and quickly install the driver.

On Debian-based systems, like Ubuntu, you can install the driver by running the following command as root or with sudo:

dpkg -i /path/to/.deb

On systems that support the RPM package format, you can install the driver by running the following command as root or with sudo:

rpm -Uvh /path/to/.rpm

Using the unixODBC Configuration Files

You can determine the location of the configuration files on your system by entering the following command into a terminal:

odbcinst -j

Below is an example of the output of this command:

DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
FILE DATA SOURCES..: /etc/ODBCDataSources
USER DATA SOURCES..: /home/myuser/.odbc.ini
SQLULEN Size.......: 8
SQLLEN Size........: 8
SQLSETPOSIROW Size.: 8

The driver installation registers the driver for system-wide use and creates a system DSN with empty values for commonly required properties. Modifying unixODBC's system-wide settings requires elevated permissions; to do so, you can use root or the sudo command.

Configuring a DSN

ODBC data sources are defined in sections in the odbc.ini file.

In addition to the connection properties required to connect to your data source, the Driver property specifies either a driver definition in the odbcinst.ini file or the path to the driver library.

[CData Cassandra Source]
Driver = CData ODBC Driver for Cassandra
Description = My Description
MyConnectionProperty1 = My Value
MyConnectionProperty2 = My Value2

You can list the data sources on your system with the following command:

odbcinst  -q -s

Connecting to the Server

Set the Server and Database connection properties to connect to Cassandra.

To connect to a distributed system, you can set Server to a comma-separated list of servers and ports, separated by colons, and ConsistencyLevel.

The following sections detail connection properties for authentication, security, and data access. See Advanced Settings if you need more control over connecting to your system.

Securing Cassandra Connections

You can set UseSSL to negotiate SSL/TLS encryption when you connect. By default, the driver attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store. To specify another certificate, see the SSLServerCert property for the available formats to do so.

Authenticating to Cassandra

The driver supports authentication with login credentials and the additional authentication features of DataStax Enterprise (DSE) Cassandra. The following sections detail connection properties your authentication method may require in addition to User, Password, and AuthScheme.

You need to set AuthScheme to the value corresponding to the authenticator configured for your system. You specify the authenticator in the authenticator property in the cassandra.yaml file. This file is typically found in /etc/dse/cassandra.

Authenticating with Login Credentials

Internal authentication is supported through Cassandra's built-in default PasswordAuthenticator or through the DSE Unified Authenticator on DSE Cassandra.


AuthScheme value	cassandra.yaml authenticator property
BASIC	PasswordAuthenticator
DSE	com.datastax.bdp.cassandra.auth.DseAuthenticator

If you are using the DSE Unified Authenticator, additionally set default_scheme as "internal" in the dse.yaml file. This file can often be found in /etc/dse.

Using Kerberos and LDAP

DataStax Enterprise Cassandra supports authentication to these external systems through the DSE Unified Authenticator. In cassandra.yaml, set the authenticator property to "com.datastax.bdp.cassandra.auth.DseAuthenticator".

Additionally, set the default_scheme property in the dse.yaml file to "kerberos" or "ldap". This file can often be found in /etc/dse.

For Kerberos, set KerberosKDC, KerberosRealm, and KerberosSPN.

Using PKI

You can specify a client certificate to authenticate the driver with SSLClientCert, SSLClientCertType, SSLClientCertSubject, and SSLClientCertPassword.

Accessing NoSQL Tables

The driver implements Automatic Schema Discovery that is highly configurable. The following sections outline the driver's defaults and link to ways to further customize.

Flattening Nested JSON

By default, the driver projects columns over the properties of objects, including objects nested in objects. Arrays are returned as JSON strings, by default. You can use the following properties to access array elements, including objects nested in arrays.

FlattenArrays: Set this property to the number of array elements that you want to return as column values. You can also use this property with FlattenObjects to extract the properties of objects nested in arrays.
FlattenObjects: By default, this is true; that is, the properties of objects and nested objects are returned as columns. When you set FlattenArrays, objects nested in the specified array elements are also flattened and returned as columns.

Other mechanisms for accessing nested objects are detailed in NoSQL Database. See Advanced Settings for more control over data access at connection time.

Configuring Driver Definitions

The sections of the odbcinst.ini file map a driver name to the driver library. The section begins with the driver name; the Driver property points to the path to the driver library. The driver library is the .so file located by default in /opt/cdata/cassandra/lib. A Description property can also be provided.

You can list the drivers installed on the system with the following command:

odbcinst -q -d

Testing the Connection

You can use isql, included with unixODBC, to execute SQL queries to Cassandra from the command line. When testing the connection, use the -v flag to output any messages from the driver manager and the driver.

isql -v "CData Cassandra Source"