DSN 和连接字符串关键字和属性
此页面列出了 ODBC Driver for SQL Server 中提供的连接字符串和 DSN 的关键字以及 SQLSetConnectAttr 和 SQLGetConnectAttr 的连接属性。
受支持的 DSN/连接字符串关键字和连接属性
下表列出了每个平台的可用关键字和属性（L：Linux；M：macOS；W：Windows）。 选择关键字或属性以获取更多详细信息。
以下是将连接字符串关键字用于 SQL Server Native Client、SQLSetConnectAttr 和 SQLSetConnectAttr 函数中未记录的一些连接字符串关键字和连接属性。
说明
用于描述数据源。
SQL_COPT_SS_ANSI_OEM
控制 ANSI 到 OEM 的数据转换。
| 属性值 | 说明 |
|---|---|
| SQL_AO_OFF | （默认）转换未完成。 |
| SQL_AO_ON | 转换已完成。 |
SQL_COPT_SS_AUTOBEGINTXN
版本 17.6+ 自动提交关闭时，控制在回滚或提交后自动开始事务。
| 属性值 | 说明 |
|---|---|
| SQL_AUTOBEGINTXN_ON | （默认值）在回滚或提交后自动开始事务。 |
| SQL_AUTOBEGINTXN_OFF | 在回滚或提交后不自动开始事务。 |
SQL_COPT_SS_FALLBACK_CONNECT
控制 SQL Server 回退连接的使用。 此属性不再受支持。
| 属性值 | 说明 |
|---|---|
| SQL_FB_OFF | （默认值）禁用回退连接。 |
| SQL_FB_ON | 回退连接已启用。 |
新的连接字符串关键字和连接属性
身份验证 - SQL_COPT_SS_AUTHENTICATION
设置连接到 SQL Server 时要使用的身份验证模式。 有关详细信息，请参阅使用 Microsoft Entra ID。
| 关键字值 | 属性值 | 说明 |
|---|---|---|
| SQL_AU_NONE | （默认值）未设置。 其他属性的组合可确定身份验证模式。 | |
| SqlPassword | SQL_AU_PASSWORD | SQL Server 身份验证（使用用户名和密码）。 |
| ActiveDirectoryIntegrated | SQL_AU_AD_INTEGRATED | Microsoft Entra 集成身份验证。 |
| ActiveDirectoryPassword | SQL_AU_AD_PASSWORD | Microsoft Entra 密码身份验证。 |
| ActiveDirectoryInteractive | SQL_AU_AD_INTERACTIVE | Microsoft Entra 交互式身份验证。 |
| ActiveDirectoryMsi | SQL_AU_AD_MSI | Microsoft Entra 托管标识身份验证。 对于用户分配的标识，UID 设置为用户标识的对象 ID。 |
| ActiveDirectoryServicePrincipal | SQL_AU_AD_SPA | Microsoft Entra 服务主体身份验证。 UID 设置为服务主体的客户端 ID。 PWD 设置为客户端密码。 |
| SQL_AU_RESET | 取消设置。 替代任何 DSN 或连接字符串设置。 |
注意
使用 Authentication 关键字或属性时，将 Encrypt 显式指定为连接字符串/DSN/连接属性中所需的值。 有关详细信息，请参阅将连接字符串关键字用于 SQL Server Native Client。
ColumnEncryption - SQL_COPT_SS_COLUMN_ENCRYPTION
控制透明列加密 (Always Encrypted)。 有关详细信息，请参阅使用 Always Encrypted (ODBC)。
| 关键字值 | 属性值 | 说明 |
|---|---|---|
| 已启用 | SQL_CE_ENABLED | 启用 Always Encrypted。 |
| 已禁用 | SQL_CE_DISABLED | （默认值）禁用 Always Encrypted。 |
| SQL_CE_RESULTSETONLY | 仅启用解密（结果和返回值）。 |
加密
指定连接是否通过网络使用 TLS 加密。 可能的值为 yes/mandatory(18.0+)、no/optional(18.0+) 和 strict(18.0+)。 在版本 18.0+ 中默认值为 yes，在早期版本中为 no。
无论 Encrypt 设置如何，始终加密服务器登录凭据（用户名和密码）。
Encrypt、TrustServerCertificate 和服务器端 Force Encryption 设置会影响连接是否通过网络加密。 下表显示了这些设置的效果。
ODBC Driver 18 和更高版本
| 加密设置 | 信任服务器证书 | 服务器强制加密 | 结果 |
|---|---|---|---|
| 否 | No | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 否 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 是 | 否 | 否 | 检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 否 | No | 是 | 检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 否 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 是 | No | 是 | 检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 严格 | - | - | 将忽略 TrustServerCertificate。 检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
注意
“严格”仅适用于支持 TDS 8.0 连接的服务器。
ODBC Driver 17 及更低版本
| 加密设置 | 信任服务器证书 | 服务器强制加密 | 结果 |
|---|---|---|---|
| 否 | No | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 否 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 是 | 否 | 否 | 检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 否 | No | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 否 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 是 | No | 是 | 检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
TransparentNetworkIPResolution - SQL_COPT_SS_TNIR
控制透明网络 IP 解析功能，此功能与 MultiSubnetFailover 交互以允许更快的重新连接尝试。 有关详细信息，请参阅使用透明网络 IP 解析。
| 关键字值 | 属性值 | 说明 |
|---|---|---|
| 已启用 | SQL_IS_ON | （默认）启用透明网络 IP 解析。 |
| 已禁用 | SQL_IS_OFF | 禁用透明网络 IP 解析。 |
UseFMTONLY
连接到 SQL Server 2012 及更高版本时，控制对元数据的 SET FMTONLY 使用。
| 关键字值 | 说明 |
|---|---|
| 否 | （默认值）如果可用，请将 sp_describe_first_result_set 用于元数据。 |
| 是 | 对元数据使用 SET FMTONLY。 |
复制
指定针对 ODBC 驱动程序版本 17.8 及更高版本使用复制登录。
| 关键字值 | 说明 |
|---|---|
| 否 | （默认）不使用复制登录。 |
| 是 | 带有 NOT FOR REPLICATION 选项的触发器不会在连接时触发。 |
RetryExec
从版本 18.1 开始，可以使用可配置的重试逻辑。 它根据可配置条件自动重新执行特定的 ODBC 函数调用。 可以使用 RetryExec 关键字以及重试规则列表通过连接字符串启用此功能。 每个重试规则都有三个冒号分隔的组件：错误匹配、重试策略和查询匹配。
查询匹配确定要用于给定执行的重试规则，并与传入命令文本 (SQLExecDirect) 或语句对象中准备好的命令文本 (SQLExecute) 匹配。 如果多个规则匹配，则使用列表中的第一个匹配规则。 此行为允许按普遍性增加的顺序列出规则。 如果没有规则匹配，则不会应用重试。
当执行导致错误，并且存在适用的重试规则时，则其错误匹配将用于确定是否应重试执行。
RetryExec 关键字的值是用分号分隔的重试规则列表。
RetryExec={rule1;rule2}
重试规则如下所示：<errormatch>:<retrypolicy>:<querymatch>
错误匹配：以逗号分隔的错误代码列表。 例如，指定 1000,2000 将是要重试的错误代码。
重试策略：指定到下一次重试前的延迟时间。 第一个参数是重试次数，而第二个参数是延迟时间。 例如，3,10+7 将是从 10 开始的 3 次尝试，后续每次重试将增加 7 秒。 如果未指定 +7，则后续每次重试将呈指数级翻倍。
查询匹配：指定要与之匹配的查询。 如果未指定任何内容，则它适用于所有查询。 指定 SELECT 表示从 select 开始的所有查询。
将上述所有三个组件组合在一起，在一个连接字符串中使用的效果如下：
RetryExec={1000,2000:3,10+7:SELECT}
这意味着：“对于以 SELECT 开头的查询上的错误 1000 和 2000。 重试两次，初始延迟时间为 10 秒，且后续每次尝试增加 7 秒”
示例
40501,40540:4,5
对于错误 40501 和 40540，最多重试四次，初始延迟时间为 5 秒，而每次重试之间呈指数级翻倍。 此规则适用于所有查询。
49919:2,10+:CREATE
对于以 CREATE 开头的查询上的错误 49919，最多重试两次，初始重试在 10 秒后，然后是 20 秒后。
49918,40501,10928:5,10+5:SELECT c1
对于以 SELECT c1 开头的查询上的错误 49918、40501 和 10928，最多重试五次，在第一次重试后等待 10 秒，之后等待时间将增加 5 秒。
上述三个规则可以在连接字符串中一起指定，如下所示：
RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}
最通用的（匹配所有）规则放置在末尾，以便前面两个更具体的规则与其各自的查询匹配。
ClientCertificate
指定用于身份验证的证书。 选项包括：
| 选项值 | 说明 |
|---|---|
sha1:<hash_value> |
ODBC 驱动程序使用 SHA1 哈希在 Windows 证书存储中查找证书 |
subject:<subject> |
ODBC 驱动程序使用主题在 Windows 证书存储中查找证书 |
file:<file_location>[,password:<password>] |
ODBC 驱动程序使用证书文件。 |
如果证书采用 PFX 格式，且 PFX 证书内的私钥受密码保护，则需要 password 关键字。 对于 PEM 和 DER 格式的证书，ClientKey 属性是必需的
ClientKey
指定由 ClientCertificate 属性指定的 PEM 或 DER 证书的私钥的文件位置。 格式：
| 选项值 | 说明 |
|---|---|
file:<file_location>[,password:<password>] |
指定私钥文件的位置。 |
如果私钥文件受密码保护，则需要 password 关键字。 如果密码包含任何 , 字符，则会在每个字符后立即添加一个额外的 , 字符。 例如，如果密码为 a,b,c，则连接字符串中存在的转义密码为 a,,b,,c。
HostnameInCertificate
指定在进行加密协商时应在服务器证书中出现的主机名（如果它与派生自 Addr/Address/Server 的默认值不同）。 使用 ServerCertificate 选项时，HostnameInCertificate 选项将被忽略。
IpAddressPreference
此选项从版本 18.1 开始可用，允许用户指定他们希望优先进行连接的 IP 地址类型。 可能的选项为“IpAddress= [ IPv4First | IPv6First | UsePlatformDefault”。UsePlatformDefault 按系统调用提供地址的顺序连接到地址，以解析服务器名称。 默认值为 IPv4First，对应于以前版本中的行为。
ServerCertificate
从版本 18.1 开始提供，此选项可用于严格的加密模式。 ServerCertificate 关键字用于指定要与 SQL Server TLS/SSL 证书匹配的证书文件的路径。 执行匹配，而不是标准证书验证（到期、主机名、信任链等）。接受的证书格式是 PEM、DER 和 CER。 如果指定，则通过查看提供的 ServerCertificate 是否完全匹配来检查 SQL Server 证书。
SQL_COPT_SS_ACCESS_TOKEN
允许使用 Microsoft Entra 访问令牌进行身份验证。 有关详细信息，请参阅使用 Microsoft Entra ID。
| 属性值 | 说明 |
|---|---|
| Null | （默认值）不提供任何访问令牌。 |
| ACCESSTOKEN* | 指向访问令牌的指针。 |
SQL_COPT_SS_CEKEYSTOREDATA
与加载的密钥存储提供程序库进行通信。 请参阅控制透明列加密 (Always Encrypted)。 此属性没有默认值。 有关详细信息，请参阅自定义密钥存储提供程序。
| 属性值 | 说明 |
|---|---|
| CEKEYSTOREDATA * | 密钥存储提供程序库的通信数据结构 |
SQL_COPT_SS_CEKEYSTOREPROVIDER
为 Always Encrypted 加载密钥存储提供程序库，或检索已加载的密钥存储提供程序库的名称。 有关详细信息，请参阅自定义密钥存储提供程序。 此属性没有默认值。
| 属性值 | 说明 |
|---|---|
| char * | 密钥存储提供程序库的路径 |
SQL_COPT_SS_ENLIST_IN_XA
要使用 XA 兼容事务处理器 (TP) 启用 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
允许将长类型数据作为最大类型数据发送到服务器。
| 属性值 | 说明 |
|---|---|
| 否 | （默认设置）发送时不将长类型转换为最大类型。 |
| 是 | 发送时将数据从长类型转换为最大类型。 |
SQL_COPT_SS_SPID
检索连接的服务器进程 ID。 此属性相当于 T-SQL T-SQL @@SPID 变量，只是它不会导致额外往返到服务器。
| 属性值 | 说明 |
|---|---|
| DWORD | SPID |