简介：这是一份基于Visual Studio 2010的MFC对话框应用示例，解决MFC项目中接入SQLite3数据库的问题。代码涵盖添加、删除、修改与查询等基础CRUD操作，并特别演示了通过回调函数处理查询结果的方式，适合刚开始接触MFC数据库编程的Windows开发者参考。压缩包共38个文件，大小约7.01MB，除h/cpp源码和sln/vcxproj等工程文件外，还包含exe可执行程序、dll/lib运行库、db/sql数据库文件以及pdb调试信息，可对照运行和断点学习。已有1338人学习下载，可先运行Release目录中的exe体验效果，再结合源码理解sqlite3_open、sqlite3_exec、sqlite3_close及错误处理等关键接口。示例还给出查询时带回调函数的写法，便于处理逐行返回的大数据量结果；同时涉及同步查询与后台异步查询的区分，对理解MFC界面线程与数据库操作的配合也有帮助。

1. MFC工程要用sqlite3，先想清楚这三件事

MFC工程要用sqlite3，问得最多的其实不是SQL语法，而是怎么把这堆C接口接进MFC的Unicode字符串、资源管理和多线程背景下。过去做MFC工具存配置常写ini，数据一多、查询一复杂就顶不住；换用sqlite3后，一台电脑不用装数据库服务，一个.db文件全搞定，特别适合离线工具、内部管理系统和小型桌面客户端。这篇笔记按一套可复现的MFC+sqlite3例子的落地过程来写：先解决编译连接和字符集，再封装数据访问层，然后给增删改查和二进制存取的范例，最后把最容易踩的坑挨个点名。适合刚开始在MFC里试点SQLite的开发者，也适合准备从文件型存储切到关系型存储的熟手，照着步骤走完，基本能拿到一套能直接改来用的骨架。

2. 接入sqlite3：源码、字符集与三个配置关键点

2.1 源码编译还是DLL：按分发场景选

接触过sqlite3的人都知道，官方给的接入姿态非常灵活，但落到MFC工程里无非两条路。方式A，把sqlite3.c、sqlite3.h拖进工程，当成普通源文件参与编译；方式B，链接预编译好的sqlite3.dll和配套lib。两者在调用层没有任何区别，都是sqlite3_open、sqlite3_prepare_v2那一套API，真正拉开差距的是运行时依赖和调试体验。

大部分时候我推荐源码编译方式。第一，交付时只带一个exe，给同事拷工具不怕漏带DLL；第二，断点能直接进sqlite3的C源码，遇到SQLITE_BUSY、SQLITE_CORRUPT这类返回码时可以直接看内部状态；第三，SQLITE_THREADSAFE这种编译期选项完全由自己控制，不会被预编译包预设的值带偏。缺点只有一个，工程编译时间会多个十几秒到几十秒，日常开发完全能接受。

DLL方式适合对exe体积敏感、或者团队里已经有统一DLL组件库的场景。用它省了编译时间，但多出来的是部署心智，调试时偶尔会遇到“明明DLL放在exe旁边，程序还是报找不到”的灵异现场。这类问题通常出在VS调试目录没有指向exe输出目录，或者系统PATH里捡到了一个旧版本DLL，排查起来特别消耗耐心。

2.2 MFC字符集与sqlite3的UTF-8契约

这一节是整套例子里最容易被忽略的部分。MFC工程默认按Unicode字符集编译，CString底层是UTF-16LE宽字符；而sqlite3对外文本接口统一按UTF-8处理，sqlite3_open的第一个参数、sqlite3_bind_text的文本参数、sqlite3_column_text返回的字符串，全部默认视为UTF-8。两端编码不一致，强制转换不做的话，结果就是中文路径打不开数据库、中文数据写入后再读变成问号。

处理思路是在数据访问层统一做转换，而不是在业务代码里到处写转码。打开数据库时，标准写法是这样的：

