设置连接属性

项目
01/31/2024

下载 JDBC 驱动程序

可以通过多种方式指定连接字符串的属性：

当使用 DriverManager 类进行连接时，在连接 URL 中通过“名称=值”属性进行指定。有关连接字符串的语法，请参阅生成连接 URL。
在 DriverManager 类的 Connect 方法中，作为 Properties 参数中的 name=value 属性。
在驱动程序数据源的适当的 setter 方法中指定值。例如：
```
datasource.setServerName(value)
datasource.setDatabaseName(value)
```

备注

属性名不区分大小写，重复的属性名将按以下顺序进行解析：

API 参数（如用户和密码）
属性集合
连接字符串中的最后一个实例

属性名允许使用未知值，JDBC 驱动程序不会对这些值进行大小写验证。

允许使用同义词，并按顺序进行解析，如同处理重复的属性名。

属性

下表列出了 JDBC 驱动程序当前可用的所有连接字符串属性。

properties 类型默认	说明
accessToken 字符串 Null	（版本 6.0+）借助此属性，可以使用访问令牌连接到数据库。无法使用连接 URL 设置 accessToken。
accessTokenCallbackClass 字符串 Null	（版本 12.4+）要与访问令牌回拨一起使用的回拨实现类名称。
applicationIntent 字符串 ReadWrite	（版本 6.0+）声明应用程序工作负载类型来连接到服务器。可能的值为 ReadOnly 和 ReadWrite 。有关灾难恢复的详细信息，请参阅 JDBC 驱动程序对高可用性和灾难恢复的支持。
applicationName 字符串 [<=128 char] Null	应用程序名称或者“Microsoft JDBC Driver for SQL Server”（如果未提供名称）。用于在各种 SQL Server 分析和日志记录工具中标识特定的应用程序。
身份验证字符串 NotSpecified	（版本 6.0+）此可选属性指示用于连接的身份验证方法。可取值为 ActiveDirectoryIntegrated、ActiveDirectoryPassword、ActiveDirectoryManagedIdentity（版本 12.2+）、ActiveDirectoryMSI（版本 7.2+）、ActiveDirectoryInteractive（版本 9.2+）、ActiveDirectoryServicePrincipal（版本 9.2+）、SqlPassword 和 NotSpecified（默认值）。借助 ActiveDirectoryIntegrated（版本 6.0+），可以使用集成 Windows 身份验证连接到 SQL。借助 ActiveDirectoryPassword（版本 6.0+），可使用 Microsoft Entra 主体名称和密码连接到 SQL。借助 ActiveDirectoryManagedIdentity（版本 12.2+）或 ActiveDirectoryMSI（版本 7.2+），可从 Azure 资源内部连接到 SQL。例如，使用托管标识身份验证的 Azure 虚拟机、应用服务或函数应用。使用 ActiveDirectoryManagedIdentity 或 ActiveDirectoryMSI 身份验证模式时，驱动程序支持以下两种类型的托管标识： 1.系统分配的托管标识：默认用于获取 accessToken。 2.用户分配的托管标识：用于获取 accessToken，前提是托管标识的客户端 ID 与 msiClientId 连接属性一起指定。借助 ActiveDirectoryInteractive，可以使用交互式身份验证流连接到数据库。借助 ActiveDirectoryServicePrincipal（版本 9.2+），可以使用服务主体标识的客户端 ID 和机密连接到数据库。在 userName 属性中指定客户端 ID，在 password 属性中指定机密 (10.2+)。借助 SqlPassword，可以使用 userName/user 和 password 属性连接到 SQL。如果不需要这些身份验证方法，请使用 NotSpecified 。重要提示：如果将身份验证设置为 ActiveDirectoryIntegrated，则必须安装下面两个库：mssql-jdbc_auth-<version>-<arch>.dll（在 JDBC 驱动程序包中提供）和使用 SQL Server 的 Microsoft 身份验证库 (ADAL.DLL)。可以从 Microsoft ODBC Driver for SQL Server 或 Microsoft OLE DB Driver for SQL Server 安装 Microsoft 身份验证库。 JDBC 驱动程序仅支持 ADAL.Dll 版本 1.0.2028.318 及更高版本。注意：如果身份验证属性设置为除“NotSpecified”以外的任何值，驱动程序默认使用传输层安全性 (TLS)（以前称为安全套接字层 (SSL)）加密。有关如何配置 Microsoft Entra 身份验证的信息，请参阅使用 Microsoft Entra 身份验证。
authenticationScheme 字符串 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 凭据。否则，就会出错（必须指定连接属性）。
calcBigDecimalPrecision boolean ["true" \| "false"] false	（版本 12.6+）此标志指示驱动程序是否应计算 BigDecimal 的输入精度，而不是使用最大允许精度值 (38)。
cancelQueryTimeout int -1	（版本 6.4+）此属性可用于取消对连接设置的 queryTimeout。如果静默删除服务器的 TCP 连接，查询执行就会挂起，但不会引发异常。只有在连接上也设置了“queryTimeout”时，此属性才适用。驱动程序等待 cancelQueryTimeout + queryTimeout 总秒数，以断开连接并关闭通道。此属性的默认值为 -1，行为是无限期等待。
clientCertificate 字符串 Null	（版本 8.4+）指定用于客户端身份验证的证书的位置。 JDBC 驱动程序支持 PFX、PEM、DER 和 CER 文件扩展名。有关详细信息，请参阅环回方案的客户端证书身份验证。
clientKey 字符串 Null	（版本 8.4+）指定由 clientCertificate 属性指定的 PEM、DER 或 CER 证书的私钥的位置。有关详细信息，请参阅环回方案的客户端证书身份验证。
clientKeyPassword 字符串 Null	（版本 8.4+）已指定用于访问 clientKey 文件私钥的可选密码字符串。有关详细信息，请参阅环回方案的客户端证书身份验证。
columnEncryptionSetting 字符串 ["Enabled" \| "Disabled"] 已禁用	（版本 6.0+）设置为“已启用”，以使用 Always Encrypted (AE) 功能。启用 AE 后，JDBC 驱动程序以透明方式加密和解密存储在服务器中的加密数据库中的敏感数据。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。注意：SQL Server 2016 或更高版本和 Azure SQL 数据库随附 Always Encrypted。
connectRetryCount int [0..255] 1	（版本 9.4+）发生连接失败时的重新连接尝试次数。
connectRetryInterval int [1..60] 10	（版本 9.4+）每次连接重试尝试之间的秒数。
databaseName, database 字符串 [<=128 char] Null	要连接到的数据库名称。如果未声明，则连接到默认的数据库。
datetimeParameterType 字符串 ["datetime" \| "datetime2" \| "datetimeoffset"] datetime2	（版本 12.2+）用于 Java 日期/时间戳参数的 SQL 数据类型。连接到 SQL Server 2016 或更高版本并与旧的“datetime”值交互时，客户端可通过将属性设置为“datetime”来获益，因为此设置可缓解服务器端“datetime”和“datetime2”值之间的转换问题。有关详细信息，请参阅解决从 2016 SQL Server 开始 datetime 到 datetime2 的转换行为变更的问题
delayLoadingLobs boolean ["true" \| "false"] true	指示是否流式处理从 ResultSet 检索的所有 LOB 对象的标志。通过将该属性设置为“false”，无需流式处理即可将整个 LOB 对象加载到内存。
domainName, 域字符串 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 字符串 Null	（版本 8.2+）此可选属性指示要用于具有安全 Enclave 的 Always Encrypted 的证明服务终结点 URL。有关具有安全 Enclave 的 Always Encrypted 的详细信息，请参阅具有安全 Enclave 的 Always Encrypted。
enclaveAttestationProtocol 字符串 Null	（版本 8.2+）此可选属性指示要用于具有安全 Enclave 的 Always Encrypted 的证明协议。目前，此字段只支持以下值：HGS、AAS 和 NONE（NONE 仅在 11.2 及更高版本中受支持）。有关具有安全 Enclave 的 Always Encrypted 的详细信息，请参阅具有安全 Enclave 的 Always Encrypted。
encrypt 字符串 Null	设置为“true”时指示在服务器已安装有证书的情况下，SQL Server 对在客户端与服务器之间发送的所有数据使用 TLS 加密。在版本 10.2 及更高版本中，默认值为“true”；在版本 9.4 及更低版本中，则为“false”。在版本 6.0 及更高版本中，有一个新的连接设置“身份验证”默认使用 TLS 加密。有关此属性的详细信息，请参阅“authentication”属性。在 11.2.0 及更高版本中，“加密”已从“布尔”更改为“字符串”，这使得在属性设置为“严格”时支持 TDS 8.0。
failoverPartner 字符串 Null	在数据库镜像配置中使用的故障转移服务器名称。在到主体服务器的初始连接失败时，使用此属性。建立初始连接后，会忽略此属性。必须与 databaseName 属性一起使用。注意：驱动程序不支持在连接字符串的 failoverPartner 属性中使用故障转移伙伴实例的服务器实例端口号。但是，支持在同一连接字符串中指定主体服务器实例的 serverName、instanceName 和 portNumber 属性以及故障转移伙伴实例的 failoverPartner 属性。如果在 Server 连接属性中指定虚拟网络名称，则无法使用数据库镜像。有关灾难恢复的详细信息，请参阅 JDBC 驱动程序对高可用性和灾难恢复的支持
`fips` boolean ["true" \| "false"] “false”	对于启用了 FIPS 的 Java 虚拟机 (JVM)，此属性应为 true。
fipsProvider 字符串 Null	JVM 中配置的 FIPS 提供程序。例如，BCFIPS 或 SunPKCS11-NSS。在版本 6.4.0 中删除。有关详细信息，请参阅 GitHub 问题 460。
gsscredential org.ietf.jgss.GSSCredential Null	（版本 6.2+）用于 Kerberos 约束委派的用户凭据可以在此属性中传递。此设置应与设为 true 的 integratedSecurity 和设为 authenticationScheme 的 JavaKerberos 结合使用。
hostNameInCertificate 字符串 Null	验证 SQL Server TLS/SSL 证书要使用的主机名。如果未指定 hostNameInCertificate 属性或此属性设置为 null，则 Microsoft JDBC Driver for SQL Server 使用连接 URL 上的 serverName 属性值作为主机名来验证 SQL Server TLS/SSL 证书。注意：此属性与 encrypt/authentication 属性和 trustServerCertificate 属性结合使用。如果连接使用 TLS 加密并且 trustServerCertificate 设置为“false”，则此属性会影响证书验证。确保传递给 hostNameInCertificate 的值与服务器证书中使用者可选名称 (SAN) 中的公用名称 (CN) 或 DNS 名称相匹配，以便成功建立 TLS 连接。有关加密支持的详细信息，请参阅了解加密支持。
INSTANCENAME 字符串 [<=128 char] Null	要连接到的数据库实例。如果未指定，则连接到默认实例。对于 instanceName 和端口均已指定的情况，请参阅有关端口的备注。如果在 Server 连接属性中指定虚拟网络名称，则无法使用 instanceName 连接属性。有关灾难恢复的详细信息，请参阅 JDBC 驱动程序对高可用性和灾难恢复的支持。
integratedSecurity boolean ["true"\|"false"] false	设置为“true”可以指明 SQL Server 在 Windows 操作系统上使用 Windows 凭据。如果设置为“true”，JDBC 驱动程序在本地计算机凭据缓存中搜索在用户登录计算机或网络时提供的凭据。设置为“true”（且 authenticationscheme=JavaKerberos）可以指明 SQL Server 使用 Kerberos 凭据。若要详细了解 Kerberos 身份验证，请参阅使用 Kerberos 集成身份验证连接到 SQL Server。设置为“true”（且 authenticationscheme=NTLM）可以指明 SQL Server 使用 NTLM 凭据。如果为“false”，则必须提供用户名和密码。
ipaddresspreference 字符串 [<=128 char] IPv4First	客户端应用程序使用的 IP 首选项。使用 IPV4First，驱动程序首先遍历 IPv4 地址。如果没有 IPv4 地址能够成功连接，驱动程序将继续尝试 IPv6 地址（如果有）。使用 IPV6First，驱动程序首先遍历 IPv6 地址。如果没有 IPv6 地址能够成功连接，驱动程序将继续尝试 IPv4 地址（如果有）。使用 UsePlatformDefault，驱动程序将按照 DNS 解析中的初始顺序遍历所有 IP 地址。
jaasConfigurationName 字符串 SQLJDBCDriver	（版本 6.2+）SQL Server 的每个连接都可以使用自己的 JAAS 登录配置名称来建立 Kerberos 连接。可通过此属性传递配置项的名称。这适用于创建 Kerberos 配置文件时使用。默认情况下，驱动程序查找名称 `SQLJDBCDriver`。如果未找到外部配置，驱动程序则为 IBM JVM 设置 `useDefaultCcache = true`，为其他 JVM 设置 `useTicketCache = true`。
keyStoreAuthentication 字符串 Null	（版本 6.0+）此属性确定了要用于 Always Encrypted 的密钥存储，并确定了用于验证密钥存储的身份验证机制。设置“keyStoreAuthentication=JavaKeyStorePassword”时，驱动程序支持无缝设置 Java 密钥存储。若要使用此属性，还必须为 Java 密钥存储设置 keyStoreLocation 和 keyStoreSecret 属性。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。从 Microsoft JDBC Driver 8.4 开始，你可以将“keyStoreAuthentication=KeyVaultManagedIdentity”或“keyStoreAuthentication=KeyVaultClientSecret”设置为使用托管标识向 Azure Key Vault 进行身份验证。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。
keyStoreLocation 字符串 Null	（版本 6.0+）如果 keyStoreAuthentication=JavaKeyStorePassword，keyStoreLocation 属性将标识 Java 密钥存储库文件的路径，此文件存储用于 Always Encrypted 数据的列主密钥。必须在密钥存储文件名中包含此路径。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。
keyStorePrincipalId 字符串 Null	（版本 8.4+）如果 keyStoreAuthentication=KeyVaultManagedIdentity，keyStorePrincipalId 属性将指定一个有效的 Microsoft Entra 应用程序客户端 ID。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。
keyStoreSecret 字符串 Null	（版本 6.0+）如果 keyStoreAuthentication=JavaKeyStorePassword，keyStoreSecret 属性将标识要用于密钥存储和密钥的密码。若要使用 Java 密钥存储，密钥存储和密钥密码必须相同。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。
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 及以下版本）	因连接失败而中止连接之前驱动程序应等待的秒数。零值表示超时为默认系统超时，在 11.2 及以上版本中默认为 30 秒，在 10.2 及以下版本中默认为 15 秒。非零值为因连接失败而中止连接之前驱动程序应等待的秒数。如果在 Server 连接属性中指定虚拟机名称，则应指定三分钟或更长的超时值，使故障转移连接有足够的时间连接成功。有关灾难恢复的详细信息，请参阅 JDBC 驱动程序对高可用性和灾难恢复的支持。
maxResultBuffer 字符串 Null	（版本 9.2+）maxResultBuffer 可用于设置在读取结果集时要读取的最大字节数。如果未指定，则读取整个结果集。可以采用以下两种样式指定大小： 1. 字节大小（例如 `100`、`150M`、`300K`、`400G`） 2. 以最大堆内存的百分比形式（例如，`10p`、`15pct`、`20percent`）。
msiClientId 字符串 Null	（已弃用）（版本 7.2+）托管标识 (MSI) 的客户端 ID，用于在使用 ActiveDirectoryManagedIdentity 或 ActiveDirectoryMSI 身份验证模式建立连接时获取 accessToken。
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 方法。
password 字符串 [<=128 char] Null	数据库密码（如果使用 SQL 用户和密码进行连接的话）。如果使用主体名称和密码进行 Kerberos 连接，此属性设置为 Kerberos 主体密码。（版本 10.2+）如果 authentication=ActiveDirectoryServicePrincipal，password 属性将标识要用于 Active Directory 主体的密码。
portNumber, port int [0..65535] 1433	服务器侦听的端口。如果在连接字符串中指定了端口号，则不会向 SQLbrowser 发出请求。如果端口和 instanceName 都已指定，则将建立到指定端口的连接。但是，将对 instanceName 进行验证，如果它与端口不符，将引发错误。重要提示：建议始终指定端口号，因为这比使用 SQLbrowser 更安全。
prepareMethod 字符串 prepexec	（11.2.0 及更高版本）指定驱动程序要使用的基础准备方法以及预定义的语句。设置为“prepare”以使用 `sp_prepare` 作为准备方法。这会导致对数据库进行单独的初始访问来准备没有任何初始值的语句，供数据库在执行计划中考虑。设置为“prepexec”以使用 `sp_prepexec` 作为准备方法。此方法将准备操作与第一次执行相结合，从而减少往返次数。它还为数据库提供初始参数值，数据库可在执行计划中考虑这些值。
queryTimeout int -1	查询发生超时之前要等待的秒数。默认值为 -1，表示无期限超时。将此值设置为 0 也表示无限期等待。
realm 字符串 Null	（版本 9.4+）Kerberos 身份验证的领域。设置此值将替代驱动程序从服务器的领域自动检测的 Kerberos 身份验证领域。
复制 boolean ["true" \| "false"] false	（版本 9.4+）此设置告知服务器此连接是否用于复制。启用后，带有 `NOT FOR REPLICATION` 选项的触发器不会在连接时触发。
responseBuffering 字符串 ["full" \| "adaptive"] 自适应	如果此属性设置为“adaptive”，将只在需要时才缓冲尽可能少的数据。默认模式为“adaptive”。如果此属性设置为“full”，则在执行语句时，将从服务器读取整个结果集。注意：在 JDBC 驱动程序版本 1.2 之后，默认缓冲行为将为“adaptive”。如果要在应用程序中保留版本 1.2 默认行为，则需在连接属性中将 responseBufferring 属性设置为“full”，或使用 SQLServerStatement 对象的 setResponseBuffering 方法。
selectMethod 字符串 ["direct" \| "cursor"] 直通	如果该属性设置为“cursor”，则对基于 TYPE_FORWARD_ONLY 和 CONCUR_READ_ONLY 游标的连接创建的每个查询，都会创建一个数据库游标。通常仅当应用程序生成较大的结果集，以至于客户端内存无法完全容纳时，才需要使用该属性。如果将该属性设置为“cursor”，则客户端内存中仅保留数目有限的结果集行。默认行为是在客户端内存中保留所有结果集行。在应用程序需要处理所有行时，此行为可提供最快性能。
sendStringParameters... AsUnicode boolean ["true" \| "false"] true	如果 sendStringParametersAsUnicode 属性设置为“true”，则字符串参数将以 Unicode 格式发送给服务器。如果 sendStringParametersAsUnicode 属性设置为“false”，则字符串参数将以非 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）时，如果数据库排序规则不支持非区域字符方法传递的字符串参数中的字符，则有些数据可能会丢失。对于 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 数据类型作为其各自的类型，而不是以 String 的形式发送它们。将此连接属性设置为“false”时，驱动程序接受每个时态数据类型的默认字符串文字格式，例如： DATE: `YYYY-MM-DD` DATETIME: `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:ss` TIME: `hh:mm:ss[.nnnnnnn]`
sendTimeAsDatetime boolean ["true" \| "false"] true	SQL Server JDBC Driver 3.0 中添加了此属性。设置为“true”可以将 java.sql.Time 值作为 SQL Server 日期/时间值发送到服务器。设置为“false”可以将 java.sql.Time 值作为 SQL Server 时间值发送到服务器。此属性的默认值暂为“true”，在今后发布的版本中可能会更改。若要详细了解 Microsoft JDBC Driver for SQL Server 在将 java.sql.Time 值发送到服务器前如何配置这些值，请参阅配置如何将 java.sql.Time 值发送到服务器。
serverCertificate, server 字符串 Null	（11.2.0 及更高版本）服务器证书文件的路径。用于在使用设置为“严格”的“加密”时进行验证。驱动程序支持 PEM 文件格式的证书文件。
serverName, server 字符串 Null	运行 SQL Server 或 Azure SQL 数据库的计算机。此外还可指定可用性组的虚拟网络名称。有关灾难恢复的详细信息，请参阅 JDBC 驱动程序对高可用性和灾难恢复的支持。
serverNameAsACE boolean ["true" \| "false"] false	（版本 6.0+）设置为“true”以指示驱动程序应将 Unicode 服务器名称转换为 ASCII 兼容编码 (Punycode) 以进行连接。如果此设置为 false，驱动程序将使用所提供的服务器名称进行连接。有关国际功能的详细信息，请参阅 JDBC 驱动程序的国际功能。
serverPreparedStatement... DiscardThreshold Integer 10	（版本 6.2+）此属性可用于控制在执行调用以清除服务器上未完成的句柄之前，每个连接可以有多少个未完成的准备的语句放弃操作 (`sp_unprepare`) 处于未完成状态。如果此属性设置为 `<= 1`，便会在准备的语句关闭时立即执行 unprepare 操作。如果设置为 `> 1`，则会对这些调用进行批处理，以避免过于频繁地调用 `sp_unprepare` 的开销。
serverSpn 字符串 Null	（版本 4.2+）此可选属性可用于指定 Java Kerberos 连接的服务主体名称 (SPN)。它与 authenticationScheme 配合使用。若要指定 SPN，它可以采用“MSSQLSvc/fqdn:port@REALM”的格式，其中 fqdn 是完全限定的域名，port 是端口号，REALM 是 SQL Server 的 Kerberos 领域的大写字母表示。注意：如果客户端的默认领域（在 Kerberos 配置中进行指定）与 SQL Server 的 Kerberos 领域相同，可选择使用 @REALM。若要详细了解如何将 serverSpn 与 Java Kerberos 结合使用，请参阅使用 Kerberos 集成身份验证连接到 SQL Server。
socketFactoryClass 字符串 Null	（版本 8.4+）指定要使用的自定义套接字工厂的类名，而不是默认套接字工厂。
socketTimeout int 0	在套接字读取或接受发生超时之前要等待的毫秒数。默认值为 0，表示无期限超时。
statementPooling... CacheSize int 0	（版本 6.4+）此属性可用于在驱动程序中启用准备的语句句柄缓存。此属性定义语句池的缓存大小。此属性只能与应设置为“false”的 disableStatementPooling 连接属性结合使用。将 disableStatementPooling 设置为“true”或将 statementPoolingCacheSize 设置为 0 会禁用准备的语句句柄缓存。
sslProtocol 字符串 TLS	（版本 6.4+）此属性可用于指定要在安全连接期间考虑的 TLS 协议。可能的值包括：TLS 、TLSv1 、TLSv1.1 和 TLSv1.2 。有关安全套接字层协议的详细信息，请参阅 SSLProtocol。
transparentNetwork... IPResolution boolean ["true" \| "false"] true	（版本 6.0+）此属性将为（当前）活动服务器提供更快的检测和连接。可取值为 true（默认值）和 false。在低于 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 字符串 Null	（版本 6.4+）自定义 `javax.net.ssl.TrustManager` 实现的完全限定的类名。
trustManager... ConstructorArg 字符串 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 的值与服务器证书中使用者可选名称 (SAN) 中的公用名称 (CN) 或 DNS 名称完全匹配，以便成功建立 TLS 连接。有关加密支持的详细信息，请参阅了解加密支持。注意：此属性与 encrypt /authentication 属性结合使用。当连接使用 TLS 加密时，此属性才会影响服务器 TLS/SSL 证书验证。
trustStore 字符串 Null	指向证书 trustStore 文件的路径（包括文件名）。 trustStore 文件包含客户端信任的证书的列表。如果未指定此属性或此属性设置为空，则驱动程序将依赖于信任关系管理器工厂的查找规则以确定要使用哪一个证书存储区。默认的 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 字符串 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 字符串 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+）此标志指示驱动程序是否应代表用户创建 GSSCredential，以便使用本机 GSS-API 进行 Kerberos 身份验证。
useDefaultJaasConfig boolean ["true" \| "false"] false	（版本 12.6+）当应用程序与在系统级别配置 JAAS 的库一起存在时，将此属性设置为 true，驱动程序即可使用相同的配置来执行 Kerberos 身份验证。
useFlexibleCallableStatements boolean ["true" \| "false"] true	（版本 12.6+）如果设置为 true，可使用索引或参数名称的任意组合设置语句参数。此外，还可按不同于 sproc 定义中的顺序设置这些参数。这两种情况都可以通过其他参数元数据查找实现。如果设置为 false，则必须使用索引或参数名称设置参数，但两者不能同时使用。此外，两者的设置顺序还必须与预准备语句定义中定义的顺序相同。将此选项设置为 false 不会触发上面提及的其他元数据查找。
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 字符串 [<=128 char] Null	数据库用户（如果使用 SQL 用户和密码进行连接的话）。如果使用主体名称和密码进行 Kerberos 连接，此属性设置为 Kerberos 主体名称。（版本 10.2+）如果 authentication=ActiveDirectoryServicePrincipal，userName 属性将指定有效的 Azure Active Directory 安全客户端 ID。
workstationID 字符串 [<=128 char] `<empty string>`	工作站 ID。用于在各种分析和记录工具中标识特定的工作站。如果未指定，将使用 `<empty string>`。
xopenStates boolean ["true" \| "false"] false	设置为“true”将指定驱动程序在异常时返回 XOPEN 兼容的状态代码。默认将返回 SQL 99 状态代码。

