System Requirements (ODBC Driver for SQL Server) | Microsoft Docs

Table of Contents

System Requirements Installing the Driver Manager Installing the Microsoft ODBC Driver for SQL Server Feature Guides Connection String Keywords and Data Source Names (DSNs) Data Access Tracing with the ODBC Driver on Linux and macOS ODBC Driver on Linux and macOS - High Availability and Disaster Recovery Programming Guidelines Tools Connecting with bcp.exe Connecting with sqlcmd.exe Using Integrated Authentication Release Notes Known Issues Frequently Asked Questions (FAQ) for ODBC Linux and macOS System Requirements 5/3/2018 • 1 min to read • Edit Online

Download ODBC Driver This topic lists the requirements to use the Microsoft ODBC Driver for SQL Server on Linux and macOS. Microsoft ODBC Driver 13, 13.1, and 17 for SQL Server The Linux and macOS drivers are available only for the 64-bit versions of the following operating systems:

OPERATING SYSTEM SUPPORTED DRIVER VERSION

Apple OS X 10.11 (El Capitan) 13, 13.1, 17

Apple macOS 10.12 (Sierra) 13, 13.1, 17

Apple macOS 10.13 (High Sierra) 17

Debian Linux 8 13, 13.1, 17

Debian Linux 9 17

RedHat Enterprise Linux 6 13, 13.1, 17

RedHat Enterprise Linux 7 13, 13.1, 17

SuSE Linux Enterprise Server 11 13, 13.1, 17

NOTE: ODBC Driver 17 supports SuSE Linux Enterprise Server 11 SP4 only

SuSE Linux Enterprise Server 12 13, 13.1, 17

Ubuntu Linux 14.04 13, 13.1, 17

Ubuntu Linux 15.10 13, 13.1

Ubuntu Linux 16.04 13, 13.1, 17

Ubuntu Linux 16.10 13, 13.1

Ubuntu Linux 17.10 17

The installation packages for the Microsoft ODBC Driver 13, 13.1, and 17 for SQL Server on Linux and macOS resolve the driver's dependencies automatically when installed using the package management system of your distribution, as described in Installing the Driver. Microsoft ODBC Driver 11 for SQL Server 64-bit UnixODBC 2.3.0 Driver Manager, built for 64-bit SQLLEN/SQLULEN. Later versions of the 64-bit UnixODBC Driver Manager are not supported with the ODBC driver on Linux. See Installing the Driver Manager for more information. ODBC driver for Red Hat Enterprise Linux 5 (64-bit) requires the following packages, and can be downloaded here: Microsoft ODBC Driver 11 for SQL Server - Red Hat Linux

glibc libgcc libstdc++ e2fsprogs-libs krb5-libs openssl ODBC driver for Red Hat Enterprise Linux 6 (64-bit) requires the following packages, and can be downloaded here: Microsoft ODBC Driver 11 for SQL Server - Red Hat Linux

glibc libgcc libstdc++ libuuid krb5-libs openssl ODBC driver for SUSE Linux Enterprise 11 Service Pack 2 (64-bit) requires the following packages, and can be downloaded here: Microsoft ODBC Driver 11 Preview for SQL Server - SUSE Linux

glibc libstdc++46 libgcc46 libuuid1 krb5 libopenssl0_9_8 See Also Installing the Driver Manager Known Issues in this Version of the Driver Release Notes Installing the Driver Manager 5/3/2018 • 3 min to read • Edit Online

Download ODBC Driver This article contains instructions to install the unixODBC Driver Manager for use with all the versions of Microsoft ODBC Driver for SQL Server on Linux and macOS.

IMPORTANT Delete any driver manager packages installed on your computer before you install the unixODBC Driver Manager. Installing the unixODBC Driver Manager could cause a failure of an existing Driver Manager.

Installing the Driver Manager for Microsoft ODBC Driver 13, 13.1, and 17 The driver manager dependency is resolved automatically by the package management system when you install the Microsoft ODBC Driver 13, 13.1, or 17 for SQL Server on Linux or macOS by following the instructions in Installing the Microsoft ODBC Driver for SQL Server on Linux or macOS. Installing the Driver Manager for Microsoft ODBC Driver 11 for SQL Server (SUSE and Red Hat Linux only.) Using the Installation Script

IMPORTANT These instructions refer to msodbcsql-11.0.2270.0.tar.gz , which is the installation file for Red Hat Linux. If you are installing the Preview for SUSE Linux, the file name is msodbcsql-11.0.2260.0.tar.gz .

To install the driver manager: 1. Make sure that you have root permission. 2. Go to the directory where the Microsoft SQL Server ODBC Driver download placed the file called msodbcsql-11.0.2270.0.tar.gz . Make sure that you have the *.tar.gz file that matches your version of Linux. To extract the files, execute the following command: tar xvzf msodbcsql-11.0.2270.0.tar.gz.

3. Change to the msodbcsql-11.0.2270.0 directory and there you should see a file called build_dm.sh . You can run build_dm.sh to install the unixODBC Driver Manager. 4. To see a list of the available options, execute the following command: ./build_dm.sh --help. 5. When you are ready to install, and if your computer can access an external site via FTP, execute the following command: ./build_dm.sh.

If your computer cannot access an external site via FTP, get unixODBC-2.3.0.tar.gz . You can get unixODBC-2.3.0.tar.gz from http://www.unixodbc.org. Click the Download link on the left side of the page to go to the download page. Then click the appropriate link to download unixODBC-2.3.0 (not unixODBC-2.3.1). unixODBC-2.3.1 is not supported with this release of the Microsoft ODBC Driver 11 for SQL Server. Execute the following command to begin the unixODBC Driver Manager installation: ./build_dm.sh --download- url=file://unixODBC-2.3.0.tar.gz. 1. Type YES to proceed with unpacking the files. This part of the process can take up to five minutes to complete. 2. After the script stops running, follow the instructions on the screen to install the unixODBC Driver Manager. You are now ready to install the driver. For more information, see Installing the Microsoft ODBC Driver for SQL Server on Linux and macOS. Manual Installation If the installation script is unable to complete, configure and build the proper driver manager yourself. 1. Remove any older installed version of unixODBC (for example, unixODBC 2.2.11). On Red Hat Enterprise Linux 5 or 6, execute the following command: yum remove unixODBC. On SUSE Linux Enterprise, zypper remove unixODBC. 2. Go to http://www.unixodbc.org. Click the Download link on the left side of the page to go to the download page. Then click the appropriate link to save the file unixODBC-2.3.0.tar.gz to your computer. UnixODBC- 2.3.1 is not supported with this release of the Microsoft ODBC Driver 11 for SQL Server. 3. On your Linux computer, execute the command: tar xvzf unixODBC-2.3.0.tar.gz. 4. Change to the unixODBC-2.3.0 directory. 5. At a command prompt, execute the command: CPPFLAGS="-DSIZEOF_LONG_INT=8". 6. At a command prompt, execute the command: export CPPFLAGS. 7. At a command prompt, execute the command: "./configure --prefix=/usr --libdir=/usr/lib64 -- sysconfdir=/etc --enable-gui=no --enable-drivers=no --enable-iconv --with-iconv-char-enc=UTF8 --with-iconv-ucode-enc=UTF16LE". 8. At a command prompt (logged in as root), execute the command: make. 9. At a command prompt (logged in as root), execute the command: make install. You are now ready to install the driver. For more information, see Installing the Microsoft ODBC Driver for SQL Server on Linux and macOS. See Also Installing the Microsoft ODBC Driver for SQL Server on Linux and macOS Known Issues in this Version of the Driver Release Notes Installing the Microsoft ODBC Driver for SQL Server on Linux and macOS 5/3/2018 • 12 min to read • Edit Online

Download ODBC Driver This article explains how to install the Microsoft ODBC Driver for SQL Server on Linux and macOS, as well as the optional Command-Line Tools for SQL Server ( bcp and sqlcmd ) and the unixODBC Development Headers. Microsoft ODBC Driver 17 for SQL Server

IMPORTANT If you installed the v17 msodbcsql package that was briefly available, you should remove it before installing the msodbcsql17 package. This will avoid conflicts. The msodbcsql17 package can be installed side by side with the msodbcsql v13 package.

Debian 8 and 9

sudo su curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add -

#Download appropriate package for the OS version #Choose only ONE of the following, corresponding to your OS version

#Debian 8 curl https://packages.microsoft.com/config/debian/8/prod.list > /etc/apt/sources.list.d/mssql-release.list

#Debian 9 curl https://packages.microsoft.com/config/debian/9/prod.list > /etc/apt/sources.list.d/mssql-release.list

exit sudo apt-get update sudo ACCEPT_EULA=Y apt-get install msodbcsql17 # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y apt-get install mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bash_profile echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo apt-get install unixodbc-dev

RedHat Enterprise Server 6 and 7 sudo su

#Download appropriate package for the OS version #Choose only ONE of the following, corresponding to your OS version

