Microsoft SQL Server 的 ODBC 驱动程序

下载 ODBC 驱动程序

ODBC 是一种原生的数据访问应用程序编程接口(API),用于用 C 和 C++ 编写的应用程序。 适用于 SQL Server 的 Microsoft ODBC 驱动程序可连接到 SQL Server、Azure SQL 数据库、Azure SQL 托管实例、Azure Synapse Analytics 和 Microsoft Fabric 中的 SQL 数据库。 关于每个驱动版本支持的数据库版本,请参见 SQL版本兼容性。

你的应用程序调用 ODBC 驱动管理器,管理器加载驱动并传递 ODBC 调用给它。 在Windows上使用Windows的ODBC驱动管理器,在Linux和macOS上使用unixODBC。

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

sqlcmd 的 ODBC 变体和 bcp 实用工具使用此驱动程序,但它们需单独安装:在 Linux 和 macOS 上安装 mssql-tools18 包,在 Windows 上安装 Microsoft 命令行实用工具。 Go版本的 sqlcmd 不使用这个驱动。 使用 sqlcmd 运行 Transact-SQL(T-SQL)语句、系统过程和脚本文件。 使用 bcp 在 SQL Server 实例和数据文件之间批量复制数据,可双向进行。

选择起点

Azure SQL的生产基线

将这个完整的 C++17 程序作为 Azure 托管应用的起点。 它连接、运行 SELECT 1、检查结果,并释放 ODBC 句柄。 在构建之前,先安装Driver 18和平台的ODBC开发文件。 关于前置条件,请参见 使用 ODBC 驱动开发 C 和 C++ 应用程序。

将应用程序环境中的 ODBC_CONNECTION_STRING 设置为完整的连接字符串。 以下示例使用系统分配的托管身份。 主机必须已启用该身份,数据库也必须授权其访问。 关于主机需求、用户分配身份和本地开发认证,请参见使用 Microsoft Entra ID 搭配 ODBC 驱动。

Driver={ODBC Driver 18 for SQL Server};Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=ActiveDirectoryMsi;Encrypt=strict;ConnectRetryCount=3;ConnectRetryInterval=2;

Encrypt=strict 需要支持表格数据流(TDS)8.0的端点。 否则使用 Encrypt=yes;TrustServerCertificate=no。 配置一个客户端信任且名称与服务器匹配的证书。 关于设置和验证,请参见 连接加密故障排除。

避免让凭证出现在源文件和 shell 历史中。 关于设置环境变量的命令,请参见 配置连接。 在 Linux 和 macOS 上,将其值指定为 UTF-8。 将以下程序保存为 odbc-baseline.cpp:

#ifdef _WIN32
#include <windows.h>
#else
#include <iconv.h>
#endif
#include <sql.h>
#include <sqlext.h>

#include <chrono>
#include <cstdint>
#include <cstdlib>
#include <cstring>
#include <iostream>
#include <random>
#include <stdexcept>
#include <string>
#include <thread>
#include <vector>

struct Handles {
    SQLHENV env = SQL_NULL_HENV;
    SQLHDBC dbc = SQL_NULL_HDBC;
    SQLHSTMT stmt = SQL_NULL_HSTMT;
    bool connected = false;

    ~Handles() {
        if (stmt) SQLFreeHandle(SQL_HANDLE_STMT, stmt);
        if (connected) SQLDisconnect(dbc);
        if (dbc) SQLFreeHandle(SQL_HANDLE_DBC, dbc);
        if (env) SQLFreeHandle(SQL_HANDLE_ENV, env);
    }
};

bool logDiagnostics(SQLSMALLINT type, SQLHANDLE handle) {
    bool retry = false;
    bool permanent = false;
    for (SQLSMALLINT record = 1; ; ++record) {
        SQLWCHAR state[6] = {};
        SQLWCHAR message[1024] = {};
        SQLINTEGER native = 0;
        SQLRETURN rc = SQLGetDiagRecW(type, handle, record, state, &native,
                                     message, 1024, nullptr);
        if (rc == SQL_NO_DATA) break;
        if (!SQL_SUCCEEDED(rc)) {
            std::cerr << "event=diagnostics_failed rc=" << rc << '\n';
            return false;
        }
        std::string sqlstate;
        for (int i = 0; i < 5; ++i) {
            sqlstate += static_cast<char>(state[i]);
        }
        std::cerr << "event=odbc_diagnostic sqlstate=" << sqlstate
                  << " native_error=" << native << '\n';
        permanent |= sqlstate.substr(0, 2) == "28" ||
                     sqlstate.substr(0, 2) == "IM" ||
                     sqlstate == "HY024" || sqlstate == "HY092";
        retry |= sqlstate == "08S01" || sqlstate == "HYT00" ||
                 sqlstate == "HYT01";
        switch (native) {
            case 10928: case 10929: case 10936:
            case 40197: case 40501: case 40613:
            case 49918: case 49919: case 49920:
                retry = true;
        }
    }
    return retry && !permanent;
}