CString dbPath = _T("D:\\工具数据\\local.db"); // CW2A 将 UTF-16 宽字符 CString 转为 UTF-8 的 CStringA CStringA utf8Path = CW2A(dbPath, CP_UTF8); sqlite3* db = nullptr; int rc = sqlite3_open(utf8Path, &db); if (rc != SQLITE_OK) { // sqlite3_errmsg 返回的也是 UTF-8，展示前要逆转换成宽字符 CString errMsg = CStringFromUtf8(sqlite3_errmsg(db)); AfxMessageBox(errMsg); if (db) { sqlite3_close(db); db = nullptr; } }

逻辑说明：sqlite3_open要求UTF-8路径，这里先用CW2A把宽字符CString转成CStringA，再交给接口。错误信息从sqlite3_errmsg返回时同样是UTF-8编码，里面的中文在弹窗前必须转回宽字符，否则对话框里全是乱码。参数说明：CP_UTF8是Windows代码页常量，表示按UTF-8编解码；sqlite3_errmsg返回的是连接内部的静态缓冲区，不需要手动释放，但拿到指针后要尽快转存，后续任何sqlite3调用都可能覆盖它。

如果工程里同时存在CStringA和CStringW的混用，建议把两个方向的转换收拢成独立函数，业务层只认这两个入口：

// 宽字符 CString -> UTF-8 CStringA CStringA Utf8FromCString(const CString& text) { return CW2A(text, CP_UTF8); } // UTF-8 char* -> 宽字符 CString CString CStringFromUtf8(const char* utf8Text) { return CA2W(utf8Text, CP_UTF8); }

这两个函数放进公共工具模块后，后面所有sqlite3相关调用都走它们，编码问题基本就隔离了。

2.3 工程配置的三个关键点

把sqlite3源码加进MFC工程后，还有三个配置细节要检查到位。

第一，预编译头处理。MFC工程默认开了预编译头，sqlite3.c直接加进去，如果没做处理，编译时会报“无法找到预编译头文件”。解决办法是选中sqlite3.c，在属性页里把它单独设成“不使用预编译头”，或者干脆在sqlite3.c顶部的宏定义区域加一句强制跳过预编译头。我一般选前者，改文件不如改工程配置。

第二，字符集设置。工程属性里的“字符集”如果是“使用Unicode字符集”，上面第2.2节的转换代码原样可用；如果项目老，还停留在“使用多字节字符集”，这时候CString本身是CStringA，CW2A依然能编译，但中间会绕一次从char到wchar再到char的转换，白耗性能。多字节工程里直接用char* + sqlite3_bind_text反而更直接。

第三，SQLITE_THREADSAFE宏。sqlite3的线程模式在编译期决定。源码编译时系统默认值是1，即串行模式，多线程调用安全，但同一时刻只有一个线程能进入sqlite3内部操作；如果链接的DLL当初以SQLITE_THREADSAFE=0编的，那你在线程池里同时调用就可能崩。我在工程属性里加了一条预处理定义SQLITE_THREADSAFE=1，强制走串行模式，后续在后台线程里操作数据库省心得多。

2.4 最小验证：建表并确认返回值

配置全部完成后，先做一个最小验证，确认整条链路已经通了：

const char* sql = "CREATE TABLE IF NOT EXISTS user_info (" "id INTEGER PRIMARY KEY AUTOINCREMENT," "name TEXT NOT NULL," "score INTEGER DEFAULT 0)"; char* errMsg = nullptr; int rc = sqlite3_exec(db, sql, nullptr, nullptr, &errMsg); if (rc != SQLITE_OK) { CString msg = CStringFromUtf8(errMsg ? errMsg : "unknown error"); AfxMessageBox(msg); sqlite3_free(errMsg); }

逻辑说明：sqlite3_exec适合执行不带结果集返回、不带参数的DDL语句，这里用来创建user_info表。errMsg由sqlite3内部通过malloc分配，使用后必须调用sqlite3_free释放，否则每个失败操作都会泄漏一块内存。参数说明：四个参数分别是“数据库句柄、SQL文本、回调函数指针、回调上下文”；回调参数和上下文传nullptr即可，因为建表不需要处理行数据。

