本文列出了 SQL Server 的 ODBC 驱动程序中可用的连接字符串和 DSN 的关键字，以及用于 SQLSetConnectAttr 和 SQLGetConnectAttr 的连接属性。
支持的 DSN、连接字符串关键字及连接属性
下表列出了每个平台可用的关键词和属性（L：Linux;M：macOS;W：Windows）。 选择关键字或属性以获取更多详细信息。
以下是一些未在《将连接字符串关键字与 SQL Server Native Client 配合使用》、SQLSetConnectAttr 和 SQLSetConnectAttr Function 中说明的连接字符串关键字和连接属性。
说明
描述数据来源。
SQL_COPT_SS_ANSI_OEM
控制 ANSI 到 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 |
启用备用连接。 |
新的连接字符串关键字和连接属性
身份验证 - SQL_COPT_SS_AUTHENTICATION
设置连接到 SQL Server 时要使用的身份验证模式。 有关详细信息，请参阅在 ODBC 驱动程序中使用 Microsoft Entra ID。
| 关键词价值 | 属性值 | 说明 |
|---|---|---|
SQL_AU_NONE（默认值） |
未设置。 其他属性的组合可确定身份验证模式。 | |
SqlPassword |
SQL_AU_PASSWORD |
SQL Server 身份验证（使用用户名和密码）。 |
ActiveDirectoryIntegrated |
SQL_AU_AD_INTEGRATED |
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 设置为客户端密钥。 |
ActiveDirectoryPassword |
SQL_AU_AD_PASSWORD |
[已弃用]Microsoft Entra 密码身份验证。ActiveDirectoryPassword 已弃用。 有关详细信息，请参阅 ActiveDirectoryPassword 已弃用。 |
SQL_AU_RESET |
未设置。 替代任何 DSN 或连接字符串设置。 |
注意
使用 Authentication 关键字或属性时，请在连接字符串、DSN 或连接属性中显式将 Encrypt 设置为所需值。 有关详细信息，请参阅在 SQL Server Native Client 中使用连接字符串关键字。
列加密 - 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
控制连接字符串时是否使用对 NULL 的 ISO 处理方式。 有关详细信息，请参阅 SET CONCAT_NULL_YIELDS_NULL。
| 关键词价值 | 属性值 | 说明 |
|---|---|---|
Yes（默认值） |
SQL_CN_ON |
NULL 串联后得到 NULL。 |
No |
SQL_CN_OFF |
NULL 串联生成字符串。 |
加密
指定连接是否通过网络使用 TLS 加密。 可能的值为 yes/mandatory(18.0+)、no/optional(18.0+) 和 strict(18.0+)。 在版本 18.0+ 中默认值为 yes，在早期版本中为 no。
无论 Encrypt 设置如何，始终加密服务器登录凭据（用户名和密码）。
TrustServerCertificate、Force Encryption和服务器端Encrypt设置决定了连接是否通过网络加密。 下表显示了这些设置的效果。
ODBC Driver 18 和更高版本
| 加密设置 | 信任服务器证书 | 服务器强制加密 | 结果 |
|---|---|---|---|
| 否 | 否 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 否 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 是 | 否 | 否 | 服务器证书已通过检查。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 否 | 否 | 是 | 服务器证书已通过检查。 在客户端和服务器之间发送的数据已加密。 |
| 否 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 否 | 是 | 服务器证书已通过检查。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 严格 | - | - |
TrustServerCertificate 将被忽略。 服务器证书已通过检查。在客户端和服务器之间发送的数据已加密。 |
注意
该 Strict 值仅适用于支持 TDS 8.0 连接的服务器。
ODBC Driver 17 及更低版本
| 加密设置 | 信任服务器证书 | 服务器强制加密 | 结果 |
|---|---|---|---|
| 否 | 否 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 否 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据没有加密。 |
| 是 | 否 | 否 | 服务器证书已通过检查。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 否 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 否 | 否 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 否 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 否 | 是 | 服务器证书已通过检查。 在客户端和服务器之间发送的数据已加密。 |
| 是 | 是 | 是 | 不检查服务器证书。 在客户端和服务器之间发送的数据已加密。 |
透明网络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 选项的触发器不会在连接时触发。 |
RetryExec
从版本 18.1 开始，可以使用可配置的重试逻辑。 它根据可配置条件自动重新执行特定的 ODBC 函数调用。 通过连接字符串，使用 RetryExec 关键字以及一组重试规则来启用此功能。 每个重试规则包含三个冒号分隔的组件：错误匹配、重试策略和查询匹配。
查询匹配结果决定了对于给定执行应使用的重试规则。 它匹配输入命令文本（SQLExecDirect）或语句对象中预备的命令文本（SQLExecute）。 如果有多条规则匹配，则使用列表中的第一个匹配规则。 这种行为允许你按更普遍的顺序列出规则。 如果规则不匹配，则不重试。
当执行导致错误且存在适用的重试规则时，其错误匹配决定是否应重试执行。
关键词的值 RetryExec 是分号分隔的重试规则列表。
RetryExec={rule1;rule2}
重试规则如下所示：<errormatch>:<retrypolicy>:<querymatch>
错误匹配：逗号分隔的错误代码列表。 例如，指定
1000,2000会列出你想重试的错误代码。重试政策：规定延迟至下一次重试。 第一个参数是重试次数，第二个参数是延迟。 例如，
3,10+7表示从 10 开始重试三次，之后每次重试都增加 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
对于以 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}
将最一般的（全部匹配）规则放在末尾，以便前两条更具体的规则能够匹配各自的查询。
客户端证书
指定了带有环回连接的认证证书。 该选项仅在 Linux 上的 SQL Server 中提供。 选项包括：
| 选项值 | 说明 |
|---|---|
sha1:<hash_value> |
ODBC 驱动程序使用 SHA1 哈希值在 Windows 证书存储库中定位证书。 |
subject:<subject> |
ODBC 驱动程序利用主体在 Windows 证书存储库中查找证书。 |
file:<file_location>[,password:<password>] |
ODBC 驱动程序使用证书文件。 |
如果证书为 PFX 格式，且 PFX 证书中的私钥受密码保护，请包含 password 关键字。 对于采用 PEM 和 DER 格式的证书，请包含 ClientKey 属性。
ClientKey
指定由 DER 属性指定的 ClientCertificate 或 PEM 证书的私钥文件位置。 格式：
| 选项值 | 说明 |
|---|---|
file:<file_location>[,password:<password>] |
指定私钥文件的位置。 |
如果私钥文件有密码保护，请包含 password 关键词。 如果密码包含任何 , 字符，紧接每个字符后添加一个额外的 , 字符。 例如，如果密码是 a,b,c，连接字符串 中的逃逸密码为 a,,b,,c。
HostnameInCertificate
指定在协商 encryption 时服务器证书中应期望的主机名（如果它不同于根据 Addr、Address 或 Server 派生出的默认值）。 使用 ServerCertificate 选项时，将忽略 HostnameInCertificate 选项。
IP 地址首选项
从18.1版本开始，使用该选项指定连接优先级IP地址类型。
可能的选项有 IPv4First、 IPv6First和 UsePlatformDefault。
UsePlatformDefault 按系统调用解析服务器名称时提供的地址顺序进行连接。 默认值为 IPv4First，对应之前版本中的行为。
服务器证书
从18.1版本开始，使用严格加密模式的该选项。 使用ServerCertificate关键字指定证书文件的路径，以匹配SQL Server的TLS/SSL证书。 匹配方式取代了标准的证书验证（如有效期、主机名、信任链等）。 接受的证书格式为 PEM、DER 和 CER。 如果指定此选项，则会通过检查所提供的 ServerCertificate 是否与 SQL Server 证书完全匹配来验证该证书。
SQL_COPT_SS_ACCESS_TOKEN
使用Microsoft Entra访问令牌进行身份验证。 有关详细信息，请参阅在 ODBC 驱动程序中使用 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 事务，应用程序需要调用 SQLSetConnectAttr，并传入 SQL_COPT_SS_ENLIST_IN_XA 以及一个指向 XACALLPARAM 对象的指针。 Windows (17.3+)、Linux 和 macOS 支持此选项。
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER); // XACALLPARAM *param
要仅将 XA 事务与 ODBC 连接关联，在调用 SQLSetConnectAttr 时，提供 TRUE 或 FALSE 以及 SQL_COPT_SS_ENLIST_IN_XA，而不要提供该指针。 此设置仅在 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
将长数据类型作为 max 数据类型发送到服务器。
| 属性值 | 说明 |
|---|---|
No（默认值） |
发送时不要把长类型转换成最大类型。 |
Yes |
发送时将数据从长类型转换为最大类型。 |
SQL_COPT_SS_SPID
检索连接的会话 ID。 此属性相当于 T-SQL T-SQL @@SPID 变量，只是它不会导致额外往返到服务器。
| 属性值 | 说明 |
|---|---|
DWORD |
SPID |