注意

Microsoft JDBC Driver for SQL Server 采用服务器的连接属性默认值，只有 ANSI_DEFAULTS 和 IMPLICIT_TRANSACTIONS 除外。 Microsoft JDBC Driver for SQL Server 将 ANSI_DEFAULTS 自动设置为 ON，将 IMPLICIT_TRANSACTIONS 自动设置为 OFF。

重要

如果 authentication 设置为 ActiveDirectoryPassword，必须在类路径中添加以下库：microsoft-authentication-library-for-java。可以在 Maven 存储库中找到它。下载此库及其依赖项的最简单方法是使用 Maven：

在系统上安装 Maven

转到驱动程序的 GitHub 页

下载 pom.xml 文件

运行下面的 Maven 命令，以下载此库及其依赖项：mvn dependency:copy-dependencies

另请参阅

通过 JDBC 驱动程序连接到 SQL Server
FIPS 模式

properties 类型默认	说明
accessToken 字符串 Null	（版本 6.0+）借助此属性，可以使用访问令牌连接到数据库。无法使用连接 URL 设置 accessToken。
accessTokenCallbackClass 字符串 Null	（版本 12.4+）要与访问令牌回拨一起使用的回拨实现类名称。
applicationIntent 字符串 ReadWrite	（版本 6.0+）声明应用程序工作负载类型来连接到服务器。可能的值为 ReadOnly 和 ReadWrite 。有关灾难恢复的详细信息，请参阅 JDBC 驱动程序对高可用性和灾难恢复的支持。
applicationName 字符串 [<=128 char] Null	应用程序名称或者“Microsoft JDBC Driver for SQL Server”（如果未提供名称）。用于在各种 SQL Server 分析和日志记录工具中标识特定的应用程序。
身份验证字符串 NotSpecified	（版本 6.0+）此可选属性指示用于连接的身份验证方法。可取值为 ActiveDirectoryIntegrated、ActiveDirectoryPassword、ActiveDirectoryManagedIdentity（版本 12.2+）、ActiveDirectoryMSI（版本 7.2+）、ActiveDirectoryInteractive（版本 9.2+）、ActiveDirectoryServicePrincipal（版本 9.2+）、SqlPassword 和 NotSpecified（默认值）。借助 ActiveDirectoryIntegrated（版本 6.0+），可以使用集成 Windows 身份验证连接到 SQL。借助 ActiveDirectoryPassword（版本 6.0+），可使用 Microsoft Entra 主体名称和密码连接到 SQL。借助 ActiveDirectoryManagedIdentity（版本 12.2+）或 ActiveDirectoryMSI（版本 7.2+），可从 Azure 资源内部连接到 SQL。例如，使用托管标识身份验证的 Azure 虚拟机、应用服务或函数应用。使用 ActiveDirectoryManagedIdentity 或 ActiveDirectoryMSI 身份验证模式时，驱动程序支持以下两种类型的托管标识： 1.系统分配的托管标识：默认用于获取 accessToken。 2.用户分配的托管标识：用于获取 accessToken，前提是托管标识的客户端 ID 与 msiClientId 连接属性一起指定。借助 ActiveDirectoryInteractive，可以使用交互式身份验证流连接到数据库。借助 ActiveDirectoryServicePrincipal（版本 9.2+），可以使用服务主体标识的客户端 ID 和机密连接到数据库。在 userName 属性中指定客户端 ID，在 password 属性中指定机密 (10.2+)。借助 SqlPassword，可以使用 userName/user 和 password 属性连接到 SQL。如果不需要这些身份验证方法，请使用 NotSpecified 。重要提示：如果将身份验证设置为 ActiveDirectoryIntegrated，则必须安装下面两个库：mssql-jdbc_auth-<version>-<arch>.dll（在 JDBC 驱动程序包中提供）和使用 SQL Server 的 Microsoft 身份验证库 (ADAL.DLL)。可以从 Microsoft ODBC Driver for SQL Server 或 Microsoft OLE DB Driver for SQL Server 安装 Microsoft 身份验证库。 JDBC 驱动程序仅支持 ADAL.Dll 版本 1.0.2028.318 及更高版本。注意：如果身份验证属性设置为除“NotSpecified”以外的任何值，驱动程序默认使用传输层安全性 (TLS)（以前称为安全套接字层 (SSL)）加密。有关如何配置 Microsoft Entra 身份验证的信息，请参阅使用 Microsoft Entra 身份验证。
authenticationScheme 字符串 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 凭据。否则，就会出错（必须指定连接属性）。
calcBigDecimalPrecision boolean ["true" \| "false"] false	（版本 12.6+）此标志指示驱动程序是否应计算 BigDecimal 的输入精度，而不是使用最大允许精度值 (38)。
cancelQueryTimeout int -1	（版本 6.4+）此属性可用于取消对连接设置的 queryTimeout。如果静默删除服务器的 TCP 连接，查询执行就会挂起，但不会引发异常。只有在连接上也设置了“queryTimeout”时，此属性才适用。驱动程序等待 cancelQueryTimeout + queryTimeout 总秒数，以断开连接并关闭通道。此属性的默认值为 -1，行为是无限期等待。
clientCertificate 字符串 Null	（版本 8.4+）指定用于客户端身份验证的证书的位置。 JDBC 驱动程序支持 PFX、PEM、DER 和 CER 文件扩展名。有关详细信息，请参阅环回方案的客户端证书身份验证。
clientKey 字符串 Null	（版本 8.4+）指定由 clientCertificate 属性指定的 PEM、DER 或 CER 证书的私钥的位置。有关详细信息，请参阅环回方案的客户端证书身份验证。
clientKeyPassword 字符串 Null	（版本 8.4+）已指定用于访问 clientKey 文件私钥的可选密码字符串。有关详细信息，请参阅环回方案的客户端证书身份验证。
columnEncryptionSetting 字符串 ["Enabled" \| "Disabled"] 已禁用	（版本 6.0+）设置为“已启用”，以使用 Always Encrypted (AE) 功能。启用 AE 后，JDBC 驱动程序以透明方式加密和解密存储在服务器中的加密数据库中的敏感数据。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。注意：SQL Server 2016 或更高版本和 Azure SQL 数据库随附 Always Encrypted。
connectRetryCount int [0..255] 1	（版本 9.4+）发生连接失败时的重新连接尝试次数。
connectRetryInterval int [1..60] 10	（版本 9.4+）每次连接重试尝试之间的秒数。
databaseName, database 字符串 [<=128 char] Null	要连接到的数据库名称。如果未声明，则连接到默认的数据库。
datetimeParameterType 字符串 ["datetime" \| "datetime2" \| "datetimeoffset"] datetime2	（版本 12.2+）用于 Java 日期/时间戳参数的 SQL 数据类型。连接到 SQL Server 2016 或更高版本并与旧的“datetime”值交互时，客户端可通过将属性设置为“datetime”来获益，因为此设置可缓解服务器端“datetime”和“datetime2”值之间的转换问题。有关详细信息，请参阅解决从 2016 SQL Server 开始 datetime 到 datetime2 的转换行为变更的问题
delayLoadingLobs boolean ["true" \| "false"] true	指示是否流式处理从 ResultSet 检索的所有 LOB 对象的标志。通过将该属性设置为“false”，无需流式处理即可将整个 LOB 对象加载到内存。
domainName, 域字符串 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 字符串 Null	（版本 8.2+）此可选属性指示要用于具有安全 Enclave 的 Always Encrypted 的证明服务终结点 URL。有关具有安全 Enclave 的 Always Encrypted 的详细信息，请参阅具有安全 Enclave 的 Always Encrypted。
enclaveAttestationProtocol 字符串 Null	（版本 8.2+）此可选属性指示要用于具有安全 Enclave 的 Always Encrypted 的证明协议。目前，此字段只支持以下值：HGS、AAS 和 NONE（NONE 仅在 11.2 及更高版本中受支持）。有关具有安全 Enclave 的 Always Encrypted 的详细信息，请参阅具有安全 Enclave 的 Always Encrypted。
encrypt 字符串 Null	设置为“true”时指示在服务器已安装有证书的情况下，SQL Server 对在客户端与服务器之间发送的所有数据使用 TLS 加密。在版本 10.2 及更高版本中，默认值为“true”；在版本 9.4 及更低版本中，则为“false”。在版本 6.0 及更高版本中，有一个新的连接设置“身份验证”默认使用 TLS 加密。有关此属性的详细信息，请参阅“authentication”属性。在 11.2.0 及更高版本中，“加密”已从“布尔”更改为“字符串”，这使得在属性设置为“严格”时支持 TDS 8.0。
failoverPartner 字符串 Null	在数据库镜像配置中使用的故障转移服务器名称。在到主体服务器的初始连接失败时，使用此属性。建立初始连接后，会忽略此属性。必须与 databaseName 属性一起使用。注意：驱动程序不支持在连接字符串的 failoverPartner 属性中使用故障转移伙伴实例的服务器实例端口号。但是，支持在同一连接字符串中指定主体服务器实例的 serverName、instanceName 和 portNumber 属性以及故障转移伙伴实例的 failoverPartner 属性。如果在 Server 连接属性中指定虚拟网络名称，则无法使用数据库镜像。有关灾难恢复的详细信息，请参阅 JDBC 驱动程序对高可用性和灾难恢复的支持
`fips` boolean ["true" \| "false"] “false”	对于启用了 FIPS 的 Java 虚拟机 (JVM)，此属性应为 true。
fipsProvider 字符串 Null	JVM 中配置的 FIPS 提供程序。例如，BCFIPS 或 SunPKCS11-NSS。在版本 6.4.0 中删除。有关详细信息，请参阅 GitHub 问题 460。
gsscredential org.ietf.jgss.GSSCredential Null	（版本 6.2+）用于 Kerberos 约束委派的用户凭据可以在此属性中传递。此设置应与设为 true 的 integratedSecurity 和设为 authenticationScheme 的 JavaKerberos 结合使用。
hostNameInCertificate 字符串 Null	验证 SQL Server TLS/SSL 证书要使用的主机名。如果未指定 hostNameInCertificate 属性或此属性设置为 null，则 Microsoft JDBC Driver for SQL Server 使用连接 URL 上的 serverName 属性值作为主机名来验证 SQL Server TLS/SSL 证书。注意：此属性与 encrypt/authentication 属性和 trustServerCertificate 属性结合使用。如果连接使用 TLS 加密并且 trustServerCertificate 设置为“false”，则此属性会影响证书验证。确保传递给 hostNameInCertificate 的值与服务器证书中使用者可选名称 (SAN) 中的公用名称 (CN) 或 DNS 名称相匹配，以便成功建立 TLS 连接。有关加密支持的详细信息，请参阅了解加密支持。
INSTANCENAME 字符串 [<=128 char] Null	要连接到的数据库实例。如果未指定，则连接到默认实例。对于 instanceName 和端口均已指定的情况，请参阅有关端口的备注。如果在 Server 连接属性中指定虚拟网络名称，则无法使用 instanceName 连接属性。有关灾难恢复的详细信息，请参阅 JDBC 驱动程序对高可用性和灾难恢复的支持。
integratedSecurity boolean ["true"\|"false"] false	设置为“true”可以指明 SQL Server 在 Windows 操作系统上使用 Windows 凭据。如果设置为“true”，JDBC 驱动程序在本地计算机凭据缓存中搜索在用户登录计算机或网络时提供的凭据。设置为“true”（且 authenticationscheme=JavaKerberos）可以指明 SQL Server 使用 Kerberos 凭据。若要详细了解 Kerberos 身份验证，请参阅使用 Kerberos 集成身份验证连接到 SQL Server。设置为“true”（且 authenticationscheme=NTLM）可以指明 SQL Server 使用 NTLM 凭据。如果为“false”，则必须提供用户名和密码。
ipaddresspreference 字符串 [<=128 char] IPv4First	客户端应用程序使用的 IP 首选项。使用 IPV4First，驱动程序首先遍历 IPv4 地址。如果没有 IPv4 地址能够成功连接，驱动程序将继续尝试 IPv6 地址（如果有）。使用 IPV6First，驱动程序首先遍历 IPv6 地址。如果没有 IPv6 地址能够成功连接，驱动程序将继续尝试 IPv4 地址（如果有）。使用 UsePlatformDefault，驱动程序将按照 DNS 解析中的初始顺序遍历所有 IP 地址。
jaasConfigurationName 字符串 SQLJDBCDriver	（版本 6.2+）SQL Server 的每个连接都可以使用自己的 JAAS 登录配置名称来建立 Kerberos 连接。可通过此属性传递配置项的名称。这适用于创建 Kerberos 配置文件时使用。默认情况下，驱动程序查找名称 `SQLJDBCDriver`。如果未找到外部配置，驱动程序则为 IBM JVM 设置 `useDefaultCcache = true`，为其他 JVM 设置 `useTicketCache = true`。
keyStoreAuthentication 字符串 Null	（版本 6.0+）此属性确定了要用于 Always Encrypted 的密钥存储，并确定了用于验证密钥存储的身份验证机制。设置“keyStoreAuthentication=JavaKeyStorePassword”时，驱动程序支持无缝设置 Java 密钥存储。若要使用此属性，还必须为 Java 密钥存储设置 keyStoreLocation 和 keyStoreSecret 属性。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。从 Microsoft JDBC Driver 8.4 开始，你可以将“keyStoreAuthentication=KeyVaultManagedIdentity”或“keyStoreAuthentication=KeyVaultClientSecret”设置为使用托管标识向 Azure Key Vault 进行身份验证。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。
keyStoreLocation 字符串 Null	（版本 6.0+）如果 keyStoreAuthentication=JavaKeyStorePassword，keyStoreLocation 属性将标识 Java 密钥存储库文件的路径，此文件存储用于 Always Encrypted 数据的列主密钥。必须在密钥存储文件名中包含此路径。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。
keyStorePrincipalId 字符串 Null	（版本 8.4+）如果 keyStoreAuthentication=KeyVaultManagedIdentity，keyStorePrincipalId 属性将指定一个有效的 Microsoft Entra 应用程序客户端 ID。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。
keyStoreSecret 字符串 Null	（版本 6.0+）如果 keyStoreAuthentication=JavaKeyStorePassword，keyStoreSecret 属性将标识要用于密钥存储和密钥的密码。若要使用 Java 密钥存储，密钥存储和密钥密码必须相同。有关 Always Encrypted 的详细信息，请参阅结合使用 Always Encrypted 和 JDBC 驱动程序。
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 及以下版本）	因连接失败而中止连接之前驱动程序应等待的秒数。零值表示超时为默认系统超时，在 11.2 及以上版本中默认为 30 秒，在 10.2 及以下版本中默认为 15 秒。非零值为因连接失败而中止连接之前驱动程序应等待的秒数。如果在 Server 连接属性中指定虚拟机名称，则应指定三分钟或更长的超时值，使故障转移连接有足够的时间连接成功。有关灾难恢复的详细信息，请参阅 JDBC 驱动程序对高可用性和灾难恢复的支持。
maxResultBuffer 字符串 Null	（版本 9.2+）maxResultBuffer 可用于设置在读取结果集时要读取的最大字节数。如果未指定，则读取整个结果集。可以采用以下两种样式指定大小： 1. 字节大小（例如 `100`、`150M`、`300K`、`400G`） 2. 以最大堆内存的百分比形式（例如，`10p`、`15pct`、`20percent`）。
msiClientId 字符串 Null	（已弃用）（版本 7.2+）托管标识 (MSI) 的客户端 ID，用于在使用 ActiveDirectoryManagedIdentity 或 ActiveDirectoryMSI 身份验证模式建立连接时获取 accessToken。
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 方法。
password 字符串 [<=128 char] Null	数据库密码（如果使用 SQL 用户和密码进行连接的话）。如果使用主体名称和密码进行 Kerberos 连接，此属性设置为 Kerberos 主体密码。（版本 10.2+）如果 authentication=ActiveDirectoryServicePrincipal，password 属性将标识要用于 Active Directory 主体的密码。
portNumber, port int [0..65535] 1433	服务器侦听的端口。如果在连接字符串中指定了端口号，则不会向 SQLbrowser 发出请求。如果端口和 instanceName 都已指定，则将建立到指定端口的连接。但是，将对 instanceName 进行验证，如果它与端口不符，将引发错误。重要提示：建议始终指定端口号，因为这比使用 SQLbrowser 更安全。
prepareMethod 字符串 prepexec	（11.2.0 及更高版本）指定驱动程序要使用的基础准备方法以及预定义的语句。设置为“prepare”以使用 `sp_prepare` 作为准备方法。这会导致对数据库进行单独的初始访问来准备没有任何初始值的语句，供数据库在执行计划中考虑。设置为“prepexec”以使用 `sp_prepexec` 作为准备方法。此方法将准备操作与第一次执行相结合，从而减少往返次数。它还为数据库提供初始参数值，数据库可在执行计划中考虑这些值。
queryTimeout int -1	查询发生超时之前要等待的秒数。默认值为 -1，表示无期限超时。将此值设置为 0 也表示无限期等待。
realm 字符串 Null	（版本 9.4+）Kerberos 身份验证的领域。设置此值将替代驱动程序从服务器的领域自动检测的 Kerberos 身份验证领域。
复制 boolean ["true" \| "false"] false	（版本 9.4+）此设置告知服务器此连接是否用于复制。启用后，带有 `NOT FOR REPLICATION` 选项的触发器不会在连接时触发。
responseBuffering 字符串 ["full" \| "adaptive"] 自适应	如果此属性设置为“adaptive”，将只在需要时才缓冲尽可能少的数据。默认模式为“adaptive”。如果此属性设置为“full”，则在执行语句时，将从服务器读取整个结果集。注意：在 JDBC 驱动程序版本 1.2 之后，默认缓冲行为将为“adaptive”。如果要在应用程序中保留版本 1.2 默认行为，则需在连接属性中将 responseBufferring 属性设置为“full”，或使用 SQLServerStatement 对象的 setResponseBuffering 方法。
selectMethod 字符串 ["direct" \| "cursor"] 直通	如果该属性设置为“cursor”，则对基于 TYPE_FORWARD_ONLY 和 CONCUR_READ_ONLY 游标的连接创建的每个查询，都会创建一个数据库游标。通常仅当应用程序生成较大的结果集，以至于客户端内存无法完全容纳时，才需要使用该属性。如果将该属性设置为“cursor”，则客户端内存中仅保留数目有限的结果集行。默认行为是在客户端内存中保留所有结果集行。在应用程序需要处理所有行时，此行为可提供最快性能。
sendStringParameters... AsUnicode boolean ["true" \| "false"] true	如果 sendStringParametersAsUnicode 属性设置为“true”，则字符串参数将以 Unicode 格式发送给服务器。如果 sendStringParametersAsUnicode 属性设置为“false”，则字符串参数将以非 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）时，如果数据库排序规则不支持非区域字符方法传递的字符串参数中的字符，则有些数据可能会丢失。对于 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 数据类型作为其各自的类型，而不是以 String 的形式发送它们。将此连接属性设置为“false”时，驱动程序接受每个时态数据类型的默认字符串文字格式，例如： DATE: `YYYY-MM-DD` DATETIME: `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:ss` TIME: `hh:mm:ss[.nnnnnnn]`
sendTimeAsDatetime boolean ["true" \| "false"] true	SQL Server JDBC Driver 3.0 中添加了此属性。设置为“true”可以将 java.sql.Time 值作为 SQL Server 日期/时间值发送到服务器。设置为“false”可以将 java.sql.Time 值作为 SQL Server 时间值发送到服务器。此属性的默认值暂为“true”，在今后发布的版本中可能会更改。若要详细了解 Microsoft JDBC Driver for SQL Server 在将 java.sql.Time 值发送到服务器前如何配置这些值，请参阅配置如何将 java.sql.Time 值发送到服务器。
serverCertificate, server 字符串 Null	（11.2.0 及更高版本）服务器证书文件的路径。用于在使用设置为“严格”的“加密”时进行验证。驱动程序支持 PEM 文件格式的证书文件。
serverName, server 字符串 Null	运行 SQL Server 或 Azure SQL 数据库的计算机。此外还可指定可用性组的虚拟网络名称。有关灾难恢复的详细信息，请参阅 JDBC 驱动程序对高可用性和灾难恢复的支持。
serverNameAsACE boolean ["true" \| "false"] false	（版本 6.0+）设置为“true”以指示驱动程序应将 Unicode 服务器名称转换为 ASCII 兼容编码 (Punycode) 以进行连接。如果此设置为 false，驱动程序将使用所提供的服务器名称进行连接。有关国际功能的详细信息，请参阅 JDBC 驱动程序的国际功能。
serverPreparedStatement... DiscardThreshold Integer 10	（版本 6.2+）此属性可用于控制在执行调用以清除服务器上未完成的句柄之前，每个连接可以有多少个未完成的准备的语句放弃操作 (`sp_unprepare`) 处于未完成状态。如果此属性设置为 `<= 1`，便会在准备的语句关闭时立即执行 unprepare 操作。如果设置为 `> 1`，则会对这些调用进行批处理，以避免过于频繁地调用 `sp_unprepare` 的开销。
serverSpn 字符串 Null	（版本 4.2+）此可选属性可用于指定 Java Kerberos 连接的服务主体名称 (SPN)。它与 authenticationScheme 配合使用。若要指定 SPN，它可以采用“MSSQLSvc/fqdn:port@REALM”的格式，其中 fqdn 是完全限定的域名，port 是端口号，REALM 是 SQL Server 的 Kerberos 领域的大写字母表示。注意：如果客户端的默认领域（在 Kerberos 配置中进行指定）与 SQL Server 的 Kerberos 领域相同，可选择使用 @REALM。若要详细了解如何将 serverSpn 与 Java Kerberos 结合使用，请参阅使用 Kerberos 集成身份验证连接到 SQL Server。
socketFactoryClass 字符串 Null	（版本 8.4+）指定要使用的自定义套接字工厂的类名，而不是默认套接字工厂。
socketTimeout int 0	在套接字读取或接受发生超时之前要等待的毫秒数。默认值为 0，表示无期限超时。
statementPooling... CacheSize int 0	（版本 6.4+）此属性可用于在驱动程序中启用准备的语句句柄缓存。此属性定义语句池的缓存大小。此属性只能与应设置为“false”的 disableStatementPooling 连接属性结合使用。将 disableStatementPooling 设置为“true”或将 statementPoolingCacheSize 设置为 0 会禁用准备的语句句柄缓存。
sslProtocol 字符串 TLS	（版本 6.4+）此属性可用于指定要在安全连接期间考虑的 TLS 协议。可能的值包括：TLS 、TLSv1 、TLSv1.1 和 TLSv1.2 。有关安全套接字层协议的详细信息，请参阅 SSLProtocol。
transparentNetwork... IPResolution boolean ["true" \| "false"] true	（版本 6.0+）此属性将为（当前）活动服务器提供更快的检测和连接。可取值为 true（默认值）和 false。在低于 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 字符串 Null	（版本 6.4+）自定义 `javax.net.ssl.TrustManager` 实现的完全限定的类名。
trustManager... ConstructorArg 字符串 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 的值与服务器证书中使用者可选名称 (SAN) 中的公用名称 (CN) 或 DNS 名称完全匹配，以便成功建立 TLS 连接。有关加密支持的详细信息，请参阅了解加密支持。注意：此属性与 encrypt /authentication 属性结合使用。当连接使用 TLS 加密时，此属性才会影响服务器 TLS/SSL 证书验证。
trustStore 字符串 Null	指向证书 trustStore 文件的路径（包括文件名）。 trustStore 文件包含客户端信任的证书的列表。如果未指定此属性或此属性设置为空，则驱动程序将依赖于信任关系管理器工厂的查找规则以确定要使用哪一个证书存储区。默认的 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 字符串 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 字符串 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+）此标志指示驱动程序是否应代表用户创建 GSSCredential，以便使用本机 GSS-API 进行 Kerberos 身份验证。
useDefaultJaasConfig boolean ["true" \| "false"] false	（版本 12.6+）当应用程序与在系统级别配置 JAAS 的库一起存在时，将此属性设置为 true，驱动程序即可使用相同的配置来执行 Kerberos 身份验证。
useFlexibleCallableStatements boolean ["true" \| "false"] true	（版本 12.6+）如果设置为 true，可使用索引或参数名称的任意组合设置语句参数。此外，还可按不同于 sproc 定义中的顺序设置这些参数。这两种情况都可以通过其他参数元数据查找实现。如果设置为 false，则必须使用索引或参数名称设置参数，但两者不能同时使用。此外，两者的设置顺序还必须与预准备语句定义中定义的顺序相同。将此选项设置为 false 不会触发上面提及的其他元数据查找。
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 字符串 [<=128 char] Null	数据库用户（如果使用 SQL 用户和密码进行连接的话）。如果使用主体名称和密码进行 Kerberos 连接，此属性设置为 Kerberos 主体名称。（版本 10.2+）如果 authentication=ActiveDirectoryServicePrincipal，userName 属性将指定有效的 Azure Active Directory 安全客户端 ID。
workstationID 字符串 [<=128 char] `<empty string>`	工作站 ID。用于在各种分析和记录工具中标识特定的工作站。如果未指定，将使用 `<empty string>`。
xopenStates boolean ["true" \| "false"] false	设置为“true”将指定驱动程序在异常时返回 XOPEN 兼容的状态代码。默认将返回 SQL 99 状态代码。

设置连接属性

备注

属性

另请参阅

反馈

反馈

其他资源