Microsoft SQL Server 的 ODBC 驱动程序

下载 ODBC 驱动程序

ODBC 是以 C 和 C++ for SQL Server 编写的用于应用程序的主要本机数据访问 API。 适用于 SQL Server 的 Microsoft ODBC 驱动程序可连接到 SQL Server、Azure SQL 数据库、Azure SQL 托管实例、Azure Synapse Analytics 和 Microsoft Fabric 中的 SQL 数据库。 关于每个驱动版本支持的数据库版本，请参见 SQL版本兼容性。

其他可以使用 ODBC 的语言包括 COBOL、Perl、PHP 和 Python。 ODBC 广泛应用于数据集成场景，Microsoft PHP for SQL Server 驱动基于该驱动程序构建。

sqlcmd 和 bcp 实用工具可与该驱动程序配合使用，但需要单独安装：在 Linux 和 macOS 上安装 mssql-tools18 包，在 Windows 上安装 Microsoft Command Line Utilities。 使用 sqlcmd 运行 Transact-SQL（T-SQL）语句、系统过程和脚本文件。 使用 bcp 在 SQL Server 实例和数据文件之间批量复制数据，无论双向。

选择起点

Azure SQL的生产基线

将此代码片段用作面向生产Azure SQL连接的起点。 它从应用配置加载服务器名称和数据库名称，使用托管身份认证，确保连接字符串中不出现秘密信息，并支持表式数据流（TDS）8.0加密及完整证书验证。 它会为每次登录尝试设置超时时间，并在发生暂时性故障时采用指数退避和抖动进行重试。

本文中的 C++ 摘要省略了 include、handle allocation 和日志辅助工具以简化。

std::wstring BuildConnectionString(const wchar_t* server, const wchar_t* database) {
    std::wstring cs = L"Driver={ODBC Driver 18 for SQL Server}";
    cs += L";Server=tcp:"; cs += server; cs += L",1433";
    cs += L";Database="; cs += database;
    cs += L";Authentication=ActiveDirectoryMsi";   // managed identity, no stored secret
    cs += L";Encrypt=strict";                      // TDS 8.0 with certificate validation
    cs += L";ConnectRetryCount=3";                 // idle connection resiliency, not initial connect
    cs += L";ConnectRetryInterval=10";
    return cs;
}

// Transient fault codes documented for Azure SQL, plus the resource governance
// codes. Network termination and timeout errors (64, 233, 258, 10053, 10054,
// 10060) are retried a bounded number of times, which is the documented
// guidance for them. 258 is the code the driver reports for a connect timeout.
// 10053 and 10054 can also mean the encryption handshake failed rather than a
// plain network reset, so read the error text before assuming a network fault.
bool IsTransient(SQLINTEGER nativeError) {
    switch (nativeError) {
        case 615: case 926: case 4060: case 4221:
        case 10928: case 10929: case 10936:
        case 40197: case 40501: case 40613:
        case 42108: case 42109:
        case 49918: case 49919: case 49920:
        case 40020: case 40143: case 40166: case 40540:   // failover subcodes
        case 64: case 233: case 258:
        case 10053: case 10054: case 10060:
            return true;
        default:
            return false;
    }
}

