本文列出了 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 |
启用备用连接。 |
新的连接字符串关键字和连接属性
连接字符串关键字统一化
自 18.7 版起，适用于 SQL Server 的 ODBC 驱动程序支持其他连接字符串关键字，这些关键字与 Microsoft.Data.SqlClient 数据提供程序中的属性名称保持一致。 这种支持使应用程序能够在 Microsoft SQL Server 数据提供者和驱动程序之间使用单一 连接字符串，而无需重命名关键词。
关键词别名
每个别名配置的选项与其对应的ODBC关键字相同：
| 别名 | 等效的ODBC关键词 | 说明 |
|---|---|---|
MultipleActiveResultSets |
MARS_Connection |
可开启或关闭多个活跃结果集（MARS）。 接受 Yes 或 No。 |
WorkstationID |
WSID |
设置工作站ID，通常是运行该应用程序的计算机的网络名称。
HOST_NAME() 返回该值。 |
FailoverPartner |
Failover_Partner |
指定数据库镜像的故障转移伙伴服务器。 仅支持 Windows。 |
司机对这些别名应用以下规则：
-
不区分大小写：驱动程序匹配别名时不区分大小写。 例如，
multipleactiveresultsets的行为与MultipleActiveResultSets相同。 - 先出现者获胜： 别名及其等效的ODBC关键字配置相同选项。 如果一个连接字符串包含这两个选项，驱动程序使用第一个值，忽略该选项的后续值。
- 仅限输入： 驱动程序接受别名作为输入。 当它返回输出连接字符串或将该设置写入数据源名称 (DSN) 时，会使用对应的 ODBC 关键字。
-
平台支持：驱动支持
MultipleActiveResultSets和WorkstationID支持Windows、Linux和macOS。 该驱动程序仅在 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 上，应用程序可以存储和检索
ConnectTimeout数据源名称（DSN）。 -
平台支持：驱动支持
ConnectTimeoutWindows、Linux和macOS。
Example
以下连接字符串使用统一的关键字拼写：
Driver={ODBC Driver 18 for SQL Server};Server=tcp:myserver.database.windows.net;Database=mydb;UID=myuser;PWD=mypassword;MultipleActiveResultSets=Yes;WorkstationID=app-node-01;ConnectTimeout=30;
前一个连接字符串中的别名配置的选项，与下面连接字符串中的原始 ODBC 关键字所配置的选项相同：
Driver={ODBC Driver 18 for SQL Server};Server=tcp:myserver.database.windows.net;Database=mydb;UID=myuser;PWD=mypassword;MARS_Connection=Yes;WSID=app-node-01;
两串字符串都启用了MARS并设置工作站ID为 app-node-01。 第一个字符串同样会等待最多30秒，直到登录完成。
ConnectTimeout 在早期版本中没有对应项。 要在较早版本中设置登录超时，请使用 SQL_ATTR_LOGIN_TIMEOUT 调用 SQLSetConnectAttr。
身份验证 - 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 加密。 版本17接受 yes 和 no。 18.0 及更高版本还接受 mandatory 作为 yes 的同义写法，optional 作为 no 的同义写法，以及 strict；后者会选择 TDS 8.0 加密，且在 17 版本中没有对应项。 默认值出现在 yes 18.0及以上版本，以及 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
指定在进行加密协商时应在服务器证书中出现的主机名（如果它与派生自 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 时，请通过 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
将长数据类型作为 max 数据类型发送到服务器。
| 属性值 | 说明 |
|---|---|
No（默认值） |
发送时不要把长类型转换成最大类型。 |
Yes |
发送时将数据从长类型转换为最大类型。 |
SQL_COPT_SS_SPID
检索连接的会话 ID。 此属性相当于 T-SQL T-SQL @@SPID 变量，只是它不会导致额外往返到服务器。
| 属性值 | 说明 |
|---|---|
DWORD |
SPID |