#RedHat Enterprise Server 6 curl https://packages.microsoft.com/config/rhel/6/prod.repo > /etc/yum.repos.d/mssql-release.repo

#RedHat Enterprise Server 7 curl https://packages.microsoft.com/config/rhel/7/prod.repo > /etc/yum.repos.d/mssql-release.repo

exit sudo yum remove unixODBC-utf16 unixODBC-utf16-devel #to avoid conflicts sudo ACCEPT_EULA=Y yum install msodbcsql17 # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y yum install mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bash_profile echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo yum install unixODBC-devel

SUSE Linux Enterprise Server 11SP4 and 12

sudo su

#Download appropriate package for the OS version #Choose only ONE of the following, corresponding to your OS version

#SUSE Linux Enterprise Server 11 SP4 zypper ar https://packages.microsoft.com/config/sles/11/prod.repo

#SUSE Linux Enterprise Server 12 zypper ar https://packages.microsoft.com/config/sles/12/prod.repo

exit sudo ACCEPT_EULA=Y zypper install msodbcsql17 # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y zypper install mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bash_profile echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo zypper install unixODBC-devel

Ubuntu 14.04, 16.04 and 17.10 sudo su curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add -

#Download appropriate package for the OS version #Choose only ONE of the following, corresponding to your OS version

#Ubuntu 14.04 curl https://packages.microsoft.com/config/ubuntu/14.04/prod.list > /etc/apt/sources.list.d/mssql- release.list

#Ubuntu 16.04 curl https://packages.microsoft.com/config/ubuntu/16.04/prod.list > /etc/apt/sources.list.d/mssql- release.list

#Ubuntu 17.10 curl https://packages.microsoft.com/config/ubuntu/17.10/prod.list > /etc/apt/sources.list.d/mssql- release.list

OS X 10.11 (El Capitan), macOS 10.12 (Sierra), and macOS 10.13 (High Sierra)

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release brew update brew install --no-sandbox msodbcsql17 mssql-tools

Microsoft ODBC Driver 13.1 for SQL Server Debian 8

sudo su curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add - curl https://packages.microsoft.com/config/debian/8/prod.list > /etc/apt/sources.list.d/mssql-release.list exit sudo apt-get update sudo ACCEPT_EULA=Y apt-get install msodbcsql # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y apt-get install mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bash_profile echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo apt-get install unixodbc-dev

RedHat Enterprise Server 6 sudo su curl https://packages.microsoft.com/config/rhel/6/prod.repo > /etc/yum.repos.d/mssql-release.repo exit sudo yum remove unixODBC-utf16 unixODBC-utf16-devel #to avoid conflicts sudo ACCEPT_EULA=Y yum install msodbcsql # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y yum install mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bash_profile echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo yum install unixODBC-devel

RedHat Enterprise Server 7

sudo su curl https://packages.microsoft.com/config/rhel/7/prod.repo > /etc/yum.repos.d/mssql-release.repo exit sudo yum remove unixODBC-utf16 unixODBC-utf16-devel #to avoid conflicts sudo ACCEPT_EULA=Y yum install msodbcsql # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y yum install mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bash_profile echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo yum install unixODBC-devel

SUSE Linux Enterprise Server 11

sudo su zypper ar https://packages.microsoft.com/config/sles/11/prod.repo exit sudo ACCEPT_EULA=Y zypper install msodbcsql # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y zypper install mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bash_profile echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo zypper install unixODBC-devel

SUSE Linux Enterprise Server 12

sudo su zypper ar https://packages.microsoft.com/config/sles/12/prod.repo exit sudo ACCEPT_EULA=Y zypper install msodbcsql # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y zypper install mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bash_profile echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo zypper install unixODBC-devel

Ubuntu 15.10 sudo su curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add - curl https://packages.microsoft.com/config/ubuntu/15.10/prod.list > /etc/apt/sources.list.d/mssql- release.list exit sudo apt-get update sudo ACCEPT_EULA=Y apt-get install msodbcsql # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y apt-get install mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bash_profile echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo apt-get install unixodbc-dev

Ubuntu 16.04

sudo su curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add - curl https://packages.microsoft.com/config/ubuntu/16.04/prod.list > /etc/apt/sources.list.d/mssql- release.list exit sudo apt-get update sudo ACCEPT_EULA=Y apt-get install msodbcsql # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y apt-get install mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bash_profile echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo apt-get install unixodbc-dev

Ubuntu 16.10

sudo su curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add - curl https://packages.microsoft.com/config/ubuntu/16.10/prod.list > /etc/apt/sources.list.d/mssql- release.list exit sudo apt-get update sudo ACCEPT_EULA=Y apt-get install msodbcsql # optional: for bcp and sqlcmd sudo ACCEPT_EULA=Y apt-get install mssql-tools echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bash_profile echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc source ~/.bashrc # optional: for unixODBC development headers sudo apt-get install unixodbc-dev

OS X 10.11 (El Capitan) and macOS 10.12 (Sierra)

Microsoft ODBC Driver 13 for SQL Server RedHat Enterprise Server 6 sudo su curl https://packages.microsoft.com/config/rhel/6/prod.repo > /etc/yum.repos.d/mssql-release.repo exit sudo yum update sudo yum remove unixODBC #to avoid conflicts sudo ACCEPT_EULA=Y yum install msodbcsql-13.0.1.0-1 mssql-tools-14.0.2.0-1 sudo yum install unixODBC-utf16-devel #this step is optional but recommended* #Create symlinks for tools ln -sfn /opt/mssql-tools/bin/sqlcmd-13.0.1.0 /usr/bin/sqlcmd ln -sfn /opt/mssql-tools/bin/bcp-13.0.1.0 /usr/bin/bcp

RedHat Enterprise Server 7

sudo su curl https://packages.microsoft.com/config/rhel/7/prod.repo > /etc/yum.repos.d/mssql-release.repo exit sudo yum update sudo yum remove unixODBC #to avoid conflicts sudo ACCEPT_EULA=Y yum install msodbcsql-13.0.1.0-1 mssql-tools-14.0.2.0-1 sudo yum install unixODBC-utf16-devel #this step is optional but recommended* #Create symlinks for tools ln -sfn /opt/mssql-tools/bin/sqlcmd-13.0.1.0 /usr/bin/sqlcmd ln -sfn /opt/mssql-tools/bin/bcp-13.0.1.0 /usr/bin/bcp

Ubuntu 15.10

sudo su curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add - curl https://packages.microsoft.com/config/ubuntu/15.10/prod.list > /etc/apt/sources.list.d/mssql- release.list exit sudo apt-get update sudo ACCEPT_EULA=Y apt-get install msodbcsql=13.0.1.0-1 mssql-tools=14.0.2.0-1 sudo apt-get install unixodbc-dev-utf16 #this step is optional but recommended* #Create symlinks for tools ln -sfn /opt/mssql-tools/bin/sqlcmd-13.0.1.0 /usr/bin/sqlcmd ln -sfn /opt/mssql-tools/bin/bcp-13.0.1.0 /usr/bin/bcp

Ubuntu 16.04

sudo su curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add - curl https://packages.microsoft.com/config/ubuntu/16.04/prod.list > /etc/apt/sources.list.d/mssql- release.list exit sudo apt-get update sudo ACCEPT_EULA=Y apt-get install msodbcsql=13.0.1.0-1 mssql-tools=14.0.2.0-1 sudo apt-get install unixodbc-dev-utf16 #this step is optional but recommended* #Create symlinks for tools ln -sfn /opt/mssql-tools/bin/sqlcmd-13.0.1.0 /usr/bin/sqlcmd ln -sfn /opt/mssql-tools/bin/bcp-13.0.1.0 /usr/bin/bcp

SUSE Linux Enterprise Server 12 sudo su zypper ar https://packages.microsoft.com/config/sles/12/prod.repo zypper update sudo ACCEPT_EULA=Y zypper install msodbcsql-13.0.1.0-1 mssql-tools-14.0.2.0-1 zypper install unixODBC-utf16-devel #Create symlinks for tools ln -sfn /opt/mssql-tools/bin/sqlcmd-13.0.1.0 /usr/bin/sqlcmd ln -sfn /opt/mssql-tools/bin/bcp-13.0.1.0 /usr/bin/bcp

Offline installation If you prefer/require the Microsoft ODBC Driver 13 to be installed on a computer with no internet connection, you will need to resolve package dependencies manually. The Microsoft ODBC Driver 13 has the following direct dependencies: Ubuntu: libc6 (>= 2.21), libstdc++6 (>= 4.9), libkrb5-3, libcurl3, openssl, debconf (>= 0.5), unixodbc (>= 2.3.1-1) Red Hat: glibc, e2fsprogs, krb5-libs, openssl, unixODBC SuSE: glibc, libuuid1, krb5, openssl, unixODBC

