設定連線屬性
您可以使用各種方法指定連接字串屬性：
當您使用 DriverManager 類別進行連線時，連線 URL 中的屬性為 name=value。 如需連接字串範例，請參閱建立連線 URL。
在 DriverManager 類別的 Connect 方法中指定為 Properties 參數的 name=value 屬性。
指定為驅動程式資料來源適當 setter 方法中的值。 例如：
datasource.setServerName(value) datasource.setDatabaseName(value)
備註
屬性名稱需區分大小寫，而重複的屬性名稱將以下列順序解析：
- API 引數 (例如使用者及密碼)
- 屬性集合
- 連接字串內的最後一個執行個體
屬性名稱允許使用未知的值，且 JDBC 驅動程式不會驗證屬性值的大小寫。
容許同義字並會依序解析，如同是重複的屬性名稱一般。
屬性
下表列出 JDBC 驅動程式目前所有可用的連接字串屬性。
| 屬性 類型 預設 |
描述 |
|---|---|
| accessToken String null |
(6.0+ 版) 使用此屬性可使用存取權杖與 SQL 資料庫連線。 無法使用連線 URL 設定 accessToken。 |
| accessTokenCallbackClass String null |
(版本 12.4+) 要搭配存取權杖回呼使用的回呼實作類別名稱。 |
| applicationIntent String 讀寫 |
(6.0+ 版) 宣告應用程式工作負載類型以便與伺服器連線。 可能的值為 ReadOnly 和 ReadWrite。 如需災害復原的詳細資訊，請參閱 JDBC 驅動程式對高可用性和災害復原的支援。 |
| applicationName String [<=128 char] null |
如果未提供任何名稱，則為應用程式名稱或「Microsoft JDBC Driver for SQL Server」。 用以識別各種 SQL Server 分析和記錄工具中的特定應用程式。 |
| 驗證 (authentication) String NotSpecified |
(6.0+ 版) 此屬性能指出連線所要使用的驗證方法，可自由選填。 可能的值包含：ActiveDirectoryIntegrated、ActiveDirectoryPassword、ActiveDirectoryManagedIdentity (12.2+ 版)、ActiveDirectoryMSI (7.2+ 版)、ActiveDirectoryInteractive (9.2+ 版)、ActiveDirectoryServicePrincipal (9.2+ 版)、SqlPassword 和預設值 NotSpecified。 搭配整合式 Windows 驗證使用 ActiveDirectoryIntegrated (6.0+ 版) 與 SQL 連線。 搭配 Microsoft Entra 主體名稱和密碼使用 ActiveDirectoryPassword (6.0+ 版) 與 SQL 連線。 使用 ActiveDirectoryManagedIdentity (12.2+ 版) 或 ActiveDirectoryMSI (7.2+ 版) 從 Azure 資源內部與 SQL 連線。 例如，使用受控識別驗證的 Azure 虛擬機器、App Service 或函數應用程式。 使用 ActiveDirectoryManagedIdentity 或 ActiveDirectoryMSI 驗證模式時，驅動程式所支援的兩種受控識別類型為： 1.系統指派的受控識別：預設會使用此類型來取得 accessToken。 2.使用者指派的受控識別：如果受控識別的用戶端識別碼是以 msiClientId 連線屬性指定，則會使用此類型來取得 accessToken。 使用 ActiveDirectoryInteractive 與使用互動式驗證流程的資料庫連線。 搭配服務主體身分識別的用戶端識別碼和密碼，使用 ActiveDirectoryServicePrincipal (9.2+ 版) 與資料庫連線。 在 userName 屬性中指定用戶端識別碼，並在 password 屬性 (10.2+) 中指定祕密。 搭配 userName/user 和 password 屬性，使用 SqlPassword 與 SQL 連線。 如果不需要這些驗證方法，請使用 NotSpecified。 重要：如果驗證設定為 ActiveDirectoryIntegrated，則必須安裝下列兩個程式庫：mssql-jdbc_auth-<version>-<arch>.dll (由 JDBC 驅動程式套件提供) 和 Microsoft Authentication Library for SQL Server (ADAL.DLL)。 您可以從 Microsoft ODBC Driver for SQL Server 或 Microsoft OLE DB Driver for SQL Server 安裝 Microsoft 驗證程式庫。 JDBC 驅動程式只支援 ADAL.DLL 的 1.0.2028.318 版和更高版本。 注意：當 authentication 屬性設定為 NotSpecified 以外的任何值時，在預設情況下，驅動程式會使用傳輸層安全性 (TLS) (原稱為安全通訊端層 (SSL)) 加密。 如需如何設定 Microsoft Entra 驗證的資訊，請參閱使用 Microsoft Entra 驗證。 |
| authenticationScheme String NativeAuthentication |
表示您希望應用程式使用的整合式安全性種類。 可能的值包括：JavaKerberos、NTLM (7.4+ 版) 和預設值 NativeAuthentication。 NativeAuthentication 會讓驅動程式在 Windows 上載入 mssql-jdbc_auth-<version>-<arch>.dll (例如 mssql-jdbc_auth-8.2.2.x64.dll)，用於取得整合式驗證資訊。 (使用驅動程式版本 6.0 到 7.4 時，載入的原生驗證程式庫名稱為 sqljdbc_auth.dll。)使用 authenticationScheme=JavaKerberos 時，您必須在 serverName 或 serverSpn 屬性中指定完整網域名稱 (FQDN)。 否則，會發生錯誤 (Kerberos 資料庫中找不到伺服器)。 如需使用 authenticationScheme=JavaKerberos 的詳細資訊，請參閱使用 Kerberos 整合式驗證連線到 SQL Server。 使用 authenticationScheme=NTLM 時，您必須在 domain 或 domainName 屬性中指定 Windows 網域，也必須在 user 或 userName 以及 password 屬性中指定 Windows 認證。 否則，會發生錯誤 (必須指定連接屬性)。 |
| cacheBulkCopyMetadata boolean ["true" | "false"] false |
(版本 12.8+) 使用 useBulkCopyForBatchInsert=true 時，這個屬性是用來告訴驅動程式是否應該快取連接層級的目的地資料中繼資料。 如果設定為 true，請確定目的地不會在大量插入之間變更，因為驅動程式沒有處理這項變更的方式。 |
| calcBigDecimalPrecision boolean ["true" | "false"] false |
(版本 12.6+) 旗標，指出驅動程式是否應該計算 BigDecimal 輸入的有效位數，而不是使用有效位數允許的最大值 (38)。 |
| cancelQueryTimeout int -1 |
(6.4+ 版) 這個屬性可用來取消您為連線設定的 queryTimeout。 查詢執行作業會停止回應，如果與伺服器之間的 TCP 連線以無訊息方式卸除，則不會擲回例外狀況。 當連線上也設定 'queryTimeout' 時，此屬性才適用。 驅動程式會等候 cancelQueryTimeout + queryTimeout 的總秒數，然後中斷連線並關閉通道。 此屬性的預設值為 -1，而行為是無限期地等候。 |
| clientCertificate String null |
(8.4+ 版) 指定用戶端憑證驗證所使用憑證的位置。 JDBC 驅動程式可支援 PFX、PEM、DER 與 CER 副檔名。 如需詳細資訊，請參閱回送案例的用戶端憑證驗證。 |
| clientKey String null |
(8.4+ 版) 針對 clientCertificate 屬性所指定的 PEM、DER 與 CER 憑證，指定私密金鑰的位置。 如需詳細資訊，請參閱回送案例的用戶端憑證驗證。 |
| clientKeyPassword String null |
(8.4+ 版) 指定存取 clientKey 檔案私密金鑰時能自由選擇使用的密碼字串。 如需詳細資訊，請參閱回送案例的用戶端憑證驗證。 |
| columnEncryptionSetting String ["Enabled" | "Disabled"] 已停用 |
(6.0+ 版) 設定為 [Enabled] 以使用 Always Encrypted (AE) 功能。 如有啟用 AE，JDBC 驅動程式會透明加密及解密儲存於 SQL Server 經過加密之資料庫資料行中的敏感資料。 如需 Always Encrypted 的詳細資訊，請參閱搭配 JDBC 驅動程式使用 Always Encrypted。 注意：SQL Server 2016 以上版本和 Azure SQL Database 均已提供 Always Encrypted。 |
| connectRetryCount int [0..255] 1 |
(9.4+ 版) 連線失敗時，重新連線的嘗試次數。 |
| connectRetryInterval int [1..60] 10 |
(9.4+ 版) 每次重新嘗試連線之間的間隔秒數。 |
| databaseName, [資料庫] String [<=128 char] null |
要連接的資料庫名稱。 如果沒有指定，將連接到預設資料庫。 |
| datetimeParameterType 字串 ["datetime" | "datetime2" | "datetimeoffset"] datetime2 |
(12.2+ 版) Java 日期/時間戳記參數所使用的 SQL 資料類型。 連線到 SQL Server 2016 或以上版本並與舊版 "datetime" 值互動時，將屬性設定為 "datetime" 可能有利於用戶端。 此設定可減輕伺服器端 "datetime" 和 "datetime2" 值之間的轉換問題。 如需詳細資訊，請參閱從 SQL Server 2016 開始解決 datetime 轉換到 datetime2 的行為變更問題。 |
| delayLoadingLobs boolean ["true" | "false"] true |
新增旗標以指出是否要串流從 ResultSet 擷取的所有 LOB 物件。 將此屬性設定為 "false" 的話，系統會在不串流的情況下，將整個 LOB 物件載入記憶體。 |
| domainName, 網域 String null |
(7.4+ 版) 使用 NTLM 驗證時要驗證的 Windows 網域。 |
| disableStatementPooling boolean ["true" | "false"] true |
旗標表示是否應該使用陳述式共用。 |
| enablePrepareOnFirst... PreparedStatementCall boolean ["true" | "false"] false |
設定為 "true" 可在已備妥的陳述式第一次執行時呼叫 sp_prepexec，啟用已備妥陳述式控制代碼的建立功能。 設定為 "false" 則可變更已備妥陳述式在第一次執行時呼叫 sp_executesql 的流程，並且不準備陳述式。 如果發生第二次執行，便會呼叫 sp_prepexec 以設定已備妥的陳述式控制代碼。 |
| enclaveAttestationUrl String null |
(8.2+ 版) 這個選用型的屬性可顯示要針對具有安全記憶體保護區的 Always Encrypted 使用的證明服務端點 URL。 如需深入了解能提供安全記憶體保護區的 Always Encrypted，請參閱具有安全記憶體保護區的 Always Encrypted。 |
| enclaveAttestationProtocol String null |
(8.2+ 版) 這個選用型的屬性可顯示要針對具有安全記憶體保護區的 Always Encrypted 使用的證明通訊協定。 目前，此欄位唯一支援的值是 HGS、AAS 和 NONE (11.2+ 版僅支援 NONE)。 如需深入了解能提供安全記憶體保護區的 Always Encrypted，請參閱具有安全記憶體保護區的 Always Encrypted。 |
| encrypt String null |
如果伺服器已安裝憑證，請設定為 "true" 以指定 SQL Server 對用戶端與伺服器之間傳送的所有資料使用 TLS 加密。 10.2 以上版本的預設值為 "true"，9.4 以下版本則預設為 "false"。 在 6.0 以上版本中，預設會有新的連線設定 'authentication' 使用 TLS 加密。 如需此屬性的詳細資訊，請參閱 'authentication' 屬性。 在 11.2.0 以上版本中，encrypt 已從布林值變更為字串，如此可在屬性設定為 strict 時支援 TDS 8.0。 |
| failoverPartner String null |
用於資料庫鏡像組態的容錯移轉伺服器名稱。 初次連線主體伺服器失敗時，系統就會使用此屬性。 初次連線後，系統就會忽略此屬性。 務必與 databaseName 屬性搭配使用。 注意：此驅動程式不支援將容錯移轉夥伴執行個體的伺服器執行個體連接埠號碼，放入連接字串的 failoverPartner 屬性中使用。 不過，此驅動程式支援在相同的連接字串中指定主體伺服器執行個體的 serverName、instanceName 和 portNumber 屬性以及容錯移轉夥伴執行個體的 failoverPartner 屬性。 如果您在 Server 連線屬性中指定虛擬網路名稱，就不能使用資料庫鏡像。 如需災害復原的詳細資訊，請參閱 JDBC 驅動程式對高可用性和災害復原的支援。 |
fipsboolean ["true" | "false"] "false" |
如果是已啟用 FIPS 的 Java 虛擬機器 (JVM))，此屬性應該要是 [true]。 |
| fipsProvider String null |
在 JVM 中設定的 FIPS 提供者。 例如，BCFIPS 或 SunPKCS11-NSS。 已於 6.4.0 版中移除。 如需詳細資訊，請參閱 GitHub 問題 #460 (英文)。 |
| gsscredential org.ietf.jgss.GSSCredential null |
(6.2+ 版) 此屬性可傳遞 Kerberos 限制委派所使用的使用者認證。 使用此設定時，應將 integratedSecurity 設定為 true 且 JavaKerberos 設定為 authenticationScheme。 |
| hostNameInCertificate String null |
驗證 SQL Server TLS/SSL 憑證所使用的主機名稱。 hostNameInCertificate 選項可用來在認證中所使用的名稱或名稱不符合傳入 serverName 屬性的名稱時指定主機名稱。 不過，如果有相符名稱，則不應使用 hostNameInCertificate 選項。 如果未指定 hostNameInCertificate 屬性，或設定為 null，Microsoft JDBC Driver for SQL Server 會在連線 URL 上使用 serverName 屬性值，作為驗證 SQL Server TLS/SSL 憑證的主機名稱。 注意：如上述段落所述，除非您可以在認證中確認名稱或名稱，否則不建議設定 hostNameInCertificate 選項，否則憑證中的名稱與 serverName 選項中傳遞的名稱不符。 注意：此屬性需搭配 encrypt/authentication 屬性和 trustServerCertificate 屬性一起使用。 如果連線使用 TLS 加密，且 trustServerCertificate 設定為 "false"，此屬性就會影響憑證驗證。 請確定傳遞給 hostNameInCertificate 的值符合伺服器憑證中主體別名 (SAN) 內一般名稱 (CN) 或 DNS 名稱，以順利執行 TLS 連線。 如需加密支援的詳細資訊，請參閱了解加密支援。 |
| INSTANCENAME String [<=128 char] null |
要連線的資料庫執行個體名稱。 如果未指定，系統就會與預設的執行個體連線。 如果已指定 instanceName 與通訊埠，請參閱通訊埠的注意事項。 如果您在 Server 連線屬性中指定虛擬網路名稱，就不能使用 instanceName 連線屬性。 如需災害復原的詳細資訊，請參閱 JDBC 驅動程式對高可用性和災害復原的支援。 |
| integratedSecurity boolean ["true" | "false"] false |
設定為 "true" 可指出 Windows 作業系統上的 SQL Server 會使用 Windows 認證。 若為 "true"，JDBC 驅動程式會搜尋本機電腦認證快取，從中找到使用者登入電腦或網路時，系統所提供的認證。 設定為 "true" (搭配 authenticationscheme=JavaKerberos) 可指出 SQL Server 使用 Kerberos 認證。 如需 Kerberos 驗證的詳細資訊，請參閱使用 Kerberos 整合式驗證連線至 SQL Server。 設定為 "true" (搭配 authenticationscheme=NTLM) 可指出 SQL Server 使用 NTLM 認證。 若為 "false"，必須提供使用者名稱及密碼。 |
| ipaddresspreference String [<=128 char] IPv4First |
用戶端應用程式所使用的 IP 偏好設定。 使用 IPV4First 時，驅動程式會先周遊 IPv4 位址。 如果沒有可以成功連線的 IPv4 位址，驅動程式會繼續嘗試 IPv6 位址 (如果有的話)。 使用 IPV6First 時，驅動程式會先周遊 IPv6 位址。 如果沒有可以成功連線的 IPv6 位址，驅動程式會繼續嘗試 IPv4 位址 (如果有的話)。 使用 UsePlatformDefault 時，驅動程式會依 DNS 解析的初始順序周遊所有 IP 位址。 |
| jaasConfigurationName String SQLJDBCDriver |
(6.2+ 版) 每個 SQL Server 連線都可以有自己的 JAAS 登入設定名稱，以便建立 Kerberos 連線。 設定項目的名稱可透過此屬性傳遞。 此屬性適用於建立 Kerberos 設定檔時使用。 根據預設，驅動程式會尋找名稱 SQLJDBCDriver。如果找不到外部組態，則驅動程式會設定針對 IBM JVM 的 useDefaultCcache = true 和針對其他 JVM的 useTicketCache = true。 |
| keyStoreAuthentication String null |
(6.0+ 版) 此屬性會識別 Always Encrypted 要使用哪一個金鑰存放區，並決定驗證金鑰存放區所要使用的驗證機制。 當您使用 "keyStoreAuthentication=JavaKeyStorePassword"，驅動程式可支援順暢地設定 Java 金鑰存放區。 若要使用此屬性，您也必須設定 Java 金鑰存放區的 keyStoreLocation 與 keyStoreSecret 屬性。 如需 Always Encrypted 的詳細資訊，請參閱搭配 JDBC 驅動程式使用 Always Encrypted。 從 Microsoft JDBC 驅動程式 8.4 開始，您可以設定 "keyStoreAuthentication=KeyVaultManagedIdentity" 或 "keyStoreAuthentication=KeyVaultClientSecret"，以使用受控識別來驗證 Azure Key Vault。 如需 Always Encrypted 的詳細資訊，請參閱搭配 JDBC 驅動程式使用 Always Encrypted。 |
| keyStoreLocation String null |
(6.0+ 版) keyStoreAuthentication=JavaKeyStorePassword 時，keyStoreLocation 屬性會識別 Java 金鑰儲存區檔案的路徑，要與 Always Encrypted 資料搭配使用的資料行主要金鑰會儲存於該檔案中。 路徑必須包含金鑰儲存區檔案名稱。 如需 Always Encrypted 的詳細資訊，請參閱搭配 JDBC 驅動程式使用 Always Encrypted。 |
| keyStorePrincipalId String null |
(8.4+ 版) keyStoreAuthentication=KeyVaultManagedIdentity 時，keyStorePrincipalId 屬性會指定有效的 Microsoft Entra 應用程式用戶端識別碼。 如需 Always Encrypted 的詳細資訊，請參閱搭配 JDBC 驅動程式使用 Always Encrypted。 |
| keyStoreSecret String null |
(6.0+ 版) keyStoreAuthentication=JavaKeyStorePassword 時，keyStoreSecret 屬性會識別金鑰儲存區和金鑰所要使用的密碼。 如果使用 Java Key Store，則金鑰儲存區和金鑰的密碼必須相同。 如需 Always Encrypted 的詳細資訊，請參閱搭配 JDBC 驅動程式使用 Always Encrypted。 |
| lastUpdateCount boolean ["true" | "false"] true |
"true" 值只會傳回 SQL 陳述式傳遞至伺服器的最新更新計數。 而且，它只會用於單一 SELECT、INSERT 或 DELETE 陳述式，忽略伺服器觸發程式可能造成的其他更新計數。 將此屬性設為 "false" 的話，則會傳回所有更新計數，包括伺服器觸發程序所傳回的更新計數。 注意：只有搭配 executeUpdate 方法使用時，此屬性才能適用。 所有其他 execute 方法都會傳回所有結果並更新計數。 這個屬性只會影響伺服器觸發程序所傳回的更新計數。 這不會影響結果集或觸發程序執行期間產生的錯誤。 |
| lockTimeout int -1 |
等候資料庫報告鎖定逾時的毫秒數。預設的行為是無限期等待。 如果使用者尚未指定此屬性的值，則在連線時，此值會成為所有陳述式的預設值。 另外，Statement.setQueryTimeout() 可用於設定特定陳述式的查詢逾時。 此值可以為 0，表示不等待。 |
| loginTimeout int [0..65535] 30 (11.2 版及更新版本) 15 （10.2 版和更低版本） |
驅動程式應等待失敗連接逾時的秒數。 值為零表示此逾時為預設系統逾時。 此值為 30 秒（版本 11.2 和更高版本的預設值）或 15 秒（10.2 版和更低版本的預設值）。 非零值為驅動程式應等待失敗連接之逾時的秒數。 如果您在 Server 連線屬性中指定虛擬網路名稱，您應該指定三分鐘或更長的逾時值，好讓容錯移轉連線有充足的時間可以順利完成。 如需災害復原的詳細資訊，請參閱 JDBC 驅動程式對高可用性和災害復原的支援。 |
| maxResultBuffer String null |
(9.2+ 版) maxResultBuffer 可用於設定讀取結果集時要讀取的最大位元組。 如果未指定，系統會讀取整個結果集。 您可採取兩種樣式來指定大小： 1. 位元組大小 (例如 100、150M、300K、400G)2. 堆積記憶體上限的百分比 (例如 10p、15pct、20percent)。 |
| msiClientId String null |
(取代) (7.2+ 版) 用於取得 accessToken 以建立與 ActiveDirectoryManagedIdentity 或 ActiveDirectoryMSI 驗證模式連線的受控識別 (MSI) 用戶端識別碼。 |
| multiSubnetFailover Boolean false |
一律指定 multiSubnetFailover=true，以連線到 SQL Server 可用性群組的可用性群組接聽程式或 SQL Server 容錯移轉叢集執行個體。 multiSubnetFailover=true 會設定驅動程式，以針對 (目前) 使用中的伺服器提供更快速的偵測與連線。 可能的值為 true 和 false。 如需災害復原的詳細資訊，請參閱 JDBC 驅動程式對高可用性和災害復原的支援。 您可以透過程式設計方式，使用 getPropertyInfo、getMultiSubnetFailover 及 setMultiSubnetFailover 存取 multiSubnetFailover 連線屬性。 注意：從 Microsoft JDBC Driver 6.0 for SQL Server 開始，連線到可用性群組接聽程式時，不再需要將 multiSubnetFailover 設定為 "true"。 預設會啟用新屬性 (transparentNetworkIPResolution)，可提供 (目前) 作用中伺服器的偵測和連線。 |
| packetSize int [-1 | 0 | 512..32767] 8000 |
用來與伺服器通訊的網路封包大小 (以位元組為單位)。 如果值為 -1，表示使用伺服器的預設封包大小。 如果值為 0，表示使用最大值，也就是 32767。 如果將此屬性設定為可接受範圍以外的值，則會發生例外狀況。 重要事項：啟用加密 (encrypt=true) 時，不建議使用 packetSize 屬性。 否則，驅動程式可能會引發連接錯誤。 如需此屬性的詳細資訊，請參閱 SQLServerDataSource 類別的 setPacketSize 方法。 |
| 密碼 String [<=128 char] null |
資料庫密碼 (如果連線使用 SQL 使用者和密碼)。 如果使用主體名稱和密碼來建立 Kerberos 連線，此屬性會設定為 Kerberos 主體密碼。 (10.2+ 版) authentication=ActiveDirectoryServicePrincipal 時，password 屬性會識別 Active Directory 主體所要使用的密碼。 |
| portNumber, 連接埠 int [0..65535] 1433 |
伺服器正在接聽的連接埠。 如果已在連接字串中指定連接埠號碼，就不需要對 SQLbrowser 進行要求。 同時指定 port 和 instanceName 時，會連接至指定的通訊埠。 然而，系統會驗證 instanceName，如果這與連接埠不符，系統就會擲回錯誤。 重要事項：建議您務必要指定連接埠號碼，因為這比使用 SQLbrowser 更安全。 |
| prepareMethod String prepexec |
(11.2.0+ 版) 指定驅動程式要搭配已備妥陳述式一起使用的基礎準備方法。 設定為 prepare 即可使用 sp_prepare 作為準備方法。 將 prepareMethod 設定為會促成個別、初始的資料庫行程，以完成陳述式準備，不需要資料庫在執行計畫中考慮任何初始值。 設定為 prepexec 即可使用 sp_prepexec 作為準備方法。 這個方法結合準備動作和第一次執行，以減少來回行程。 這也能為資料庫提供其在執行計畫中可能考慮的初始參數值。 |
| queryTimeout int -1 |
查詢發生逾時前要等候的秒數。 預設值為 -1，表示無限期逾時。 將此值設定為 0 也表示無限期地等候。 |
| realm String null |
(9.4+ 版) Kerberos 驗證的領域。 將此值設定為覆寫驅動程式自動偵測自伺服器領域的 Kerberos 驗證領域。 |
| 複寫 boolean ["true" | "false"] false |
(9.4+ 版) 此設定會告知伺服器是否使用連線來執行複寫作業。 啟用時，連線上不會觸發具有 NOT FOR REPLICATION 選項的觸發程序。 |
| responseBuffering String ["full" | "adaptive"] adaptive |
如果此屬性設定為 "adaptive"，就會在必要時緩衝處理可能的資料下限。 預設模式為 "adaptive"。 如果此屬性設定為 "full"，執行陳述式時，系統會從伺服器讀取整個結果集。 注意：JDBC 驅動程式 1.2 版之後，預設的緩衝行為會是 "adaptive"。如果您要在應用程式中保留 1.2 版的預設行為，則必須在連線屬性中將 responseBufferring 屬性設定為 "full"，或使用 SQLServerStatement 物件的 setResponseBuffering 方法。 |
| selectMethod String ["direct" | "cursor"] 直接 |
如果將此屬性設定為 "cursor"，便會為在 TYPE_FORWARD_ONLY 及 CONCUR_READ_ONLY 資料指標之連線上建立的每個查詢，建立資料庫資料指標。 通常只有當應用程式所產生的結果集過大，用戶端記憶體無法完全容納時，才需要使用此屬性。 此屬性設定為 "cursor" 時，用戶端記憶體中只會保留有限數量的結果集資料列。 預設的行為是將所有結果集資料列保留於用戶端記憶體。 當應用程式處理所有資料列時，此行為提供最快的效能。 |
| sendStringParameters... AsUnicode boolean ["true" | "false"] true |
如果 sendStringParametersAsUnicode 屬性設定為 "true"，String 參數就會以 Unicode 格式傳送至伺服器。 如果 sendStringParametersAsUnicode 屬性設定為 "false"，String 參數就會以非 Unicode 格式 (例如 ASCII/MBCS) 而非 Unicode 傳送至伺服器。 sendStringParametersAsUnicode 屬性的預設值為 "true"。 注意：只有在傳送具有 CHAR、VARCHAR 或 LONGVARCHAR 等 JDBC 類型的參數值時，才會檢查 sendStringParametersAsUnicode 屬性。 新的 JDBC 4.0 國際字元方法包括 SQLServerPreparedStatement 和 SQLServerCallableStatement 類別的 setNString、setNCharacterStream 及 setNClob 方法。 不論此屬性的設定為何，這些方法一律會將參數值以 Unicode 格式傳送至伺服器。 若要讓 CHAR、VARCHAR 和 LONGVARCHAR JDBC 資料類型達到最佳效能，應用程式應該將 sendStringParametersAsUnicode 屬性設定為 "false"，並且使用 SQLServerPreparedStatement 和 SQLServerCallableStatement 類別的 setString、setCharacterStream 及 setClob 非國家字元方法。 應用程式將 sendStringParametersAsUnicode 屬性設定為 "false"，並使用非國家字元方法來存取伺服器端的 Unicode 資料類型 (例如 nchar、nvarchar 和 ntext) 時，如果資料庫定序不支援非國家字元方法所傳遞之 String 參數中的字元，某些資料可能就會遺失。 應用程式應針對 NCHAR、NVARCHAR 和 LONGNVARCHAR 等 JDBC 資料類型，使用 SQLServerPreparedStatement 和 SQLServerCallableStatement 類別的 setNString、setNCharacterStream 和 setNClob 國際字元方法。 變更此值可能會影響資料庫的結果排序。 排序差異是因為 Unicode 與非 Unicode 字元的排序規則不同。 |
| sendTemporalDataTypes... AsStringForBulkCopy boolean ["true" | "false"] true |
(8.4+ 版) 這個連線屬性設定為 "false" 時，會傳送 DATE、DATETIME、DATIMETIME2、DATETIMEOFFSET、SMALLDATETIME 和 TIME 等資料類型作為其各自的類型，而不是以字串的形式傳送。 這個連線屬性設定為 "false" 時，驅動程式接受每個時態性資料類型的預設字串常值格式，例如： DATE： YYYY-MM-DDDATETIME： YYYY-MM-DD hh:mm:ss[.nnn]DATETIME2： YYYY-MM-DD hh:mm:ss[.nnnnnnn]DATETIMEOFFSET： YYYY-MM-DD hh:mm:ss[.nnnnnnn] [{+/-}hh:mm]SMALLDATETIME： YYYY-MM-DD hh:mm:ssTIME： hh:mm:ss[.nnnnnnn] |
| sendTimeAsDatetime boolean ["true" | "false"] true |
這個屬性是在 SQL Server JDBC Driver 3.0 中新增。 設定為 "true" 時，系統會將 java.sql.Time 值當作 SQL Server datetime 值傳送至伺服器。 設定為 "false" 時，系統會將 java.sql.Time 值當作 SQL Server time 值傳送至伺服器。 這個屬性的預設值目前為 "true"，但後續版本可能會有所變更。 如需 Microsoft JDBC Driver for SQL Server 如何設定 java.sql.Time 值並傳送至伺服器的詳細資訊，請參閱設定 java.sql.Time 值如何傳送給伺服器。 |
| serverCertificate, 伺服器 String null |
(11.2.0+ 版) 伺服器憑證檔案的路徑。 encrypt 設定為 strict 時，驗證作業就會使用這個屬性。 驅動程式支援使用 PEM 檔案格式的憑證檔案。 |
| serverName, 伺服器 String null |
執行 SQL Server 或 Azure SQL 資料庫的電腦。 您也可以指定可用性群組的虛擬網路名稱。 如需災害復原的詳細資訊，請參閱 JDBC 驅動程式對高可用性和災害復原的支援。 |
| serverNameAsACE boolean ["true" | "false"] false |
(6.0+ 版) 設定為 "true" 表示驅動程式應將連線中的 Unicode 伺服器名稱轉譯成 ASCII 相容的編碼 (Punycode)。 如果此設定為 "false"，驅動程式會使用所提供的伺服器名稱來連線。 如需國際功能的詳細資訊，請參閱 JDBC 驅動程式的國際功能。 |
| serverPreparedStatement... DiscardThreshold 整數 10 |
(6.2+ 版) 此屬性可控制在執行呼叫以清理伺服器上未完成的控制代碼之前，每個連線可以有多少未完成的已備妥陳述式捨棄動作 (sp_unprepare)。 如果此屬性設定為 <= 1，備妥的陳述式一結束就會立即執行未準備動作。 如果將此屬性設定為 > 1，則會將這些呼叫一併進行批次處理，以避免太常呼叫 sp_unprepare 所造成的額外負荷。 |
| serverSpn String null |
(4.2+ 版) 這個選用型的屬性可以指定 Java Kerberos 連線的服務主體名稱 (SPN)， 不過需與 authenticationScheme 搭配使用。 若要指定 SPN，您可以使用 "MSSQLSvc/fqdn:port@REALM"，其中 fqdn 是完整網域名稱，port 是連接埠號碼，REALM 是 SQL Server 的 Kerberos 領域，需以大寫字母表示。 注意：如果該用戶端的預設領域 (如 Kerberos 設定中所指定) 與 SQL Server 的 Kerberos 領域相同，則 @REALM 是選擇性項目。 如需搭配 Java Kerberos 使用 serverSpn 的詳細資訊，請參閱使用 Kerberos 整合式驗證連線到 SQL Server。 |
| socketFactoryClass String null |
(8.4+ 版) 指定自訂通訊端處理站的類別名稱，以取代預設的通訊端處理站。 |
| socketTimeout int 0 |
在通訊端讀取或接受時發生逾時之前要等候的毫秒數。 預設值為 0，表示無限期逾時。 |
| statementPooling... CacheSize int 0 |
(6.4+ 版) 此屬性可啟用驅動程式中已備妥的陳述式控制代碼快取。 此屬性定義陳述式共用的快取大小。 此屬性只能搭配 disableStatementPooling 連線屬性 (應該設定為 "false") 使用。 將 disableStatementPooling 設定為 "true" 或將 statementPoolingCacheSize 設定為 0 時，會停用備妥陳述式控制代碼快取。 |
| sslProtocol String TLS |
(6.4+ 版) 此屬性可指定安全連線期間所要考慮使用的 TLS 通訊協定。 可能的值包括：TLS、TLSv1、TLSv1.1 和 TLSv1.2。 如需安全通訊端層通訊協定的詳細資訊，請參閱 SSLProtocol。 |
| transparentNetwork... IPResolution boolean ["true" | "false"] true |
(6.0+ 版) 此屬性可針對 (目前) 運作中的伺服器提供更快速的偵測和連線。 可能的值為 "true" 和 "false"，其中 "true" 為預設值。 在 Microsoft JDBC Driver 6.0 for SQL Server 之前，應用程式必須將連接字串設定為包含 "multiSubnetFailover=true"，以指出其連線對象為 Always On 可用性群組。 若未將 multiSubnetFailover 連線關鍵字設定為 "true"，應用程式在連線到 Always On 可用性群組時，可能會發生逾時問題。 使用 6.0 以上版本時，應用程式不再需要將 multiSubnetFailover 設定為 "true"。 注意： 當 transparentNetworkIPResolution=true 時，第一次連線嘗試會使用 500 毫秒作為逾時。 之後的任何嘗試都會使用 multiSubnetFailover 屬性所採用的逾時邏輯。 |
| trustManagerClass String null |
(6.4+ 版) 自訂 javax.net.ssl.TrustManager 實作的完整類別名稱。 |
| trustManager... ConstructorArg String null |
(6.4+ 版) 要傳遞到 TrustManager 建構函式的選用型引數。 如果已指定 trustManagerClass 屬性並要求採用加密連線，系統會使用自訂 TrustManager，而不是預設的系統 JVM 金鑰儲存區型 TrustManager。 |
| trustServerCertificate boolean ["true" | "false"] false |
設為 "true" 可指定驅動程式不驗證伺服器 TLS/SSL 憑證。 若為 "true"，通訊層使用 TLS 加密時，系統會自動信任伺服器 TLS/SSL 憑證。 若為 "false"，驅動程式會驗證伺服器 TLS/SSL 憑證。 如果伺服器憑證驗證失敗，驅動程式會引發錯誤並中斷連線。 預設值為 "false"。 請確定傳遞給 serverName 的值完全符合伺服器憑證中主體別名內一般名稱 (CN) 或 DNS 名稱，以順利執行 TLS/SSL 連線。 如需加密支援的詳細資訊，請參閱了解加密支援。 注意： 此屬性會搭配 encrypt/authentication 屬性一起使用。 只有當連線使用 TLS 加密，此屬性才會影響伺服器 TLS/SSL 憑證驗證。 |
| trustStore String null |
trustStore 憑證檔案的路徑 (包括檔案名稱)。 trustStore 檔案包含用戶端所信任之憑證的清單。 未指定此屬性或將其設定為 null 時，驅動程式會依賴信任管理員 Factory 的查閱規則，決定要使用的憑證存放區。 預設的 SunX509 TrustManagerFactory 會嘗試以下列的搜尋順序，找出信任的資料： 由 "javax.net.ssl.trustStore" JVM 系統屬性所指定的檔案。 <java-home>/lib/security/jssecacerts 檔案。<java-home>/lib/security/cacerts 檔案。如需 SUNX509 TrustManager 介面的詳細資訊，請參閱 Sun Microsystems 網站提供的 SUNX509 TrustManager 介面文件。 注意：只有當連線使用 TLS 加密，且 trustServerCertificate 屬性設定為 "false" 時，此屬性才會影響憑證 trustStore 查閱。 |
| trustStorePassword String null |
用於檢查 trustStore 資料完整性的密碼。 如果已設定 trustStore 屬性，但未設定 trustStorePassword 屬性，系統不會檢查 trustStore 的完整性。 當 trustStore 和 trustStorePassword 屬性都未指定時，驅動程式會使用 JVM 系統屬性 "javax.net.ssl.trustStore" 和 "javax.net.ssl.trustStorePassword"。 如果未指定 "javax.net.ssl.trustStorePassword" 系統屬性，系統不會檢查 trustStore 的完整性。 如果使用者未設定 trustStore 屬性，但設定了 trustStorePassword 屬性，JDBC 驅動程式會使用 "javax.net.ssl.trustStore" 指定為信任存放區的檔案。 此外，驅動程式會使用指定的 trustStorePassword 來檢查信任存放區的完整性。 如果用戶端應用程式不想在 JVM 系統屬性中儲存密碼，您可能就需要使用這項設定。 注意：只有當連線是使用 TLS 連線，且 trustServerCertificate 屬性設定為 "false" 時，trustStorePassword 屬性才會影響憑證 trustStore 查閱。 |
| trustStoreType String JKS |
設定此屬性來指定要用於 FIPS 模式信任存放區類型。 可能的值為 PKCS12 或由 FIPS 提供者所定義的類型。 |
| useBulkCopyFor... BatchInsert boolean ["true" | "false"] false |
(9.2+ 版) 使用 java.sql.PreparedStatement 執行批次插入作業時，您可啟用此連線屬性，以透明的方式使用大量複製 API。 此功能可能會提供比啟用期間更高的效能。 此功能預設為停用。 將此屬性設定為 "true" 即可啟用此功能。 重要注意事項：此功能僅支援完全參數化的 INSERT 查詢。 如果 INSERT 查詢是由其他 SQL 查詢結合，或包含值型式的資料，則執行會回復為基本批次插入作業。 如需使用此屬性的詳細資訊，請參閱使用大量複製 API 執行批次插入作業。 |
| useDefaultGSSCredential boolean ["true" | "false"] false |
(版本 12.6+) 旗標，指出驅動程式是否應該代表使用者使用原生 GSS-API 進行 Kerberos 驗證來建立 GSSCredential。 |
| useDefaultJaasConfig boolean ["true" | "false"] false |
(版本 12.6+) 當應用程式與在系統層級設定 JAAS 的程式庫並存時，將此屬性設定為 true 可讓驅動程式使用相同的組態來執行 Kerberos 驗證。 |
| useFmtOnly boolean ["true" | "false"] false |
(7.4+ 版) 提供從伺服器查詢參數中繼資料的替代方式。 將此屬性設定為 "true"，以指定驅動程式在查詢參數中繼資料時，應該使用 SET FMTONLY 邏輯。 此功能預設為關閉，加上 SET FMTONLY 已標記為淘汰，因此不建議您使用此屬性。 提供使用 useFmtOnly 只是作為 sp_describe_undeclared_parameters \(部分機器翻譯\) 中已知問題和限制的因應措施。此功能目前只支援單一 SELECT/INSERT/UPDATE/DELETE 查詢。 嘗試搭配不支援的查詢/多個查詢使用此功能，會導致驅動程式嘗試剖析查詢內容，但很可能會導致產生例外狀況。如需此屬性的詳細資訊，請參閱透過 useFmtOnly 擷取 ParameterMetaData。 |
| userName, user String [<=128 char] null |
資料庫使用者 (如果連線使用 SQL 使用者和密碼)。 針對使用主體名稱和密碼的 Kerberos 連線，此屬性是設定為 Kerberos 主體名稱。 (10.2+ 版) authentication=ActiveDirectoryServicePrincipal 時，userName 屬性會指定有效的 Azure Active Directory 安全用戶端識別碼。 |
| workstationID String [<=128 char] <empty string> |
工作站識別碼。 用以識別各種分析和記錄工具中的特定工作站。 如果未指定，系統會使用 <empty string>。 |
| xopenStates boolean ["true" | "false"] false |
設定為 "true"，以指定驅動程式傳回例外狀況的 XOPEN 相容狀態碼。 預設為傳回 SQL 99 狀態碼。 |
注意
Microsoft JDBC Driver for SQL Server 會針對連線屬性採用伺服器預設值，不過 ANSI_DEFAULTS and IMPLICIT_TRANSACTIONS 除外。 Microsoft JDBC Driver for SQL Server 會自動將 ANSI_DEFAULTS 設定為 ON，並將 IMPLICIT_TRANSACTIONS 設定為 OFF。
重要
如果驗證設定為 ActiveDirectoryPassword，Classpath 中必須包含下列程式庫：microsoft-authentication-library-for-java。 您可以在 Maven 存放庫 \(英文\) 找到該程式庫。 下載程式庫及其相依性最簡單的方式是使用 Maven：
- 在您的系統上安裝 Maven
- 移至驅動程式的 GitHub 頁面 \(英文\)
- 下載 pom.xml 檔案
- 執行下列 Maven 命令，以下載程式庫和其相依性：
mvn dependency:copy-dependencies