本文列出了Microsoft ODBC 驱动程序在数据源名称(DSN)和连接字符串中接受的关键词SQL Server。 它还列出了 SQLSetConnectAttr 和 SQLGetConnectAttr 的连接属性。
选择DSN或无DSN连接
有关选择连接方法、身份验证、加密、路由、重试和应用程序设置的指导,请参阅配置 ODBC 连接至 Microsoft SQL 的指南。 利用本文查找准确的关键词和连接属性。
支持的 DSN、连接字符串关键字及连接属性
下表列出了每个平台可用的关键词和属性(L:Linux;M:macOS;W:Windows)。 选择关键字或属性以获取更多详细信息。
SQL_ATTR_DBC_INFO_TOKEN保留给 Windows 驱动程序管理器的驱动程序感知的连接池。 应用程序不会设置这个属性。
以下是一些未在《将连接字符串关键字与 SQL Server Native Client 配合使用》、SQLSetConnectAttr 和 SQLSetConnectAttr Function 中说明的连接字符串关键字和连接属性。
说明
描述数据来源。
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接受或YesNo,但不接受True或False。
司机对这些别名应用以下规则:
-
不区分大小写: 驱动程序无论大小写如何都能匹配别名。 例如,
multipleactiveresultsets的行为与MultipleActiveResultSets相同。 - 首次出现者获胜: 别名及其对应的 ODBC 关键字配置相同的选项。 如果一个连接字符串包含这两个选项,驱动程序使用第一个值,忽略该选项的后续值。
- 仅输入: 驱动程序接受别名作为输入。 当它返回输出连接字符串或将该设置写入数据源名称 (DSN) 时,会使用对应的 ODBC 关键字。
-
平台支持:驱动程序在 Windows、Linux 和 macOS 上支持
MultipleActiveResultSets和WorkstationID。 该驱动程序仅在 Windows 上支持FailoverPartner和Failover_Partner。
ConnectTimeout 关键字
关键字 ConnectTimeout 配置的登录超时与 SQL_ATTR_LOGIN_TIMEOUT 连接属性相同。 应用程序可以在 连接字符串 中指定超时时间,而无需调用 SQLSetConnectAttr。
如果应用程序在调用连接函数之前显式设置了 SQL_ATTR_LOGIN_TIMEOUT,则该连接属性优先于 ConnectTimeout 连接字符串值。
-
单位及默认值: 该值指定等待登录完成所需的秒数。 默认值为
15秒。 -
无超时: 值为
0表示驱动程序无限期等待。 -
最大值和夹紧: 最大值为
65534。 当你提供负值、大于65534或超过支持数值范围的值时,驱动变量使用65534。 如果驱动程序将该值限制在允许范围内,并且连接在其他方面均成功,则驱动程序返回SQL_SUCCESS_WITH_INFO,并附带一个01S02(选项值已更改)警告。 - 验证: 驱动程序拒绝空值和非数值值。
-
DSN 支持:在 Windows 上,应用程序可以在数据源名称(DSN)中存储和检索
ConnectTimeout值。 -
平台支持:驱动程序支持在Windows、Linux和macOS上使用
ConnectTimeout。
Example
以下 连接字符串 使用统一的关键词拼写。 将 <server>、<database>、<user_id> 和 <password> 替换为自定义值。 对于 Azure SQL 数据库,请使用 <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 应用服务 或 Azure 容器实例 上将其 client ID 设置为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 属性中明确设置Encrypt。 有关行为和默认值,请参见加密。
列加密 - 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
控制国际标准化组织(ISO)对 NULL 在串接字符串时的处理方式。 有关详细信息,请参阅 SET CONCAT_NULL_YIELDS_NULL。
| 关键词价值 | 属性值 | 说明 |
|---|---|---|
Yes(默认值) |
SQL_CN_ON |
NULL 串联得到 NULL。 |
No |
SQL_CN_OFF |
NULL 串联后得到一个字符串。 |
加密
指定连接是否在网络上使用传输层安全(TLS)加密。 驱动程序17接受 yes 和 no。 驱动 18 也接受 mandatory 作为 optional 的同义词、no 作为 strict 的同义词,以及 yes;后者选择表格数据流(TDS)8.0 加密,且在 Driver 17 中没有对应项。
驱动程序 18 默认为 yes。 驱动程序 17 通常默认为 no,但当提供非空Authentication设置或访问令牌时,则默认为 yes 。 明确设置 Encrypt ,而非依赖这些依赖身份验证的默认设置。
无论 Encrypt 设置如何,始终加密服务器登录凭据(用户名和密码)。
TrustServerCertificate、Force Encryption和服务器端Encrypt设置决定了连接是否通过网络加密。 下表显示了这些设置的效果。
ODBC Driver 18 及以后版本
| 加密设置 | 信任服务器证书 | 强制服务器加密 | Result |
|---|---|---|---|
| 否 | 否 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 否 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 是 | 否 | 否 | 服务器证书已通过检查。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 否 | 否 | 是 | 服务器证书已通过检查。 在客户端和服务器之间发送的数据已加密。 |
| 否 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 否 | 是 | 服务器证书已通过检查。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 严格 | - | - |
TrustServerCertificate 被忽略。 服务器证书已通过检查。在客户端和服务器之间发送的数据已加密。 |
注意
该 Strict 值仅适用于支持 TDS 8.0 连接的服务器。
ODBC 驱动程序 17 及更早版本
| 加密设置 | 信任服务器证书 | 服务器强制加密 | Result |
|---|---|---|---|
| 否 | 否 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 否 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 是 | 否 | 否 | 服务器证书已通过检查。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 否 | 否 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 否 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 否 | 是 | 服务器证书已通过检查。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
透明网络IP解析 - SQL_COPT_SS_TNIR
控制透明网络 IP 解析功能,这是 ODBC 驱动程序的旧版多 IP 回退机制。 当MultiSubnetFailover=Yes时,此设置不会影响连接顺序;这是 Azure SQL 数据库、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}
对于错误 1000 和 2000 以 开头 SELECT的命令,此规则允许在 10、17 和 24 秒后重复尝试三次。
示例
40501,40540:4,5
对于错误 40501 和 40540,最多重试四次,初始延迟时间为 5 秒,并且每次重试之间的延迟时间按指数翻倍。 此规则适用于所有查询。
49919:2,10+:CREATE
对于以 49919 开头的查询出现的错误 CREATE,最多重试两次,首次在 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 驱动程序使用安全哈希算法 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。
HostnameInCertificate
指定在进行加密协商时应在服务器证书中出现的主机名(如果它与派生自 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 分布式事务,请使用 SQL_COPT_SS_ENLIST_IN_XA 和指向 XACALLPARAM 对象的指针调用 SQLSetConnectAttr。 该选项支持Windows(17.3及以上版本)、Linux和macOS。
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER); // XACALLPARAM *param
要仅将 XA 事务与 ODBC 连接进行关联,在调用 SQLSetConnectAttr 时,请通过 SQL_COPT_SS_ENLIST_IN_XA 提供 TRUE 或 FALSE,而不是提供该指针。 此设置仅在 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,默认) |
发送时不要把长类型转换成最大类型。 |
SQL_XL_ON (1) |
发送时将 long 类型转换为 max 类型。 |
这些是 SQLSetConnectAttr 的数值。 对应LongAsMax的 连接字符串 关键字使用 No 和 Yes。
SQL_COPT_SS_SPID
检索连接的会话 ID。 该属性等同于 Transact-SQL (T-SQL) @@SPID 变量,但不会额外往返服务器。
| 属性值 | 说明 |
|---|---|
DWORD |
会话 ID。 |