Connecting your macOS applications to Microsoft SQL Server databases requires the right tools, and the ODBC (Open Database Connectivity) driver is essential for this. This guide walks you through the process of installing the Microsoft ODBC Driver for SQL Server on macOS, ensuring a smooth and efficient connection. Whether you’re a developer, database administrator, or IT professional, this article will provide you with clear, step-by-step instructions and troubleshooting tips to get you connected quickly.
The Microsoft ODBC Driver for SQL Server allows applications on macOS to communicate with SQL Server databases. This driver is crucial for tasks ranging from data analysis and reporting to application development and deployment. This article focuses on installation using the command line via brew, a popular package manager for macOS. If you prefer direct downloads, you can find packages on the Microsoft Download Center.
Note that the Microsoft ODBC driver for SQL Server on macOS supports both x64 and Apple ARM64 architectures. For versions up to 17.7, only x64 was supported. Starting with version 17.8, ARM64 support was introduced. Homebrew automatically detects your system architecture and installs the appropriate package. If you are using a command prompt running in x64 emulation on an ARM64 Mac, the x64 package will be installed. If not in emulation, the ARM64 package will be installed. Be aware that default Homebrew directory paths differ between architectures (/opt/homebrew for ARM64, /usr/local for x64). File paths mentioned in the Driver files section are based on the x64 Homebrew default path (/usr/local), so adjust accordingly for ARM64 systems.
Installing Microsoft ODBC Driver 18 for SQL Server
Microsoft ODBC Driver 18 is the latest version, offering enhanced features and compatibility. To install it on your macOS system, open your Terminal application and execute the following commands:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18These commands will:
- Install Homebrew (if not already installed): The first line ensures Homebrew is installed on your system, using the official installation script.
- Tap the Microsoft repository:
brew tap microsoft/mssql-releaseadds Microsoft’s repository to Homebrew, making the ODBC driver packages available. - Update Homebrew:
brew updaterefreshes the package lists, ensuring you have the latest information. - Install ODBC Driver 18 and SQL Server command-line tools:
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18installs the ODBC driver itself (msodbcsql18) and the SQL Server command-line tools (mssql-tools18), includingbcpandsqlcmd. TheHOMEBREW_ACCEPT_EULA=Ypart automatically accepts the End-User License Agreement, allowing the installation to proceed without prompting.
Installing Previous Versions of the ODBC Driver
If you need to install an older version of the Microsoft ODBC Driver for SQL Server, follow the instructions below for ODBC 17 and ODBC 13.1.
Microsoft ODBC Driver 17
For Microsoft ODBC Driver 17 for SQL Server on macOS, use these commands in your Terminal:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql17 mssql-toolsThis process is similar to installing ODBC 18, but it specifically installs version 17 of the driver (msodbcsql17) and the mssql-tools.
Important: If you previously installed a version 17 package named msodbcsql (without 17), it’s crucial to remove it before installing msodbcsql17 to prevent conflicts. msodbcsql17 can coexist with the older msodbcsql version 13.
ODBC Driver 13.1
To install Microsoft ODBC Driver 13.1 for SQL Server, which supports older macOS versions like OS X 10.11 (El Capitan) and macOS 10.12 (Sierra), use the following commands:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
brew install [email protected] [email protected]This installs specific versions of the ODBC driver ([email protected]) and the SQL Server command-line tools ([email protected]) compatible with older systems.
Understanding the ODBC Driver Files
After installation, the ODBC driver components are placed in specific directories on your macOS system. Knowing these locations can be helpful for troubleshooting and configuration.
| Component | Description | Location (Default x64 Homebrew path) |
|---|---|---|
libmsodbcsql.18.dylib / libmsodbcsql.17.dylib / libmsodbcsql.13.dylib |
The core dynamic library file containing the driver’s functionality. | /usr/local/lib/ |
msodbcsqlr18.rll / msodbcsqlr17.rll / msodbcsqlr13.rll |
The resource file for the driver library, containing localized strings and other resources. | [driver .dylib directory]../share/msodbcsql18/resources/en_US/ (Driver 18), [driver .dylib directory]../share/msodbcsql17/resources/en_US/ (Driver 17), [driver .dylib directory]../share/msodbcsql/resources/en_US/ (Driver 13) |
msodbcsql.h |
The header file with definitions needed to use the driver in C/C++ applications. Note: Do not include both msodbcsql.h and odbcss.h in the same program. |
/usr/local/include/msodbcsql18/ (Driver 18), /usr/local/include/msodbcsql17/ (Driver 17), /usr/local/include/msodbcsql/ (Driver 13) |
LICENSE.txt |
The End-User License Agreement for the ODBC driver. | /usr/local/share/doc/msodbcsql18/ (Driver 18), /usr/local/share/doc/msodbcsql17/ (Driver 17), /usr/local/share/doc/msodbcsql/ (Driver 13) |
RELEASE_NOTES |
Release notes for the specific ODBC driver version. | /usr/local/share/doc/msodbcsql18/ (Driver 18), /usr/local/share/doc/msodbcsql17/ (Driver 17), /usr/local/share/doc/msodbcsql/ (Driver 13) |
Resource File Loading Mechanism
The ODBC driver relies on the resource file (.rll) to operate correctly. This file must be loaded by the driver. As indicated in the table above, the .rll file is located in a subdirectory relative to the driver library (.dylib). Starting with version 17.1, if the driver fails to load the .rll file from the relative path, it will also attempt to load it from the default resource directory, which on macOS is /usr/local/share/msodbcsql18/resources/en_US/.
Troubleshooting Connection Issues
A common problem users encounter after installing the ODBC driver is a connection error message similar to: "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server' : file not found (0) (SQLDriverConnect)". This typically indicates that unixODBC, the ODBC driver manager on macOS, is not correctly configured to locate the installed drivers.
Symbolic links can often resolve this issue by creating standard locations for configuration files:
sudo ln -s /usr/local/etc/odbcinst.ini /etc/odbcinst.ini
sudo ln -s /usr/local/etc/odbc.ini /etc/odbc.iniThese commands create symbolic links from the Homebrew-managed configuration files (/usr/local/etc/odbcinst.ini and /usr/local/etc/odbc.ini) to the system-wide standard locations (/etc/odbcinst.ini and /etc/odbc.ini).
For other connection problems when using the ODBC driver, refer to the Microsoft documentation on troubleshooting connection problems for more detailed guidance.
If Homebrew encounters issues finding the necessary formulas during installation, double-check that you have correctly added the Microsoft repository using the brew tap command as shown in the installation steps: brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release.
By following these steps, you should be able to successfully install the Microsoft ODBC Driver for SQL Server on your macOS system and establish connections to your SQL Server databases. Remember to choose the driver version appropriate for your needs and macOS version.
