共用方式為


DSN 和連接字串關鍵字和屬性

此頁面會列出連接字串和 DSN 的關鍵字,以及 ODBC Driver for SQL Server 中可用的 SQLSetConnectAttr 和 SQLGetConnectAttr 連接屬性。

支援的 DSN/連接字串關鍵字和連接屬性

下表列出每個平台可用的關鍵字和屬性 (L:Linux;M:macOS;W:Windows)。 選取關鍵字或屬性可查看詳細資料。

DSN/連接字串關鍵字 連線屬性 平台
Addr LMW
位址 LMW
AnsiNPW SQL_COPT_SS_ANSI_NPW LMW
APP LMW
ApplicationIntent SQL_COPT_SS_APPLICATION_INTENT LMW
AttachDBFileName SQL_COPT_SS_ATTACHDBFILENAME LMW
驗證 SQL_COPT_SS_AUTHENTICATION LMW
AutoTranslate SQL_COPT_SS_TRANSLATE LMW
ClientCertificate LMW
ClientKey LMW
ColumnEncryption SQL_COPT_SS_COLUMN_ENCRYPTION LMW
ConnectRetryCount SQL_COPT_SS_CONNECT_RETRY_COUNT LMW
ConnectRetryInterval SQL_COPT_SS_CONNECT_RETRY_INTERVAL LMW
Database SQL_ATTR_CURRENT_CATALOG LMW
說明 LMW
驅動程式 LMW
DSN LMW
Encrypt SQL_COPT_SS_ENCRYPT LMW
Failover_Partner SQL_COPT_SS_FAILOVER_PARTNER W
FailoverPartnerSPN SQL_COPT_SS_FAILOVER_PARTNER_SPN W
FileDSN LMW
GetDataExtensions (v18.0+) SQL_COPT_SS_GETDATA_EXTENSIONS LMW
HostnameInCertificate (v18.0+) LMW
IpAddressPreference (v18.1+) LMW
KeepAlive (v17.4+,僅限 DSN 17.8 之前版本) LMW
KeepAliveInterval (v17.4+,僅限 DSN 17.8 之前版本) LMW
KeystoreAuthentication LMW
KeystorePrincipalId LMW
KeystoreSecret LMW
語言 LMW
LongAsMax (v18.0+) SQL_COPT_SS_LONGASMAX LMW
MARS_Connection SQL_COPT_SS_MARS_ENABLED LMW
MultiSubnetFailover SQL_COPT_SS_MULTISUBNET_FAILOVER LMW
Net LMW
Network LMW
PWD LMW
QueryLog_On SQL_COPT_SS_PERF_QUERY W
QueryLogFile SQL_COPT_SS_PERF_QUERY_LOG W
QueryLogTIme SQL_COPT_SS_PERF_QUERY_INTERVAL W
QuotedId SQL_COPT_SS_QUOTED_IDENT LMW
Regional LMW
複寫 LMW
RetryExec (18.1+) LMW
SaveFile LMW
Server LMW
ServerCertificate (v18.1+) LMW
ServerSPN SQL_COPT_SS_SERVER_SPN LMW
StatsLog_On SQL_COPT_SS_PERF_DATA W
StatsLogFile SQL_COPT_SS_PERF_DATA_LOG W
TransparentNetworkIPResolution SQL_COPT_SS_TNIR LMW
Trusted_Connection SQL_COPT_SS_INTEGRATED_SECURITY LMW
TrustServerCertificate SQL_COPT_SS_TRUST_SERVER_CERTIFICATE LMW
UID LMW
UseFMTONLY LMW
WSID LMW
SQL_ATTR_ACCESS_MODE
(SQL_ACCESS_MODE)
LMW
SQL_ATTR_ASYNC_DBC_EVENT W
SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE W
SQL_ATTR_ASYNC_DBC_PCALLBACK W
SQL_ATTR_ASYNC_DBC_PCONTEXT W
SQL_ATTR_ASYNC_ENABLE W
SQL_ATTR_AUTO_IPD LMW
SQL_ATTR_AUTOCOMMIT
(SQL_AUTOCOMMIT)
LMW
SQL_ATTR_CONNECTION_DEAD LMW
SQL_ATTR_CONNECTION_TIMEOUT LMW
SQL_ATTR_DBC_INFO_TOKEN LMW
SQL_ATTR_LOGIN_TIMEOUT
(SQL_LOGIN_TIMEOUT)
LMW
SQL_ATTR_METADATA_ID LMW
SQL_ATTR_ODBC_CURSORS
(SQL_ODBC_CURSORS)
LMW
SQL_ATTR_PACKET_SIZE
(SQL_PACKET_SIZE)
LMW
SQL_ATTR_QUIET_MODE
(SQL_QUIET_MODE)
LMW
SQL_ATTR_RESET_CONNECTION
(SQL_COPT_SS_RESET_CONNECTION)
LMW
SQL_ATTR_TRACE
(SQL_OPT_TRACE)
LMW
SQL_ATTR_TRACEFILE
(SQL_OPT_TRACEFILE)
LMW
SQL_ATTR_TRANSLATE_LIB
(SQL_TRANSLATE_DLL)
LMW
SQL_ATTR_TRANSLATE_OPTION
(SQL_TRANSLATE_OPTION)
LMW
SQL_ATTR_TXN_ISOLATION
(SQL_TXN_ISOLATION)
LMW
SQL_COPT_SS_ACCESS_TOKEN LMW
SQL_COPT_SS_ANSI_OEM W
SQL_COPT_SS_AUTOBEGINTXN LMW
SQL_COPT_SS_BCP LMW
SQL_COPT_SS_BROWSE_CACHE_DATA LMW
SQL_COPT_SS_BROWSE_CONNECT LMW
SQL_COPT_SS_BROWSE_SERVER LMW
SQL_COPT_SS_CEKEYSTOREDATA LMW
SQL_COPT_SS_CEKEYSTOREPROVIDER LMW
SQL_COPT_SS_CLIENT_CONNECTION_ID LMW
SQL_COPT_SS_CONCAT_NULL LMW
SQL_COPT_SS_CONNECTION_DEAD LMW
SQL_COPT_SS_DATACLASSIFICATION_VERSION (17.4.2+ 版) LMW
SQL_COPT_SS_ENLIST_IN_DTC W
SQL_COPT_SS_ENLIST_IN_XA LMW
SQL_COPT_SS_FALLBACK_CONNECT LMW
SQL_COPT_SS_INTEGRATED_AUTHENTICATION_METHOD LMW
SQL_COPT_SS_MUTUALLY_AUTHENTICATED LMW
SQL_COPT_SS_OLDPWD LMW
SQL_COPT_SS_PERF_DATA_LOG_NOW W
SQL_COPT_SS_PRESERVE_CURSORS LMW
SQL_COPT_SS_SPID (v17.5+) LMW
SQL_COPT_SS_TXN_ISOLATION LMW
SQL_COPT_SS_USER_DATA LMW
SQL_COPT_SS_WARN_ON_CP_ERROR LMW

以下是搭配 SQL Server Native Client 使用連接字串關鍵字SQLSetConnectAttrSQLSetConnectAttr 函式中所未記載的一些連接字串關鍵字和連接屬性。

描述

用於描述資料來源。

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 的設定為何,伺服器登入認證 (使用者名稱和密碼) 一律會經過加密。

EncryptTrustServerCertificate 和伺服器端 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 屬性所指定的 PEMDER 憑證,請指定私密金鑰的檔案位置。 格式:

選項值 描述
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