通过选择存储 ODBC 连接的设置位置、连接到哪个数据库、如何认证以及如何保护连接来配置 ODBC 连接。 只有在部署需要时才添加路由、恢复或应用特定设置。
本指南说明了 Microsoft ODBC Driver for SQL Server 在 Windows、Linux 和 macOS 上的这些选项。 ODBC 驱动 18 是当前的主要版本;ODBC 驱动 17 仍然是受支持的目标。 示例中使用了驱动程序 18,并标明了驱动程序 17 中存在差异的设置。 使用 关键词和属性引用 查找所有被接受的关键词、数值和平台。
选择连接方法
连接字符串 为驱动程序提供 keyword=value; 键/值对。 数据源名称(DSN)单独存储连接设置,以便应用程序按名称引用它们。 两种方法都使用相同的驱动程序、身份验证方法和数据库权限。
| 方法 | 何时使用它 | 应用程序提供的内容 |
|---|---|---|
| 无DSN | 保持配置与应用程序放在一起,例如在部署配置中或容器中。 你不需要在每个客户端上创建 DSN。 |
Driver、Server、Database、认证以及其他连接设置。 驱动程序仍需安装。 |
| 用户DSN | 为单个操作系统用户配置桌面应用程序,或为需要命名数据源的应用程序配置。 |
DSN=<data_source_name> 以及连接时提供的任何设置,包括凭据。 只有该用户的应用程序可以使用用户的 DSN。 |
| 系统DSN | 允许以不同身份(如服务账户)运行的应用程序使用机器级配置。 |
DSN=<data_source_name> 以及连接时设置。 进程必须能够访问系统DSN及其驱动程序。 |
| 文件 DSN | 使用一个需要在 .dsn 文件中进行连接设置的应用程序。 |
FileDSN=<file_path> 以及连接时设置。 该文件不会安装驱动程序,也不会使其路径在不同操作系统之间可移植。 |
每个连接只使用一种选择方法。 不要将Driver、FileDSN和DSN组合使用来尝试更改 DSN 的驱动程序。 服务不会自动使用交互用户的 DSN。
在本地应用中, SQLConnect 接受 DSN 以及单独的用户 ID 和密码参数。
SQLDriverConnect接受 连接字符串,包括 DSN 和无 DSN 的形式。 使用 ODBC 的应用程序和框架会决定它们对外提供哪些输入项。 请遵循应用程序的配置界面,而不是假设它接受所有 ODBC 关键字作为命令行选项。
从一个 连接字符串 开始
先选择连接窗体,然后在后续各节中选择身份验证及其他选项。 这些示例使用 SQL 身份验证。 切换到不兼容的身份验证方式时不要保留 UID、 PWD、 Authentication=SqlPassword 。
将 <server>、<database>、<user_id> 和 <password> 替换为自定义值。 对于 Azure SQL 数据库,请使用 <server>.database.windows.net 作为主机名。 示例中使用传输控制协议(TCP)端口 1433;请将其替换为为您的终结点配置的端口。
无需DSN连接
请直接提供已安装的驱动程序名称和连接设置:
Driver={ODBC Driver 18 for SQL Server};Server=tcp:<server>,1433;Database=<database>;UID=<user_id>;PWD=<password>;Authentication=SqlPassword;Encrypt=yes;TrustServerCertificate=no;
对于驱动程序 17,将驱动程序名称替换为 ODBC Driver 17 for SQL Server。 本示例中的其他设置适用于两个主要版本。
与DSN连接
创建 DSN 后,请提供其名称和应用程序的身份验证设置:
DSN=MSSQLTest;UID=<user_id>;PWD=<password>;Authentication=SqlPassword;Encrypt=yes;TrustServerCertificate=no;
DSN 选择驱动程序、服务器和数据库。 示例中显式重复安全设置,使应用程序在任一连接方式下请求相同的保护。
不要在 DSN、文件 DSN、odbc.ini、源文件或 shell 命令中保存真实密码。 通过应用程序的凭据管理机制检索机密信息,并在连接时提供。 将包含密码、令牌或密钥存储密钥的任何 连接字符串 视为敏感数据,包括日志和诊断捕获中。
选择驱动程序、服务器和数据库
这些设置决定了应用程序加载的内容以及连接位置。
| 设置 | 何时以及如何使用它 |
|---|---|
Driver |
通过其注册名称选择已安装的驱动程序,用于无 DSN 连接。 驱动程序 17 和驱动程序 18 有不同的名称,可以并排安装。 安装驱动程序 18 不会重定向明确选择驱动程序 17 的连接。 |
Server=tcp:<server>,1433 |
使用已知的 TCP 端点和端口。 逗号将主机名与端口分隔开。 Linux 和 macOS 仅支持 TCP。 显式端口可避免依赖命名实例发现。 |
Server=<server>\<instance> |
当实例发现可用时连接到命名的 SQL Server 实例。 在 Linux 和 macOS 上,这需要驱动程序 17.4 及更高版本,包括驱动程序 18。 如果无法进行发现,请获取实例的 TCP 端口并使用显式端口格式。 |
Database=<database> |
请有意识地选择初始数据库,尤其是对于包含的数据库用户或不能依赖登录默认数据库的应用程序。 此设置不会创建数据库或授予访问权限。 |
Address 或 Addr |
维护一个使用独立网络地址的应用程序。 避免指定冲突的 Server;使用一个有意的端点,而非依赖名称之间的优先顺序。 |
Network 或 Net |
维护一个明确选择网络库的 Windows 配置。 优先使用 tcp: 跨平台 TCP 连接的服务器前缀。 不要将协议前缀与相互冲突的网络选择组合使用。 |
服务器别名、命名实例、域名系统(DNS)主机名和端口不可互换。 使用与加密远程连接证书相匹配的 DNS 名称。 Internet 协议(IP)地址无法解决证书名称不匹配。
对于 Azure SQL 数据库 及其他托管服务,请使用该服务已发布的端点。 对于可用性组,当您需要 故障转移或只读路由时,请使用其监听器,而不是硬编码副本的主机名。
选择身份验证
身份验证决定连接的是哪个身份。 它不会授予该身份数据库权限,也不会替换加密设置。
| 方法 | 连接设置 | 何时使用及先决条件 |
|---|---|---|
| SQL 身份验证 |
Authentication=SqlPassword、 UID和 PWD。 |
目标启用 SQL 身份验证,并且您有一个带有密码的 SQL 登录名或数据库用户。 驱动程序 17 和驱动程序 18 都支持此形式。
UID是 SQL 用户名,而非 Microsoft Entra ID 账户。 |
| Windows 集成身份验证 |
Trusted_Connection=yes;省略 UID和PWD。 |
为配置为 Windows 身份验证 的目标使用进程的Windows身份。 在 Linux 和 macOS 上,配置 Kerberos 并获取应用程序身份的票证。 这不是 Microsoft Entra 集成身份验证。 |
| Microsoft Entra 集成身份验证 |
Authentication=ActiveDirectoryIntegrated;省略 SQL 凭据。 |
在支持集成身份验证的 Microsoft Entra 配置中使用现有的 Windows 或 Kerberos 身份。 Linux 和 macOS 需要驱动程序 17.6 及更高版本,包括驱动程序 18。 |
| Microsoft Entra 交互式身份验证 |
Authentication=ActiveDirectoryInteractive;省略 PWD。 |
用户可以完成登录和多因素认证。 支持Windows,包括驱动程序17.1及更高版本。 对于驱动程序 17.1 到 17.7,请在 UID 中提供 Microsoft Entra 用户名。 驱动程序 17.8 及更高版本(包括驱动程序 18)允许您省略 UID。 请不要为无人值守服务选择此方法。 |
| Microsoft Entra 托管标识 |
Authentication=ActiveDirectoryMsi。 |
在暴露受支持的托管身份端点的主机上运行。 系统分配的身份不需要 UID。 用户分配的身份需要带有该主机相应标识符的 UID。 在驱动程序 17.3.1.1 及更高版本(包括驱动程序 18)中可用。 |
| Microsoft Entra服务主体 |
Authentication=ActiveDirectoryServicePrincipal; UID 是应用程序客户端 ID, PWD 是其客户端密钥。 |
无人值守应用程序使用Microsoft Entra应用程序身份,而托管身份不适用。 在 Driver 17.7 及更高版本中可用,包括 Driver 18。 保护并轮换客户端密钥。 |
| 应用程序提供的 Microsoft Entra 访问令牌 | 连接前设置 SQL_COPT_SS_ACCESS_TOKEN 连接属性。 |
应用程序自行获取令牌。 这是一个应用程序编程接口(API)属性,而不是 连接字符串 关键字。 在连接配置中省略 UID、 PWD、 Trusted_Connection和 Authentication 。 |
只有当目标支持该方法并且您已配置身份的数据库访问时,才选择 Microsoft Entra 方法。 驱动程序支持的方法并不一定在每个 SQL Server 部署或托管服务中都可用。 有关设置、主机特定托管身份标识符和平台限制,请参阅《使用 Microsoft Entra ID 搭配 ODBC 驱动程序》和《在 Linux 和 macOS 上使用集成身份验证》。
不要将 Authentication 与 Trusted_Connection=yes 值结合使用。 不要在 PWD 中放置访问令牌。 更改 DSN 的身份验证方法时,删除不兼容的凭据和应用程序属性,同时更改关键字。
ActiveDirectoryPassword使用 Microsoft Entra 用户名和密码,且已弃用。 不要为新应用选择它。 优先采用适合交互用户或工作负载身份的方法。
配置加密和证书验证
对使用驱动程序 17 或驱动程序 18 的传输层安全(TLS)连接,请使用 Encrypt=yes;TrustServerCertificate=no 来验证服务器证书。 客户端必须信任签发证书颁发机构,且证书必须与预期的服务器名称匹配。
| 配置 | 何时使用它 | 驱动程序 17 和驱动程序 18 的行为 |
|---|---|---|
Encrypt=yes;TrustServerCertificate=no |
要求加密和常规证书验证。 | 两个主要版本均支持。 驱动程序 18 也接受 mandatory 作为 yes 的同义词。 |
Encrypt=strict |
要求对支持该加密的终端使用表格数据流(TDS)8.0 加密。 | 仅适用于驱动程序 18。 驱动程序验证证书并忽略 TrustServerCertificate。 Driver 17 没有对应项。 |
Encrypt=yes;TrustServerCertificate=yes |
一个经过刻意批准的例外,在不进行普通证书验证的情况下加密流量。 | 不要把它当作证书错误的常规修复方法。 它并不能确认客户端正在与预期的服务器通信。 严格模式下它不会禁用验证功能。 |
Encrypt=no |
保持一个不需要客户端进行全会话加密的配置。 | 这不是远程连接的基线。 驱动程序18也接受 optional。 服务器仍然可以要求加密。 |
驱动程序 18 默认请求加密。 驱动程序 17 通常默认不请求加密,但如果将 Authentication 设置为非空值,或提供了访问令牌,则会改变驱动程序 17 的加密默认值。 明确设置 Encrypt ,而非依赖依赖身份验证的默认值。
对于具有 Encrypt=no 和 TrustServerCertificate=no的普通非严格连接,仅服务器加密请求会使驱动程序 18 验证证书,但不会在驱动程序 17 中选择正常证书验证。 不要仅依赖服务器强制加密来在两个驱动程序中获得相同的验证行为。 有关与服务器设置的完整交互,请参见 加密行为表。
选择预期的证书标识
大多数应用程序只需要一份受信任的证书和正确的 Server 名称。 针对特定部署需求使用额外的证书关键字:
| 关键 字 | 何时使用它 | 适用性与限制 |
|---|---|---|
HostnameInCertificate |
部署需要与连接端点不同的预期证书主机名,例如配置好的别名。 | 仅适用于 Driver 18。 它并不能建立对不受信任的发行机构的信任。 当使用 ServerCertificate 时,会忽略它。 |
ServerCertificate |
匹配显式提供的服务器证书文件,而非普通的证书链和主机名验证。 | 驱动程序 18.1 及更高版本,仅适用于 Encrypt=strict。 使用隐私增强邮件(PEM)或可辨别编码规则(DER)证书。 证书必须完全匹配,且有效期仍需核对。 规划如何在服务器证书轮换前分发替换证书。 |
ClientCertificate 和 ClientKey |
使用专用的证书身份验证机制,用于 Linux 上的 SQL Server 的回环连接。 | 这些不是 SQL 或 Microsoft Entra 认证的通用替代品,也不是服务器证书信任设置。 |
解决证书链、主机名和证书文件问题,而不是禁用验证。 在 Linux 和 macOS 上,还要检查驱动程序支持的 OpenSSL 依赖以及该进程所使用的信任存储。 有关详细信息,请参阅 “连接加密故障排除”。
Linux 和 macOS 证书信任
Linux 和 macOS 上的 TLS 使用 OpenSSL。 获取经批准的信任材料,并遵循您平台的信任存储管理流程。 从未认证的终端下载的证书不足以证明其可信。 检查您的驱动程序和平台支持的库的 系统要求 。
以下历史平台清单记录了 OpenSSL 最低版本和默认的证书信任存储位置。 它并未确定这些平台版本当前的驱动支持情况。 在依赖所列位置之前,请确认您已安装的驱动程序和平台所使用的 OpenSSL 版本和信任存储配置。
| 平台 | 最低 OpenSSL 版本 | 默认证书信任存储位置 |
|---|---|---|
| Debian 10、11、12 | 1.1.1 | /etc/ssl/certs |
| Debian 9 | 1.1.0 | /etc/ssl/certs |
| Debian 8.71 | 1.0.1 | /etc/ssl/certs |
| OS X 10.11、macOS | 1.0.2 | /usr/local/etc/openssl/certs |
| Red Hat Enterprise Linux 9 | 3.0.1 | /etc/pki/tls/cert.pem |
| Red Hat Enterprise Linux 8 | 1.1.1 | /etc/pki/tls/cert.pem |
| 红帽企业 Linux 7 | 1.0.1 | /etc/pki/tls/cert.pem |
| Red Hat Enterprise Linux 6 | 1.0.0-10 | /etc/pki/tls/cert.pem |
| SUSE Linux Enterprise 15 | 1.1.0 | /etc/ssl/certs |
| SUSE Linux Enterprise 11、12 | 1.0.1 | /etc/ssl/certs |
| Ubuntu 22.04,23.04 | 3.0.2 | /etc/ssl/certs |
| Ubuntu 20.04 | 1.1.1 | /etc/ssl/certs |
| Ubuntu 18.04 | 1.1.0 | /etc/ssl/certs |
| Ubuntu 16.04 | 1.0.2 | /etc/ssl/certs |
| Ubuntu 14.04 | 1.0.1 | /etc/ssl/certs |
| Alpine 3.17,3.18 | 3.0.1 | /etc/ssl/certs |
配置路由和故障转移
根据目标拓扑和工作负载选择这些设置。 它们不会创建副本、配置监听器,也不会授予对次级服务器的访问权限。
| 设置 | 何时使用它 | 重要区别 |
|---|---|---|
MultiSubnetFailover=Yes |
连接到可用性组监听器、故障转移集群实例、Azure SQL 数据库、Azure SQL 托管实例 或 Microsoft Fabric 中的 SQL 数据库。 | 驱动程序会并行尝试与解析后的地址建立 TCP 连接。 当名称解析到一个地址时,它也同样有效。 它由 Driver 17 和 Driver 18 支持。 不要把它和数据库镜像 Failover_Partner结合起来。 |
ApplicationIntent=ReadOnly |
为只读工作负载请求连接,包括通过适当配置的可用性组侦听器进行只读路由。 | 指定参与数据库并配置服务器端路由。 此设置不能替代只读数据库权限。 默认值为 ReadWrite。 |
TransparentNetworkIPResolution |
维护或诊断驱动程序在多个已解析 IP 地址中的旧版回退机制。 | 值为 Enabled 和 Disabled;默认值为 Enabled。 不要把这当作另一个拼写 MultiSubnetFailover。 |
IpAddressPreference |
对于具有特定地址族需求的部署,选择 IPv4 优先、IPv6 优先或操作系统地址顺序。 | 驱动程序 18.1 及更高版本。 值为 IPv4First、 IPv6First、 UsePlatformDefault和 。 这不会改变 DNS 记录或修复网络路由。 |
Failover_Partner |
维护现有的 SQL Server 数据库镜像连接。 | 仅适用于Windows。 这不是可用性组监听器的选项。 Driver 18.7 及更高版本也接受别名 FailoverPartner;Driver 17 使用 Failover_Partner。 |
对于只读可用性组连接,请向相应的经过身份验证的 连接字符串 中添加 ApplicationIntent=ReadOnly;MultiSubnetFailover=Yes,并使用 Server 中的侦听器。 直接连接到任意辅助副本不会配置只读路由。
故障切换后,应用程序可能需要重新打开连接。 有关服务器的先决条件和应用行为,请参阅 高可用性和灾难恢复。
设置超时、恢复和重试行为
为您需要控制的操作选择一个设置。 登录超时、查询超时、空闲连接恢复策略和命令重试策略适用于不同的操作。
| 要求 | 设置 | 何时以及如何使用它 |
|---|---|---|
| 限制连接建立。 |
SQL_ATTR_LOGIN_TIMEOUT,或者 ConnectTimeout 搭配驱动程序18.7及更高版本。 |
在本地应用程序中,连接前请先设置该属性。 Driver 17 及更早版本以及 Driver 18 版本需要该属性,而非此关键字。 明确设置的属性优先于 ConnectTimeout。 |
| 限制语句执行。 |
SQL_ATTR_QUERY_TIMEOUT 语句属性。 |
通过应用程序的 API 进行配置。
ConnectTimeout 不会设置查询超时。 |
| 恢复在闲置时中断的符合条件的连接。 |
ConnectRetryCount 和 ConnectRetryInterval. |
当前版本的 Driver 17 和 Driver 18 均支持。 默认设置为一次恢复尝试和两次尝试间隔10秒。 计数为 0 时将禁用恢复。 这些设置不会重试应用程序的初始连接或重放其命令。 |
| 检测到已无响应的空闲 TCP 连接。 |
KeepAlive 和 KeepAliveInterval. |
仅针对经过测量的网络需求进行调优。 默认为30秒和1秒。 驱动程序 17.4 引入了配置支持;连接字符串 支持需要驱动程序 17.8 及更高版本,包括驱动程序 18。 早期支持的版本使用 DSN 或驱动程序配置。 |
| 重新执行选定的失败命令。 |
RetryExec。 |
驱动程序 18.1 及后续版本。 只有在确定重复操作是否安全后,才为特定错误和命令定义规则。 这不是空闲连接恢复。 |
例如,ConnectRetryCount=3;ConnectRetryInterval=2 选择最多三次空闲恢复尝试,间隔为 2 秒。 它不会使初始登录失败变为成功,也不会重试中断的写入。
ConnectRetryCount接受 0 到 255,60接受 ConnectRetryInterval 到 1 秒。 在驱动程序 18.7 及更高版本中,ConnectTimeout=30 会请求 30 秒的登录超时。 默认为 15 秒; 0 请求无限期等待。 当应用程序需要有限制的响应时间时,避免无限期的登录等待。
针对瞬时的初始连接失败实施有界的应用程序重试策略。 不要把错误的凭证、缺少的驱动程序注册或证书验证错误当作暂时性中断来重试。 对于命令重试,考虑服务器是否在连接失败前已完成写入。
有关恢复前提条件和错误处理,请参见 连接弹性。 有关规则语法,请参见 RetryExec。 保持连接和查询超时选项与您的应用程序可接受的总延迟保持一致。
Linux 和 macOS 的 keep-alive 配置
KeepAlive 控制 TCP 发送数据包以检查空闲连接的频率。
KeepAliveInterval 控制在没有响应时重传之间的间隔。 它们的默认时间分别是30秒和1秒。
对于 Driver 17.4 及更高版本,您可以在 odbcinst.ini 的驱动程序部分或 odbc.ini 的 DSN 部分配置这些值。 使用 DSN 连接时,DSN 的设置优先于驱动程序的设置。 没有 DSN 时,驱动程序会使用 odbcinst.ini 中的相应部分。 如果两个位置都未指定值,驱动程序使用默认值。
驱动程序 17.8 及更高版本(包括驱动程序 18)也接受 KeepAlive 和 KeepAliveInterval 包含在 连接字符串 中。 替换现有关键字,而不是附加重复的关键字,并在将连接时设置与 DSN 组合时检查 配置优先级。
配置应用程序和数据行为
当应用程序需要该行为时使用这些选项,而不是将它们添加到每个 连接字符串 中。
| 设置 | 何时使用它 | 行为和限制 |
|---|---|---|
APP |
在服务器端会话信息中识别应用程序。 | 使用稳定的应用程序名称。 它既不是认证身份,也不是授权控制。 |
WSID |
当您需要工作站标识符用于会话识别时,请提供一个工作站标识符。 | 驱动程序 18.7 及更高版本也支持 WorkstationID。 驱动程序 17 使用 WSID。 不要用客户端提供的名称作为来电者身份的证明。 |
MARS_Connection=Yes |
应用程序需要在一个连接上有多个活动结果集(MARS)。 | 默认值为 No。 驱动程序 18.7 及更高版本也支持 MultipleActiveResultSets=Yes。 驱动程序 17 使用 MARS_Connection。 |
LongAsMax=Yes |
将长字符或二进制参数发送为 varchar(max)、nvarchar(max) 或 varbinary(max),而不是传统大型对象类型。 | 仅限 Driver 18;默认为 No。 在更改应用程序之前,请检查应用程序的参数和架构预期。 |
GetDataExtensions=Yes |
维护一个需要检索列数据且顺序 SQLGetData 错乱的应用程序。 |
仅适用于 Driver 18。 这种兼容性行为可能增加内存使用并降低性能。 在新应用中,优先按升序检索列。 |
Language |
选择会话的服务器消息语言。 | 使用服务器上安装的语言。 它不会选择应用程序的源代码编码。 |
AutoTranslate |
控制客户端和服务器代码页之间的非 Unicode 字符数据转换。 | 默认值为 Yes。 在更改应用程序之前,先使用应用程序中的实际字符数据进行测试;禁用翻译可能会改变字符的解释方式。 |
Regional |
维护一个应用程序,在将货币、日期或时间数据转换为字符数据时,期望采用客户端区域格式。 | 默认值为 No。 不要以为改变输出格式就能让这些区域字符串成为有效的输入参数。 |
AnsiNPW |
维护会话行为以处理空值处理、字符填充和警告。 | 默认值为 Yes。 在更改之前,请检查相应的 Transact-SQL(T-SQL)会话选项和服务器版本行为。 |
QuotedId |
控制会话是否使用双引号作为标识符。 | 默认值为 Yes。 仅当应用程序的 T-SQL 需要不同的 QUOTED_IDENTIFIER 行为时才更改它。 |
ConcatNullYieldsNull |
控制服务器支持该会话选择的 NULL 串联行为。 | 驱动程序 18.6 及以后版本。 驱动程序17不识别这个关键词。 |
UseFMTONLY |
维护一条需要 SET FMTONLY 而不是驱动程序常规元数据发现的元数据发现路径。 |
默认值为 No。 对于普通连接,这不是必需的。 |
通过驱动程序管理器或应用程序的 ODBC 环境配置连接池。 不要将其他提供者的Pooling关键字复制到此驱动程序的 连接字符串 中。 有关原生 ODBC 配置,请参见驱动程序管理器连接池。 关于 Windows 特定的重用行为,请参见驱动程序相关连接池。
配置专用功能
以下选项需要在 连接字符串 之外进行功能特定设置。
| Settings | 何时使用它们 | 你还需要的内容 |
|---|---|---|
ColumnEncryption=Enabled |
读取或写入使用“始终加密”保护的列。 | 通过支持的密钥存储访问列加密密钥。 “始终加密”保护列值,且与网络加密是分开的。 对于 enclave 连接,请使用功能特定的连接设置。 |
KeystoreAuthentication、KeystorePrincipalId 和 KeystoreSecret |
将驱动程序认证到用于“始终加密”的密钥存储库。 | 密钥存储的身份和权限 这些凭据并不是数据库登录凭据。 像保护密码一样保护密钥存储机密。 |
ServerSPN |
为需要显式值的 Kerberos 部署指定服务主体名称(SPN)。 | 当前的驱动程序 17 和 Driver 18 版本在 Windows、Linux 和 macOS 上支持此设置。 配置 Kerberos 服务注册以匹配所提供的 SPN。 SPN 不是 TLS 证书主机名。 |
FailoverPartnerSPN |
为数据库镜像合作伙伴维护显式 Kerberos SPN。 | 仅限 Windows,并配有相应的镜像配置。 |
AttachDBFileName |
使用用于附加数据库文件的 SQL Server 工作流。 | 匹配的 Database 名称、服务器可访问的文件以及所需权限。 不要用它来识别 Azure SQL 数据库 中的现有数据库。 |
Replication=Yes |
使用一个刻意需要复制代理行为的连接。 | Driver 17.8及以后版本,包括Driver 18。 它会改变标记为 NOT FOR REPLICATION的对象(包括触发器)的行为;它并不是通用性能选项。 |
QueryLog_On, QueryLogFile, QueryLogTime, StatsLog_On, 和 StatsLogFile |
通过驱动程序查询或性能日志诊断现有 Windows 应用程序。 | 仅限 Windows;这些连接设置需要 DSN。 使用 QueryLogTime 设置慢查询阈值,以毫秒为单位。 使用受控的日志目标、适当的权限和保留策略。 不要认为诊断日志不包含敏感数据。 |
有关设置和限制,请参见 “始终加密”、“ Kerberos SPN”以及 关键字引用。 某些原生功能,如分布式事务登记,需要 API 属性而非 连接字符串 关键字。
创建 DSN
仅在选择基于 DSN 的连接时创建 DSN。 DSN 存储配置;保存配置并不意味着应用程序能够进行身份验证或运行查询。
Windows用户DSN
以下过程为 SQL 身份验证示例创建一个用户 DSN。 对于某个服务,请刻意选择系统 DSN ,并在服务身份下安排访问。
打开与您应用程序架构匹配的 ODBC 数据源管理员。
在 用户 DSN 上,选择 “添加”。
选择 ODBC Driver 18 for SQL Server 或 ODBC Driver 17 for SQL Server。 选择 “完成 ”以打开驱动程序向导。
将 DSN 命名为
MSSQLTest。 在“服务器”框中输入tcp:<server>,1433,然后选择 “下一步”。选择 SQL 身份验证。 清除 登录ID 和 密码,然后选择“下一步”。
选中“将默认数据库更改为”。 在不打开数据库列表的情况下输入
<database>,然后选择 下一步。对于驱动程序 18,选择 “强制” 连接加密。 对于驱动程序 17,选择“为数据使用强加密”。 保持未选择 信任服务器证书 。
选择 “完成” 并查看配置摘要。
选择 “确定 ”以保存 DSN,而无需运行向导的连接测试。 确认
MSSQLTest显示在 用户 DSN 上。
应用程序在连接时提供 SQL 凭据。 有关其他身份验证方法和向导字段,请参阅 ODBC 数据源管理员 DSN 选项。
Linux 或 macOS 用户 DSN
运行 odbcinst -j 以查找适用于你的 unixODBC 安装的 USER DATA SOURCES 和 SYSTEM DATA SOURCES 路径。 向用户文件添加以下部分,替换服务器和数据库占位符:
[MSSQLTest]
Driver = ODBC Driver 18 for SQL Server
Server = tcp:<server>,1433
Database = <database>
Authentication = SqlPassword
Encrypt = yes
TrustServerCertificate = no
对于驱动程序 17,更改驱动程序名称。 不要存储 PWD 在这个文件里。 在 odbcinst.ini 中的驱动程序注册和在 odbc.ini 中的 DSN 用于不同用途:一个用于定位驱动程序库,另一个用于命名连接设置。
对于系统 DSN,请将相同的设置添加到所示的 SYSTEM DATA SOURCES 文件中,并使用管理员权限。 对于某个服务,在服务身份下配置访问权限。
该 Driver 值可以是注册的驱动程序名称,也可以是安装模板中指定的驱动程序库路径。 在 odbc.ini中,使用注册名且不加连接字符串大括号。 在Server中指定服务器端口;Port不是此驱动程序在 Linux 或 macOS 上的有效 DSN 关键字。
或者,将 DSN 部分保存到模板文件中,并使用以下命令注册用户 DSN:
odbcinst -i -s -h -f <template_file>
用模板路径替换 <template_file> 。 有关 .ini 文件和注册的详细信息,请参阅 unixODBC 文档。 通过使用 DSN 的应用程序测试连接;仅仅注册无法建立数据库连接。
文件 DSN
当应用程序期望文件数据源时使用 FileDSN=<file_path> 。 客户端仍然需要安装一个能够解读这些设置的驱动程序。 将凭据放在文件之外。
SaveFile 用于请求在连接成功后将连接设置保存到文件中。 仅在应用程序有意创建文件 DSN 时使用。 有关文件内容和合并规则,请参见 SQLDriverConnect 参考。
了解配置优先级
应用程序可以从 DSN、其 连接字符串 和 API 属性接收设置。 当有效连接与你预期的字符串不同时,请检查这三者。
| 源或语法 | 规则 |
|---|---|
| 关键词拼写 | 驱动程序匹配关键词名称,不考虑大小写。 接受的值是关键词特定的;不要假设每个布尔选项都接受 true 和 false。 |
| 重复关键字 | 在解析驱动程序选项时,驱动 17 和 Driver 18 会保留识别关键字的首次出现。 同一选项的别名不会提供单独的覆盖。 此规则不适用于驱动程序管理器较早阶段的驱动程序或 DSN 选择:在该阶段,unixODBC 会使用重复的 DSN 或 Driver 值中最后一次出现的值。 替换现有值,而不是追加重复值,并且只指定一次选择关键字。 |
| 连接字符串与 DSN 的区别 | 显式 连接字符串 值通常会覆盖对应的 DSN 字段。 驱动程序的 RegPrecedence DSN 设置可以反转这一优先级。 当现有DSN出现意外行为时检查它。 |
| API 属性 | 应用程序设置的属性可能会改变有效配置。 检查具体属性的契约,而不是假设每个属性都使用相同的合并规则。 |
| 带大括号的值 | 将包含分号的值括在大括号中,并在该值内将右大括号写成两个。 例如, Database={database;name} 提供一个数据库名称。 Shell 或编程语言中的引号处理与 ODBC 转义是分开的。 |
在 DSN 和应用程序之间保持身份验证和安全设置一致。 更换驱动程序时,请根据需要更新 DSN 所选的驱动程序或无 DSN 的Driver值。 有关迁移检查,请参见 主要版本差异。
在您的应用程序中检查连接情况
在应用程序的实际操作系统身份和部署配置下进行测试。 成功的 DSN 向导测试并不证明服务能够看到相同的 DSN 或获取相同的凭据。
- 使用预期的身份验证方法连接到所选的 DSN 或无 DSN 字符串。
- 连接成功后,确认应用程序加载的是哪种驱动程序和版本。 在本地代码中,将
SQLGetInfo与SQL_DRIVER_VER和SQL_DRIVER_NAME一起使用。 - 在目标数据库中运行查询并检查结果。 有关完整的应用程序示例,请参阅 使用 C++ 连接并查询数据库。
- 检查加密以及应用程序所需的行为,例如只读路由或恢复。 测试您独立部署的每个连接表单。
- 在不暴露凭据的情况下捕捉失败。 有关 SQLSTATE 值、本地错误代码和受保护诊断集合,请参见 ODBC 诊断。
如果连接失败,请在更改身份验证前检查驱动程序注册和DSN可见性。 在更改重试设置之前,请检查端点和可达性。 对于证书错误,请修复信任或名称配置,而不是设置 TrustServerCertificate=yes 以消除错误。