本文列出 Microsoft ODBC Driver for SQL Server 在資料來源名稱(DSN)及連線字串中所接受的關鍵字。 它同時列出了 SQLSetConnectAttr 和 SQLGetConnectAttr的連線屬性。
選擇 DSN 或無 DSN 連線
有關選擇連線方法、驗證、加密、路由、重試及應用程式設定的指引,請參閱「設定 ODBC 連線至 Microsoft SQL」。 利用本文查詢精確的關鍵字與連線屬性。
支援 DSN 與 連接字串 關鍵字與連線屬性
下表列出各平台可用的關鍵字與屬性(L:Linux;M:macOS;W:Windows)。 選取關鍵字或屬性可查看詳細資料。
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。 -
平台支援:驅動程式支援
ConnectTimeoutWindows、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 |
會話編號。 |