本文列出 ODBC Driver for SQL Server 中可用的連接字串和 DSN 關鍵字，以及 SQLSetConnectAttr 和 SQLGetConnectAttr 的連線屬性。
支援 DSN 與 連接字串 關鍵字與連線屬性
下表列出各平台可用的關鍵字與屬性（L：Linux;M：macOS;W：Windows）。 選取關鍵字或屬性可查看詳細資料。
以下列出一些未記載於搭配 SQL Server Native Client 使用連接字串關鍵字、SQLSetConnectAttr及SQLSetConnectAttr 函式中的連接字串關鍵字和連線屬性。
描述
描述資料來源。
SQL_COPT_SS_ANSI_OEM
控制 ANSI 至 OEM 的資料轉換。
| 屬性值 | 描述 |
|---|---|
SQL_AO_OFF (預設值) |
翻譯還沒完成。 |
SQL_AO_ON |
翻譯已完成。 |
SQL_COPT_SS_AUTOBEGINTXN
從 17.6 版本開始，當自動提交停用時，請使用此選項來控制在 ROLLBACK 或 COMMIT 之後自動執行 BEGIN TRANSACTION。
| 屬性值 | 描述 |
|---|---|
SQL_AUTOBEGINTXN_ON (預設值) |
在 COMMIT 或 BEGIN TRANSACTION 之後自動 ROLLBACK。 |
SQL_AUTOBEGINTXN_OFF |
在 ROLLBACK 或 COMMIT 之後，不會自動加入 BEGIN TRANSACTION。 |
SQL_COPT_SS_FALLBACK_CONNECT
控制 SQL Server 備援連線的使用。 此選項已不再支援。
| 屬性值 | 描述 |
|---|---|
SQL_FB_OFF (預設值) |
停用備用連線。 |
SQL_FB_ON |
啟用備援連線。 |
新增連線字串關鍵字與連線屬性
連線字串關鍵字統一
從 18.7 版本開始，SQL Server 的 ODBC 驅動程式支援與資料提供者中Microsoft.Data.SqlClient屬性名稱對齊的額外 連接字串 關鍵字。 此支援使應用程式能在 Microsoft SQL Server 資料提供者與驅動程式間使用單一 連接字串，而無需重新命名關鍵字。
關鍵字別名
每個別名配置的選項與其對應的 ODBC 關鍵字相同：
| 別名 | 等效的 ODBC 關鍵字 | 描述 |
|---|---|---|
MultipleActiveResultSets |
MARS_Connection |
可開啟或關閉多個主動結果集（MARS）。 接受 Yes 或 No。 |
WorkstationID |
WSID |
設定工作站 ID，通常是執行該應用程式的電腦的網路名稱。
HOST_NAME() 回傳此值。 |
FailoverPartner |
Failover_Partner |
指定用於資料庫鏡像的容錯移轉夥伴伺服器。 僅支援 Windows。 |
駕駛者對這些別名適用以下規則：
-
不區分大小寫： 驅動程式在比對別名時不區分大小寫。 例如，
multipleactiveresultsets行為與 相同MultipleActiveResultSets。 - 先出現者獲勝： 別名及其等效的 ODBC 關鍵字會設定相同的選項。 如果一個 連接字串 同時包含這兩個選項，驅動程式會使用第一個值，並忽略該選項的後續值。
- 僅輸入： 驅動程式接受別名作為輸入。 當它傳回輸出連接字串，或將設定寫入資料來源名稱（DSN）時，會使用對應的 ODBC 關鍵字。
-
平台支援：驅動程式支援
MultipleActiveResultSets及WorkstationID支援 Windows、Linux 及 macOS。 驅動程式僅在 Windows 上支援FailoverPartner和Failover_Partner。
ConnectTimeout 關鍵字
ConnectTimeout 關鍵字設定的登入逾時與 SQL_ATTR_LOGIN_TIMEOUT 連線屬性相同。 應用程式可以在 連接字串 中指定逾時，而非呼叫 SQLSetConnectAttr。
如果應用程式在呼叫 connection 函式前明確設定SQL_ATTR_LOGIN_TIMEOUT了 ，connection 屬性會優先於 ConnectTimeout 連接字串 值。
-
單位與預設值： 該值指定等待登入完成的秒數。 預設數值是
15秒數。 -
無超時： 值
0表示駕駛必須無限期等待。 -
最大值與夾緊： 最大值為
65534。 當你提供負值、大於65534或超出支援數值範圍的值時，驅動程式會使用65534。 若驅動程式將該值限制在允許範圍內，且連線在其他方面仍成功，則驅動程式會回傳SQL_SUCCESS_WITH_INFO，並附帶01S02（選項值已變更）警告。 - 驗證： 驅動程式拒絕空值與非數字值。
-
DSN 支援：在 Windows 上，應用程式可以儲存並檢索
ConnectTimeout資料來源名稱（DSN）。 -
平台支援：驅動程式支援
ConnectTimeoutWindows、Linux 及 macOS。
範例
以下連線字串使用統一的關鍵字寫法：
Driver={ODBC Driver 18 for SQL Server};Server=tcp:myserver.database.windows.net;Database=mydb;UID=myuser;PWD=mypassword;MultipleActiveResultSets=Yes;WorkstationID=app-node-01;ConnectTimeout=30;
前述連線字串中的別名，設定的選項與下列連線字串中的原始 ODBC 關鍵字相同：
Driver={ODBC Driver 18 for SQL Server};Server=tcp:myserver.database.windows.net;Database=mydb;UID=myuser;PWD=mypassword;MARS_Connection=Yes;WSID=app-node-01;
這兩個字串都啟用 MARS並設定工作站 ID 為 app-node-01。 第一串也需等待最多 30 秒才能完成登入。
ConnectTimeout 在早期版本中沒有對應的名稱。 若要在較早版本中設定登入逾時，請使用 SQL_ATTR_LOGIN_TIMEOUT 呼叫 SQLSetConnectAttr。
驗證 - SQL_COPT_SS_AUTHENTICATION
設定連線到 SQL Server 時要使用的驗證模式。 如需詳細資訊，請參閱搭配使用 Microsoft Entra ID 與 ODBC 驅動程式。
| 關鍵字價值 | 屬性值 | 描述 |
|---|---|---|
SQL_AU_NONE (預設值) |
未設定。 其他屬性的組合會決定驗證模式。 | |
SqlPassword |
SQL_AU_PASSWORD |
SQL Server 驗證 (使用使用者名稱和密碼)。 |
ActiveDirectoryIntegrated |
SQL_AU_AD_INTEGRATED |
Microsoft Entra 整合式驗證。 |
ActiveDirectoryInteractive |
SQL_AU_AD_INTERACTIVE |
Microsoft Entra 互動式認證。 |
ActiveDirectoryMsi |
SQL_AU_AD_MSI |
Microsoft Entra 受控識別驗證。 對於使用者指派的身分識別，UID 會設為該使用者身分識別的物件 ID。 |
ActiveDirectoryServicePrincipal |
SQL_AU_AD_SPA |
Microsoft Entra 服務主體驗證。
UID 設定為服務主體的客戶端 ID。
PWD 設定為客戶端秘密。 |
ActiveDirectoryPassword |
SQL_AU_AD_PASSWORD |
[已棄用]Microsoft Entra 密碼驗證。ActiveDirectoryPassword 已被取代。 如需詳細資訊，請參閱 ActiveDirectoryPassword 已被取代。 |
SQL_AU_RESET |
未設定。 覆寫任何 DSN 或連接字串設定。 |
注意
使用Authentication關鍵字或屬性時，明確指定Encrypt在 連接字串、DSN 或 connection 屬性中設定為所需值。 如需詳細資訊，請參閱搭配 SQL Server Native Client 使用連線字串關鍵字。
列加密 (ColumnEncryption) - SQL_COPT_SS_COLUMN_ENCRYPTION
控制透明的資料行加密 (Always Encrypted)。 如需詳細資訊，請參閱搭配 ODBC Driver for SQL Server 使用 Always Encrypted。
| 關鍵字價值 | 屬性值 | 描述 |
|---|---|---|
Enabled |
SQL_CE_ENABLED |
啟用 Always Encrypted。 |
Disabled (預設值) |
SQL_CE_DISABLED |
啟用時總是加密。 |
SQL_CE_RESULTSETONLY |
只啟用解密 (結果和傳回值)。 |
ConcatNullYieldsNull - SQL_COPT_SS_CONCAT_NULL
控制串連字串時對 NULL 使用 ISO 處理方式。 如需詳細資訊，請參閱 SET CONCAT_NULL_YIELDS_NULL。
| 關鍵字價值 | 屬性值 | 描述 |
|---|---|---|
Yes (預設值) |
SQL_CN_ON |
NULL 串接會得到 NULL。 |
No |
SQL_CN_OFF |
NULL 串接產生字串。 |
Encrypt
指定連線是否透過網路使用 TLS 加密。 版本 17 接受 yes 和 no。 18.0 版及更新版本也接受 mandatory 作為 yes 的同義詞、optional 作為 strict 的同義詞，以及 no；其中 no 會選擇 TDS 8.0 加密，且在 17 版中沒有對應項目。 預設值為 yes 18.0 及以上版本，以及 no 更早版本。
無論 Encrypt 的設定為何，伺服器登入認證 (使用者名稱和密碼) 一律會經過加密。
Encrypt、 TrustServerCertificate以及伺服器端Force Encryption的設定決定了連線是否在網路上加密。 下表顯示這些設定的效果。
ODBC 驅動程式 18 和更新版本
| 加密設定 | 信任伺服器憑證 | 伺服器強制加密 | 結果 |
|---|---|---|---|
| 否 | 否 | 否 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料不會加密。 |
| 否 | .是 | 否 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料不會加密。 |
| .是 | 否 | 否 | 會檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| .是 | .是 | 否 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| 否 | 否 | .是 | 會檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| 否 | .是 | .是 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| .是 | 否 | .是 | 會檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| .是 | .是 | .是 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| 嚴格 | - | - |
TrustServerCertificate 被忽略。 會檢查伺服器憑證。在用戶端和伺服器之間傳送的資料會加密。 |
注意
此 Strict 值僅適用於支援 TDS 8.0 連線的伺服器。
ODBC 驅動程式 17 和更舊版本
| 加密設定 | 信任伺服器憑證 | 伺服器強制加密 | 結果 |
|---|---|---|---|
| 否 | 否 | 否 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料不會加密。 |
| 否 | .是 | 否 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料不會加密。 |
| .是 | 否 | 否 | 會檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| .是 | .是 | 否 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| 否 | 否 | .是 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| 否 | .是 | .是 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| .是 | 否 | .是 | 會檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| .是 | .是 | .是 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
TransparentNetworkIPResolution - SQL_COPT_SS_TNIR
控制透明網路 IP 解析功能，這是 ODBC 驅動程式的舊版多 IP 容錯機制。 此設定不影響 當 MultiSubnetFailover=Yes時的連線順序，這是 Azure SQL Database、Azure SQL 受控執行個體、Microsoft Fabric 中的 SQL 資料庫、可用性群組監聽器及故障轉移叢集實例的建議設定。 欲了解更多資訊，請參閱使用 ODBC 驅動程式的透明網路 IP 解析 或 高可用性與災難復原。
| 關鍵字價值 | 屬性值 | 描述 |
|---|---|---|
Enabled (預設值) |
SQL_IS_ON |
啟用透明網路 IP 解析。 |
Disabled |
SQL_IS_OFF |
停用透明網路 IP 解析。 |
UseFMTONLY
控制連線到 SQL Server 2012 及更新版本時是否使用 SET FMTONLY 來取得中繼資料。
| 關鍵字價值 | 描述 |
|---|---|
No (預設值) |
如果有，請使用 sp_describe_first_result_set 作為元資料。 |
Yes |
使用 SET FMTONLY 作為中繼資料。 |
複寫
指定在 ODBC 驅動程式 17.8 版和更新版本上使用複寫登入。
| 關鍵字價值 | 描述 |
|---|---|
No (預設值) |
未使用複寫登入。 |
Yes |
使用 NOT FOR REPLICATION 選項的觸發程序不會在該連線上觸發。 |
RetryExec
從 18.1 版開始提供可設定的重試邏輯。 其會根據可設定的條件，自動重新執行特定的 ODBC 函式呼叫。 透過關鍵字 RetryExec 連接字串 啟用此功能，並附上重試規則清單。 每個重試規則包含三個冒號分隔的元件：錯誤匹配、重試策略與查詢匹配。
查詢匹配決定了執行中應使用的重試規則。 它會與輸入的指令文本SQLExecDirect（）或陳述句物件SQLExecute中已準備好的命令文本（）相匹配。 若多條規則匹配，則使用列表中第一個匹配規則。 這種行為可讓你依照一般性遞增的順序列出規則。 如果沒有任何規則符合，則不會套用重試。
當執行產生錯誤且有適用的重試規則時，其錯誤匹配決定是否應該重試執行。
關鍵字的 RetryExec 值是分號分隔的重試規則清單。
RetryExec={rule1;rule2}
重試規則如下所示：<errormatch>:<retrypolicy>:<querymatch>
錯誤匹配：以逗號分隔的錯誤代碼列表。 例如，指定
1000,2000會列出你想重試的錯誤碼。重試政策：規定延遲至下一次重試。 第一個參數是重試次數，第二個參數是延遲。 例如，
3,10+7表示從 10 秒開始嘗試三次，之後每次重試都會增加 7 秒。 如果你不指定+7，每次重試都會呈指數倍增。查詢匹配：指定你想要匹配的查詢。 如果你沒有特別指定，這條規則會適用於所有查詢。 指定
SELECT指所有以SELECT開頭的查詢。
將這三個元件組合在一起，以用於連線字串：
RetryExec={1000,2000:3,10+7:SELECT}
此規則的意思是：對於以 SELECT 開頭的查詢中出現的錯誤 1000 和 2000，重試兩次，初始延遲為 10 秒，之後每次重試再增加 7 秒。
範例
40501,40540:4,5
對於錯誤 40501 和 40540，最多可重試四次，初始延遲為 5 秒，且每次重試之間的延遲時間以指數方式加倍。 這規則適用於所有查詢。
49919:2,10+:CREATE
對於以 CREATE 開頭的查詢所發生的錯誤 49919，最多重試兩次，第一次在 10 秒後，第二次在 20 秒後。
49918,40501,10928:5,10+5:SELECT c1
對於以 40501 開頭的查詢中出現的錯誤 49918、10928 和 SELECT c1，最多重試五次；第一次重試前等待 10 秒，此後每次將等待時間增加 5 秒。
將前述三條規則一起指定在 連接字串 中如下：
RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}
將最一般（全部匹配）規則放在最後，讓前兩條更具體的規則能匹配各自的查詢。
用戶端憑證
指定用於回送連線驗證的憑證。 此選項僅適用於 Linux 上的 SQL Server。 可用選項包括：
| 選項值 | 描述 |
|---|---|
sha1:<hash_value> |
ODBC 驅動程式使用 SHA1 雜湊值在 Windows 憑證庫中定位憑證。 |
subject:<subject> |
ODBC 驅動程式會根據主體，在 Windows 憑證存放區中尋找憑證。 |
file:<file_location>[,password:<password>] |
ODBC 驅動程式會使用憑證檔案。 |
如果憑證格式為格式 PFX ，且憑證內 PFX 的私鑰受密碼保護，請包含 password 關鍵字。 對於採用 PEM 和 DER 格式的憑證，請包含 ClientKey 屬性。
ClientKey
指定由 DER 屬性指定的 ClientCertificate 或 PEM 憑證之私密金鑰檔案位置。 格式：
| 選項值 | 描述 |
|---|---|
file:<file_location>[,password:<password>] |
指定私鑰檔案的位置。 |
如果私鑰檔案有密碼保護，請包含 password 關鍵字。 如果密碼包含任何 , 字元，請在每個字元後立即新增一個 , 字元。 例如，若密碼為 a,b,c，連接字串 中逃逸的密碼為 a,,b,,c。
憑證中的主機名稱
指定在協商 加密 時，伺服器憑證中預期的主機名稱；如果該主機名稱不同於從 Addr、Address 或 Server 衍生的預設值。 當你使用這個ServerCertificate選項時，這個HostnameInCertificate選項會被忽略。
IP 位址偏好設定
從版本 18.1 開始，使用此選項來指定連線優先順序的 IP 位址類型。
可能的選項有 IPv4First、 IPv6First、 UsePlatformDefault和 。
UsePlatformDefault 會依照系統呼叫解析伺服器名稱時所提供的位址順序進行連線。 預設值為 IPv4First，對應於先前版本的行為。
伺服器憑證
從版本 18.1 開始，請使用此選項並啟用嚴格加密模式。 使用ServerCertificate關鍵字指定憑證檔案的路徑，與 SQL Server 的 TLS/SSL 憑證相符。 這種比對方式取代了標準的憑證驗證（如過期、主機名稱、信任鏈等）。 接受的憑證格式為 PEM、DER 和 CER。 如果你指定此選項，系統會透過檢查所提供的 ServerCertificate 是否完全相符來驗證 SQL Server 憑證。
SQL_COPT_SS_ACCESS_TOKEN
使用 Microsoft Entra 存取權杖來進行驗證。 如需詳細資訊，請參閱搭配使用 Microsoft Entra ID 與 ODBC 驅動程式。
| 屬性值 | 描述 |
|---|---|
NULL (預設值) |
不提供存取憑證。 |
ACCESSTOKEN* |
存取權杖的指標。 |
SQL_COPT_SS_CEKEYSTOREDATA
與載入的金鑰儲存區提供者程式庫通訊。 控制透明的資料行加密 (Always Encrypted)。 此屬性沒有預設值。 如需詳細資訊，請參閱自訂金鑰儲存區提供者。
| 屬性值 | 描述 |
|---|---|
CEKEYSTOREDATA * |
金鑰儲存區提供者程式庫的通訊資料結構 |
SQL_COPT_SS_CEKEYSTOREPROVIDER
載入 Always Encrypted 的金鑰儲存區提供者程式庫，或擷取載入的金鑰儲存區提供者程式庫名稱。 如需詳細資訊，請參閱自訂金鑰儲存區提供者。 此屬性沒有預設值。
| 屬性值 | 描述 |
|---|---|
char * |
金鑰儲存區提供者程式庫路徑 |
SQL_COPT_SS_ENLIST_IN_XA
若要透過符合 XA 規範的交易處理器（TP）啟用 XA 交易，應用程式必須呼叫 SQLSetConnectAttr，並傳入 SQL_COPT_SS_ENLIST_IN_XA 以及指向 XACALLPARAM 物件的指標。 此選項支援 Windows（17.3 及更新版本）、Linux 與 macOS。
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER); // XACALLPARAM *param
若要將 XA 交易僅與 ODBC 連線建立關聯，請在呼叫 FALSE 時提供 SQLSetConnectAttr 或 SQL_COPT_SS_ENLIST_IN_XA 搭配 TRUE，而不要提供指標。 此設定僅在 Windows 上有效，因此無法用來透過用戶端應用程式指定 XA 作業。
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, (SQLPOINTER)TRUE, 0);
| 值 | 描述 | 平台 |
|---|---|---|
XACALLPARAM 物件* |
指向 XACALLPARAM 物件的指標。 |
Windows、Linux 和 macOS |
TRUE |
將 XA 交易與 ODBC 連線建立關聯。 所有相關的資料庫活動都將在 XA 交易的保護底下進行。 | Windows |
FALSE |
解除該交易與 ODBC 連線的關聯。 | Windows |
如需 XA 交易的詳細資訊，請參閱使用 XA 交易。
SQL_COPT_SS_LONGASMAX
將長資料型態傳送給伺服器，作為最大資料型別。
| 屬性值 | 描述 |
|---|---|
No (預設值) |
傳送時，不要將 long 型別轉換為 max 型別。 |
Yes |
傳送時將資料從長型態轉換成最大型態。 |
SQL_COPT_SS_SPID
擷取連線的工作階段識別碼。 此屬性相當於 T-SQL @@SPID 變數，不同之處在於其不會對伺服器產生額外的往返。
| 屬性值 | 描述 |
|---|---|
DWORD |
SPID |