第25章 ODBC统一数据库接口

课程目录第25章 ODBC统一数据库接口

第25章：ODBC统一数据库接口：ODBC架构、SQLAllocHandle、SQLExecDirect、跨数据库移植

说到数据库编程，我猜你肯定遇到过这种场景：项目刚做完，客户说要把MySQL换成PostgreSQL。或者更狠的，生产环境是Oracle，测试环境只能用SQLite。这时候你怎么办？把所有数据库API重写一遍？

嗯，ODBC就是来解决这个问题的。它像是一个数据库的万能转接头，让你用同一套代码，对接不同的数据库。我个人习惯把ODBC叫做“数据库界的USB接口”——插上就能用，管你背后是什么设备。

ODBC架构：三层结构，各司其职

ODBC的全称是Open Database Connectivity，微软在90年代推出的标准。别看它年纪大，至今仍是跨数据库移植的黄金标准。

它的架构分三层，我画了张图帮你理解：

你看，你的代码只跟驱动管理器打交道。驱动管理器根据你配置的数据源名称（DSN），自动加载对应的驱动。说白了，你写一次代码，换数据库只需要改个连接字符串。

核心要点：ODBC的魔力在于——应用程序不直接操作数据库，而是通过驱动管理器这个中间人。驱动管理器负责加载、卸载驱动，转发调用。

SQLAllocHandle：一切从这里开始

在ODBC里，所有操作都围绕“句柄”展开。句柄是什么？你可以把它理解成一把钥匙——有了它，你才能打开数据库的门。

ODBC有四种句柄，我习惯按层级记：

句柄类型	宏定义	作用
环境句柄	SQL_HANDLE_ENV	全局环境，一个程序只有一个
连接句柄	SQL_HANDLE_DBC	代表一个数据库连接
语句句柄	SQL_HANDLE_STMT	执行SQL语句，获取结果
描述符句柄	SQL_HANDLE_DESC	描述参数和列的信息

分配句柄用SQLAllocHandle，释放用SQLFreeHandle。我刚开始用ODBC时，老忘记释放句柄，结果程序跑几天就崩了。后来养成了习惯：分配句柄后，立刻在脑子里想好什么时候释放。

// 标准ODBC初始化流程
SQLHENV henv = SQL_NULL_HENV;   // 环境句柄
SQLHDBC hdbc = SQL_NULL_HDBC;   // 连接句柄
SQLHSTMT hstmt = SQL_NULL_HSTMT; // 语句句柄

// 1. 分配环境句柄
SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);

// 2. 设置ODBC版本（必须！）
SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER)SQL_OV_ODBC3, 0);

// 3. 分配连接句柄
SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);

// 4. 连接数据库
SQLCHAR connStr[] = "DSN=mydb;UID=user;PWD=pass;";
SQLDriverConnect(hdbc, NULL, connStr, SQL_NTS, 
                 NULL, 0, NULL, SQL_DRIVER_COMPLETE);

// 5. 分配语句句柄
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);

// ... 执行SQL ...

// 6. 清理：先释放语句，再释放连接，最后释放环境
SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
SQLDisconnect(hdbc);
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
SQLFreeHandle(SQL_HANDLE_ENV, henv);

⚠️ 注意：释放顺序不能乱！必须先释放子句柄，再释放父句柄。我曾经犯过先释放环境句柄再释放连接句柄的错误，结果程序直接崩溃。ODBC的句柄管理是树形结构，从叶子到根释放。

SQLExecDirect：执行SQL的两种姿势

ODBC执行SQL有两种方式：SQLExecDirect 和 SQLPrepare + SQLExecute。前者一步到位，后者分两步走。

SQLExecDirect：直接执行SQL语句。适合一次性操作，比如建表、插入数据。

SQLHSTMT hstmt;
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);

// 直接执行SQL
SQLCHAR *sql = "CREATE TABLE users (id INT, name VARCHAR(50))";
SQLRETURN rc = SQLExecDirect(hstmt, sql, SQL_NTS);

if (rc == SQL_SUCCESS || rc == SQL_SUCCESS_WITH_INFO) {
    printf("表创建成功\n");
} else {
    // 错误处理
    SQLCHAR state[6], msg[256];
    SQLINTEGER native;
    SQLGetDiagRec(SQL_HANDLE_STMT, hstmt, 1, state, &native, msg, sizeof(msg), NULL);
    printf("错误: %s\n", msg);
}