// Retries only errors that a new connection can clear, with exponential backoff
// plus jitter so that concurrent clients don't retry in lockstep.
SQLRETURN ConnectWithRetry(SQLHDBC hDbc, const std::wstring& connectionString, int maxAttempts) {
    SQLRETURN rc = SQL_ERROR;
    for (int attempt = 1; attempt <= maxAttempts; ++attempt) {
        // Set the per-attempt connect timeout through the connection attribute.
        // This works on every driver version, so the sample doesn't depend on
        // which connection string keywords a given release accepts.
        SQLSetConnectAttrW(hDbc, SQL_ATTR_LOGIN_TIMEOUT,
                           reinterpret_cast<SQLPOINTER>(static_cast<SQLLEN>(30)), 0);

        rc = SQLDriverConnectW(hDbc, nullptr,
                               const_cast<SQLWCHAR*>(reinterpret_cast<const SQLWCHAR*>(connectionString.c_str())),
                               SQL_NTS, nullptr, 0, nullptr, SQL_DRIVER_NOPROMPT);
        if (SQL_SUCCEEDED(rc)) {
            Log("INFO", "connected on attempt %d/%d", attempt, maxAttempts);
            return rc;
        }

        // Walks the diagnostic records and returns the first record that carries
        // a real SQL Server error number. Microsoft Entra failures report several
        // driver-specific records first, whose native error is 0.
        SQLINTEGER native = LogDiagnostics(SQL_HANDLE_DBC, hDbc, "connect");
        if (attempt == maxAttempts || !IsTransient(native)) return rc;

        // Cap the backoff at 64 seconds. This also keeps the shift in range
        // when a caller passes a large maxAttempts.
        int shift = (attempt - 1 < 6) ? attempt - 1 : 6;
        DWORD delayMs = (1UL << shift) * 1000UL + (DWORD)(GetTickCount64() % 500);
        Log("WARN", "retrying in %lu ms (attempt %d/%d)", delayMs, attempt + 1, maxAttempts);
        Sleep(delayMs);
    }
    return rc;
}

ConnectRetryCount 并 ConnectRetryInterval 启用 空闲连接弹性，透明地恢复空闲时断开的连接。 它们不会重试初始连接，这也是为什么这个片段还实现了应用层的重试。 两者都留着。

ODBC通过报告诊断结果 SQLGetDiagRec ，而非仅返回代码，因此在重试前应对故障进行分类。 认证或配置错误会立即失败，而不是消耗全部重试预算。

有关此配置的每个部分的详细信息，请参阅：

有关 Azure SQL 瞬态错误的目录，请参阅瞬态故障错误代码。

主要功能

  • 跨平台：Windows、Linux 和 macOS 使用相同的 API。
  • Microsoft Entra ID认证：无密码连接，支持托管身份、服务主体、交互式和集成流程。
  • 严格加密：TDS 8.0连接，18版及以后版本支持完整的证书验证。
  • 始终加密：用于敏感列的客户端加密，并支持自定义密钥存储提供程序。
  • 连接弹性：对空闲时断开的连接进行透明恢复。
  • 高可用性：支持与 MultiSubnetFailover 配合使用的可用性组侦听器。
  • 数据分类：分类列的敏感元数据。
  • 向量数据类型：原生支持 vector 类型。
  • 分布式事务：通过 Microsoft 分布式事务处理协调器（MSDTC）支持 XA 事务。
  • 配套工具： sqlcmd 和 bcp，分别安装。

开始

文章 Description
下载 SQL Server 的 ODBC 驱动程序 为所有支持的驱动版本提供安装程序和包下载，适用于三个平台。
使用 ODBC 驱动开发 C 和 C++ 应用程序 包含哪些头部、顺序、链接哪些库，以及如何在异步执行和线程之间选择。
用C++连接并查询数据库 一个完整的C++示例，连接、运行查询并读取结果，这样你可以从头到尾确认你的设置。
支持生命周期 哪些驱动程序版本仍受支持，以及各版本停止支持的日期。
主版本差异 从版本 17 升级到版本 18 会导致哪些问题，先从默认加密设置的更改说起。

安装驱动程序

文章 Description
系统需求、安装及驱动程序文件（Windows） 受支持的 Windows 版本、用于静默部署的安装程序命令行，以及每个驱动程序文件在磁盘上的存放位置。
系统需求（Linux 和 macOS） 每个驱动程序版本支持哪些 Linux 发行版和 macOS 版本，以及与哪些 SQL Server 版本兼容。
在Linux上安装ODBC驱动 Alpine、Debian、Red Hat、SUSE、Ubuntu 和 Azure Linux 的包管理器步骤，以及离线安装和驱动文件位置。
在macOS上安装ODBC驱动 macOS 上 Homebrew tap 和 formula 的操作步骤，包括如何安装 18、17 或 13.1 版本。
安装UnixODBC驱动管理器（Linux和macOS） 安装或升级 unixODBC，这是在 Linux 和 macOS 上加载 ODBC 驱动的驱动管理器。

