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

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

  1. API 参数(如用户和密码)
  2. 属性集合
  3. 连接字符串中的最后一个实例

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

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

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

属性 类型 默认值 说明

applicationName

字符串

[<=128 个字符]

null

如果未提供名称,则使用应用程序名称或“Microsoft SQL Server JDBC Driver”。用于在各种 SQL Server 分析和日志记录工具中标识特定的应用程序。

databaseName、database

字符串

[<=128 个字符]

null

要连接到的数据库名称。如果未声明,则连接到默认的数据库。

disableStatementPooling

布尔型

["true"|"false"]

true

当前仅支持值“true”。如果设置为“false”,将出现异常。

encrypt

布尔型

["true"|"false"]

false

如果设置为“true”,则指定在服务器安装了证书的情况下,SQL Server 将为在客户端与服务器之间发送的所有数据使用安全套接字层 (SSL) 加密。默认值为 false。

failoverPartner

字符串

null

在数据库镜像配置中使用的故障转移服务器名称。与主服务器进行初始连接时若发生失败,则会使用此属性;建立初始连接后,将忽略此属性。必须与 databaseName 属性结合使用。

注意: 驱动程序不支持将故障转移伙伴实例的服务器实例端口号指定为连接字符串中 failoverPartner 属性的一部分。但是,支持在同一连接字符串中指定主体服务器实例的 serverName、instanceName 和 portNumber 属性以及故障转移伙伴实例的 failoverPartner 属性。

hostNameInCertificate

字符串

null

要用于验证 SQL Server SSL 证书的主机名。

如果未指定 hostNameInCertificate 属性或此属性设置为空,则 Microsoft SQL Server JDBC Driver 将使用连接 URL 上的 serverName 属性值作为主机名来验证 SQL Server SSL 证书。

注意: 此属性与 encrypt 属性和 trustServerCertificate 属性结合使用。当且仅当 encrypt 属性设置为“true”且 trustServerCertificate 设置为“false”时,此属性才影响证书验证。

instanceName

String

[<=128 个字符]

null

要连接的 SQL Server 实例名。如果未指定,则连接到默认实例。对于 instanceName 和端口均已指定的情况,请参阅有关端口的备注。

integratedSecurity

布尔型

["true"|"false"]

false

设置为“true”表示 SQL Server 将使用 Windows 凭据来验证应用程序用户的身份。如果为“true”,则 JDBC 驱动程序将搜索本地计算机凭据缓存,以寻找在登录计算机或网络时已提供的凭据。如果为“false”,则必须提供用户名和密码。

注意: 只有 Microsoft Windows 操作系统才支持此连接属性。

lastUpdateCount

布尔型

["true"|"false"]

true

如果值为“true”,则仅返回传递给服务器的 SQL 语句的最终更新计数,它可用于单个的 SELECT、INSERT 或 DELETE 语句中,以忽略由服务器触发器引起的其他更新计数。将此属性设置为“false”可导致所有更新计数都被返回,包括由服务器触发器返回的更新计数。

注意: 此属性仅当与 executeUpdate 方法一起使用时才适用。其他所有 execute 方法返回所有结果和更新计数。

此属性仅影响由服务器触发器返回的更新计数,而不影响作为触发器执行结果的一部分的结果集或错误。

lockTimeout

int

-1

数据库报告锁定超时之前要等待的毫秒数。默认行为是无限期等待。如果指定,该值将成为此连接上所有语句的默认值。请注意,可以使用 Statement.setQueryTimeout() 设置特定语句的超时值。该值可为 0,这表示无需等待。

loginTimeout

int [0..65535]

15

因连接失败而中止连接之前驱动程序应等待的秒数。零值表示该超时为默认系统超时,默认情况下指定为 15 秒。非零值为因连接失败而中止连接之前驱动程序应等待的秒数。

packetSize

int [-1| 0 | 512..32767]

8000

用来与 SQL Server 通信的网络包大小,以字节为单位指定。值为 -1 表示使用服务器默认数据包大小。值 0 表示使用最大值 32767。如果将此属性设置为可接受范围外的值,将出现异常。

重要提示: 当启用加密 (encrypt=true) 时,建议您不要使用 packetSize 属性。否则,驱动程序可能引发连接错误。有关详细信息,请参阅 SQLServerDataSource 类的 setPacketSize 方法。

password

字符串

[<=128 个字符]

null

数据库密码。

portNumber、port

int [0..65535]

1433

SQL Server 侦听的端口。如果在连接字符串中指定了端口号,则不会向 sqlbrowser 发出请求。如果端口和 instanceName 都已指定,则将建立到指定端口的连接。但是,将对 instanceName 进行验证,如果它与端口不符,将引发错误。

重要提示: 建议始终指定端口号,因为这比使用 sqlbrowser 更安全。

responseBuffering

String

["full"|"adaptive"]

adaptive

如果此属性设置为“adaptive”,将只在需要时才缓冲尽可能少的数据。默认模式为“adaptive”。

如果此属性设置为“full”,当执行语句时,将从服务器读取整个结果集。

注意:

将 JDBC 驱动程序从版本 1.2 升级后,默认缓冲行为将为“adaptive”。如果应用程序从未设置“responseBuffering”属性,而您需要在应用程序中保留版本 1.2 的默认行为,则必须在连接属性中或使用 SQLServerStatement 对象的 setResponseBuffering 方法将 responseBufferring 属性设置为“full”。

