DSN 和连接字符串关键字和属性

此页面列出了 ODBC Driver for SQL Server 中提供的连接字符串和 DSN 的关键字以及 SQLSetConnectAttr 和 SQLGetConnectAttr 的连接属性。

受支持的 DSN/连接字符串关键字和连接属性

下表列出了每个平台的可用关键字和属性(L:Linux;M:macOS;W:Windows)。 选择关键字或属性以获取更多详细信息。

DSN / 连接字符串关键字 连接属性 平台
Addr LMW
Address LMW
AnsiNPW SQL_COPT_SS_ANSI_NPW LMW
APP LMW
ApplicationIntent SQL_COPT_SS_APPLICATION_INTENT LMW
AttachDBFileName SQL_COPT_SS_ATTACHDBFILENAME LMW
身份验证 SQL_COPT_SS_AUTHENTICATION LMW
AutoTranslate SQL_COPT_SS_TRANSLATE LMW
ColumnEncryption SQL_COPT_SS_COLUMN_ENCRYPTION LMW
ConnectRetryCount SQL_COPT_SS_CONNECT_RETRY_COUNT LMW
ConnectRetryInterval SQL_COPT_SS_CONNECT_RETRY_INTERVAL LMW
Database SQL_ATTR_CURRENT_CATALOG LMW
说明 LMW
驱动程序 LMW
DSN LMW
Encrypt SQL_COPT_SS_ENCRYPT LMW
Failover_Partner SQL_COPT_SS_FAILOVER_PARTNER W
FailoverPartnerSPN SQL_COPT_SS_FAILOVER_PARTNER_SPN W
FileDSN LMW
GetDataExtensions(版本 18.0 及更高版本) SQL_COPT_SS_GETDATA_EXTENSIONS LMW
HostnameInCertificate(版本 18.0 及更高版本) LMW
IpAddressPreference (v18.1+) LMW
KeepAlive(v17.4+;仅限 17.8 版本之前的 DSN) LMW
KeepAliveInterval(v17.4+;仅限 17.8 版本之前的 DSN) LMW
KeystoreAuthentication LMW
KeystorePrincipalId LMW
KeystoreSecret LMW
语言 LMW
LongAsMax(版本 18.0 及更高版本) SQL_COPT_SS_LONGASMAX LMW
MARS_Connection SQL_COPT_SS_MARS_ENABLED LMW
MultiSubnetFailover SQL_COPT_SS_MULTISUBNET_FAILOVER LMW
Net LMW
Network LMW
PWD LMW
QueryLog_On SQL_COPT_SS_PERF_QUERY W
QueryLogFile SQL_COPT_SS_PERF_QUERY_LOG W
QueryLogTIme SQL_COPT_SS_PERF_QUERY_INTERVAL W
QuotedId SQL_COPT_SS_QUOTED_IDENT LMW
Regional LMW
复制 LMW
RetryExec (18.1+) LMW
SaveFile LMW
Server LMW
ServerCertificate (v18.1+) LMW
ServerSPN SQL_COPT_SS_SERVER_SPN LMW
StatsLog_On SQL_COPT_SS_PERF_DATA W
StatsLogFile SQL_COPT_SS_PERF_DATA_LOG W
TransparentNetworkIPResolution SQL_COPT_SS_TNIR LMW
Trusted_Connection SQL_COPT_SS_INTEGRATED_SECURITY LMW
TrustServerCertificate SQL_COPT_SS_TRUST_SERVER_CERTIFICATE LMW
UID LMW
UseFMTONLY LMW
WSID LMW
SQL_ATTR_ACCESS_MODE
(SQL_ACCESS_MODE)
LMW
SQL_ATTR_ASYNC_DBC_EVENT W
SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE W
SQL_ATTR_ASYNC_DBC_PCALLBACK W
SQL_ATTR_ASYNC_DBC_PCONTEXT W
SQL_ATTR_ASYNC_ENABLE W
SQL_ATTR_AUTO_IPD LMW
SQL_ATTR_AUTOCOMMIT
(SQL_AUTOCOMMIT)
LMW
SQL_ATTR_CONNECTION_DEAD LMW
SQL_ATTR_CONNECTION_TIMEOUT LMW
SQL_ATTR_DBC_INFO_TOKEN LMW
SQL_ATTR_LOGIN_TIMEOUT
(SQL_LOGIN_TIMEOUT)
LMW
SQL_ATTR_METADATA_ID LMW
SQL_ATTR_ODBC_CURSORS
(SQL_ODBC_CURSORS)
LMW
SQL_ATTR_PACKET_SIZE
(SQL_PACKET_SIZE)
LMW
SQL_ATTR_QUIET_MODE
(SQL_QUIET_MODE)
LMW
SQL_ATTR_RESET_CONNECTION
(SQL_COPT_SS_RESET_CONNECTION)
LMW
SQL_ATTR_TRACE
(SQL_OPT_TRACE)
LMW
SQL_ATTR_TRACEFILE
(SQL_OPT_TRACEFILE)
LMW
SQL_ATTR_TRANSLATE_LIB
(SQL_TRANSLATE_DLL)
LMW
SQL_ATTR_TRANSLATE_OPTION
(SQL_TRANSLATE_OPTION)
LMW
SQL_ATTR_TXN_ISOLATION
(SQL_TXN_ISOLATION)
LMW
SQL_COPT_SS_ACCESS_TOKEN LMW
SQL_COPT_SS_ANSI_OEM W
SQL_COPT_SS_AUTOBEGINTXN LMW
SQL_COPT_SS_BCP LMW
SQL_COPT_SS_BROWSE_CACHE_DATA LMW
SQL_COPT_SS_BROWSE_CONNECT LMW
SQL_COPT_SS_BROWSE_SERVER LMW
SQL_COPT_SS_CEKEYSTOREDATA LMW
SQL_COPT_SS_CEKEYSTOREPROVIDER LMW
SQL_COPT_SS_CLIENT_CONNECTION_ID LMW
SQL_COPT_SS_CONCAT_NULL LMW
SQL_COPT_SS_CONNECTION_DEAD LMW
SQL_COPT_SS_ENLIST_IN_DTC W
SQL_COPT_SS_ENLIST_IN_XA LMW
SQL_COPT_SS_FALLBACK_CONNECT LMW
SQL_COPT_SS_INTEGRATED_AUTHENTICATION_METHOD LMW
SQL_COPT_SS_MUTUALLY_AUTHENTICATED LMW
SQL_COPT_SS_OLDPWD LMW
SQL_COPT_SS_PERF_DATA_LOG_NOW W
SQL_COPT_SS_PRESERVE_CURSORS LMW
SQL_COPT_SS_SPID (v17.5+) LMW
SQL_COPT_SS_TXN_ISOLATION LMW
SQL_COPT_SS_USER_DATA LMW
SQL_COPT_SS_WARN_ON_CP_ERROR LMW
ClientCertificate LMW
ClientKey LMW

