本文說明在 Linux 或 macOS 上使用 Microsoft ODBC Driver for SQL Server 的應用程式所需注意的程式設計考量。 有些連結指向 SQL Server Native Client 的資料。 這些頁面提供了歷史 API 的背景資訊。
選擇驅動版本
使用Microsoft ODBC Driver 18 for SQL Server，即目前的驅動程式系列，進行新開發。 Microsoft ODBC Driver 17 for SQL Server 仍支援已部署該驅動程式的應用程式，依照支援生命週期所述。 隨 SQL Server 2017 一同發行的 ODBC 驅動程式 13，僅可在延長支援合約下獲得延長支援，期限至 2027 年 10 月 12 日。
請在你的 連接字串 中標明已安裝的驅動程式名稱，並用大括號包住：
Driver={ODBC Driver 18 for SQL Server}
Driver={ODBC Driver 17 for SQL Server}
在 odbc.ini 的資料來源名稱（DSN）中，請使用不含大括號的名稱，例如 Driver = ODBC Driver 18 for SQL Server。 關於 DSN 語法，請參見連線字串關鍵字與資料來源名稱（DSN）。
關於特定版本的連線設定，請參見 Major 版本差異。 關於支援日期及作業系統相容性，請參閱 支援生命週期 與 系統需求。
建置應用程式
關於標頭位置，包括包含順序、編譯器指令、函式庫名稱及 C++ 範例，請參見 使用 ODBC 驅動程式開發 C 與 C++ 應用程式，以及 Connect and query with C++ and ODBC。
ODBC 應用程式可以透過在 unixODBC 標頭（sqlext.h、sqltypes.h、sqlucode.h 和 msodbcsql.h）後加入 sql.h，使用多重主動結果集（MARS）及其他 SQL Server 專屬功能。 使用 SQL Server 專用項目與 Windows ODBC 應用程式相同的符號名稱。
尋找驅動程式能力
從標準應用程式設計介面（API）的 ODBC 程式設計師參考 開始。 接著使用目前的驅動文件來處理驅動程式的專屬行為。
Microsoft ODBC Driver for SQL Server 概覽連結至驅動程式文件。 以下 SQL Server Native Client 文章為使用 Linux 與 macOS 驅動程式的應用程式提供 API 上下文：
- 與 SQL Server 進行通訊 (ODBC)
- 連線和查詢逾時支援
- 游標
- 日期/時間改進（ODBC）
- 執行查詢（ODBC）
- 錯誤與訊息處理
- Kerberos 驗證
- 大型通用語言執行時（CLR）使用者定義型別（ODBC）
- 執行交易作業（ODBC）。 在 Linux 和 macOS 上進行分散式交易時，請使用 XA 交易搭配 DTC。
- 處理結果（ODBC）
- 執行預存程序
- 稀疏欄位支援（ODBC）
- 使用加密而不進行驗證
- 資料表值參數
- 指令與資料 API 的 UTF-8 與 UTF-16
- 使用型錄函式
限制
以下功能尚未在 Linux 和 macOS 的 ODBC 驅動程式中被驗證是否正常運作：
- 故障轉移叢集連線。
- ODBC 驅動程式 17 之前的透明網路 IP 解析。
- Linux 和 macOS 的 ODBC 驅動程式 Built-In 診斷（BID）追蹤（ODBC 驅動程式 17.3 之前）
不支援的功能
以下功能在 Linux 和 macOS 的 ODBC 驅動程式中無法使用：
透過屬性
SQL_ATTR_ENLIST_IN_DTC進行分散式交易。 驅動程式透過 Microsoft Distributed Transaction Coordinator（DTC）支援 XA 交易。 欲了解更多資訊，請參閱 搭配 DTC 使用 XA 交易。資料庫鏡像。
FILESTREAM。
剖析 ODBC 驅動程式效能，詳見 SQLSetConnectAttr，以及以下與效能相關的連線屬性：
SQL_COPT_SS_PERF_DATASQL_COPT_SS_PERF_DATA_LOGSQL_COPT_SS_PERF_DATA_LOG_NOWSQL_COPT_SS_PERF_QUERYSQL_COPT_SS_PERF_QUERY_INTERVALSQL_COPT_SS_PERF_QUERY_LOG
SQLBrowseConnect在版本 17.2 之前。C 區間類型，例如
SQL_C_INTERVAL_YEAR_TO_MONTH，記錄於 資料型別識別碼與描述符 中。SQL_CUR_USE_ODBC的SQL_ATTR_ODBC_CURSORS屬性的SQLSetConnectAttr值。
處理字元資料
在 Linux 和 macOS 上，請使用 UTF-16 SQLWCHAR 緩衝區搭配 ODBC 寬字元 API，而非原生 wchar_t 類型。 驅動介面使用 16 位元編碼單元。
字元編碼
對於 ODBC 驅動程式 13 和 13.1，對 SQLCHAR 資料必須使用 UTF-8。 這些版本不支援其他編碼。
從 ODBC 驅動程式 17 開始，支援用於 SQLCHAR 資料的字元集與編碼包括：
注意
由於 glibc 和 musl 之間的 iconv 差異，許多這些語言環境在 Alpine Linux 上不被支援。 更多資訊請參見 與 glibc 的功能差異。
| 名稱 | 描述 |
|---|---|
| UTF-8 | Unicode |
| CP437 | MS-DOS 拉丁美洲 |
| CP850 | MS-DOS 拉丁文 1 |
| CP874 | Latin/Thai |
| CP932 | 日文（Windows 代碼頁 932） |
| CP936 | 簡體中文，GBK |
| CP949 | 韓文（Windows 代碼頁 949） |
| CP950 | 繁體中文，Big5 |
| CP1250 | 中歐 |
| CP1251 | 西里爾字母 |
| CP1252 | 西歐 |
| CP1253 | 希臘文 |
| CP1254 | 土耳其文 |
| CP1255 | 希伯來語 |
| CP1256 | 阿拉伯文 |
| CP1257 | 波羅的 |
| CP1258 | 越南文 |
| ISO-8859-1 | Latin-1 |
| ISO-8859-2 | Latin-2 |
| ISO-8859-3 | Latin-3 |
| ISO-8859-4 | Latin-4 |
| ISO-8859-5 | 拉丁文/西里爾文 |
| ISO-8859-6 | 拉丁文/阿拉伯文 |
| ISO-8859-7 | Latin/Greek |
| ISO-8859-8 | 希伯來語 |
| ISO-8859-9 | 土耳其文 |
| ISO-8859-13 | Latin-7 |
| ISO-8859-15 | Latin-9 |
當你連線時，驅動程式會偵測其載入所在程序目前的地區設定。 若地區設定使用上述編碼，驅動程式則使用該編碼來處理 SQLCHAR （窄字元）資料。 否則，預設為 UTF-8。 程序預設從 C locale 地區設定開始，導致驅動程式預設為 UTF-8。 如果應用程式需要上述編碼之一，請在連接前先呼叫 setlocale。 明確指定 locale，或使用空字串（例如 setlocale(LC_ALL, "")）來使用環境的 locale 設定。
在典型的 Linux 或 macOS 環境中，編碼為 UTF-8，從 13 或 13.1 升級到 ODBC Driver 17 的使用者不會察覺差異。 透過 setlocale 使用列出的非 UTF-8 編碼的應用程式，必須對往返驅動程式的資料使用該編碼，而非 UTF-8。
您必須對 SQLWCHAR 資料使用 UTF-16LE（小端序）。
當你使用 SQLBindParameter，若指定狹義字元的 SQL 類型 SQL_VARCHAR，驅動程式會將用戶端編碼中提供的資料轉換為該參數的伺服器端編碼。 編碼方式取決於定序；不一定是代碼頁 1252。 針對輸出參數，驅動程式會從資料相關聯定序資訊中指定的編碼轉換為用戶端編碼。 在來源編碼中無法在目標編碼中表示的字元會轉換為問號（?）。
為避免綁定輸入參數時的資料遺失，請指定 Unicode SQL 字元類型，例如 SQL_WVARCHAR。 驅動程式會將用戶端編碼轉換為 UTF-16，該編碼可代表所有 Unicode 字元。 目標欄位或參數也必須是 Unicode 類型（nchar、nvarchar 或 ntext），或是具有可表示所有原始來源資料的定序或編碼的型別。 對於輸出參數，請指定一個 Unicode SQL 型態，並指定一個 Unicode C 型別（SQL_C_WCHAR），使驅動程式回傳資料為 UTF-16，或是帶有用戶端編碼的窄型 C 型態，能代表來源資料。 UTF-8 總是能表示這些資料。
欲了解更多關於定序與編碼的資訊，請參見 定序與 Unicode 支援。
Windows 與 Linux 或 macOS iconv 版本之間存在轉換差異：
- 對於代碼頁 1255，位元組
0xCA在 Windows 上會轉換為 UTF-16 碼點0x00CA，而在 macOS 和 Linux 上，若0x05BA版本早於 1.15，則會轉換為libiconv。 - 沒有 2003 年版 Big5/CP950（
iconv）的 LinuxBIG5-2003函式庫，無法正確轉換該版本新增的字元。 - 對於代碼頁 932（日文，Shift-JIS），對未在編碼標準中定義的字元，其解碼方式有所不同。 例如，位元組
0x80在 Windows 上可轉換為 U+0080，而在 Linux 和 macOS 上則可能變成 U+30FB，視iconv版本而定。
在 ODBC 驅動程式 13 與 13.1 中，將 UTF-8 多位元組字元或 UTF-16 代理碼分割至 SQLPutData 緩衝區會導致資料損壞。 使用不以部分字元編碼結尾的串流緩衝區。 此限制在 ODBC 驅動程式 17 中被移除。
關於字元編碼、轉換、參數綁定及緩衝區大小的指引，請參見 已知問題。
OpenSSL
從 ODBC 驅動程式 17.4 開始，驅動程式會動態載入 OpenSSL，允許它在沒有獨立驅動檔案的情況下，在擁有 1.0 或 1.1 版本的系統上執行。 從 17.9 版開始，驅動程式除了先前版本之外，也支援 OpenSSL 3.0。 當 OpenSSL 存在多個版本時，驅動程式會嘗試從函式庫搜尋路徑載入支援的版本。
| 驅動程式版本 | 支援的 OpenSSL 版本 |
|---|---|
| 17.4 至 17.8 | 1.0, 1.1 |
| 17.9 及後續 17.x 版本，以及所有 Driver 18 版本 | 1.0, 1.1, 3.0 |
OpenSSL 4 不被支援。 在 macOS 上，指向 OpenSSL 4 的 Homebrew openssl 連結可能會導致驅動程式無法載入 OpenSSL，即使已安裝 OpenSSL 3。 檢查函式庫路徑以及已安裝的版本。
注意
若使用驅動程式或其元件的應用程式連結或動態載入不同版本的 OpenSSL，可能會發生潛在衝突。 如果系統上有多個版本的 OpenSSL，且應用程式使用它，請確保應用程式載入的版本與驅動程式不會不匹配。 錯誤可能會損壞記憶體，且可能不會以明顯或一致的方式出現。
阿爾卑斯Linux
musl 中新執行緒的預設堆疊大小為 128 KB，除非執行檔要求更大的預設值。 執行緒在呼叫驅動程式時可以超過這個限制。 將 Alpine Linux 上的 ODBC 應用程式與 -Wl,-z,stack-size=<size_in_bytes> 連結，以請求更大的預設執行緒堆疊。 建立明確堆疊大小的執行緒的應用程式，也必須為這些執行緒選擇適當的堆疊大小。
主執行緒的堆疊和新執行緒的預設堆疊設定不一樣。 在 glibc 系統上，新執行緒的預設通常遵循程序的堆疊資源限制，當該限制為無限制時，則有架構特定的備援。 不要假設 Linux 系統都有固定的 2 MB 預設值。
其他注意事項
要從 ODBC 應用程式建立專用管理員連線（DAC），請在你的連線字串中設定「admin:Server=tcp:<server>,<dac_port>」。 使用發現的 DAC 埠，而不是實例的一般連接埠。 例如，如果 DAC 埠口是 33000，則將 Server=tcp:<server>,33000 設為 33000。 這些連接字串片段僅指定端點，而非認證。 請分別設定認證與伺服器憑證驗證。
登入帳戶必須是 sysadmin 伺服器角色的成員。 遠端存取需要啟用伺服器的遠端管理連線選項。 關於存取需求、伺服器設定及命令列管理程序，請參見 資料庫管理員的診斷連線。 如需了解連接埠探索，請參見 DAC 埠。
unixODBC 驅動程式管理器處理經過 SQLSetConnectAttr 傳遞的陳述式屬性，與 Windows 驅動程式管理器相同。 ODBC 2.x 的語句選項，如 SQL_ATTR_QUERY_TIMEOUT 和 SQL_ATTR_MAX_ROWS，適用於連線上的現有及新陳述式。 ODBC 3.x 僅用語句的屬性，例如 SQL_ATTR_ROW_ARRAY_SIZE 和 SQL_ATTR_PARAMSET_SIZE，回傳 SQLSTATE HY092。 在連接層級與陳述式層級定義的屬性，例如 SQL_ATTR_METADATA_ID，都可以在任一層級設定。 在 ODBC 3.x 中，在連線層級設定僅限陳述式的屬性已被棄用，因此改為呼叫 SQLSetStmtAttr 。 欲了解更多資訊，請參閱 SQLSetConnectAttr 函式。
在高度多執行緒的應用中，unixODBC 的句柄驗證可能會成為效能瓶頸。 以 --enable-fastvalidate 編譯 unixODBC 可能會提升效能。 然而，此選項可能導致將無效句柄傳給 ODBC API 的應用程式當機，而非回傳 SQL_INVALID_HANDLE。
關於平台的安裝與配置步驟，請參見：