这一步能正常跑通，就说明sqlite3核心、字符集转换、返回码检查三件事都已经就位，可以开始封装了。

3. 封装数据访问层：让MFC代码别再裸写sqlite3查询

3.1 为什么必须包一层

网上搜MFC+sqlite3例子，会看到大量直接在按钮事件里写sqlite3_open、sqlite3_prepare、sqlite3_step的代码。这种写法临时验证没问题，但项目一旦有十几个窗口、几十个查询，代码就变成黑匣子：statement忘了释放、返回码散落在各处、错误信息只能靠断点看。所以我通常把sqlite3的C接口包成两层：连接会话层和语句层。

连接层负责sqlite3的打开、关闭、错误信息提取，业务窗口永远不直接持有sqlite3；语句层负责prepare、bind、step、finalize的完整生命周期。这样UI层写出来的是接近业务语义的代码，比如db.Execute(sql)、db.QueryRows(sql, params)，而不是满屏的C接口调用。

3.2 连接会话类 CDbSession

先看头文件，接口尽量收敛，暴露给外面调用的方法越少越好：

class CDbSession { public: CDbSession(); virtual ~CDbSession(); bool Open(const CString& dbPath); void Close(); bool Execute(const CString& sql); sqlite3* GetHandle() const { return m_db; } CString GetLastError() const; private: sqlite3* m_db; CString m_lastError; };

实现文件里，Open负责UTF-8路径转换和sqlite3_open，失败时记下错误信息：