以下是将连接字符串关键字用于 SQL Server Native ClientSQLSetConnectAttrSQLSetConnectAttr 函数中未记录的一些连接字符串关键字和连接属性。

说明

用于描述数据源。

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 时要使用的身份验证模式。 有关详细信息,请参阅使用 Azure Active Directory

关键字值 属性值 说明
SQL_AU_NONE (默认值)未设置。 其他属性的组合可确定身份验证模式。
SqlPassword SQL_AU_PASSWORD SQL Server 身份验证(使用用户名和密码)。
ActiveDirectoryIntegrated SQL_AU_AD_INTEGRATED Azure Active Directory 集成身份验证。
ActiveDirectoryPassword SQL_AU_AD_PASSWORD Azure Active Directory 密码身份验证。
ActiveDirectoryInteractive SQL_AU_AD_INTERACTIVE Azure Active Directory 交互式身份验证。
ActiveDirectoryMsi SQL_AU_AD_MSI Azure Active Directory 托管标识身份验证。 对于用户分配的标识,UID 设置为用户标识的对象 ID。
ActiveDirectoryServicePrincipal SQL_AU_AD_SPA Azure Active Directory 服务主体身份验证。 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 设置如何,始终加密服务器登录凭据(用户名和密码)。

EncryptTrustServerCertificate 和服务器端 Force Encryption 设置会影响连接是否通过网络加密。 下表显示了这些设置的效果。