void requireSuccess(SQLRETURN rc, SQLSMALLINT type, SQLHANDLE handle,
                    const char* operation) {
    if (rc == SQL_SUCCESS) return;
    logDiagnostics(type, handle);
    if (!SQL_SUCCEEDED(rc)) throw std::runtime_error(operation);
}

std::vector<SQLWCHAR> readConnectionString() {
    static_assert(sizeof(SQLWCHAR) == 2, "Use a driver manager with 16-bit SQLWCHAR");
#ifdef _WIN32
    size_t length = 0;
    if (_wgetenv_s(&length, nullptr, 0, L"ODBC_CONNECTION_STRING") != 0 ||
        length == 0) {
        throw std::runtime_error("ODBC_CONNECTION_STRING is required");
    }
    std::vector<wchar_t> raw(length);
    if (_wgetenv_s(&length, raw.data(), raw.size(), L"ODBC_CONNECTION_STRING") != 0) {
        throw std::runtime_error("Cannot read ODBC_CONNECTION_STRING");
    }
    std::vector<SQLWCHAR> result(raw.begin(), raw.end() - 1);
#else
    const char* raw = std::getenv("ODBC_CONNECTION_STRING");
    if (!raw) throw std::runtime_error("ODBC_CONNECTION_STRING is required");
    iconv_t converter = iconv_open("UTF-16LE", "UTF-8");
    if (converter == reinterpret_cast<iconv_t>(-1)) {
        throw std::runtime_error("Cannot create UTF-8 converter");
    }
    size_t inputBytes = std::strlen(raw);
    std::vector<SQLWCHAR> result(inputBytes + 1);
    char* input = const_cast<char*>(raw);
    char* output = reinterpret_cast<char*>(result.data());
    size_t outputBytes = result.size() * sizeof(SQLWCHAR);
    const size_t capacity = outputBytes;
    size_t status = iconv(converter, &input, &inputBytes, &output, &outputBytes);
    int closeStatus = iconv_close(converter);
    if (status == static_cast<size_t>(-1) || inputBytes != 0 || closeStatus != 0) {
        throw std::runtime_error("ODBC_CONNECTION_STRING must be valid UTF-8");
    }
    result.resize((capacity - outputBytes) / sizeof(SQLWCHAR));
#endif
    if (result.empty() || result.size() >= 32767) {
        throw std::runtime_error("Invalid ODBC_CONNECTION_STRING length");
    }
    result.push_back(0);
    return result;
}

void connectWithRetry(SQLHDBC dbc, std::vector<SQLWCHAR>& connectionString) {
    constexpr int maxAttempts = 4;
    std::mt19937 random{std::random_device{}()};
    std::uniform_int_distribution<int> jitter{0, 250};
    for (int attempt = 1; attempt <= maxAttempts; ++attempt) {
        requireSuccess(SQLSetConnectAttr(
            dbc, SQL_ATTR_LOGIN_TIMEOUT,
            reinterpret_cast<SQLPOINTER>(std::uintptr_t{30}), 0),
            SQL_HANDLE_DBC, dbc, "Set login timeout");
        SQLRETURN rc = SQLDriverConnectW(
            dbc, nullptr, connectionString.data(), SQL_NTS,
            nullptr, 0, nullptr, SQL_DRIVER_NOPROMPT);
        if (SQL_SUCCEEDED(rc)) {
            if (rc == SQL_SUCCESS_WITH_INFO) logDiagnostics(SQL_HANDLE_DBC, dbc);
            std::cout << "event=connected attempt=" << attempt << '\n';
            return;
        }
        bool transient = logDiagnostics(SQL_HANDLE_DBC, dbc);
        if (!transient || attempt == maxAttempts) {
            throw std::runtime_error("Connect failed");
        }
        auto delay = std::chrono::milliseconds{
            (1 << (attempt - 1)) * 10000 + jitter(random)};
        std::cerr << "event=connect_retry attempt=" << attempt
                  << " delay_ms=" << delay.count() << '\n';
        std::this_thread::sleep_for(delay);
    }
}

