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 实例和数据文件之间批量复制数据,可双向进行。
选择起点
- 要安装驱动,请进入 Windows 的系统需求、安装和驱动文件,或者在 Linux 上安装 ODBC 驱动,在 macOS 上安装 ODBC 驱动,然后安装 unixODBC 驱动管理器。
- 要写第一个应用,去 连接并用C++查询数据库。 对于数据源名称(DSN)和连接字符串选项,请使用DSN和连接字符串关键字及属性。 如果编译器找不到头文件,或者构建无法完成链接,请转到 使用 ODBC 驱动开发 C 和 C++ 应用程序。
- 要通过无密码认证连接Azure SQL,请访问使用ODBC驱动的Microsoft Entra ID。
- 要让现有应用对暂时性故障具备韧性,请访问 连接韧性 和 高可用性与灾难恢复。
- 要从版本17升级,请查看 主要版本差异 和 连接加密故障排除。
- 要诊断连接或查询问题,请访问连接加密故障排除和已知问题(Linux和macOS)。
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反馈提交想法。
相关内容
- ODBC 程序员参考手册:该驱动程序实现的 ODBC API 规范,记录在独立于驱动程序文档的单独文档中。
- SQL Server 原生客户端特性:历史 API 上下文。 请查看当前驱动文档中的平台支持、认证和加密行为。 Native Client 和 OLE DB 指导不能说明当前 ODBC 驱动程序是否受支持。
- BCP 工具:批量复制工具,单独安装于驱动程序之外。
- SQLcmd 工具:命令行查询工具,独立安装于驱动程序之外。
- 驱动功能支持矩阵
- SQL Server 驱动程序博客