配置和连接

文章 Description
DSN 和连接字符串关键字和属性 连接字符串关键字、DSN 条目和 SQLSetConnectAttr 属性的完整目录，以及每一项各自的可接受值。
连接字符串关键词和数据源名称（Linux和macOS） 如何在 Linux 和 macOS 上使用 odbc.ini 和 odbcinst.ini 定义 DSN，以及这些平台特有的 TLS 和 TCP 保活设置。
ODBC 数据源管理员 DSN（Windows） Windows DSN 向导各页面上的每个选项，当通过用户界面而非连接字符串来配置数据源时适用。
驱动程序识别连接池（Windows） 哪些连接字符串关键字和属性会将连接放入其各自独立的连接池中，哪些会在重置时需要额外一次往返。

认证与安全

文章 Description
使用Microsoft Entra ID搭配ODBC驱动 每个 Authentication 关键字值（从托管标识和服务主体到交互式和集成式），以及每一种所需的设置。
使用Always Encrypted搭配ODBC驱动 加密客户端进程中的敏感列，使明文永远无法到达服务器，同时包含驱动程序的 API 摘要及其文档中的限制。
数据分类 阅读服务器在机密列上附加的敏感性标签，以便你的应用程序能够执行自己的数据保护策略。
使用集成认证（Linux和macOS） 配置Kerberos，让Linux或macOS客户端可以用Windows凭证连接，而不是SQL Server登录。

高可用性和复原能力

文章 Description
连接复原能力 介绍当服务器在连接空闲时断开连接后，ConnectRetryCount和ConnectRetryInterval如何恢复连接，以及在无法恢复时驱动程序返回的IMCxx错误。
高可用性和灾难恢复 通过可用性组监听器进行连接，并使用 MultiSubnetFailover，这样故障切换就不会因子网超时而停滞。
使用透明网络IP解析 遗留的 TransparentNetworkIPResolution 回退机制如何对跨多个 IP 地址的连接尝试进行排序，以及为何 MultiSubnetFailover 会取而代之。

处理数据

文章 Description
矢量数据类型 绑定、发送和获取 vector 类型，包括其原生 C 表示和批量复制支持。
将 DTC 与 XA 事务配合使用 通过Windows、Linux或macOS上的Microsoft 分布式事务处理协调器，将SQL Server纳入分布式事务。
编程指南（Linux和macOS） 驱动在Linux和macOS上支持哪些功能，哪些不支持，以及字符集和OpenSSL处理与Windows有何不同。

诊断和故障排除

文章 Description
连接加密故障排除 修复版本18因默认加密而出现的证书和加密错误。
数据访问追踪（Linux 和 macOS） 开启驾驶员追踪，并在需要查看应用实际调用时捕获日志文件。
已知问题（Linux和macOS） 已确认缺陷及其变通方法。 在提交支持案件前请先查看这里。
常见问题解答（Linux和macOS） 对Linux和macOS上关于驱动最常见的问题的简短回答。

发布说明与修复错误

文章 Description
Windows 发布说明 每个 Windows 驱动版本中的新功能、行为变更和修复。
Linux和macOS版本的发布说明 每个Linux和macOS驱动版本都会新增新功能、行为变更和修复。
SQL Server 工具的发布说明 对 SQL cmd 和 bcp 工具的更改，这些工具在 Linux 和 macOS 上是单独安装的，与驱动分离。

Reference

文章 Description
Windows 上的 ODBC 驱动 按版本汇总该驱动程序在 Windows 上支持的内容，以及 Windows 特定文章的索引。
Windows 上 ODBC 驱动的功能 哪个版本引入了每个 Windows 功能，以及随之而来的行为变化。

请求功能

要请求功能，请通过SQL Server反馈提交想法。

相关内容

  • Last updated on