本文回答了關於安裝、連接及針對 Linux 和 macOS 上的 Microsoft SQL Server ODBC 驅動程式開發應用程式的常見問題。
關於驅動程式
我應該使用哪個 ODBC 驅動版本?
使用Microsoft ODBC Driver 18 for SQL Server,即目前的驅動程式系列,進行新開發。 Microsoft ODBC Driver 17 for SQL Server 仍支援已部署該驅動程式的應用程式,依照支援生命週期所述。
影響大多數應用程式的升級變更是 Driver 18 預設會加密連線。 關於所有差異,請參見 主要版本差異。
驅動程式支援哪些作業系統和處理器架構?
驅動程式 18 支援以下作業系統與處理器架構:
| 作業系統 | x64 支援 | Arm64 支援 |
|---|---|---|
| 阿爾卑斯Linux | Yes | 從 Driver 18.3 開始 |
| Azure Linux | Yes | 從 Driver 18.6.1 開始 |
| Debian | Yes | 從 Driver 18.1 開始 |
| Oracle Linux | Yes | No |
| Red Hat Enterprise Linux | Yes | 從 Driver 18.1 開始 |
| SUSE Linux Enterprise Server | Yes | No |
| Ubuntu | Yes | 從 Driver 18.1 開始 |
| macOS | Yes | 從 Driver 17.8 開始 |
支援的作業系統版本會隨著每次驅動程式的發布而改變。 關於各版本對照表,請參見 系統需求。
Linux 和 macOS 驅動程式支援哪些 SQL Server 功能?
Linux 和 macOS 的驅動程式支援大多數 SQL Server 功能。 它不支援透過 SQL_ATTR_ENLIST_IN_DTC 屬性、資料庫鏡像、FILESTREAM 或驅動程式效能剖析屬性來進行分散式交易登記。 LocalDB 在 Linux 和 macOS 上都無法使用。 自驅動程式 17.3 起,支援透過分散式交易協調器(DTC)進行 XA 交易。 欲了解更多資訊,請參閱 搭配 DTC 使用 XA 交易。 完整清單請參見 限制。
驅動程式是開放原始碼嗎?
No. Microsoft 的 SQL Server ODBC 驅動程式並非 開放原始碼。
安裝及設定
驅動程式使用哪個驅動程式管理器?
此驅動程式使用 unixODBC 驅動程式管理員。 當你用平台的套件管理器或 Homebrew 安裝 Driver 17 或 18 時,UnixODBC 會以相依性安裝。 請依照 Linux 或 macOS 的步驟操作。
在 macOS 上,請用 unixODBC 建置並執行應用程式,而不是 iODBC。 與應用程式、驅動程式管理員及驅動程式的處理器架構相匹配。 像 incompatible architecture (have 'arm64', need 'x86_64') 這樣的錯誤表示架構不匹配,不一定是驅動程式管理器錯誤。
我要怎麼檢查安裝了哪些驅動程式,以及哪些設定檔正在使用?
執行 odbcinst -q -d 以列出已註冊的驅動程式。 輸出會精確顯示每個驅動程式名稱,連線字串必須如此拼寫:
[ODBC Driver 18 for SQL Server]
執行 odbcinst -j 以顯示 unixODBC 版本以及 odbcinst.ini 和 odbc.ini 的路徑,其中 odbcinst.ini 負責註冊驅動程式,而 odbc.ini 保存系統與使用者資料來源名稱(DSN):
unixODBC 2.3.11
DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
FILE DATA SOURCES..: /etc/ODBCDataSources
USER DATA SOURCES..: /home/<user>/.odbc.ini
要設定 DSN,請參見 Connection strings and DSN。
為什麼驅動程式管理員會回報無法開啟驅動程式庫?
錯誤如下:
[01000][unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server' : file not found
依序檢查這些原因:
- 連接字串 或 DSN 中的
Driver值與註冊的驅動程式名稱不符。 執行odbcinst -q -d並原封不動地複製名稱。 - 你的應用程式使用的設定檔與你編輯的設定檔不同。 從與應用程式相同的環境執行
odbcinst -j,檢查該應用程式載入的是哪個驅動程式管理員。 在 macOS 上,只有當應用程式需要時才建立設定符號連結,詳見 macOS 的故障排除。 - 安裝了不只一個 unixODBC 驅動管理器副本,但你的應用程式載入了錯誤的那一個。 在 Linux 上執行
find /usr -name 'libodbc*.so*'。 在 macOS 上,執行find /opt/homebrew /usr/local -name 'libodbc*.dylib'。 僅有多條路徑並不能證明安裝了多個驅動程式管理器:Homebrew 連結可能指向其 Cellar 目錄中的同一個函式庫。 檢查應用程式實際載入的是哪個函式庫。 欲了解更多資訊,請參閱「疑難排解連線問題」。
連結並驗證
為什麼一個能用驅動程式 17 的連線,會在驅動程式 18 上出現憑證錯誤而失敗?
驅動程式 18 預設為 Encrypt=yes。 驅動程式 17 只在未提供非空的Encrypt=no設定或存取權杖時,才預設為Authentication。 非空的 Authentication 設定(包含 Authentication=SqlPassword)或存取權杖會將驅動程式 17 預設為 Encrypt=yes。 明確的加密設定會覆蓋這些預設值。
檢查透過 SQLSetConnectAttr 設定的 連接字串、DSN 和 preconnection 屬性的有效設定。 例如,DSN 中的 SQL_COPT_SS_ENCRYPT=SQL_EN_ON 或 Encrypt=yes 會要求加密,即使連線字串省略了 Encrypt。 僅透過 SQL_COPT_SS_ACCESS_TOKEN 連接屬性提供存取權杖,而非連接字串關鍵字。
使用 Encrypt=yes 和 TrustServerCertificate=no 時,兩個驅動程式都會加密連線並驗證伺服器憑證。 在 Encrypt=no的情況下,驅動程式 17 不會驗證憑證,而驅動程式 18 則在伺服器強制加密且 TrustServerCertificate=no時會驗證該憑證。 先前使用 Driver 17 Encrypt=no 預設的連線,因此可能會在使用 Driver 18 連線至具有自我簽署或其他不受信任憑證的伺服器時失敗。 使用自簽憑證時,Driver 18 錯誤如下:
[Microsoft][ODBC Driver 18 for SQL Server]SSL Provider: [error:0A000086:SSL routines::certificate verify failed:self-signed certificate]
[Microsoft][ODBC Driver 18 for SQL Server]Client unable to establish connection. For solutions related to encryption errors, see https://go.microsoft.com/fwlink/?linkid=2226722
偏好使用受信任的憑證或憑證釘選。 請使用以下選項:
- 在伺服器上安裝由用戶端信任的憑證授權中心發出的憑證。 如果憑證是可信的,但其名稱與
Server值不符,則將HostNameInCertificate設定為憑證中的名稱。HostNameInCertificate它只改變預期名稱,因此無法修正自簽憑證的問題。 - 在驅動程式 18.1 及更新版本,且伺服器支援 Tabular Data Stream(TDS)8.0 的情況下,設定
Encrypt=strict,並將ServerCertificate設為伺服器憑證副本的路徑。 驅動程式接著只接受該完全相符的憑證。ServerCertificate只在嚴格模式下有效。 - 只有在伺服器不強制加密,且您接受未加密的應用程式流量時,才設定
Encrypt=no。 這僅在未提供非空Authentication設定或存取權杖且未設定加密覆寫時,才與 Driver 17 預設相符。 如果伺服器強制加密,Driver 18 仍會驗證憑證,除非TrustServerCertificate=yes停用驗證。
Caution
TrustServerCertificate=yes 未啟用加密。 使用 Encrypt=yes,它會繞過憑證驗證,同時保持流量加密,使連線暴露於中間人攻擊。 使用 Encrypt=no 時,應用程式流量會保持未加密,除非伺服器強制加密;若伺服器強制加密,則會繞過憑證驗證。 使用 Encrypt=strict 時,驅動程式會忽略 TrustServerCertificate 並驗證憑證,或在設定時將憑證與 ServerCertificate 比對。 偏好使用受信任的憑證或憑證釘選。
更多資訊請參閱 預設加密行為。
驅動程式支援 Kerberos 認證嗎?
是。 先使用 kinit 取得 Kerberos 票證,然後在連線字串或 DSN 中使用 Trusted_Connection=yes 連線。 SQL Server 實例需要註冊的服務主體名稱(SPN)。 關於設定步驟,請參見 使用整合驗證。
驅動程式支援 Microsoft Entra ID 認證嗎?
是的,適用於 Azure SQL Database、Azure SQL 受控執行個體 以及 SQL Server 2022 及以後版本。 要設定 SQL Server,包括透過 Azure Arc,請使用 適用於 SQL Server 的 Microsoft Entra 認證。 在 Linux 和 macOS 上,驅動程式 17 及更新版本支援以下方法:
- 受控識別,從
Authentication=ActiveDirectoryMsiDriver 17.3 開始。 - 服務主體,含
Authentication=ActiveDirectoryServicePrincipal,從 Driver 17.7 開始支援。 - 從 Driver 17.6 開始,支援在聯邦環境中透過 Kerberos 整合認證,並包含
Authentication=ActiveDirectoryIntegrated。 - 你的應用程式所取得的存取權杖,透過
SQL_COPT_SS_ACCESS_TOKEN連線屬性傳遞。
ActiveDirectoryInteractive僅在 Windows 驅動程式中提供。
ActiveDirectoryPassword 已被 棄用。 Linux 和 macOS 的由驅動程式管理的驗證不支援需要條件存取政策的情境。 如果您的應用程式單獨取得存取權杖,則由認證函式庫與 Microsoft Entra ID 政策來管理該權杖的取得。 透過 SQL_COPT_SS_ACCESS_TOKEN 傳遞權杖。
在 Alpine Linux 上,整合式驗證需要支援簡單且受保護的通用安全服務應用程式介面協商機制(SPNEGO)的 libcurl 版本。 檢查你安裝的libcurl能力,而不是假設預設套件支援該能力。
關於連線字串與程式碼範例,請參見 使用 Microsoft Entra ID 搭配 ODBC 驅動程式。
開發與疑難排解
現有的 ODBC 應用程式可以在 Linux 或 macOS 上使用這個驅動程式嗎?
是。 以 ODBC 應用程式介面(API)撰寫並基於 UnixODBC 建置的應用程式可以載入此驅動程式。 若要使用 SQL Server 專屬功能,請在 unixODBC 標頭後方加入msodbcsql.h。 關於編譯器指令與函式庫名稱,請參見 使用 ODBC 驅動程式開發 C 與 C++ 應用程式。
有範例應用程式嗎?
是。 使用 C++ 和 ODBC 連線及查詢會在 Linux、macOS 和 Windows 上建置並執行範例。
我該如何追蹤 ODBC 呼叫?
追蹤檔案可能包含敏感資料。 作為執行你應用程式的帳號,請建立一個只有該帳號能存取的目錄:
mkdir -m 700 "$HOME/odbc-trace"
將這些設定加入 odbcinst.ini 的 [ODBC] 區塊中。 將 /home/<user>/odbc-trace/odbctrace.log 替換為你建立的目錄內的絕對路徑。 在 macOS 上,家庭目錄通常使用 /Users/<user>,而非 /home/<user>。
保持完整的追蹤檔案路徑不超過62位元組,以避免被unixODBC截斷。
[ODBC]
Trace = Yes
TraceFile = /home/<user>/odbc-trace/odbctrace.log
這些設定能讓使用此驅動程式管理員設定的應用程式進行追蹤,而追蹤會讓它們變慢。 為每個應用程式帳號使用獨立的私人目錄。 完成後刪除 Trace = Yes ,並刪除不需要的追蹤檔案。 關於每個應用程式的追蹤,請參見 Linux 和 macOS 上的資料存取追蹤。
字元資料
應用程式應該使用哪種 Unicode 編碼?
對 SQLWCHAR資料使用 UTF-16LE(小端序)。 使用 UTF-16 SQLWCHAR 緩衝區搭配 ODBC 寬字元 API,而非在 Linux 和 macOS 上為 32 位元的原生 wchar_t 型別。
對 SQLCHAR 資料使用 UTF-8。 從驅動程式 17 開始,當程序區域選取其中一種碼頁時,驅動程式也接受用於 SQLCHAR 資料的一組單位元組和雙位元組碼頁。 處理程序從 C 地區設定開始,因此驅動程式使用 UTF-8,除非應用程式呼叫 setlocale。 關於編碼列表,請參見 處理字元資料。