Linux 和 macOS 上的 ODBC 驅動程式已知問題

  • 發行項

下載 ODBC 驅動程式

本文包含 Linux 和 macOS 上 Microsoft ODBC Driver for SQL Server 13、13.1、17 和 18 版的已知問題清單。 其中也包含針對連線能力問題進行疑難排解的步驟。

已知問題

其他問題將會張貼於 SQL Server 驅動程式部落格上。

  • 由於系統程式庫的限制，Alpine Linux 支援較少的字元編碼和地區設定。 例如，en_US.UTF-8 無法使用。 如需詳細資訊，請參閱musl libc - 與 glibc 的功能差異 (英文)。

  • Windows、Linux 和 macOS 可能會以不同的方式轉換來自專用區 (PUA) 或使用者定義字元 (EUDC) 的字元。 透過 Transact-SQL 在伺服器上執行的轉換，會使用 Windows 轉換程式庫。 驅動程式中的轉換會使用 Windows、Linux 或 macOS 轉換程式庫。 執行這些轉換時，這兩個程式庫可能會產生不同的結果。 如需詳細資訊，請參閱終端使用者定義字元和專用區字元。

  • 如果用戶端編碼是 UTF-8，則驅動程式管理員不一定會正確地從 UTF-8 轉換為 UTF-16。 目前，字串中若有一或多個字元不是有效的 UTF-8 字元，即會發生資料損毀。 ASCII 字元會正確地對應。 在呼叫 ODBC API 的 SQLCHAR 版本 (例如 SQLDriverConnectA) 時，驅動程式管理員會嘗試這項轉換。 在呼叫 ODBC API 的 SQLWCHAR 版本 (例如 SQLDriverConnectW) 時，驅動程式管理員不會嘗試這項轉換。

  • SQLBindParameter 的 ColumnSize 參數會參考 SQL 類型中的字元數，而 BufferLength 是應用程式緩衝區中的位元組數目。 不過，如果 SQL 資料類型是 varchar(n) 或 char(n)，應用程式會繫結 C 類型的 SQL_C_CHAR 參數，以及 SQL 類型的 SQL_CHAR 或 SQL_VARCHAR 參數，且用戶端的字元編碼為 UTF-8，即使 ColumnSize 其值與伺服器的資料類型大小保持一致，驅動程式仍會顯示「字串資料，右側截斷」的錯誤。 因為字元編碼之間的轉換可能會變更資料長度，所以發生此錯誤。 例如，右單引號字元 (U+2019) 以 CP-1252 編碼時會成為單位元組 0x92，但以 UTF-8 編碼時會成為 3 個位元組的序列 0xe2 0x80 0x99。

例如，如果您的編碼為 UTF-8，並同時為 out 參數 SQLBindParameter 中的 Columnsize 和 ColumnSize 指定 1，然後嘗試擷取伺服器上儲存在 char(1) 資料行的前一個字元 (使用 CP-1252)，則驅動程式會嘗試將它轉換成 3 個位元組的 UTF-8 編碼方式，但無法將結果放入 1 個位元組的緩衝區內。 換個方向，它在執行用戶端與伺服器上不同字碼頁之間的轉換前，會先比較 SQLBindParameter 中的 ColumnSize 與 BufferLength。 由於 ColumnSize 1 小於 BufferLength 3 (舉例來說)，因此驅動程式會產生錯誤。 若要避免這個錯誤，請確認資料在轉換後的長度可放入指定的緩衝區或資料行內。 請注意，就 varchar(n) 類型而言，ColumnSize 不可大於 8000。

連接問題的疑難排解

如果您無法使用 ODBC 驅動程式連線到 SQL Server，請使用下列資訊來識別問題。

最常見的連線問題是安裝了兩個 UnixODBC 驅動程式管理員複本。 請在 /usr 中搜尋 libodbc*.so*。 如果您看見多個檔案版本，表示您 (可能) 安裝了多個驅動程式管理員。 您的應用程式可能使用了錯誤的版本。

藉由編輯 /etc/odbcinst.ini 檔案以包含下列區段和這些項目來啟用連接記錄檔：

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

如果連線再次失敗，且未出現記錄檔，表示您的電腦上 (可能) 有兩個驅動程式管理員複本。 否則，記錄輸出應如下所示：

[ODBC][28783][1321576347.077780][SQLDriverConnectW.c][290]
        Entry:
            Connection = 0x17c858e0
            Window Hdl = (nil)
            Str In = [DRIVER={ODBC Driver 18 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'

如果 ASCII 字元編碼不是 UTF-8，例如：

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

安裝了多個驅動程式管理員，且應用程式使用了錯誤的管理員，或是驅動程式管理員未正確建置。

有些 macOS 使用者在使用驅動程式 17.8 版或舊版時遇到下列錯誤
(驅動程式 17.9+ 版已解決此錯誤)：

[08001][Microsoft][ODBC Driver 17 for SQL Server]SSL Provider: [OpenSSL library could not be loaded, make sure OpenSSL 1.0 or 1.1 is installed]
[08001][Microsoft][ODBC Driver 17 for SQL Server]Client unable to establish connection (0) (SQLDriverConnect)

安裝 OpenSSL 3.0 時，可能會發生此錯誤。 OpenSSL 通常是透過 Brew 安裝，並包含 openssl、openssl@1.1 和 openssl@3　二進位檔。

若要解決此錯誤，請將 openssl 二進位檔的符號連結變更為 openssl@1.1：

rm -rf $(brew --prefix)/opt/openssl
version=$(ls $(brew --prefix)/Cellar/openssl@1.1 | grep "1.1")
ln -s $(brew --prefix)/Cellar/openssl@1.1/$version $(brew --prefix)/opt/openssl

如需解決連接失敗的詳細資訊，請參閱：

後續步驟

如需 ODBC 驅動程式安裝指示，請參閱下列文章：

如需詳細資訊，請參閱程式設計指導方針和版本資訊。