SQLFreeHandle(SQL_HANDLE_STMT, hstmt);

SQLPrepare + SQLExecute：先准备SQL，再执行。适合需要多次执行的SQL，比如批量插入。预编译能提高性能，还能防止SQL注入。

SQLHSTMT hstmt;
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);

// 准备带参数的SQL
SQLCHAR *sql = "INSERT INTO users(id, name) VALUES(?, ?)";
SQLPrepare(hstmt, sql, SQL_NTS);

// 绑定参数
SQLINTEGER id = 1001;
SQLCHAR name[50] = "张三";
SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_SLONG, 
                 SQL_INTEGER, 0, 0, &id, 0, NULL);
SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, 
                 SQL_VARCHAR, 50, 0, name, 0, NULL);

// 执行
SQLExecute(hstmt);

// 换参数再执行
id = 1002;
strcpy(name, "李四");
SQLExecute(hstmt);

SQLFreeHandle(SQL_HANDLE_STMT, hstmt);

💡 我的建议：如果是用户输入的SQL，一定要用参数化查询（Prepare + BindParameter）。直接拼接字符串太危险了，我在项目中见过因为SQL注入导致数据被删光的惨案。

跨数据库移植：写一次，跑多处

ODBC最大的价值就在这里。你想想看，如果你的代码直接调用MySQL的API，换数据库就得重写。但用ODBC，只需要改连接字符串。

不过，跨数据库移植也不是完全无痛的。我总结了几条实战经验：

SQL语法差异：不同数据库的SQL方言不同。比如分页查询，MySQL用LIMIT，SQL Server用TOP，Oracle用ROWNUM。我的做法是：把SQL语句抽成配置文件，不同数据库加载不同的SQL。
数据类型映射：ODBC定义了标准数据类型，但各数据库的实现有差异。比如SQL_TIMESTAMP，在MySQL里是datetime，在SQLite里是text。建议用ODBC的SQLGetTypeInfo查询数据库支持的类型。
驱动兼容性：不是所有驱动都实现了全部ODBC功能。我遇到过某个数据库的ODBC驱动不支持SQLBulkOperations，只好改用逐行插入。

// 跨数据库的连接字符串示例
// MySQL
"DRIVER={MySQL ODBC 8.0 Driver};SERVER=localhost;DATABASE=test;UID=root;PWD=123;"

// PostgreSQL
"DRIVER={PostgreSQL Unicode};SERVER=localhost;DATABASE=test;UID=postgres;PWD=123;"

// SQLite
"DRIVER={SQLite3 ODBC Driver};DATABASE=/path/to/test.db;"

// SQL Server
"DRIVER={ODBC Driver 17 for SQL Server};SERVER=localhost;DATABASE=test;UID=sa;PWD=123;"

核心原则：跨数据库移植的关键是——只使用ODBC标准API，避免使用数据库特有的扩展功能。如果必须用，用条件编译或运行时检测来隔离差异。

避坑指南：我踩过的那些坑

做ODBC开发这些年，我踩过不少坑。分享几个典型的：

忘记设置ODBC版本：SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, ...) 这步不能省。不设置的话，驱动管理器会用默认版本，可能导致某些API行为异常。
缓冲区太小：获取数据时，如果提供的缓冲区不够大，ODBC会返回SQL_SUCCESS_WITH_INFO，数据被截断。我建议先用SQLGetData获取实际长度，再分配足够大的缓冲区。
事务未提交：ODBC默认是自动提交模式。如果改成手动提交，别忘了在程序退出前SQLEndTran提交或回滚。否则数据可能丢失。
Unicode编码问题：处理中文时，建议用SQL_C_WCHAR和SQL_WVARCHAR，避免乱码。我早期用SQL_C_CHAR处理中文，结果在不同系统上表现不一致。

⚠️ 曾经有一次：我在生产环境上调试一个ODBC程序，发现查询结果总少几条记录。查了半天，原来是SQLFetch的返回值判断写错了——我把SQL_NO_DATA当成了错误处理。记住：SQL_NO_DATA不是错误，是正常结束。

ODBC虽然有点老，但胜在稳定和通用。你只要掌握了SQLAllocHandle、SQLExecDirect这几个核心API，再注意一下跨数据库的差异点，基本上就能应对大部分场景了。

嗯，这一章就到这里。代码示例我都测试过，你可以直接拿去用。遇到问题别慌，ODBC的错误信息虽然啰嗦，但仔细看都能找到线索。

📚 课程目录