bool CDbSession::Open(const CString& dbPath) { Close(); // 先清理上次可能残留的连接 CStringA utf8Path = CW2A(dbPath, CP_UTF8); int rc = sqlite3_open(utf8Path, &m_db); if (rc != SQLITE_OK) { m_lastError = CStringFromUtf8(sqlite3_errmsg(m_db)); sqlite3_close(m_db); m_db = nullptr; return false; } return true; } void CDbSession::Close() { if (m_db) { sqlite3_close(m_db); m_db = nullptr; } }

逻辑说明：m_db在打开失败后必须置空，否则析构时Close会对同一个指针二次关闭。sqlite3_open成功时，句柄内部引用计数加一；失败时，sqlite3_errmsg拿到的错误信息仍然有效，但随后sqlite3_close会立刻释放连接，所以错误信息要先拷贝到CString里再关。很多裸写代码在这里翻车，直接用sqlite3_errmsg的返回值拼完了再close，顺序反了，拿到的是被释放的内存。

3.3 语句类 CDbStatement

为了避免sqlite3_stmt泄漏，写一个RAII风格的语句包装。析构函数负责finalize，业务函数只关心绑定参数和取列值：

class CDbStatement { public: CDbStatement() : m_stmt(nullptr) {} ~CDbStatement() { if (m_stmt) sqlite3_finalize(m_stmt); } bool Prepare(sqlite3* db, const CString& sql); void BindInt(int index, int value); void BindText(int index, const CString& value); bool StepRow(); void Reset(); int GetInt(int col); CString GetText(int col); private: sqlite3_stmt* m_stmt; };

Prepare和Bind的典型实现如下：

bool CDbStatement::Prepare(sqlite3* db, const CString& sql) { CStringA utf8Sql = CW2A(sql, CP_UTF8); int rc = sqlite3_prepare_v2(db, utf8Sql, -1, &m_stmt, nullptr); return rc == SQLITE_OK; } void CDbStatement::BindText(int index, const CString& value) { CStringA utf8Value = CW2A(value, CP_UTF8); // SQLITE_TRANSIENT 表示 sqlite3 内部拷贝一份，局部变量销毁不影响后续执行 sqlite3_bind_text(m_stmt, index, utf8Value, -1, SQLITE_TRANSIENT); }

逻辑说明：prepare_v2的第三个参数传-1，表示按SQL文本的完整长度处理，不用手动数字节数；最后一个参数pzTail传nullptr，表示不关心SQL文本末尾是否还有未解析的内容。BindText最容易出错的地方是第五个参数：utf8Value是局部变量，函数返回后内存立即失效，所以这里绝不能传SQLITE_STATIC，必须传SQLITE_TRANSIENT，让sqlite3在绑定的瞬间把文本数据拷贝到自己的内部缓冲区。

3.4 错误信息统一出口

会话类和语句类的所有方法，失败时统一把错误记到m_lastError。业务层出现异常操作后，调GetLastError去弹窗或写日志。

有些开发者习惯在每个sqlite3调用后自己弹一个AfxMessageBox，我见过不少MFC工程这么干，一点都不推荐。第一，弹窗会打断用户操作，SQLITE_BUSY这种瞬时错误弹一次就够了；第二，弹窗信息无法留痕，事后排查还是要靠日志。所以错误统一收口到会话层，界面只关心“这次操作有没有成功”，具体原因交给日志文件。

4. 增删改查落地：参数绑定、结果集读取与二进制存取

4.1 参数绑定代替SQL拼接

MFC里最容易出问题的写法是用CString::Format拼SQL，例如：

CString sql; sql.Format(_T("INSERT INTO user_info(name, score) VALUES('%s', %d)"), name, score);

这段代码在用户名为“O'Brien”时直接语法错误，更别提把SQL语句拼接到日志里去查问题。参数绑定是更稳的做法，sqlite3官方接口就支持：

bool InsertUser(CDbSession& db, const CString& name, int score) { CDbStatement stmt; if (!stmt.Prepare(db.GetHandle(), _T("INSERT INTO user_info(name, score) VALUES(?, ?)"))) { return false; } stmt.BindText(1, name); // 参数索引从1开始 stmt.BindInt(2, score); return stmt.StepRow(); // 执行INSERT，返回false表示完成 }

逻辑说明：SQL文本里的问号是占位符，sqlite3_bind_xxx系列函数负责把实际值绑上去。BindText内部已经做了UTF-8转换，业务层不再关心编码。参数说明：绑定索引从1开始，不是0；第2个参数score是整数，没有编码问题，直接BindInt。StepRow的返回值在这里表示是否取到行，INSERT没有结果集，返回false恰恰说明执行成功。如果SQL执行失败，错误信息会留在会话层的m_lastError里。

4.2 查询结果提取与类型转换

查询场景需要一个稍完整的结果集结构。简单做法是返回“行列表”，每行里面按列名取值：

struct UserRow { int id; CString name; int score; }; bool QueryUsers(CDbSession& db, CArray<UserRow, UserRow>& results) { CDbStatement stmt; if (!stmt.Prepare(db.GetHandle(), _T("SELECT id, name, score FROM user_info ORDER BY id"))) { return false; } results.RemoveAll(); while (stmt.StepRow()) { UserRow row; row.id = stmt.GetInt(0); row.name = stmt.GetText(1); row.score = stmt.GetInt(2); results.Add(row); } return true; }

逻辑说明：StepRow每调用一次让sqlite3_stmt前进到下一行，返回true表示还有数据，返回false表示行取完或出错。GetInt和GetText内部的实现分别调用sqlite3_column_int和sqlite3_column_text，列索引从0开始，与SELECT语句里的列顺序一致。特别提醒：sqlite3_column_text返回的char*指针只在下一次sqlite3_step或sqlite3_reset之前有效，所以在GetText实现里必须立刻把它转成CString拷贝走，绝不能存下指针后面再用。

4.3 BLOB字段读写图片与文件

业务里偶尔要把图片、附件塞进数据库。sqlite3对二进制数据用BLOB类型存储，绑定和读取都有专门接口：

// 写入二进制数据（如文件内容） CFile file; if (file.Open(_T("D:\\temp\\avatar.png"), CFile::modeRead)) { ULONGLONG len = file.GetLength(); BYTE* buf = new BYTE[(size_t)len]; file.Read(buf, (UINT)len); CDbStatement stmt; stmt.Prepare(db.GetHandle(), _T("UPDATE user_info SET avatar = ? WHERE id = ?")); // SQLITE_TRANSIENT：sqlite3 内部拷贝一份，buf 释放不影响数据 sqlite3_bind_blob(stmt.GetHandle(), 1, buf, (int)len, SQLITE_TRANSIENT); stmt.BindInt(2, userId); stmt.StepRow(); delete[] buf; }

读取时用sqlite3_column_bytes拿长度，sqlite3_column_blob拿指针，再memcpy出来转存到CByteArray或直接写文件。逻辑说明：bind_blob和bind_text一样，第五个参数用SQLITE_TRANSIENT让sqlite3内部拷贝数据，缓冲区用完即可释放。读取端指针同样只在下一次step前有效，需要立刻拷贝。

5. 避坑报告：MFC+sqlite3组合里的五个真实翻车记录

5.1 数据库文件打不开，返回值却是SQLITE_OK

现象：sqlite3_open执行后rc返回SQLITE_OK，没有报错，但紧接着建表、插入全部失败，错误信息是“unable to open database file”。头两次遇到这个问题容易在返回值上绕圈，明明第一步没报错，后面全挂。

原因：sqlite3_open的行为是“路径指向的文件不存在时自动创建”，但如果路径的目录不存在，或者路径字符串里包含了文件名之外的非法字符，open阶段能通过，真正读写时才发现文件根本没落盘。MFC里常见的触发点是CString转UTF-8时用了ANSI代码页，中文目录名被转成GBK存进数据库路径，数据库实际写到另一个名字去了，后续操作全对着错误路径操作。

解决：在调用sqlite3_open之前，先检查目录是否存在，用PathFileExists或者直接判断父目录。对路径字符串做预处理，统一走CW2A(dbPath, CP_UTF8)，不要图省事用(W2A)默认转换。还有一点，sqlite3_open返回后马上调用sqlite3_errmsg(db)确认是否是SQLITE_OK，正常情况是“not an error”。

5.2 中文数据写入后读出来全是问号

现象：界面输入中文用户名，insert后马上select，表格里显示“？？？”或者“口口口”。数据库里用十六进制工具查看，存的字节和输入完全对不上。

原因：绑定参数时把CString直接传给了sqlite3_bind_text，没有转UTF-8。CString在Unicode工程下是UTF-16LE，sqlite3按UTF-8去解析，高低字节被拆开重组，出来全是乱码。另一种常见触发点是错误地用了CString::GetBuffer返回的指针绑文本，然后把SQLITE_STATIC传给了第五个参数，局部缓冲销毁后sqlite3内部还引用着原地址。

解决：所有文本参数进出数据库都要经过封装层的Utf8FromCString和CStringFromUtf8两个函数，不要在业务代码里做裸转换；绑定文本一律使用SQLITE_TRANSIENT，让sqlite3拷贝数据，不要依赖外部缓冲区的生命周期。

5.3 sqlite3_close返回SQLITE_BUSY，数据库文件一直在占用

现象：程序退出后，数据库文件被占用，无法手动复制或删除，任务管理器里看进程已经结束，但.db文件仍然被某个句柄锁住。

原因：某个sqlite3_stmt执行完之后只调用了sqlite3_reset，没有调sqlite3_finalize。reset只是把语句状态重置回初始状态，占用的连接资源没有释放；close时检测到还有未完成的语句，返回SQLITE_BUSY，连接也不关闭。MFC程序里窗口销毁和线程退出的时序一乱，这类泄漏特别隐蔽，Debug跑几小时才出现一次。

解决：给CDbStatement写析构函数，析构里强制sqlite3_finalize。封装之后业务层不需要记得finalize，语句对象出作用域就自动释放。如果还有什么临时手写的sqlite3_stmt裸指针，务必养成prepare和finalize成对出现的习惯。

5.4 后台线程复用同一个连接时崩溃或报locked

现象：程序开了后台工作线程做批量导入，同时UI线程偶尔要查询数据，同一个CDbSession连接被两个线程交替使用，跑几十次后要么崩溃，要么报“database table is locked”。

原因：sqlite3的串行模式保证SQL层面的线程安全，但它不等于“多线程共享同一个sqlite3*并发操作”。多个线程在同一时间用同一个连接prepare不同的语句，即使SQLITE_THREADSAFE=1也不能保证跨语句的资源互不干扰。加上UI线程和后台线程的调用时序一旦交错，WAL模式下还可能碰到锁等待超时。

解决：两条路选一条，要么给CDbSession加临界区，让每个sqlite3操作序列在锁内完成；要么干脆每个线程单独Open一个连接。我一般选后者，MFC工具类程序的连接数不大，独立连接省去锁竞争，也避免了跨线程传递SQLITE_HANDLE的隐性问题。

5.5 批量插入几千行耗时爆炸，UI卡死几秒

现象：程序里循环insert一百条数据，每一条都是单条INSERT语句，插入到五百条的时候UI直接卡死几秒钟。Release和Debug表现还不一样，Release下更容易崩。

原因：每条INSERT默认自动提交一个事务，意味着每插一条就做一次磁盘写入同步，几千行就是几千次fsync。Release崩的原因常和语句泄漏糅合在一起，Debug下对象销毁慢，时序被掩盖，Release下指针释放提前，触发访问野指针。

解决：批量写入时手动包一个事务，外面加BEGIN，全部插入完成后再COMMIT。一个事务里几千条insert会快到接近内存操作。至于Release表现不一致，先把语句泄漏修干净，然后确认绑定参数是SQLITE_TRANSIENT，再谈优化。批处理代码在下一章给出。

6. 进阶收尾：事务批量写、WAL与备份检查

6.1 批量写入的最终形态

外面包一层事务，批量插入的耗时能压缩到原来的十分之一甚至更低：

db.Execute(_T("BEGIN")); for (int i = 0; i < itemCount; i++) { CDbStatement stmt; stmt.Prepare(db.GetHandle(), _T("INSERT INTO log_table(tag, content) VALUES(?, ?)")); stmt.BindText(1, tagArray[i]); stmt.BindText(2, contentArray[i]); stmt.StepRow(); } db.Execute(_T("COMMIT"));

注意中途出错时的处理，我一般在循环里判断StepRow返回值，遇到失败就执行ROLLBACK并记录日志。事务开着不做回滚，连接会一直持有写锁，其他线程的读操作会被卡住，这个状态最容易忽略。

6.2 WAL模式与锁等待

建库后立刻执行一条PRAGMA，把连接切到WAL模式：

sqlite3_exec(db, "PRAGMA journal_mode=WAL;", nullptr, nullptr, nullptr); sqlite3_exec(db, "PRAGMA busy_timeout=3000;", nullptr, nullptr, nullptr);

WAL模式的好处是读写不互相阻塞，桌面工具里后台写数据时UI线程还能正常查询。busy_timeout设为3000毫秒，遇到锁冲突先等三秒而不是立刻报错。代价是会多生成.db-wal和.db-shm两个文件，交付时别漏掉，否则另一台机器无法读到最新数据。

6.3 交付前备份检查

每轮版本交付前，我都会在测试版里加一段自检逻辑：先执行PRAGMA integrity_check，确认数据库完整性；再执行一次checkpoint，让WAL文件内容合并回主库，最后把.db文件复制出去留档。这套动作跑完才敢把工具交给别人用，不然对方拷走的数据很可能缺了WAL里还没合并的记录。

从那以后我每次交付MFC工具程序前，都强制走一遍“完整性检查、WAL合并、文件复制”的流程，数据类的坑基本不再找上门。希望这套经验能帮到你，少走两趟弯路。

本文还有配套的精品资源，点击获取