selectMethod

String

["direct"|"cursor"]

direct

如果该属性设置为“cursor”,则对基于 TYPE_FORWARD_ONLY 和 CONCUR_READ_ONLY 游标的连接创建的每个查询,都会创建一个数据库游标。通常仅当应用程序生成的结果集非常大,以至于客户端内存无法完全容纳时,才需要使用该属性。如果将该属性设置为“cursor”,则客户端内存中仅保留数目有限的结果集行。默认行为是在客户端内存中保留所有结果集的行。在应用程序需要处理所有行时,此行为可提供最快性能。

sendStringParametersAsUnicode

boolean

["true"|"false"]

true

如果 sendStringParametersAsUnicode 属性设置为“true”,则字符串参数将以 Unicode 格式发送给服务器。

如果 sendStringParametersAsUnicode 属性设置为“false”,则字符串参数将以非 Unicode 格式(例如 ASCII/MBCS 而不是 Unicode)发送给服务器。

sendStringParametersAsUnicode 属性的默认值为“true”。

注意: 只有在发送 CHARVARCHARLONGVARCHAR JDBC 类型的参数值时才检查 sendStringParametersAsUnicode 属性。新的 JDBC 4.0 区域字符方法(例如 SQLServerPreparedStatement 类和 SQLServerCallableStatement 类的 setNStringsetNCharacterStreamsetNClob 方法)始终以 Unicode 格式将参数值发送给服务器,而与此属性的设置无关。

为了获得 CHARVARCHARLONGVARCHAR JDBC 数据类型的最佳性能,应用程序应将 sendStringParametersAsUnicode 属性设置为“false”,并使用 SQLServerPreparedStatementSQLServerCallableStatement 类的 setStringsetCharacterStreamsetClob 非区域字符方法。

当应用程序将 sendStringParametersAsUnicode 属性设置为“false”,并在服务器端使用非区域字符方法访问 Unicode 数据类型(例如,ncharnvarcharntext)时,如果数据库排序规则不支持非区域字符方法传递的字符串参数中的字符,则有些数据可能会丢失。

请注意,对于 NCHARNVARCHARLONGNVARCHAR JDBC 数据类型,应用程序应使用 SQLServerPreparedStatementSQLServerCallableStatement 类的 setNStringsetNCharacterStreamsetNClob 区域字符方法。

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 值发送到服务器。

还可以使用 SQLServerDataSource.setSendTimeAsDatetime 通过编程方式修改 sendTimeAsDatetime

在将来的版本中此属性的默认值可能会更改。

有关 SQL Server JDBC 驱动程序在将 java.sql.Time 值发送到服务器之前如何配置这些值的详细信息,请参阅配置如何将 java.sql.Time 值发送到服务器

serverName、server

String

null

运行 SQL Server 的计算机。

userName、user

字符串

[<=128 个字符]

null

数据库用户。

trustServerCertificate

boolean

["true"|"false"]

false

如果设置为“true”,则指定 Microsoft SQL Server JDBC Driver 将不会验证 SQL Server SSL 证书。

如果设置为“true”,当使用 SSL 对通信层加密时,将自动信任 SQL Server SSL 证书。

如果设置为“false”,Microsoft SQL Server JDBC Driver 将验证服务器 SSL 证书。如果服务器证书验证失败,驱动程序将报错并终止连接。默认值为“false”。

注意: 此属性与 encrypt 属性结合使用。当且仅当 encrypt 属性设置为“true”时,此属性才影响服务器 SSL 证书验证。

trustStore

字符串

null

指向证书 trustStore 文件的路径(包括文件名)。trustStore 文件包含客户端信任的证书的列表。

如果未指定此属性或此属性设置为空,则驱动程序将依赖于信任关系管理器工厂的查找规则以确定要使用哪一个证书存储区。

默认的 SunX509 TrustManagerFactory 试图按以下搜索顺序查找信任的材料:

  • 由“javax.net.ssl.trustStore”Java 虚拟机 (JVM) 系统属性指定的文件。
  • “<java 主文件夹>/lib/security/jssecacerts”文件。
  • “<java 主文件夹>/lib/security/cacerts”文件。

有关详细信息,请参阅 Sun Microsystems 网站上的 SUNX509 TrustManager 接口文档。

注意: 当且仅当 encrypt 属性设置为“true”且 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 系统属性中存储密码时,这一点可能是必需的。

注意: 当且仅当 encrypt 属性设置为“true”且 trustServerCertificate 属性设置为“false”时,trustStorePassword 属性才影响证书 trustStore 查找。

workstationID

字符串

[<=128 个字符]

<空字符串>

工作站 ID。用于在各种 SQL Server 探查和日志记录工具中标识特定的工作站。如果未指定任何内容,则使用 <空字符串>。

xopenStates

布尔型

["true"|"false"]

false

设置为“true”将指定驱动程序在异常时返回 XOPEN 兼容的状态代码。默认将返回 SQL 99 状态代码。

注意: SQL Server JDBC 驱动程序采用服务器的连接属性默认值,只有 ANSI_DEFAULTS 和 IMPLICIT_TRANSACTIONS 除外。SQL Server JDBC 驱动程序将 ANSI_DEFAULTS 自动设置为 ON,将 IMPLICIT_TRANSACTIONS 自动设置为 OFF。

请参阅

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