Each of these packages in turn has their own dependencies, which may or may not be present on the system. For a general solution to this issue, refer to your distribution's package manager documentation: Redhat, Ubuntu, and SUSE It is also common to manually download all the dependent packages and place them together on the installation computer, then manually install each package in turn, finishing with the Microsoft ODBC Driver 13 package. Redhat Linux Enterprise Server 7 Download the latest msodbcsql .rpm from here: http://packages.microsoft.com/rhel/7/prod/ Install dependencies and the driver

yum install glibc e2fsprogs krb5-libs openssl unixODBC unixODBC-devel #install dependencies sudo rpm -i msodbcsql-13.1.X.X-X.x86_64.rpm #install the Driver

Ubuntu 16.04 Download the latest msodbcsql .deb from here: http://packages.microsoft.com/ubuntu/16.04/prod/pool/main/m/msodbcsql/ Install dependencies and the driver

sudo apt-get install libc6 libstdc++6 libkrb5-3 libcurl3 openssl debconf unixodbc unixodbc-dev #install dependencies sudo dpkg -i msodbcsql_13.1.X.X-X_amd64.deb #install the Driver

SUSE Linux Enterprise Server 12 Download the latest msodbcsql .rpm from here: http://packages.microsoft.com/sles/12/prod/ Install the dependencies and the driver

zypper install glibc, libuuid1, krb5, openssl, unixODBC unixODBC-devel #install dependencies sudo rpm -i msodbcsql-13.1.X.X-X.x86_64.rpm #install the Driver

Once you have completed the package installation, you can verify that the Microsoft ODBC Driver 13 can find all its dependencies by running ldd and inspecting its output for missing libraries: ldd /opt/microsoft/msodbcsql/lib64/libmsodbcsql-*

Microsoft ODBC Driver 11 for SQL Server on Linux Before you can use the driver, install the unixODBC driver manager. For more information, see Installing the Driver Manager. Installation Steps

IMPORTANT These instructions refer to msodbcsql-11.0.2270.0.tar.gz , which is installation file for Red Hat Linux. If you are installing the Preview for SUSE Linux, the file name is msodbcsql-11.0.2260.0.tar.gz .

To install the driver: 1. Make sure that you have root permission.

2. Change to the directory where the download placed the file msodbcsql-11.0.2270.0.tar.gz . Make sure that you have the *.tar.gz file that matches your version of Linux. To extract the files, execute the following command, tar xvzf msodbcsql-11.0.2270.0.tar.gz .

3. Change to the msodbcsql-11.0.2270.0 directory and there you should see a file called install.sh. 4. To see a list of the available installation options, execute the following command: ./install.sh. 5. Make a backup of odbcinst.ini. The driver installation updates odbcinst.ini. odbcinst.ini contains the list of drivers that are registered with the unixODBC Driver Manager. To discover the location of odbcinst.ini on your computer, execute the following command: odbc_config --odbcinstini .

6. Before you install the driver, execute the following command: ./install.sh verify . The output of ./install.sh verify reports if your computer has the required software to support the ODBC driver on Linux.

7. When you are ready to install the ODBC driver on Linux, execute the command: ./install.sh install . If you need to specify an install command ( bin-dir or lib-dir ), specify the command after the install option. 8. After reviewing the license agreement, type YES to continue with the installation.

Installation puts the driver in /opt/microsoft/msodbcsql/11.0.2270.0 . The driver and its support files must be in /opt/microsoft/msodbcsql/11.0.2270.0 . To verify that the Microsoft ODBC driver on Linux was registered successfully, execute the following command: odbcinst -q -d -n "ODBC Driver 11 for SQL Server" . Use Existing MSDN C++ ODBC Samples for the ODBC Driver on Linux shows a code sample that connects to SQL Server using the ODBC driver on Linux. Uninstalling You can uninstall the ODBC driver 11 on Linux by executing the following commands:

1. rm -f /usr/bin/sqlcmd

2. rm -f /usr/bin/bcp 3. rm -rf /opt/microsoft/msodbcsql

4. odbcinst -u -d -n "ODBC Driver 11 for SQL Server" Troubleshooting Connection Problems If you are unable to make a connection to SQL Server using the ODBC driver, use the following information to identify the problem. The most common connection problem is to have two copies of the UnixODBC Driver Manager installed. Search /usr for libodbc*.so*. If you see more than one version of the file, you (possibly) have more than one driver manager installed. Your application might use the wrong version.

Enable the connection log by editing your /etc/odbcinst.ini file to contain the following section with these items:

[ODBC] Trace = Yes TraceFile = (path to log file, or /dev/stdout to output directly to the terminal)

If you get another connection failure and do not see a log file, there (possibly) are two copies of the driver manager on your computer. Otherwise, the log output should be similar to the following:

[ODBC][28783][1321576347.077780][SQLDriverConnectW.c][290] Entry: Connection = 0x17c858e0 Window Hdl = (nil) Str In = [DRIVER={ODBC Driver 13 for SQL Server};SERVER={contoso.com};Trusted_Connection= {YES};WSID={mydb.contoso.com};AP...][length = 139 (SQL_NTS)] Str Out = (nil) Str Out Max = 0 Str Out Ptr = (nil) Completion = 0 UNICODE Using encoding ASCII 'UTF8' and UNICODE 'UTF16LE'

If the ASCII character encoding is not UTF-8, for example:

UNICODE Using encoding ASCII 'ISO8859-1' and UNICODE 'UCS-2LE'