int main() {
    try {
        auto connectionString = readConnectionString();
        Handles handles;
        if (!SQL_SUCCEEDED(SQLAllocHandle(
                SQL_HANDLE_ENV, SQL_NULL_HANDLE, &handles.env))) {
            throw std::runtime_error("Allocate environment");
        }
        requireSuccess(SQLSetEnvAttr(
            handles.env, SQL_ATTR_ODBC_VERSION,
            reinterpret_cast<SQLPOINTER>(std::uintptr_t{SQL_OV_ODBC3}), 0),
            SQL_HANDLE_ENV, handles.env, "Set ODBC version");
        requireSuccess(SQLAllocHandle(SQL_HANDLE_DBC, handles.env, &handles.dbc),
                       SQL_HANDLE_ENV, handles.env, "Allocate connection");
        connectWithRetry(handles.dbc, connectionString);
        handles.connected = true;
        requireSuccess(SQLAllocHandle(SQL_HANDLE_STMT, handles.dbc, &handles.stmt),
                       SQL_HANDLE_DBC, handles.dbc, "Allocate statement");
        requireSuccess(SQLSetStmtAttr(
            handles.stmt, SQL_ATTR_QUERY_TIMEOUT,
            reinterpret_cast<SQLPOINTER>(std::uintptr_t{10}), 0),
            SQL_HANDLE_STMT, handles.stmt, "Set query timeout");
        SQLWCHAR query[] = {'S', 'E', 'L', 'E', 'C', 'T', ' ', '1', 0};
        requireSuccess(SQLExecDirectW(handles.stmt, query, SQL_NTS),
                       SQL_HANDLE_STMT, handles.stmt, "Execute probe");
        requireSuccess(SQLFetch(handles.stmt),
                       SQL_HANDLE_STMT, handles.stmt, "Fetch probe");
        SQLINTEGER value = 0;
        SQLLEN indicator = 0;
        requireSuccess(SQLGetData(handles.stmt, 1, SQL_C_SLONG,
                                 &value, sizeof(value), &indicator),
                       SQL_HANDLE_STMT, handles.stmt, "Read probe");
        if (indicator == SQL_NULL_DATA || value != 1) {
            throw std::runtime_error("Unexpected probe result");
        }
        std::cout << "event=ready result=" << value << '\n';
        return 0;
    } catch (const std::exception& error) {
        std::cerr << "event=failed operation=\"" << error.what() << "\"\n";
        return 1;
    }
}

程序对最多四次连接尝试中的每一次都请求30秒的连接超时,以及10秒的查询超时。 在失败的临时连接尝试之间,它会分别等待 10 秒、20 秒和 40 秒,每次等待都带有 0 到 250 毫秒的随机抖动。 这些限制并不对认证设定严格的总体截止期限。 示例对选定的瞬态连接错误进行分类;利用 Azure SQL 瞬态故障错误目录调整策略以适应您的工作负载。 它不会重试应用程序命令或写入操作。

ConnectRetryCount 和 ConnectRetryInterval 为空闲时断开的合格连接配置 连接复原能力。 它们不会重试初始连接,也不会重放应用程序命令。 保持空闲恢复的延迟比查询超时时间短。 示例日志显示 SQLSTATE 值和本地错误编号,而非连接字符串或完整诊断消息。 如果你需要消息文本进行故障排除,可以将其记录在受保护的诊断日志中。

构建并运行基线

使用与你应用处理器架构相匹配的编译器环境。 在 Windows 上,在 Visual Studio 的开发者 PowerShell 中执行命令。 在 Linux 和 macOS 上,请使用具备编译器和 unixODBC 开发文件的 shell。

cl /nologo /std:c++17 /EHsc /W4 odbc-baseline.cpp odbc32.lib
.\odbc-baseline.exe

成功的第一次连接会打印以下输出。 还可能出现额外的诊断记录。

event=connected attempt=1
event=ready result=1

完成后清除 ODBC_CONNECTION_STRING:在 PowerShell 中使用 Remove-Item Env:\ODBC_CONNECTION_STRING,或者在 Bash 或 Zsh 中使用 unset ODBC_CONNECTION_STRING。

对于可用性组监听器和故障切换设置,请使用 高可用性和灾难恢复。

主要功能

  • 跨平台:Windows、Linux 和 macOS 使用相同的 API。
  • Microsoft Entra ID认证:托管身份、服务主体和集成认证,并在Windows上支持交互式认证。 可用的方法取决于主机和数据库配置。
  • 严格加密: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用户界面配置数据源,而不是连接字符串。
驱动程序识别连接池(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和Alpine Linux。

诊断和故障排除

文章 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反馈提交想法。