DSN 和連接字串關鍵字和屬性
此頁面會列出連接字串和 DSN 的關鍵字，以及 ODBC Driver for SQL Server 中可用的 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 | (預設) 在 ROLLBACK 或 COMMIT 之後自動進行 BEGIN TRANSACTION。 |
| SQL_AUTOBEGINTXN_OFF | 在 ROLLBACK 或 COMMIT 之後不會自動進行 BEGIN TRANSACTION。 |
SQL_COPT_SS_FALLBACK_CONNECT
控制 SQL Server 後援連線的使用。 這一項已不再支援。
| 屬性值 | 描述 |
|---|---|
| SQL_FB_OFF | (預設) 已停用後援連線。 |
| SQL_FB_ON | 已啟用後援連線。 |
新的連接字串關鍵字和連接屬性
驗證 - SQL_COPT_SS_AUTHENTICATION
設定連線到 SQL Server 時要使用的驗證模式。 如需詳細資訊，請參閱 使用 Microsoft Entra ID。
| 關鍵字值 | 屬性值 | 描述 |
|---|---|---|
| SQL_AU_NONE | (預設) 未設定。 其他屬性的組合會決定驗證模式。 | |
| SqlPassword | SQL_AU_PASSWORD | SQL Server 驗證 (使用使用者名稱和密碼)。 |
| ActiveDirectoryIntegrated | SQL_AU_AD_INTEGRATED | Microsoft Entra 整合式驗證。 |
| ActiveDirectoryPassword | SQL_AU_AD_PASSWORD | Microsoft Entra 密碼驗證 |
| ActiveDirectoryInteractive | SQL_AU_AD_INTERACTIVE | Microsoft Entra Interactive Authentication。 |
| ActiveDirectoryMsi | SQL_AU_AD_MSI | Microsoft Entra 受控識別驗證。 針對使用者指派的識別，UID 設成使用者身分識別的物件識別碼。 |
| ActiveDirectoryServicePrincipal | SQL_AU_AD_SPA | Microsoft Entra 服務主體驗證。 UID 設定為服務主體的用戶端識別碼。 PWD 設定為用戶端密碼。 |
| SQL_AU_RESET | 未設定。 覆寫任何 DSN 或連接字串設定。 |
注意
使用 Authentication 關鍵字或屬性時，明確地將 Encrypt 設定指定為連接字串/DSN/連接屬性中所要的值。 如需詳細資訊，請參閱搭配 SQL Server Native Client 使用連接字串關鍵字。
ColumnEncryption - SQL_COPT_SS_COLUMN_ENCRYPTION
控制透明的資料行加密 (Always Encrypted)。 如需詳細資訊，請參閱使用 Always Encrypted (ODBC)。
| 關鍵字值 | 屬性值 | 描述 |
|---|---|---|
| 啟用 | SQL_CE_ENABLED | 啟用 Always Encrypted。 |
| 已停用 | SQL_CE_DISABLED | (預設) 停用 Always Encrypted。 |
| SQL_CE_RESULTSETONLY | 只啟用解密 (結果和傳回值)。 |
Encrypt
指定連線是否透過網路使用 TLS 加密。 可能的值為 yes/mandatory(18.0+)、no/optional(18.0+) 和 strict(18.0+)。 預設值為 yes (18.0+ 版) 和 no (舊版)。
無論 Encrypt 的設定為何，伺服器登入認證 (使用者名稱和密碼) 一律會經過加密。
Encrypt、TrustServerCertificate 和伺服器端 Force Encryption 設定在連線是否透過網路加密方面扮演著重要角色。 下表顯示這些設定的效果。
ODBC 驅動程式 18 和更新版本
| 加密設定 | 信任伺服器憑證 | 伺服器強制加密 | 結果 |
|---|---|---|---|
| 否 | 無 | No | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料不會加密。 |
| No | .是 | 否 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料不會加密。 |
| 是 | 無 | No | 會檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| Yes | .是 | 否 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| No | 無 | Yes | 會檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| No | .是 | Yes | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| 是 | 無 | Yes | 會檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| Yes | .是 | Yes | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| Strict | - | - | 忽略 TrustServerCertificate。 會檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
注意
嚴格僅適用於支援 TDS 8.0 連線的伺服器。
ODBC 驅動程式 17 和更舊版本
| 加密設定 | 信任伺服器憑證 | 伺服器強制加密 | 結果 |
|---|---|---|---|
| 否 | 無 | No | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料不會加密。 |
| No | .是 | 否 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料不會加密。 |
| 是 | 無 | No | 會檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| Yes | .是 | 否 | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| No | 無 | Yes | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| No | .是 | Yes | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| 是 | 無 | Yes | 會檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
| Yes | .是 | Yes | 不檢查伺服器憑證。 在用戶端和伺服器之間傳送的資料會加密。 |
TransparentNetworkIPResolution - SQL_COPT_SS_TNIR
控制透明網路 IP 解析功能，它會與 MultiSubnetFailover 互動，以允許更快的重新連線嘗試。 如需詳細資訊，請參閱使用透明網路 IP 解析。
| 關鍵字值 | 屬性值 | 描述 |
|---|---|---|
| 啟用 | SQL_IS_ON | (預設) 啟用透明網路 IP 解析。 |
| 已停用 | SQL_IS_OFF | 停用透明網路 IP 解析。 |
UseFMTONLY
控制在連線到 SQL Server 2012 及更新版本時，對中繼資料使用 SET FMTONLY。
| 關鍵字值 | 描述 |
|---|---|
| 否 | (預設) 如果有的話，對中繼資料使用 sp_describe_first_result_set。 |
| 是 | 對中繼資料使用 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 開始嘗試 3 次，隨後的每次重試都會增加 7 秒。 如果未指定 +7，則隨後的每次重試都會以指數方式加倍。
查詢比對：指定您想要比對的查詢。 如果未指定任何項目，則會套用至所有查詢。 指定 SELECT 表示開頭為 select 的所有查詢。
將上述所有三個元件結合在一起，用於連接字串中將是：
RetryExec={1000,2000:3,10+7:SELECT}
這表示：「針對錯誤 1000 和 2000，開頭為 SELECT 的查詢。 重試兩次，最初延遲時間為 10 秒，並針對隨後每次嘗試增加 7 秒」
範例
40501,40540:4,5
針對錯誤 40501 和 40540，重試最多四次，最初延遲時間為 5 秒，且每次重試之間以指數倍數增加。 這規則適用於所有查詢。
49919:2,10+:CREATE
針對錯誤 49919，開頭為 CREATE 的查詢，至少重試兩次，一開始在 10 秒之後，然後是 20 秒。
49918,40501,10928:5,10+5:SELECT c1
針對錯誤 49918、40501 和 10928，開頭為 SELECT c1 的查詢，最多重試五次，第一次重試時等候 10 秒，之後等候時間增加 5 秒。
上述三個規則可以在連接字串中一起指定，如下所示：
RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}
最普遍的 (全部比對) 規則已放在結尾，以允許前面兩個更明確的規則比對其各自的查詢。
ClientCertificate
指定要用於驗證的憑證。 可用選項包括：
| 選項值 | 描述 |
|---|---|
sha1:<hash_value> |
ODBC 驅動程式會使用 SHA1 雜湊來找出 Windows 憑證存放區中的憑證 |
subject:<subject> |
ODBC 驅動程式會使用主旨來找出 Windows 憑證存放區中的憑證 |
file:<file_location>[,password:<password>] |
ODBC 驅動程式會使用憑證檔案。 |
如果憑證採用 PFX 格式，且 PFX 憑證內的私密金鑰受到密碼保護，則需要密碼關鍵字。 若是 PEM 和 DER 格式的憑證，ClientKey 屬性為必要項
ClientKey
針對 ClientCertificate 屬性所指定的 PEM 或 DER 憑證，請指定私密金鑰的檔案位置。 格式：
| 選項值 | 描述 |
|---|---|
file:<file_location>[,password:<password>] |
指定私密金鑰檔案的位置。 |
如果私密金鑰檔案受到密碼保護，則需要密碼關鍵字。 如果密碼包含任何 , 字元，則會緊接在每個字元之後加入一個額外的 , 字元。 例如，如果密碼是 a,b,c，則連接字串中的逸出密碼會是 a,,b,,c。
HostnameInCertificate
指定交涉加密時，伺服器憑證中預期的主機名稱 (如果主機名稱與衍生自 Addr/Address/Server 的預設值不同)。 若指定 HostnameInCertificate，即會忽略 ServerCertificate 選項。
IpAddressPreference
從 18.1 版開始提供，此選項可讓使用者指定其想要設定連線優先順序的 IP 位址類型。 可能的選項是 "IpAddress= [ IPv4First | IPv6First | UsePlatformDefault]"。UsePlatformDefault 會依系統呼叫提供的順序連線到位址，以解析伺服器名稱。 預設值為 IPv4First，其對應到舊版的行為。
ServerCertificate
從 18.1 版開始提供，此選項可以搭配嚴格的加密模式使用。 ServerCertificate 關鍵字用來指定要與 SQL Server TLS/SSL 憑證相符之憑證檔案的路徑。 比對會完成，而不是標準憑證驗證 (到期、主機名稱、信任鏈結等) 接受的憑證格式為 PEM、DER 和 CER。 若已指定，則會檢查 SQL Server 憑證，方法是查看提供的 ServerCertificate 是否完全相符。
SQL_COPT_SS_ACCESS_TOKEN
允許使用 Microsoft Entra 存取權杖進行驗證。 如需詳細資訊，請參閱 使用 Microsoft Entra ID。
| 屬性值 | 描述 |
|---|---|
| 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 連接建立關聯，呼叫 SQLSetConnectAttr 時請使用 SQL_COPT_SS_ENLIST_IN_XA 而不是指標來提供 TRUE 或 FALSE。 此設定僅在 Windows 上有效，因此無法用來透過用戶端應用程式指定 XA 作業。
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, (SQLPOINTER)TRUE, 0);
| 值 | 描述 | 平台 |
|---|---|---|
| XACALLPARAM 物件* | 指向 XACALLPARAM 物件的指標。 |
Windows、Linux 和 macOS |
| TRUE | 建立 XA 交易與 ODBC 連接的關聯。 所有相關的資料庫活動都將在 XA 交易的保護底下進行。 | Windows |
| FALSE | 取消 XA 交易與 ODBC 連接的關聯。 | Windows |
如需 XA 交易的詳細資訊，請參閱使用 XA 交易。
SQL_COPT_SS_LONGASMAX
允許將長類型資料傳送至伺服器作為最大類型資料。
| 屬性值 | 描述 |
|---|---|
| 否 | (預設) 傳送時不要將長類型轉換成最大類型。 |
| Yes | 傳送時，將資料從長類型轉換成最大類型。 |
SQL_COPT_SS_SPID
擷取連接的伺服器處理序識別碼。 此屬性相當於 T-SQL @@SPID 變數，不同之處在於其不會對伺服器產生額外的往返。
| 屬性值 | 描述 |
|---|---|
| DWORD | SPID |