Known issues for the ODBC driver on Linux and macOS

DownloadDownload 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. It also contains steps for troubleshooting connectivity issues.

Known issues

Additional issues will be posted on the SQL Server Drivers blog.

  • Due to system library limitations, Alpine Linux supports fewer character encodings and locales. For example, en_US.UTF-8 is not available. See musl libc - functional differences from glibc for more information.

  • 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.

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 17 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:

Next steps

For ODBC driver installation instructions, see the following articles:

For more information, see the Programming guidelines and the Release notes.