There is more than one Driver Manager installed and your application is using the wrong one, or the Driver Manager was not built correctly. For more information about resolving connection failures, see: Steps to troubleshoot SQL connectivity issues SQL Server 2005 Connectivity Issue Troubleshoot - Part I Connectivity troubleshooting in SQL Server 2008 with the Connectivity Ring Buffer SQL Server Authentication Troubleshooter Error details (http://www.microsoft.com/products/ee/transform.aspx? ProdName=Microsoft+SQL+Server&EvtSrc=MSSQLServer&EvtID=11001) The error number specified in the URL (11001) should be changed to match the error that you see. Driver Files The ODBC Driver on Linux and MacOS consists of the following components: Linux

COMPONENT DESCRIPTION

libmsodbcsql-17.X.so.X.X or libmsodbcsql-13.X.so.X.X The shared object ( so ) dynamic library file that contains all of the driver's functionality. This file is installed in /opt/microsoft/msodbcsql17/lib64/ for the Driver 17 and in /opt/microsoft/msodbcsql/lib64/ for Driver 13.

msodbcsqlr17.rll or msodbcsqlr13.rll The accompanying resource file for the driver library. This file is installed in [driver .so directory]../share/resources/en_US/

msodbcsql.h The header file that contains all of the new definitions needed to use the driver.

Note: You cannot reference msodbcsql.h and odbcss.h in the same program.

msodbcsql.h is installed in /opt/microsoft/msodbcsql17/include/ for Driver 17 and in /opt/microsoft/msodbcsql/include/ for Driver 13.

LICENSE.txt The text file that contains the terms of the End-User License Agreement. This file is placed in /usr/share/doc/msodbcsql17/ for Driver 17 and in /usr/share/doc/msodbcsql/ for Driver 13.

RELEASE_NOTES The text file that contains release notes. This file is placed in /usr/share/doc/msodbcsql17/ for Driver 17 and in /usr/share/doc/msodbcsql/ for Driver 13.

MacOS

COMPONENT DESCRIPTION

libmsodbcsql.17.dylib or libmsodbcsql.13.dylib The dynamic library ( dylib ) file that contains all of the driver's functionality. This file is installed in /usr/local/lib/ .

msodbcsqlr17.rll or msodbcsqlr13.rll The accompanying resource file for the driver library. This file is installed in [driver .dylib directory]../share/msodbcsql17/resources/en_US/ for Driver 17 and in [driver .dylib directory]../share/msodbcsql/resources/en_US/ for Driver 13. COMPONENT DESCRIPTION

msodbcsql.h The header file that contains all of the new definitions needed to use the driver.

Note: You cannot reference msodbcsql.h and odbcss.h in the same program.

msodbcsql.h is installed in /usr/local/include/msodbcsql17/ for Driver 17 and in /usr/local/include/msodbcsql/ for Driver 13.

LICENSE.txt The text file that contains the terms of the End-User License Agreement. This file is placed in /usr/local/share/doc/msodbcsql17/ for Driver 17 and in /usr/local/share/doc/msodbcsql/ for Driver 13.

RELEASE_NOTES The text file that contains release notes. This file is placed in /usr/local/share/doc/msodbcsql17/ for Driver 17 and in /usr/local/share/doc/msodbcsql/ for Driver 13.

Resource File Loading

The driver needs to load the resource file in order to function. This file is called msodbcsqlr17.rll or msodbcsqlr13.rll depending on the driver version. The location of the .rll file is relative to the location of the driver itself ( so or dylib ), as noted in the table above. As of version 17.1 the driver will also attempt to load the .rll from the default directory if loading from the relative path fails. The default resource file paths are:

Linux: /opt/microsoft/msodbcsql17/share/resources/en_US/

MacOS: /usr/local/share/msodbcsql17/resources/en_US/ See Also Installing the Driver Manager Release Notes System Requirements Connecting to SQL Server 5/3/2018 • 3 min to read • Edit Online

Download ODBC Driver This topic discusses how you can create a connection to a SQL Server database. Connection Properties See DSN and Connection String Keywords and Attributes for all the connection string keywords and attributes supported on Linux and Mac

IMPORTANT When connecting to a database that uses database mirroring (has a failover partner), do not specify the database name in the connection string. Instead, send a use database_name command to connect to the database before executing your queries.

The value passed to the Driver keyword can be one of the following: The name you used when you installed the driver. The path to the driver library, which was specified in the template .ini file used to install the driver.

To create a DSN, create (if necessary) and edit the file ~/.odbc.ini ( .odbc.ini in your home directory) for a User DSN only accessible to the current user, or /etc/odbc.ini for a System DSN (administrative privileges required.) The following is a sample file that shows the minimal required entries for a DSN:

[MSSQLTest] Driver = ODBC Driver 13 for SQL Server Server = [protocol:]server[,port] # # Note: # Port is not a valid keyword in the odbc.ini file # for the Microsoft ODBC driver on Linux or macOS #

You can optionally specify the protocol and port to connect to the server. For example, Server=tcp:servername,12345. Note that the only protocol supported by the Linux and macOS drivers is tcp . To connect to a named instance on a static port, use Server=servername,port_number. Connecting to a dynamic port is not supported. Alternatively, you can add the DSN information to a template file, and execute the following command to add it to ~/.odbc.ini : odbcinst -i -s -f template_file

You can verify that your driver is working by using isql to test the connection, or you can use this command: bcp master.INFORMATION_SCHEMA.TABLES out OutFile.dat -S -U -P Using Secure Sockets Layer (SSL) You can use Secure Sockets Layer (SSL) to encrypt connections to SQL Server. SSL protects SQL Server user names and passwords over the network. SSL also verifies the identity of the server to protect against man-in-the- middle (MITM) attacks. Enabling encryption increases security at the expense of performance. For more information, see Encrypting Connections to SQL Server and Using Encryption Without Validation. Regardless of the settings for Encrypt and TrustServerCertificate, the server login credentials (user name and password) are always encrypted. The following table shows the effect of the Encrypt and TrustServerCertificate settings.

TRUSTSERVERCERTIFICATE=NO TRUSTSERVERCERTIFICATE=YES

Encrypt=no Server certificate is not checked. Server certificate is not checked.

Data sent between client and server is Data sent between client and server is not encrypted. not encrypted.

Encrypt=yes Server certificate is checked. Server certificate is not checked.

Data sent between client and server is Data sent between client and server is encrypted. encrypted.

The name (or IP address) in a Subject Common Name (CN) or Subject Alternative Name (SAN) in a SQL Server SSL certificate should exactly match the server name (or IP address) specified in the connection string.

By default, encrypted connections always verify the server’s certificate. However, if you connect to a server that has a self-signed certificate, also add the TrustServerCertificate option to bypass checking the certificate against the list of trusted certificate authorities:

Driver={ODBC Driver 13 for SQL Server};Server=ServerNameHere;Encrypt=YES;TrustServerCertificate=YES

SSL uses the OpenSSL library. The following table shows the minimum supported versions of OpenSSL and the default Certificate Trust Store locations for each platform:

DEFAULT CERTIFICATE TRUST STORE PLATFORM MINIMUM OPENSSL VERSION LOCATION

Debian 9 1.1.0 /etc/ssl/certs

Debian 8.71 1.0.1 /etc/ssl/certs

macOS 10.13 1.0.2 /usr/local/etc/openssl/certs

macOS 10.12 1.0.2 /usr/local/etc/openssl/certs

OS X 10.11 1.0.2 /usr/local/etc/openssl/certs

Red Hat Enterprise Linux 7 1.0.1 /etc/pki/tls/cert.pem

Red Hat Enterprise Linux 6 1.0.0-10 /etc/pki/tls/cert.pem DEFAULT CERTIFICATE TRUST STORE PLATFORM MINIMUM OPENSSL VERSION LOCATION

SuSE Linux Enterprise 12 1.0.1 /etc/ssl/certs

SuSE Linux Enterprise 11 0.9.8 /etc/ssl/certs

Ubuntu 17.10 1.0.2 /etc/ssl/certs

Ubuntu 16.10 1.0.2 /etc/ssl/certs

Ubuntu 16.04 1.0.2 /etc/ssl/certs

You can also specify encryption in the connection string using the Encrypt option when using SQLDriverConnect to connect. See Also Installing the Microsoft ODBC Driver for SQL Server on Linux and macOS Programming Guidelines Data Access Tracing with the ODBC Driver on Linux and macOS 5/3/2018 • 2 min to read • Edit Online

Download ODBC Driver The unixODBC Driver Manager on macOS and Linux supports tracing of ODBC API call entry and exit of the ODBC Driver for SQL Server.

To trace your application's ODBC behavior, edit the odbcinst.ini file's [ODBC] section to set the values Trace=Yes and TraceFile to the path of the file which is to contain the trace output; for example:

Trace=Yes TraceFile=/home/myappuser/odbctrace.log

(You may also use /dev/stdout or any other device name to send trace output there instead of to a persistent file.) With the above settings, every time an application loads the unixODBC Driver Manager, it will record all the ODBC API calls which it performed into the output file.

After you finish tracing your application, remove Trace=Yes from the odbcinst.ini file to avoid the performance penalty of tracing, and ensure any unnecessary trace files are removed.

Tracing applies to all applications that use the driver in odbcinst.ini . To not trace all applications (for example, to avoid disclosing sensitive per-user information), you can trace an individual application instance by providing it the location of a private odbcinst.ini , using the ODBCSYSINI environment variable. For example:

$ ODBCSYSINI=/home/myappuser myapp

In this case, you can add Trace=Yes to the [ODBC Driver 13 for SQL Server] section of /home/myappuser/odbcinst.ini . Determining which odbc.ini File the Driver is Using

The Linux and macOS ODBC drivers do not know which odbc.ini is in use, or the path to the odbc.ini file. However, information about which odbc.ini file is in use is available from the unixODBC tools odbc_config and odbcinst , and from the unixODBC Driver Manager documentation.

For example, the following command prints (among other information) the location of system and user odbc.ini files which contain, respectively, system and user DSNs:

$ odbcinst -j unixODBC 2.3.1 DRIVERS...... : /etc/odbcinst.ini SYSTEM DATA SOURCES: /etc/odbc.ini FILE DATA SOURCES..: /etc/ODBCDataSources USER DATA SOURCES..: /home/odbcuser/.odbc.ini` SQLULEN Size...... : 8 SQLLEN Size...... : 8 SQLSETPOSIROW Size.: 8 The unixODBC documentation explains the differences between user and system DSNs. In summary: User DSNs --- these are DSNs which are only available to a specific user. Users can connect using, add, modify, and remove their own user DSNs. User DSNs are stored in a file in the user's home directory, or a subdirectory thereof. System DSNs --- these DSNs are available for every user on the system to connect using them, but can only be added, modified, and removed by a system administrator. If a user has a user DSN with the same name as a system DSN, the user DSN will be used upon connections by that user. See Also Programming Guidelines ODBC Driver on Linux and macOS Support for High Availability and Disaster Recovery 5/16/2018 • 5 min to read • Edit Online

Download ODBC Driver The ODBC drivers for Linux and macOS support AlwaysOn Availability Groups. For more information about AlwaysOn Availability Groups, see: Availability Group Listeners, Client Connectivity, and Application Failover (SQL Server) Creation and Configuration of Availability Groups (SQL Server) Failover Clustering and AlwaysOn Availability Groups (SQL Server) Active Secondaries: Readable Secondary Replicas (AlwaysOn Availability Groups) You can specify the availability group listener of a given availability group in the connection string. If an ODBC application on Linux or macOS is connected to a database in an availability group that fails over, the original connection is broken and the application must open a new connection to continue work after the failover. The ODBC drivers on Linux and macOS iterate sequentially through all IP addresses associated with a DNS hostname if you are not connecting to an availability group listener, and multiple IP addresses are associated with the hostname. If the DNS server's first returned IP address is not connectable, these iterations can be time consuming. When connecting to an availability group listener, the driver attempts to establish connections to all IP addresses in parallel. If a connection attempt succeeds, the driver discards any pending connection attempts.

NOTE Because a connection can fail due to an availability group failover, implement connection retry logic; retry a failed connection until it reconnects. Increasing connection timeout and implementing connection retry logic increases the chance of connecting to an availability group.

Connecting With MultiSubnetFailover Always specify MultiSubnetFailover=Yes when connecting to a SQL Server 2012 (11.x) availability group listener or SQL Server 2012 (11.x) Failover Cluster Instance. MultiSubnetFailover enables faster failover for all Availability Groups and failover cluster instance in SQL Server 2012 (11.x). MultiSubnetFailover also significantly reduces failover time for single and multi-subnet AlwaysOn topologies. During a multisubnet failover, the client attempts connections in parallel. During a subnet failover, the driver aggressively retries the TCP connection. The MultiSubnetFailover connection property indicates that the application is being deployed in an availability group or Failover Cluster Instance. The driver tries to connect to the database on the primary SQL Server instance by trying to connect to all the IP addresses. When connecting with MultiSubnetFailover=Yes, the client retries TCP connection attempts faster than the operating system's default TCP retransmit intervals. MultiSubnetFailover=Yes enables faster reconnection after failover of either an AlwaysOn Availability Group or an AlwaysOn Failover Cluster Instance. MultiSubnetFailover=Yes applies to both single- and multi-subnet Availability Groups and Failover Cluster Instances. Use MultiSubnetFailover=Yes when connecting to an availability group listener or Failover Cluster Instance. Otherwise, your application's performance can be negatively affected. Note the following when connecting to a server in an availability group or Failover Cluster Instance: Specify MultiSubnetFailover=Yes to improve performance when connecting to a single subnet or multisubnet Availability Group. Specify the availability group listener of the availability group as the server in your connection string. You cannot connect to a SQL Server instance configured with more than 64 IP addresses. Both SQL Server Authentication or Kerberos Authentication can be used with MultiSubnetFailover=Yes without affecting the behavior of the application. You can increase the value of loginTimeout to accommodate for failover time and reduce the application's connection retry attempts. Distributed transactions are not supported. If read-only routing is not in effect, connecting to a secondary replica location in an availability group fails in the following situations: 1. If the secondary replica location is not configured to accept connections. 2. If an application uses ApplicationIntent=ReadWrite and the secondary replica location is configured for read-only access. A connection fails if a primary replica is configured to reject read-only workloads and the connection string contains ApplicationIntent=ReadOnly. Specifying Application Intent The keyword ApplicationIntent can be specified in your connection string. The assignable values are ReadWrite or ReadOnly. The default is ReadWrite. When ApplicationIntent=ReadOnly, the client requests a read workload when connecting. The server enforces the intent at connection time, and during a USE database statement. The ApplicationIntent keyword does not work with legacy read-only databases. Targets of ReadOnly When a connection chooses ReadOnly, the connection is assigned to any of the following special configurations that might exist for the database: Always On A database can allow or disallow read workloads on the targeted Always On database. This choice is controlled by using the ALLOW_CONNECTIONS clause of the PRIMARY_ROLE and SECONDARY_ROLE Transact-SQL statements. Geo-Replication Read Scale-Out If none of those special targets are available, the regular database is read from.

The ApplicationIntent keyword enables read-only routing. Read-Only Routing Read-only routing is a feature that can ensure the availability of a read-only replica of a database. To enable read- only routing, all of the following apply: You must connect to an Always On Availability Group availability group listener. The ApplicationIntent connection string keyword must be set to ReadOnly. The Availability Group must be configured by the database administrator to enable read-only routing. Multiple connections each using read-only routing might not all connect to the same read-only replica. Changes in database synchronization or changes in the server's routing configuration can result in client connections to different read-only replicas. You can ensure that all read-only requests connect to the same read-only replica. Ensure this sameness by not passing an availability group listener to the Server connection string keyword. Instead, specify the name of the read-only instance. Read-only routing may take longer than connecting to the primary. The longer wait is because read-only routing first connects to the primary, and then looks for the best available readable secondary. Due to these multiple staps, you should increase your login timeout to to at least 30 seconds. ODBC Syntax Two ODBC connection string keywords support AlwaysOn Availability Groups: ApplicationIntent MultiSubnetFailover For more information about ODBC connection string keywords, see Using Connection String Keywords with SQL Server Native Client. The equivalent connection attributes are: SQL_COPT_SS_APPLICATION_INTENT SQL_COPT_SS_MULTISUBNET_FAILOVER For more information about ODBC connection attributes, see SQLSetConnectAttr. An ODBC application that uses AlwaysOn Availability Groups can use one of two functions to make the connection:

FUNCTION DESCRIPTION

SQLConnect Function SQLConnect supports both ApplicationIntent and MultiSubnetFailover via a data source name (DSN) or connection attribute.

SQLDriverConnect Function SQLDriverConnect supports ApplicationIntent and MultiSubnetFailover via DSN, connection string keyword, or connection attribute.

See Also Connection String Keywords and Data Source Names (DSNs) Programming Guidelines Release Notes Programming Guidelines 5/3/2018 • 5 min to read • Edit Online

Download ODBC Driver The programming features of the Microsoft ODBC Driver for SQL Server on macOS and Linux are based on ODBC in SQL Server Native Client (SQL Server Native Client (ODBC)). SQL Server Native Client is based on ODBC in Windows Data Access Components (ODBC Programmer's Reference). An ODBC application can use Multiple Active Result Sets (MARS) and other SQL Server specific features by including /usr/local/include/msodbcsql.h after including the unixODBC headers ( sql.h , sqlext.h , sqltypes.h , and sqlucode.h ). Then use the same symbolic names for SQL Server-specific items that you would use in your Windows ODBC applications. Available Features The following sections from the SQL Server Native Client documentation for ODBC (SQL Server Native Client (ODBC)) are valid when using the ODBC driver on macOS and Linux: Communicating with SQL Server (ODBC) Connection and query timeout support Cursors Date/Time Improvements (ODBC) Executing Queries (ODBC) Handling Errors and Messages Kerberos authentication Large CLR User-Defined Types (ODBC) Performing Transactions (ODBC) (except distributed transactions) Processing Results (ODBC) Running Stored Procedures Sparse Columns Support (ODBC) SSL encryption Table Valued Parameters UTF-8 and UTF-16 for command and data API Using Catalog Functions Unsupported Features The following features have not been verified to work correctly in this release of the ODBC driver on macOS and Linux: Failover Cluster Connection Transparent Network IP Resolution (before ODBC Driver 17) Advanced Driver Tracing The following features are not available in this release of the ODBC driver on macOS and Linux: Distributed Transactions (SQL_ATTR_ENLIST_IN_DTC attribute is not supported) Database Mirroring FILESTREAM Profiling ODBC driver performance, discussed in SQLSetConnectAttr, and the following performance-related connection attributes: SQL_COPT_SS_PERF_DATA SQL_COPT_SS_PERF_DATA_LOG SQL_COPT_SS_PERF_DATA_LOG_NOW SQL_COPT_SS_PERF_QUERY SQL_COPT_SS_PERF_QUERY_INTERVAL SQL_COPT_SS_PERF_QUERY_LOG SQLBrowseConnect C interval types such as SQL_C_INTERVAL_YEAR_TO_MONTH (documented in Data Type Identifiers and Descriptors) The SQL_CUR_USE_ODBC value of the SQL_ATTR_ODBC_CURSORS attribute of the SQLSetConnectAttr function. Character Set Support For ODBC Driver 13 and 13.1, SQLCHAR data must be UTF-8. No other encodings are supported. For ODBC Driver 17, SQLCHAR data in one of the following character sets/encodings is supported:

NAME DESCRIPTION

UTF-8 Unicode

CP437 MS-DOS Latin US

CP850 MS-DOS Latin 1

CP874 Latin/Thai

CP932 Japanese, Shift-JIS

CP936 Simplified Chinese, GBK

CP949 Korean, EUC-KR

CP950 Traditional Chinese, Big5

CP1251 Cyrillic

CP1253 Greek

CP1256 Arabic

CP1257 Baltic

CP1258 Vietnamese

ISO-8859-1 / CP1252 Latin-1

ISO-8859-2 / CP1250 Latin-2 NAME DESCRIPTION

ISO-8859-3 Latin-3

ISO-8859-4 Latin-4

ISO-8859-5 Latin/Cyrillic

ISO-8859-6 Latin/Arabic

ISO-8859-7 Latin/Greek

ISO-8859-8 / CP1255 Hebrew

ISO-8859-9 / CP1254 Turkish

ISO-8859-13 Latin-7

ISO-8859-15 Latin-9

Upon connection, the driver detects the current locale of the process it is loaded in. If it uses one of the encodings above, the driver uses that encoding for SQLCHAR (narrow-character) data; otherwise, it defaults to UTF-8. Since all processes start in the "C" locale by default (and thus cause the driver to default to UTF-8), if an application needs to use one of the encodings above, it should use the setlocale function to set the locale appropriately before connecting; either by specifying the desired locale explicitly, or using an empty string for example setlocale(LC_ALL, "") to use the locale settings of the environment. Thus, in a typical Linux or Mac environment where the encoding is UTF-8, users of ODBC Driver 17 upgrading from 13 or 13.1 will not observe any differences. However, applications that use a non-UTF-8 encoding in the above list via setlocale() need to use that encoding for data to/from the driver instead of UTF-8. SQLWCHAR data must be UTF-16LE (Little Endian). When binding input parameters with SQLBindParameter, if a narrow character SQL type such as SQL_VARCHAR is specified, the driver converts the supplied data from the client encoding to the default (typically codepage 1252) SQL Server encoding. For output parameters, the driver converts from the encoding specified in the collation information associated with the data to the client encoding. However, data loss is possible --- characters in the source encoding not representable in the target encoding will convert to a question mark ('?'). To avoid this data loss when binding input parameters, specify a Unicode SQL character type such as SQL_NVARCHAR. In this case, the driver converts from the client encoding to UTF-16, which can represent all Unicode characters. Furthermore, the target column or parameter on the server must also be either a Unicode type (nchar, nvarchar, ntext) or one with a collation/encoding, which can represent all the characters of the original source data. For avoiding data loss with output parameters, specify a Unicode SQL type, and either a Unicode C type (SQL_C_WCHAR), causing the driver to return data as UTF-16; or a narrow C type, and ensure that the client encoding can represent all the characters of the source data (this is always possible with UTF-8.) For more information about collations and encodings, see Collation and Unicode Support. There are some encoding conversion differences between Windows and several versions of the iconv library on Linux and macOS. Text data in codepage 1255 (Hebrew) has one code point (0xCA) that behaves differently upon conversion to Unicode. On Windows, this character converts to the UTF-16 code point of 0x05BA. On macOS and Linux with libiconv versions earlier than 1.15, it converts to 0x00CA. On Linux with iconv libraries that do not support the 2003 revision of Big5/CP950 (named BIG5-2003 ), characters added with that revision will not convert correctly. In codepage 932 (Japanese, Shift-JIS), the result of decoding of characters not originally defined in the encoding standard also differs. For example, the byte 0x80 converts to U+0080 on Windows but may become U+30FB on Linux and macOS, depending on iconv version. In ODBC Driver 13 and 13.1, when UTF-8 multibyte characters or UTF-16 surrogates are split across SQLPutData buffers, it results in data corruption. Use buffers for streaming SQLPutData that do not end in partial character encodings. This limitation has been removed with ODBC Driver 17. Additional Notes 1. You can make a dedicated administrator connection (DAC) using SQL Server authentication and host,port. A member of the Sysadmin role first needs to discover the DAC port. See Diagnostic Connection for Database Administrators to discover how. For example, if the DAC port were 33000, you could connect to it with sqlcmd as follows:

sqlcmd –U -P -S ,33000

NOTE DAC connections must use SQL Server Authentication.

2. The UnixODBC driver manager returns "invalid attribute/option identifier" for all statement attributes when they are passed through SQLSetConnectAttr. On Windows, when SQLSetConnectAttr receives a statement attribute value, it causes the driver to set that value on all active statements which are children of the connection handle. See Also Frequently Asked Questions Known Issues in this Version of the Driver Release Notes Connecting with bcp 5/3/2018 • 3 min to read • Edit Online

Download ODBC Driver The bcp utility is available in the Microsoft ODBC Driver for SQL Server on Linux and macOS. This page documents the differences from the Windows version of bcp . The field terminator is a tab ("\t"). The line terminator is a newline ("\n").

Character mode is the preferred format for bcp format files and data files that do not contain extended characters.

NOTE A backslash '\' on a command-line argument must either be quoted or escaped. For example, to specify a newline as a custom row terminator, you must use one of the following mechanisms: -r\\n -r"\n" -r'\n'

The following is a sample command invocation of bcp to copy table rows to a text file:

bcp AdventureWorks2008R2.Person.Address out test.dat -Usa -Pxxxx -Sxxx.xxx.xxx.xxx

Available Options In the current release, the following syntax and options are available: [database.]schema.table in data_file | out data_file -a packet_size Specifies the number of bytes, per network packet, sent to and from the server. -b batch_size Specifies the number of rows per batch of imported data. -c Uses a character data type. -d database_name Specifies the database to connect to. -D Causes the value passed to the bcp -S option to be interpreted as a data source name (DSN). For more information, see "DSN Support in sqlcmd and bcp" in Connecting with sqlcmd.

-e error_file Specifies the full path of an error file used to store any rows that the bcp utility cannot transfer from the file to the database. -E Uses an identity value or values in the imported data file for the identity column. -f format_file Specifies the full path of a format file. -F first_row Specifies the number of the first row to export from a table or import from a data file. -k Specifies that empty columns should retain a null value during the operation, rather than have any default values for the columns inserted. -l Specifies a login timeout. The –l option specifies the number of seconds before a login to SQL Server times out when you try to connect to a server. The default login timeout is 15 seconds. The login timeout must be a number between 0 and 65534. If the value supplied is not numeric or does not fall into that range, bcp generates an error message. A value of 0 specifies an infinite timeout. -L last_row Specifies the number of the last row to export from a table or import from a data file. -m max_errors Specifies the maximum number of syntax errors that can occur before the bcp operation is cancelled. -n Uses the native (database) data types of the data to perform the bulk-copy operation. -P password Specifies the password for the login ID. -q Executes the SET QUOTED_IDENTIFIERS ON statement in the connection between the bcp utility and an instance of SQL Server. -r row_terminator Specifies the row terminator. -R Specifies that currency, date, and time data is bulk copied into SQL Server using the regional format defined for the locale setting of the client computer. -S server Specifies the name of the SQL Server instance to connect to, or if -D is used, a DSN. -t field_terminator Specifies the field terminator. -T Specifies that the bcp utility connect to SQL Server with a trusted connection (integrated security). -U login_id Specifies the login ID used to connect to SQL Server. -v Reports the bcp utility version number and copyright. -w Uses Unicode characters to perform the bulk copy operation. In this release, Latin-1 and UTF-16 characters are supported. Unavailable Options In the current release, the following syntax and options are not available: -C Specifies the code page of the data in the data file. -h hint Specifies the hint or hints used during a bulk import of data into a table or view. -i input_file Specifies the name of a response file. -N Uses the native (database) data types of the data for noncharacter data, and Unicode characters for character data. -o output_file Specifies the name of a file that receives output redirected from the command prompt. -V (80 | 90 | 100) Uses data types from an earlier version of SQL Server. -x Used with the format and -f format_file options, generates an XML-based format file instead of the default non-XML format file. See Also Connecting with sqlcmd Connecting with sqlcmd 5/3/2018 • 5 min to read • Edit Online

Download ODBC Driver The sqlcmd utility is available in the Microsoft ODBC Driver for SQL Server on Linux and macOS. The following commands show how to use Windows Authentication (Kerberos) and SQL Server Authentication, respectively:

sqlcmd –E –Sxxx.xxx.xxx.xxx sqlcmd –Sxxx.xxx.xxx.xxx –Uxxx -Pxxx

Available Options In the current release, the following options are available:

-? Display sqlcmd usage. -a Request a packet size. -b Terminate batch job if there is an error. -c batch_terminator Specify the batch terminator. -C Trust server certificate.

-d database_name Issue a USE database_name statement when you start sqlcmd .

-D Causes the value passed to the sqlcmd -S option to be interpreted as a data source name (DSN). For more information, see "DSN Support in sqlcmd and bcp " at the end of this topic. -e Write input scripts to the standard output device (stdout). -E Use trusted connection (integrated authentication.) For more information about making trusted connections that use integrated authentication from a Linux or macOS client, see Using Integrated Authentication. -h number_of_rows Specify the number of rows to print between the column headings. -H Specify a workstation name. -i input_file[,input_file[,…]] Identify the file that contains a batch of SQL statements or stored procedures.

-I Set the SET QUOTED_IDENTIFIER connection option to ON. -k Remove or replace control characters. -Kapplication_intent Declares the application workload type when connecting to a server. The only currently supported value is ReadOnly. If -K is not specified, sqlcmd does not support connectivity to a secondary replica in an AlwaysOn availability group. For more information, see ODBC Driver on Linux and macOS - High Availability and Disaster Recovery. NOTE -K is not supported in the CTP for SUSE Linux. You can, however, specify the ApplicationIntent=ReadOnly keyword in a DSN file passed to sqlcmd . For more information, see "DSN Support in sqlcmd and bcp " at the end of this topic.

-l timeout Specify the number of seconds before a sqlcmd login times out when you try to connect to a server. -m error_level Control which error messages are sent to stdout. -Mmultisubnet_failover Always specify -M when connecting to the availability group listener of a SQL Server 2012 (11.x) availability group or a SQL Server 2012 (11.x) Failover Cluster Instance. -M provides for faster detection of failovers and connection to the (currently) active server. If –M is not specified, -M is off. For more information about AlwaysOn Availability Groups, see ODBC Driver on Linux and macOS - High Availability and Disaster Recovery.

NOTE -M is not supported in the CTP for SUSE Linux. You can, however, specify the MultiSubnetFailover=Yes keyword in a DSN file passed to sqlcmd . For more information, see "DSN Support in sqlcmd and bcp " at the end of this topic.

-N Encrypt connection.

-o output_file Identify the file that receives output from sqlcmd . -p Print performance statistics for every result set. -P Specify a user password.

-q commandline_query Execute a query when sqlcmd starts, but does not exit when the query has finished running.

-Q commandline_query Execute a query when sqlcmd starts. sqlcmd will exit when the query finishes. -r Redirects error messages to stderr. -R Causes the driver to use client regional settings to convert currency and date and time data to character data. Currently only uses en_US (US English) formatting. -s column_separator_char Specify the column-separator character. -S [protocol:] server[,port] Specify the instance of SQL Server to connect to, or if -D is used, a DSN. The ODBC driver on Linux and macOS requires -S. Note that tcp is the only valid protocol. -t query_timeout Specify the number of seconds before a command (or SQL statement) times out. -u Specify that output_file is stored in Unicode format, regardless of the format of input_file. -U login_id Specify a user login ID. -V error_severity_level Control the severity level that is used to set the ERRORLEVEL variable. -w column_width Specify the screen width for output. -W Remove trailing spaces from a column. -x Disable variable substitution. -X Disable commands, startup script, and environment variables.

-y variable_length_type_display_width Set the sqlcmd scripting variable SQLCMDMAXFIXEDTYPEWIDTH .

-Y fixed_length_type_display_width Set the sqlcmd scripting variable SQLCMDMAXVARTYPEWIDTH . Available Commands In the current release, the following commands are available: [:]!! :Connect :Error [:]EXIT GO [count] :Help :List :Listvar :On Error :Out :Perftrace [:]QUIT :r :RESET :setvar Unavailable Options In the current release, the following options are not available: -A Log in to SQL Server with a Dedicated Administrator Connection (DAC). For information on how to make a dedicated administrator connection (DAC), see Programming Guidelines. -f code_page Specify the input and output code pages. -L List the locally configured server computers, and the names of the server computers that are broadcasting on the network.

-v Create a sqlcmd scripting variable that can be used in a sqlcmd script.

You can use the following alternative method: Put the parameters inside one file, which you can then append to another file. This will help you use a parameter file to replace the values. For example, create a file called a.sql (the parameter file) with the following content:

:setvar ColumnName object_id :setvar TableName sys.objects Then create a file called b.sql , with the parameters for replacement:

select $(ColumnName) from $(TableName)

At the command line, combine a.sql and b.sql into c.sql using the following commands:

cat a.sql > c.sql

cat b.sql >> c.sql

Run sqlcmd and use c.sql as input file:

slqcmd -S<…> -P<..> –U<..> -I c.sql

-z password Change password. -Z password Change password and exit. Unavailable Commands In the current release, the following commands are not available: :ED :ServerList :XML DSN Support in sqlcmd and bcp

You can specify a data source name (DSN) instead of a server name in the sqlcmd or bcp -S option (or sqlcmd :Connect command) if you specify -D. -D causes sqlcmd or bcp to connect to the server specified in the DSN by the -S option.

System DSNs are stored in the odbc.ini file in the ODBC SysConfigDir directory ( /etc/odbc.ini on standard installations). User DSNs are stored in .odbc.ini in a user's home directory ( ~/.odbc.ini ). The following entries are supported in a DSN on Linux or macOS: ApplicationIntent=ReadOnly Database=database_name Driver=ODBC Driver 11 for SQL Server or Driver=ODBC Driver 13 for SQL Server MultiSubnetFailover=Yes Server=server_name_or_IP_address Trusted_Connection=yes|no

In a DSN, only the DRIVER entry is required, but to connect to a server, sqlcmd or bcp needs the value in the SERVER entry.

If the same option is specified in both the DSN and the sqlcmd or bcp command line, the command line option overrides the value used in the DSN. For example, if the DSN has a DATABASE entry and the sqlcmd command line includes -d, the value passed to -d is used. If Trusted_Connection=yes is specified in the DSN, Kerberos authentication is used and user name (–U) and password (–P), if provided, are ignored.

Existing scripts that invoke isql can be modified to use sqlcmd by defining the following alias: alias isql="sqlcmd –D" . See Also Connecting with bcp Using Integrated Authentication 5/3/2018 • 5 min to read • Edit Online

Download ODBC Driver The Microsoft ODBC Driver for SQL Server on Linux and macOS supports connections that use Kerberos integrated authentication. It supports the MIT Kerberos Key Distribution Center (KDC), and works with Generic Security Services Application Program Interface (GSSAPI) and Kerberos v5 libraries. Using Integrated Authentication to Connect to SQL Server from an ODBC Application You can enable Kerberos integrated authentication by specifying Trusted_Connection=yes in the connection string of SQLDriverConnect or SQLConnect. For example:

Driver='ODBC Driver 13 for SQL Server';Server=your_server;Trusted_Connection=yes

When connecting with a DSN, you can also add Trusted_Connection=yes to the DSN entry in odbc.ini .

The -E option of sqlcmd and the -T option of bcp can also be used to specify integrated authentication; see Connecting with sqlcmd and Connecting with bcp for more information. Ensure that the client principal which is going to connect to SQL Server is already authenticated with the Kerberos KDC. ServerSPN and FailoverPartnerSPN are not supported. Deploying a Linux or macOS ODBC Driver Application Designed to Run as a Service A system administrator can deploy an application to run as a service that uses Kerberos Authentication to connect to SQL Server. You first need to configure Kerberos on the client and then ensure that the application can use the Kerberos credential of the default principal.

Ensure that you use kinit or PAM (Pluggable Authentication Module) to obtain and cache the TGT for the principal that the connection uses, via one of the following methods:

Run kinit , passing in a principal name and password.

Run kinit , passing in a principal name and a location of a keytab file that contains the principal’s key created by ktutil . Ensure that the login to the system was done using the Kerberos PAM (Pluggable Authentication Module). When an application runs as a service, because Kerberos credentials expire by design, renew the credentials to ensure continued service availability. The ODBC driver does not renew credentials itself; ensure that there is a cron job or script that periodically runs to renew the credentials before their expiration. To avoid requiring the password for each renewal, you can use a keytab file. Kerberos Configuration and Use provides details on ways to Kerberize services on Linux. Tracking Access to a Database A database administrator can create an audit trail of access to a database when using system accounts to access SQL Server using Integrated Authentication. Logging in to SQL Server uses the system account and there is no functionality on Linux to impersonate security context. Therefore, more is required to determine the user. To audit activities in SQL Server on behalf of users other than the system account, the application must use Transact-SQL EXECUTE AS. To improve application performance, an application can use connection pooling with Integrated Authentication and auditing. However, combining connection pooling, Integrated Authentication, and auditing creates a security risk because the unixODBC driver manager permits different users to reuse pooled connections. For more information, see ODBC Connection Pooling.

Before reuse, an application must reset pooled connections by executing sp_reset_connection . Using Active Directory to Manage User Identities An application system administrator does not have to manage separate sets of login credentials for SQL Server. It is possible to configure Active Directory as a key distribution center (KDC) for Integrated Authentication. See Microsoft Kerberos for more information. Using Linked Server and Distributed Queries Developers can deploy an application that uses a linked server or distributed queries without a database administrator who maintains separate sets of SQL credentials. In this situation, a developer must configure an application to use integrated authentication: User logs in to a client machine and authenticates to the application server. The application server authenticates as a different database and connects to SQL Server. SQL Server authenticates as a database user to another database ( SQL Server. After integrated authentication is configured, credentials will be passed to the linked server. Integrated Authentication and sqlcmd

To access SQL Server using integrated authentication, use the -E option of sqlcmd . Ensure that the account which runs sqlcmd is associated with the default Kerberos client principal. Integrated Authentication and bcp

To access SQL Server using integrated authentication, use the -T option of bcp . Ensure that the account which runs bcp is associated with the default Kerberos client principal.

It is an error to use -T with the -U or -P option. Supported Syntax for an SPN Registered by SQL Server The syntax that SPNs use in the connection string or connection attributes is as follows: SYNTAX DESCRIPTION

MSSQLSvc/fqdn:port The provider-generated, default SPN when TCP is used. port is a TCP port number. fqdn is a fully qualified domain name.

Authenticating a Linux or macOS Computer with Active Directory

To configure Kerberos, enter data into the krb5.conf file. krb5.conf is in /etc/ but you can refer to another file using the syntax e.g. export KRB5_CONFIG=/home/dbapp/etc/krb5.conf . The following is an example krb5.conf file:

[libdefaults] default_realm = YYYY.CORP.CONTOSO.COM dns_lookup_realm = false dns_lookup_kdc = true ticket_lifetime = 24h forwardable = yes

[domain_realm] .yyyy.corp.contoso.com = YYYY.CORP.CONTOSO.COM .zzzz.corp.contoso.com = ZZZZ.CORP.CONTOSO.COM

If your Linux or macOS computer is configured to use the Dynamic Host Configuration Protocol (DHCP) with a Windows DHCP server providing the DNS servers to use, you can use dns_lookup_kdc=true. Now, you can use Kerberos to sign in to your domain by issuing the command kinit [email protected] . Parameters passed to kinit are case-sensitive and the SQL Server computer configured to be in the domain must have that user [email protected] added for login. Now, you can use trusted connections (Trusted_Connection=YES in a connection string, bcp -T, or sqlcmd -E). The time on the Linux or macOS computer and the time on the Kerberos Key Distribution Center (KDC) must be close. Ensure that your system time is set correctly, e.g. by using the Network Time Protocol (NTP). If Kerberos authentication fails, the ODBC driver on Linux or macOS does not use NTLM authentication. For more information about authenticating Linux or macOS computers with Active Directory, see Authenticate Linux Clients with Active Directory and Best Practices for Integrating OS X with Active Directory. For more information about configuring Kerberos, see the MIT Kerberos Documentation. See Also Programming Guidelines Release Notes Using Azure Active Directory Release Notes for the Microsoft ODBC Driver for SQL Server on Linux and macOS 5/3/2018 • 3 min to read • Edit Online

Download ODBC Driver What's New in the Microsoft ODBC Driver 17.1 for SQL Server on Windows Features Added:

Support for SQL_COPT_SS_CEKCACHETTL and SQL_COPT_SS_TRUSTEDCMKPATHS connection attributes (For more information, see Using Always Encrypted with the ODBC Driver for SQL Server)

SQL_COPT_SS_CEKCACHETTL Allows controlling the time that the local cache of Column Encryption Keys exists, as well as flushing it SQL_COPT_SS_TRUSTEDCMKPATHS Allows the application to restrict AE operations to only use the specified list of Column Master Keys

Support for loading the .rll from default location (For more information, see 'Resource File Loading' section in the Installation document) Bug fixes What's New in the Microsoft ODBC Driver 17 for SQL Server on Linux and macOS New distributions supported: macOS High Sierra and Ubuntu 17.10 Performance Improvements: Greater than 10x performance improvement when driver converts to/from UTF- 8/16. Features Added: Always Encrypted support for BCP API New connection string attribute UseFMTOnly causes driver to use legacy metadata in special cases requiring temp tables. Support for Azure SQL Managed Instance (Extended Private Preview). NOTE There are a number of differences when using Managed Instance: FILESTREAM is not supported Local filesystem access is not supported, but required for things like tracefiles Create UDT from local path is not supported Windows Integrated Authentication is not supported DTC is not supported 'sa' account is not present (default account is called 'cloudSA') TDS token ERROR (0xAA) returns incorrect server name Special characters in database name are not supported ALTER DATABASE [dbname1] MODIFY NAME = [dbname2] is not supported The error messages are always shown in English, regardless of language settings (same as Azure)

What's New in the Microsoft ODBC Driver 13.1 for SQL Server on Linux and macOS ODBC Driver 13.1 for SQL Server adds support for Always Encrypted and Azure Active Directory when used in conjunction with Microsoft SQL Server 2016. New distributions supported: OS X 10.11 and macOS 10.12 are supported in the first release of the ODBC Driver on macOS. Ubuntu 16.10 is now also supported, along with Red Hat 6, 7, and SUSE 12. Each platform has a platform-relevant package (RPM or DEB) to ease installation and configuration. See Installing the Driver for installation instructions. unixODBC Driver Manager 2.3.1 Support Changes: The ODBC driver no longer depends on custom packaging for the unixODBC driver manager (except on RedHat 6), and instead relies on the distribution package manager to resolve the UnixODBC dependency from the distribution's repositories. BCP API Support: The Linux and macOS ODBC driver now supports the use of the BCP API functions (bcp_init, etc.) What's New in the Microsoft ODBC Driver 13.0 for SQL Server on Linux With Microsoft ODBC Driver 13.0 for SQL Server, SQL Server 2014 and SQL Server 2016 are now also supported. New distributions supported: Ubuntu is now supported, along with Red Hat and SUSE. Each platform has a platform-relevant package (RPM or DEB) to ease installation and configuration. See Installing the Driver for installation instructions. unixODBC Driver Manager 2.3.1 Support: In addition to a newer driver manager, there is also a package for installing this dependency that eases installation and configuration. Transparent Network IP Resolution: Transparent Network IP Resolution is a revision of the existing Multi- Subnet Failover feature that affects the connection sequence of the driver in the case where the first resolved IP of the hostname does not respond and there are multiple IPs associated with the hostname. TLS 1.2 Support: The Microsoft ODBC Driver 13.0 for SQL Server on Linux now supports TLS 1.2 when secure communications with SQL Server are used. What's New in the Microsoft ODBC Driver 11 for SQL Server on Linux The ODBC driver on SUSE Linux (Preview) supports 64-bit SUSE Linux Enterprise 11 Service Pack 2. For more information, see System Requirements. The ODBC driver on Linux supports AlwaysOn Availability Groups. For more information, see ODBC Driver on Linux Support for High Availability, Disaster Recovery. The ODBC driver on Linux supports connections to Microsoft Azure SQL Database. For more information, see How to: Connect to Windows Azure SQL Database Using ODBC.

The -l option (login timeout) has been added to bcp . For more information, see Connecting with bcp. Known Issues in this Version of the Driver 5/3/2018 • 2 min to read • Edit Online

Download ODBC Driver This article contains a list of known issues with the Microsoft ODBC Driver 13, 13.1, and 17 for SQL Server on Linux and macOS. Additional issues will be posted on the Microsoft ODBC driver team blog. Windows, Linux, and macOS convert characters from the Private Use Area (PUA) or End User-Defined Characters (EUDC) differently. Conversions performed on the server within Transact-SQL use the Windows conversion library. Conversions in the driver use the Windows, Linux, or macOS conversion libraries. Each library may produce different results when performing these conversions. For more information, see End- User-Defined and Private Use Area Characters. If the client encoding is UTF-8, the driver manager does not always correctly convert from UTF-8 to UTF- 16. Currently, data corruption occurs when one or more characters in the string are not valid UTF-8 characters. ASCII characters are mapped correctly. The driver manager attempts this conversion when calling the SQLCHAR versions of the ODBC API (for example, SQLDriverConnectA). The driver manager will not attempt this conversion when calling the SQLWCHAR versions of the ODBC API (for example, SQLDriverConnectW). The ColumnSize parameter of SQLBindParameter refers to the number of characters in the SQL type, while BufferLength is the number of bytes in the application's buffer. However, if the SQL data type is varchar(n) or char(n) , the application binds the parameter as SQL_C_CHAR or SQL_C_VARCHAR, and the character encoding of the client is UTF-8, you may get a "String data, right truncation" error from the driver even if the value of ColumnSize is aligned with the size of the data type on the server. This error occurs since conversions between character encodings may change the length of the data. For example, a right apostrophe character (U+2019) is encoded in CP-1252 as the single byte 0x92, but in UTF-8 as the 3- byte sequence 0xe2 0x80 0x99. For example, if your encoding is UTF-8 and you specify 1 for both BufferLength and ColumnSize in SQLBindParameter for an out-parameter, and then attempt to retrieve the preceding character stored in a char(1) column on the server (using CP-1252), the driver attempts to convert it to the 3-byte UTF-8 encoding, but cannot fit the result into a 1-byte buffer. In the other direction, it compares ColumnSize with the BufferLength in SQLBindParameter before doing the conversion between the different code pages on the client and server. Because a ColumnSize of 1 is less than a BufferLength of (for example) 3, the driver generates an error. To avoid this error, ensure that the length of the data after conversion fits into the specified buffer or column. Note that ColumnSize cannot be greater than 8000 for the varchar(n) type. See Also Programming Guidelines Release Notes Frequently Asked Questions (FAQ) for ODBC Linux and macOS 5/3/2018 • 1 min to read • Edit Online

Download ODBC Driver The following are answers to questions about the ODBC Driver for SQL Server on Linux and macOS. Frequently Asked Questions How do existing ODBC applications on Linux or macOS work with the driver? You should be able to compile and run the ODBC applications that you have been compiling and running on Linux or macOS using other drivers. Which features of SQL Server 2012 (11.x) does this version of the driver support? The ODBC driver on Linux and macOS supports all server features in SQL Server 2012 (11.x) except LocalDB. For more information about SQL Server supported features, see Programming Guidelines. Does the driver support Kerberos authentication? Yes. If you have an existing Kerberos environment setup, you should be able to connect to servers using the Trusted_Connection=Yes DSN or connection string option. For more information, see Using Integrated Authentication. Which Unicode encoding should an application use? UTF-8 for SQL_CHAR data and UTF-16 for SQL_WCHAR data. Are there ODBC samples that I can download and run with the driver to experiment with or evaluate it? See Use Existing MSDN C++ ODBC Samples for the ODBC Driver on Linux for a sample. This is also applicable to the macOS ODBC driver. Is the ODBC driver on Linux or macOS open source? No, the ODBC drivers on Linux and macOS are not an open source product. See Also Installing the Microsoft ODBC Driver for SQL Server on Linux and macOS