ODBC Driver 18 和更高版本

加密设置 信任服务器证书 服务器强制加密 结果
不检查服务器证书。
在客户端和服务器之间发送的数据没有加密。
不检查服务器证书。
在客户端和服务器之间发送的数据没有加密。
检查服务器证书。
在客户端和服务器之间发送的数据已加密。
不检查服务器证书。
在客户端和服务器之间发送的数据已加密。
检查服务器证书。
在客户端和服务器之间发送的数据已加密。
不检查服务器证书。
在客户端和服务器之间发送的数据已加密。
检查服务器证书。
在客户端和服务器之间发送的数据已加密。
不检查服务器证书。
在客户端和服务器之间发送的数据已加密。
严格 - - 将忽略 TrustServerCertificate。 检查服务器证书。
在客户端和服务器之间发送的数据已加密。

注意

“严格”仅适用于支持 TDS 8.0 连接的服务器。

ODBC Driver 17 及更低版本

加密设置 信任服务器证书 服务器强制加密 结果
不检查服务器证书。
在客户端和服务器之间发送的数据没有加密。
不检查服务器证书。
在客户端和服务器之间发送的数据没有加密。
检查服务器证书。
在客户端和服务器之间发送的数据已加密。
不检查服务器证书。
在客户端和服务器之间发送的数据已加密。
不检查服务器证书。
在客户端和服务器之间发送的数据已加密。
不检查服务器证书。
在客户端和服务器之间发送的数据已加密。
检查服务器证书。
在客户端和服务器之间发送的数据已加密。
不检查服务器证书。
在客户端和服务器之间发送的数据已加密。

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 开始的所有查询。

将上述所有 3 个组件组合在一起,在一个连接字符串中使用的效果如下:

RetryExec={1000,2000:3,10+7:SELECT}

这意味着:“对于以 SELECT 开头的查询上的错误 1000 和 2000。 重试两次,初始延迟时间为 10 秒,且后续每次尝试增加 7 秒”

示例

40501,40540:4,5

对于错误 40501 和 40540,最多重试 4 次,初始延迟时间为 5 秒,而每次重试之间呈指数级翻倍。 这适用于所有查询。

49919:2,10+:CREATE

对于以 CREATE 开头的查询上的错误 49919,最多重试两次,初始重试在 10 秒后,然后是 20 秒后。

49918,40501,10928:5,10+5:SELECT c1

对于以 SELECT c1 开头的查询上的错误 49918、40501 和 10928,最多重试 5 次,在第一次重试后等待 10 秒,之后等待时间将增加 5 秒。

上述 3 个规则可以在连接字符串中一起指定,如下所示:

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 属性指定的 PEMDER 证书的私钥的文件位置。 格式:

选项值 说明
file:<file_location>[,password:<password>] 指定私钥文件的位置。

如果私钥文件受密码保护,则需要 password 关键字。 如果密码包含任何“,”字符,则会在每个字符后立即添加一个额外的“,”字符。 例如,如果密码为“a,b,c”,则连接字符串中存在的转义密码为“a,,b,,c”。

HostnameInCertificate

指定在进行加密协商时应在服务器证书中出现的主机名(如果它与派生自 Addr/Address/Server 的默认值不同)。

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

允许使用 Azure Active Directory 访问令牌进行身份验证。 有关详细信息,请参阅使用 Azure Active Directory

属性值 说明
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