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

本文列出 Microsoft ODBC Driver for SQL Server 在資料來源名稱(DSN)及連線字串中所接受的關鍵字。 它同時列出了 SQLSetConnectAttr 和 SQLGetConnectAttr的連線屬性。

選擇 DSN 或無 DSN 連線

有關選擇連線方法、驗證、加密、路由、重試及應用程式設定的指引,請參閱「設定 ODBC 連線至 Microsoft SQL」。 利用本文查詢精確的關鍵字與連線屬性。

支援 DSN 與 連接字串 關鍵字與連線屬性

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

DSN / 連接字串 關鍵字 連線屬性 平台
Addr LMW
地址 LMW
AnsiNPW SQL_COPT_SS_ANSI_NPW LMW
應用程式 LMW
ApplicationIntent SQL_COPT_SS_APPLICATION_INTENT LMW
AttachDBFileName SQL_COPT_SS_ATTACHDBFILENAME LMW
驗證 SQL_COPT_SS_AUTHENTICATION LMW
自動翻譯 SQL_COPT_SS_TRANSLATE LMW
ClientCertificate LMW
ClientKey LMW
ColumnEncryption SQL_COPT_SS_COLUMN_ENCRYPTION LMW
ConcatNullYieldsNull (v18.6 及更新版本) SQL_COPT_SS_CONCAT_NULL LMW
ConnectRetryCount SQL_COPT_SS_CONNECT_RETRY_COUNT LMW
ConnectRetryInterval SQL_COPT_SS_CONNECT_RETRY_INTERVAL LMW
ConnectTimeout (v18.7 及更新版本) SQL_ATTR_LOGIN_TIMEOUT LMW
Database SQL_ATTR_CURRENT_CATALOG LMW
Description LMW
驅動程式 LMW
DSN LMW
加密 SQL_COPT_SS_ENCRYPT LMW
Failover_Partner SQL_COPT_SS_FAILOVER_PARTNER W
FailoverPartner (v18.7 及更新版本) 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 及更新版本;17.8 以前僅限 DSN) LMW
KeepAliveInterval (v17.4 及更新版本;在 17.8 之前僅限 DSN) LMW
金鑰儲存驗證 LMW
KeystorePrincipalId LMW
KeystoreSecret LMW
語言 LMW
LongAsMax (v18.0 及更新版本) SQL_COPT_SS_LONGASMAX LMW
MARS_Connection SQL_COPT_SS_MARS_ENABLED LMW
MultipleActiveResultSets (v18.7 及更新版本) SQL_COPT_SS_MARS_ENABLED LMW
MultiSubnetFailover SQL_COPT_SS_MULTISUBNET_FAILOVER LMW
網路 LMW
Network LMW
PacketSize (驅動程式 18.7) SQL_ATTR_PACKET_SIZE 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
區域 LMW
Replication 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
vectorTypeSupport (v18.6.1.1 及更新版本) SQL_COPT_SS_VECTOR_TYPE_SUPPORT LMW
WorkstationID (v18.7 及更新版本) 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 W
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_CONNECTION_DEAD LMW
SQL_COPT_SS_DATACLASSIFICATION_VERSION (v17.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_ATTR_DBC_INFO_TOKEN 保留給 Windows Driver Manager 驅動程式感知連線池。 應用程式不會設定這個屬性。

以下列出一些未記載於搭配 SQL Server Native Client 使用連接字串關鍵字、SQLSetConnectAttr及SQLSetConnectAttr 函式中的連接字串關鍵字和連線屬性。

描述

描述資料來源。

SQL_COPT_SS_ANSI_OEM

控制 Windows 與原始設備製造商(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 資料提供者與驅動程式間切換時的關鍵字重新命名。 每個提供者仍有其支持的關鍵字與數值。

關鍵字別名

每個別名配置的選項與其對應的 ODBC 關鍵字相同:

別名 等效的 ODBC 關鍵字 描述
MultipleActiveResultSets MARS_Connection 可開啟或關閉多個主動結果集(MARS)。 接受 Yes 或 No。
WorkstationID WSID 設定工作站 ID,通常是執行該應用程式的電腦的網路名稱。 HOST_NAME() 回傳此值。
FailoverPartner Failover_Partner 指定用於資料庫鏡像的容錯移轉夥伴伺服器。 僅支援 Windows。

注意

在 18.7 版本中, MultipleActiveResultSets 接受 Yes 或 No,但不接受 True 或 False。

駕駛者對這些別名適用以下規則:

  • 不區分大小寫: 驅動程式不論大小寫,都能匹配別名。 例如, 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 上,應用程式可以在資料來源名稱(DSN)中儲存並擷取 ConnectTimeout。
  • 平台支援:驅動程式支援 ConnectTimeout Windows、Linux 及 macOS。

範例

以下 連接字串 使用統一的關鍵字拼字。 以您自己的值取代 <server>、<database>、<user_id> 和 <password>。 對於 Azure SQL Database,請使用 <server>.database.windows.net 作為主機名稱:

Driver={ODBC Driver 18 for SQL Server};Server=tcp:<server>;Database=<database>;UID=<user_id>;PWD=<password>;Encrypt=yes;TrustServerCertificate=no;MultipleActiveResultSets=Yes;WorkstationID=app-node-01;ConnectTimeout=30;

前述連線字串中的別名,設定的選項與下列連線字串中的原始 ODBC 關鍵字相同:

Driver={ODBC Driver 18 for SQL Server};Server=tcp:<server>;Database=<database>;UID=<user_id>;PWD=<password>;Encrypt=yes;TrustServerCertificate=no;MARS_Connection=Yes;WSID=app-node-01;

這兩個字串都啟用 MARS並設定工作站 ID 為 app-node-01。 第一串也需等待最多 30 秒才能完成登入。 ConnectTimeout 在 Driver 17 或較早版本,以及 Driver 18 的較早版本中,沒有對應的關鍵字。 若要設定登入逾時,請呼叫 SQLSetConnectAttr,並搭配 SQL_ATTR_LOGIN_TIMEOUT。

驗證 - SQL_COPT_SS_AUTHENTICATION

設定連線的驗證模式。 如需更多資訊,請參閱〈使用 Microsoft Entra ID 搭配 ODBC 驅動程式〉。

關鍵字價值 屬性值 描述
SQL_AU_NONE (預設) 若未明確設定屬性,其他連線設定會決定驗證。 明確設定此屬性會覆寫 DSN 或 連接字串 的Authentication選取。
SqlPassword SQL_AU_PASSWORD 使用 SQL 驗證,使用使用者名稱和密碼。
ActiveDirectoryIntegrated SQL_AU_AD_INTEGRATED Microsoft Entra 整合式驗證。
ActiveDirectoryInteractive SQL_AU_AD_INTERACTIVE Microsoft Entra 互動式認證。
ActiveDirectoryMsi SQL_AU_AD_MSI Microsoft Entra 受控識別驗證。 對於使用者指派的身分識別,請在 Azure App 服務 或 Azure 容器執行個體 上將 UID 設為其用戶端 ID;在其他支援的主機上使用其物件 ID。 若為系統指派的身分識別,請省略 UID。
ActiveDirectoryServicePrincipal SQL_AU_AD_SPA Microsoft Entra 服務主體驗證。 UID 設定為服務主體的用戶端 ID。 PWD 設定為用戶端密鑰。
ActiveDirectoryPassword SQL_AU_AD_PASSWORD 已棄用的 Microsoft Entra 使用者名稱與密碼驗證功能。 如需更多資訊,請參閱 ActiveDirectoryPassword 棄用說明。
SQL_AU_RESET 清除明確設定的驗證屬性,以便 DSN 或 連接字串 的 Authentication 設定能再次套用。

注意

使用Authentication關鍵字或屬性時,請在 連接字串、DSN 或 connection attribute 中明確設定Encrypt。 有關行為與預設值,請參閱 「加密」。

列加密 (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 也接受 mandatory 作為 optional 的同義詞、no 作為 strict 的同義詞,以及 yes;後者會選取表格資料串流(TDS)8.0 加密,且在 Driver 17 中沒有對應項目。

驅動程式 18 預設為 yes。 驅動程式 17 通常預設為 no,但當提供非空 yes 設定或存取權杖時,則預設為 Authentication。 請明確設定 Encrypt ,而非依賴這些依賴驗證的預設值。

無論 Encrypt 的設定為何,伺服器登入認證 (使用者名稱和密碼) 一律會經過加密。

Encrypt、 TrustServerCertificate以及伺服器端Force Encryption的設定決定了連線是否在網路上加密。 下表顯示這些設定的效果。

ODBC Driver 18 及之後版本

加密設定 信任伺服器證書 伺服器強制加密 Result
否 否 否 不檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料不會加密。
否 .是 否 不檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料不會加密。
.是 否 否 會檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。
.是 .是 否 不檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。
否 否 .是 會檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。
否 .是 .是 不檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。
.是 否 .是 會檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。
.是 .是 .是 不檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。
嚴格 - - TrustServerCertificate 被忽視了。 會檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。

注意

此 Strict 值僅適用於支援 TDS 8.0 連線的伺服器。

ODBC 驅動程式 17 及更早版本

加密設定 信任伺服器證書 伺服器強制加密 Result
否 否 否 不檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料不會加密。
否 .是 否 不檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料不會加密。
.是 否 否 會檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。
.是 .是 否 不檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。
否 否 .是 不檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。
否 .是 .是 不檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。
.是 否 .是 會檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。
.是 .是 .是 不檢查伺服器憑證。
在用戶端和伺服器之間傳送的資料會加密。

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 選項的觸發程序不會在該連線上觸發。

PacketSize

驅動程式 18.7 支援 PacketSize 請求以位元組為單位的網路封包大小。 協商後的大小可能與要求的值不同。 使用 SQL_ATTR_PACKET_SIZE 設定對應的連線屬性或擷取協商後的大小。 有關屬性限制與行為,請參閱 SQLSetConnectAttr。 Driver 17 應用程式使用屬性而非 PacketSize 關鍵字。

RetryExec

可設定重試邏輯可在驅動程式 18.1 及更新版本中使用。 驅動程式 17 不支援 RetryExec。 使用 RetryExec 連接字串 關鍵字及控制 SQLExecute 和 SQLExecDirect 重新執行的規則清單來啟用。

發生執行錯誤後,驅動程式會選擇其錯誤清單包含該錯誤代碼的第一個規則。 接著它會將該規則的查詢前綴與 SQLExecDirect 的輸入指令文字或 SQLExecute 的預備文字進行比對。 如果前綴不符,驅動程式不會重試該指令或繼續執行後續規則。 較晚的通配規則並非先前規則中已列出錯誤代碼的備用方案。

僅重試可安全重複執行的操作。 重試可以執行同一指令多次,連線失敗並不代表前一次寫入失敗。

關鍵字的 RetryExec 值是分號分隔的重試規則清單。
RetryExec={rule1;rule2}

重試規則如下所示:<errormatch>:<retrypolicy>:<querymatch>

  • 錯誤匹配: 以逗號分隔的錯誤代碼清單,例如 1000,2000。

  • 重試策略: 重試次數加上初始延遲(秒數)。 例如,允許 3,10+7 在初次執行後重試三次,延遲時間為 10、17 及 24 秒:若每次嘗試失敗,總共執行四次。 若沒有 +,延遲每次重試都會加倍。 沒有增量的末尾的 + 則是使用初始延遲作為增量。

  • 查詢匹配: 命令文字前綴。 空前綴適用於所有指令。 例如,SELECT 會符合以 SELECT 開頭的指令。

將這三個元件組合在一起,以用於連線字串:

RetryExec={1000,2000:3,10+7:SELECT}

對於以 SELECT 開頭的指令上發生的錯誤 1000 和 2000,此規則允許在 10、17 及 24 秒後重試三次。

範例

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}

在此組合中,錯誤 40501 會選擇第一條規則,並只重試以 SELECT c1 開頭的指令。 最終規則不對其他因 40501 而失敗的指令提供備援方案。 若要將最終原則套用於所有有該錯誤的指令,請從第一條規則的錯誤清單中移除 40501 。 當每個程式碼需要一個政策時,優先使用不重疊的錯誤清單。

用戶端憑證

指定用於回送連線驗證的憑證。 此選項僅適用於 Linux 上的 SQL Server。 可用選項包括:

選項值 描述
sha1:<hash_value> ODBC 驅動程式使用 Secure Hash Algorithm 1 (SHA-1) 雜湊值來在 Windows 憑證存放區中尋找憑證。
subject:<subject> ODBC 驅動程式會根據主體,在 Windows 憑證存放區中尋找憑證。
file:<file_location>[,password:<password>] ODBC 驅動程式會使用憑證檔案。

如果憑證為個人資訊Exchange(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 關鍵字指定憑證檔案路徑,以與伺服器的 TLS 憑證相匹配。 檔案匹配取代了一般的主機名稱與信任鏈驗證,但驅動程式仍會檢查伺服器憑證的有效日期。 請使用 PEM 或 DER 編碼的憑證檔案。 使用上述任一編碼的具有 .cer 副檔名的檔案可被接受。 伺服器憑證必須與指定檔案中的憑證完全相符。

SQL_COPT_SS_ACCESS_TOKEN

請使用 Microsoft Entra ID 存取權杖進行驗證。 如需更多資訊,請參閱〈使用 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 分散式交易,請呼叫 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

控制驅動程式是否將長字元和二進位參數作為 varchar(max)、nvarchar(max) 和 varbinary(max) 傳送。 驅動程式 18 支援此選項;驅動程式 17 則不支援。

屬性值 描述
SQL_XL_OFF (0, 預設) 傳送時,不要將 long 型別轉換為 max 型別。
SQL_XL_ON (1) 發送時將 long 型別轉換為 max 型別。

這些是 SQLSetConnectAttr 的數值。 對應LongAsMax的 連接字串 關鍵字使用 No 和 Yes。

SQL_COPT_SS_SPID

擷取連線的工作階段識別碼。 此屬性等同於 Transact-SQL (T-SQL) @@SPID 變數,但不會額外往返伺服器。

屬性值 描述
DWORD 會話編號。