简介qt-sqlite-database是一个基于Qt与SQLite的分层架构示例项目围绕数据库连接DBC、数据访问对象DAO和值对象VO三层设计使业务逻辑与SQL操作解耦适合中高级Qt开发者参考。压缩包共21个文件以10个cpp源文件和9个h头文件为主另含sqlite.db数据库和.pro工程文件体积仅4KB。已有3935人学习通过DatabaseManage类可掌握QSqlDatabase连接管理、DAO封装增删改查、VO层间传值等关键写法sqlite.db文件也便于直接运行验证是理解Qt数据库分层编程的实用范例。代码注释详细适合直接作为项目参考。1. 先说结论qt-sqlite-database 解决的不只是“存数据”而是本地数据的检索、并发与迁移做过桌面工具类应用的人应该都有这种感觉项目刚起步时用 JSON 文件存配置、存记录简单直接等到数据量上了几万条每次启动全量加载变得肉眼可见地慢而且改一条记录要把整个文件重写一遍。我早期的几个 Qt 项目就是在这个阶段开始切到 SQLite 的。qt-sqlite-database 看起来只是“Qt 里接入 SQLite 数据库”它真正替开发者解决的是四件事结构化查询、事务性写入、多线程安全访问、以及后续的数据库结构升级。这个方向适合正在做桌面客户端、离线工具、产线数据采集这类应用的开发者也适合从一开始就想避免“数据文件越写越大、越写越乱”的 Qt 新人。SQLite 不是银弹但在单文件、零配置、跨平台的本地存储场景里它确实是 Qt 生态里最值得投入的一条路。这篇文章不去讲概念直接把我平时在项目里怎么建连接、怎么写 CRUD、怎么处理多线程、以及踩过哪些坑整理出来。2. 连接与初始化为什么单独给 SQLite 建一个连接管理模块很多第一次写 Qt 数据库代码的开发者会直接在业务代码里调用QSqlDatabase::addDatabase(QSQLITE)然后把数据库路径随手一填跑通了就再也不管连接这件事。这个做法在小 Demo 里没问题一旦进入真实项目连接名冲突、工作目录变化、多线程误用这些问题会一个接一个冒出来。所以我一般会把连接管理单独抽成一个模块先想清楚三个问题选型边界、连接命名、连接选项。2.1 选型先立住SQLite 在 Qt 生态里最适合哪类场景Qt 的 SQL 模块同时支持 MySQL、PostgreSQL、SQLite 等数据库但前两者需要独立的数据库服务进程安装、运维、网络连接都是额外的负担。对桌面应用和工具类软件来说用户拿到的只是一个可执行文件和若干数据文件指望用户去装一个数据库服务并不现实。SQLite 是嵌入式数据库整个数据库就是一个普通文件Qt 的 QSQLITE 驱动直接通过 SQLite 的 C 接口读写不需要网络、不需要鉴权、不需要服务守护进程。我选择 SQLite 的判断标准很朴素单机应用、写入频率不超过每秒几十次、数据量在几 GB 以内、需要 SQL 查询能力这四条满足的话SQLite 就是最省心的选择。数据量超过几 GB、或者有大量并发写入、或者需要多个客户端同时访问同一份数据的时候SQLite 的边界就很明显了。它的锁粒度是数据库级别的写操作会锁住整个库并发一高就频繁报database is locked。另外如果应用需要支持多用户通过网络共享数据SQLite 也不是合适的方案。把这些边界想清楚再动手后续的路会顺很多。2.2 初始化连接的代码模板连接名、路径和三个连接选项我习惯在程序启动阶段创建主线程的连接用带前缀的连接名避免 Qt 内部默认连接和业务连接混在一起。下面这段代码是我项目里的初始化模板#include QSqlDatabase #include QSqlError #include QDir #include QStandardPaths QString getDatabasePath() { // 优先使用系统约定的应用数据目录而不是可执行文件目录 QString dataDir QStandardPaths::writableLocation( QStandardPaths::AppDataLocation); QDir().mkpath(dataDir); // 目录不存在时主动创建 return dataDir /app.db; } QSqlDatabase createDatabaseConnection(const QString connName) { QSqlDatabase db QSqlDatabase::addDatabase(QSQLITE, connName); db.setDatabaseName(getDatabasePath()); // 等待锁的毫秒数并发写时不立刻失败而是等对方释放锁 db.setConnectOptions(QSQLITE_BUSY_TIMEOUT5000); if (!db.open()) { // 生产环境这里应该落到日志文件里 qWarning() open database failed: db.lastError().text(); } return db; }代码里有两个关键点。第一是QStandardPaths::AppDataLocation这个路径在不同系统上有不同映射比如 Windows 上是“AppData 目录下的固定子目录”Linux 上是~/.local/share。用它的好处是数据库文件有稳定的落点目录不存在时先用mkpath创建。很多“数据库文件找不到”的问题根源就是用了相对路径而运行时的工作目录不是开发者预想的位置。第二是setConnectOptions(QSQLITE_BUSY_TIMEOUT5000)这是 Qt 给 QSQLITE 驱动提供的连接选项设置 SQLite 在拿不到写锁时最多等待 5000 毫秒。不设这个值SQLite 的默认 busy timeout 在很多编译版本下是 0一旦有另一个连接正在写库立刻返回database is locked。补充一点addDatabase的第二个参数是连接名连接名是全局注册表里的标识。不传连接名就落到默认连接qt_sqlite_connection_default上。默认连接和自定义连接不能混用多线程场景下每个线程只能操作自己创建的连接这就是我坚持传入connName的原因。2.3 连接的生命周期不随手关闭也不让连接泄漏连接什么时候关闭、什么时候移除在 Qt 里有一套严格的顺序。QSqlDatabase本身是一个值类型内部指向一个共享的连接句柄真正持有连接的是 Qt 的全局连接表。关闭连接的常见做法是调用db.close()但要彻底从连接表里移除必须调用QSqlDatabase::removeDatabase(connName)。而且调用removeDatabase之前该连接关联的所有QSqlQuery对象必须已经销毁连接本身已经 close否则 Qt 会在控制台输出警告并拒绝移除。我处理这个问题的习惯是在数据库管理模块里封装一个releaseConnection方法把 close 和 removeDatabase 成对调用避免在业务代码里零散地关闭连接。void releaseDatabaseConnection(const QString connName) { { // 这个作用域确保最后一段代码执行后该连接下不再有 query 实例 QSqlDatabase db QSqlDatabase::database(connName); if (db.isOpen()) { db.close(); } } QSqlDatabase::removeDatabase(connName); }这段代码先是取出连接并关闭当变量db在作用域结束时Qt 里该连接的所有持有者引用都已释放这时再调用removeDatabase就不会触发 “connection is still in use”。真实项目中我会在数据库管理类的析构函数或者路由切换数据库时调用它这个顺序几乎不会变。3. 建表与 CRUD把落地代码写成可维护的模板连接建立之后下一个问题就是建表和增删改查。很多 Qt 项目的表结构没有统一管理有人用可视化工具建表有人在代码里写裸 SQL还有人在运行时exec拼接出来的字符串。我采用的方式是把 DDL 脚本集中在代码里启动时统一执行并且所有 SQL 语句都带IF NOT EXISTS保证幂等。3.1 DDL 建表与 SQLite 字段类型映射SQLite 是弱类型系统但 Qt 的 QSQLITE 驱动会把 C 类型映射成 SQLite 类型。下面是我常用的建表语句QSqlQuery createTableQuery(db); bool ok createTableQuery.exec( CREATE TABLE IF NOT EXISTS note ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, content TEXT DEFAULT , created_at INTEGER NOT NULL )); if (!ok) { // 处理建表失败通常是权限或路径问题 }id INTEGER PRIMARY KEY AUTOINCREMENT是 SQLite 里的自增主键写法和 MySQL 的AUTO_INCREMENT不同SQLite 要求主键必须是INTEGER PRIMARY KEY才能自增故意不加UNIQUE或使用TEXT PRIMARY KEY都不会触发自增行为。created_at我用的不是DATETIME类型而是INTEGER存 Unix 时间戳。这样排序、比较、计算时间范围都方便也没有时区问题。SQLite 没有真正的DATETIME类型即使建表写DATETIME实际存储的还是 TEXT 或数字。建表的执行时机放在数据库连接 open 之后、业务代码开始之前。每次启动都执行一遍IF NOT EXISTS不会重复建表也不会有副作用。3.2 参数绑定替代字符串拼接从增删改查到查询遍历我在代码审查里见过不少用字符串拼接 SQL 的例子比如QString(SELECT * FROM note WHERE title %1).arg(title)。这个写法最直接的问题是引号、转义、注入尤其是字段内容里出现单引号或反斜杠时SQL 语句直接就是错的。改用prepare加bindValue之后这些问题全部由驱动层解决代码也更容易读。下面是一组标准的插入和查询写法// 插入一条记录并取回自增主键 QSqlQuery insertQuery(db); insertQuery.prepare( INSERT INTO note(title, content, created_at) VALUES(?, ?, ?)); insertQuery.addBindValue(title); insertQuery.addBindValue(content); insertQuery.addBindValue(QDateTime::currentSecsSinceEpoch()); if (!insertQuery.exec()) { // 上报错误不再继续 } int newId insertQuery.lastInsertId().toInt();// 按标题关键词查询遍历结果集 QSqlQuery query(db); query.prepare(SELECT id, title, created_at FROM note WHERE title LIKE ?); query.addBindValue(% keyword %); if (!query.exec()) { // 处理查询失败 return {}; } QVectorNoteItem results; while (query.next()) { NoteItem item; item.id query.value(0).toInt(); item.title query.value(1).toString(); item.createdAt query.value(2).toInt(); results.append(item); }这里addBindValue按顺序绑定?占位符顺序不能乱。lastInsertId()在 SQLite 驱动里返回的就是自增字段的值前提是表里有INTEGER PRIMARY KEY或INTEGER PRIMARY KEY AUTOINCREMENT。查询时query.next()每调用一次前进到下一行读字段可以用query.value(columnIndex)。要注意query.value()返回的是QVariant读取后需要转换到目标类型转换失败会得到默认值所以字段顺序和类型定义要保持一致。3.3 批量写入必须开事务实测差异与事务的边界SQLite 默认每执行一条写语句都会自动开启一个隐式事务并在语句结束时提交。这意味着如果循环插入一万条数据就会执行一万次文件写入和一万次 fsync速度慢得让人怀疑机器出了问题。把一批写入包在一个事务里之后SQLite 只在 commit 时刷一次盘性能差距可以在几十倍。我一般这样处理批量插入QSqlDatabase db QSqlDatabase::database(connName); if (!db.transaction()) { // 事务开启失败通常是已有事务未结束 return false; } QSqlQuery insertQuery(db); insertQuery.prepare( INSERT INTO note(title, content, created_at) VALUES(?, ?, ?)); foreach (const NoteItem item, items) { insertQuery.addBindValue(item.title); insertQuery.addBindValue(item.content); insertQuery.addBindValue(item.createdAt); if (!insertQuery.exec()) { db.rollback(); // 出错时回滚整个批次 return false; } } if (!db.commit()) { db.rollback(); return false; }这段代码的思路是重复执行同一条 prepared statement每轮循环重新绑定值再execSQLite 会复用语句的执行计划省去反复解析 SQL 的开销。注意addBindValue每次循环都会覆盖之前的绑定值不需要重建语句。事务有一个边界SQLite 不支持嵌套事务。如果在transaction()还没有commit()或rollback()的时候再次调用transaction()函数返回 false并且 Qt 会把错误信息打到lastError()里。所以在封装写入方法时我会先判断当前连接是否已经在事务中代码里用一个成员变量记录事务状态避免调用方嵌套使用。4. 多线程访问与写锁Qt 里 SQLite 最容易翻车的区域单线程读写跑通之后接下来遇到的就是多线程。Qt 的 GUI 线程和业务线程天然就是多线程环境数据库操作如果直接跨线程共享同一个QSqlDatabase对象很快会出现connection is not open、崩溃或者数据错乱。这个问题必须在设计阶段就处理好。4.1 一个线程一个连接QSqlDatabase 的线程归属规则Qt 对 QSQLITE 驱动有一条硬性约束一个QSqlDatabase连接只能被创建它的线程使用。在 Qt 的文档里这个规则表述为连接绑定到创建它的线程的事件循环和上下文另一个线程去调用这个连接上的查询行为是未定义的实际表现就是连接不可用。正确的做法是每个线程自己创建连接、自己打开、自己关闭连接名用线程标识区分。void WorkerThread::run() { QString connName QStringLiteral(worker_) QString::number(reinterpret_castquintptr( QThread::currentThreadId())); QSqlDatabase db QSqlDatabase::addDatabase(QSQLITE, connName); db.setDatabaseName(dbPath); db.setConnectOptions(QSQLITE_BUSY_TIMEOUT5000); if (!db.open()) { // 线程内记录错误 return; } // 在线程内执行一系列查询 doWork(db); // 线程结束前关闭连接 db.close(); // 注意query 对象必须在下面这行之前全部析构 { QSqlDatabase::removeDatabase(connName); } }这里有两个细节。第一连接名用QThread::currentThreadId()转成字符串来保证唯一避免两个线程用同一个名字注册连接导致其中一个失效。第二removeDatabase必须在db.close()之后调用而且该连接下的所有QSqlQuery都已经不存在。我在doWork里会把查询限制在局部作用域这样函数返回时 query 对象已经析构不会干扰后续的 removeDatabase。线程里对数据库的访问只经过这个线程创建的连接就绕开了“跨线程使用 QSqlDatabase”这条红线。4.2 WAL 模式和 busy_timeout缓解锁冲突的两个旋钮即使每个线程一个连接SQLite 的锁机制仍然会让写操作互相阻塞。默认的 rollback journal 模式下写操作持有数据库文件的排他锁期间任何其他连接想要写库都会失败。解决这个问题有两个层面的配置第一个是前面已经提过的QSQLITE_BUSY_TIMEOUT它让写操作在拿不到锁时等待而不是立即报错第二个是开启 WAL 模式。QSqlQuery configQuery(db); configQuery.exec(PRAGMA journal_modeWAL;); configQuery.exec(PRAGMA synchronousNORMAL;);journal_modeWAL把数据库的写入日志改成 write-ahead logging读操作和写操作不再互相阻塞只有两个写操作之间会有锁竞争。synchronousNORMAL是 WAL 模式下的推荐设置它把崩溃安全级别从最高降到适度换来更快的提交速度。代价是数据库目录下会出现app.db-wal和app.db-shm两个附属文件数据库不再是一个孤立的文件。备份和拷贝数据库时不能简单复制app.db必须用 SQLite 的备份接口或者VACUUM INTO生成一致性的快照。我一般在初始化脚本里统一配置这两条 PRAGMA并把这个配置动作放在建表之前保证连接一打开就是 WAL 模式。5. 避坑Qt SQLite 的五个典型翻车现场与处理记录这一章写的五个问题都是我或者认识的一线开发者在真实项目里踩过的每条都按“现象 → 原因 → 解决”的顺序给你拆开。5.1 database is locked写入并发时的头号报错现象两个线程同时往数据库里写数据其中一个线程的exec()返回 falselastError().text()里出现database is locked。原因SQLite 的写锁是数据库级别的同一时刻只允许一个写事务。另一个连接没有设置 busy timeout或者设置的等待时间太短会在拿锁失败时立刻抛出错误而不是等待对方提交。解决初始化连接时设置setConnectOptions(QSQLITE_BUSY_TIMEOUT5000)让等待时间按业务能接受的上限来设。同时检查是不是有长事务没有提交比如某段代码transaction()之后忘了commit()写锁一直被持有其他连接等再久也没用。我排查这类问题时的习惯是先把所有数据库操作的日志打印出来定位到是哪条语句持有锁。5.2 connection is not open最容易出现在多线程和迁移后的报错现象程序运行一段时间后某一线程里的查询突然报connection is not open或者直接在控制台打印 “QSqlDatabasePrivate::removeDatabase: connection ... is still in use”。原因在一个线程里创建了连接并把QSqlDatabase当作普通对象传到另一个线程使用或者调用removeDatabase时还有QSqlQuery对象指向这个连接导致连接被 Qt 从连接表里移除失败之后该连接名下的所有操作都异常。解决坚持“一个线程一个连接”的规则把QSqlQuery限制在局部作用域内创建和析构销毁顺序严格按“先销毁 query再 close最后 removeDatabase”执行。如果业务代码里确实需要跨线程传递数据应该传数据本身如结构体或者序列化文本不要传数据库连接对象。5.3 中文乱码SQLite 编码与 QString 的边界现象写入数据库的中文直接查看app.db时看到的是一段乱码或者读出来之后 QString 显示为一串问号。原因SQLite 存储文本时只认 UTF-8 和 UTF-16Qt 的QSQLITE驱动在调用 SQLite 接口时默认会把QString转换到 UTF-8。如果上游数据本身就不在 UTF-8 编码里比如从 GBK 编码的文本文件里读取内容再写入转换到 UTF-8 这一步会先产生错误字节序列最终落库的就是乱码。解决保证所有进入数据库的QString在源头就是正确编码读取文件时用QTextStream::setEncoding显式指定文件编码不要依赖系统默认。从数据库读出来再写到终端或文件时同样显式指定 UTF-8。只要源头正确SQLite 这一层不需要额外干预。另外建议在调试时用sqlite3命令行工具以 UTF-8 模式查看库内容能快速判断问题出在哪一环。5.4 数据库文件找不到相对路径与工作目录的坑现象开发环境下程序正常运行双击部署版本后数据库文件出现在桌面上或者程序创建了一个新库导致原本的数据读不出来。原因代码里用了db.setDatabaseName(app.db)这样的相对路径。SQLite 会把这个路径解析到进程当前工作目录而桌面启动和开发调试的工作目录经常不一样部署后的应用工作目录也可能是系统目录或安装目录导致数据库被创建到意料之外的位置。解决一律使用绝对路径推荐用QStandardPaths::writableLocation(QStandardPaths::AppDataLocation)拼出固定目录并主动建目录。同时要在启动时打印数据库实际路径部署到别的机器上一眼就能看出路径变化。5.5 removeDatabase 与连接名冲突关闭连接的顺序现象程序退出时崩溃或者控制台反复出现 “QSqlDatabasePrivate::removeDatabase: connection ... is still in use” 的警告。原因调用removeDatabase时该连接名下仍然存在QSqlQuery局部变量或者QSqlDatabase对象还没有被完全释放。Qt 的连接表不允许移除一个仍被引用的连接警告输出后连接继续存在下次反复注册同名连接时会触发断言或者崩溃。解决把数据库操作封装在独立的类里统一管理连接生命周期。在类的析构函数或者显式的shutdown()方法中先销毁所有QSqlQuery和QSqlDatabase实例再调用removeDatabase。我在实际代码里用前面 2.2 节那种作用域手法局部变量在函数返回时析构析构后才执行removeDatabase这个顺序几乎没有出过问题。6. 再进一步版本迁移、基准测试与封装习惯数据库在线上跑起来之后最不想遇到的事情就是表结构要加字段数据又不能丢。SQLite 没有原生的表结构变更接口常规做法是依赖PRAGMA user_version做版本号管理。我在项目里的做法是启动时读取PRAGMA user_version然后按版本号顺序执行迁移脚本执行成功后更新版本号。下面是一个简化的迁移函数void runMigrations(QSqlDatabase db) { QSqlQuery query(db); query.exec(PRAGMA user_version); int version 0; if (query.next()) { version query.value(0).toInt(); } if (version 1) { // 迁移到版本 1建表 query.exec(CREATE TABLE IF NOT EXISTS note (...)); query.exec(PRAGMA user_version 1); } if (version 2) { // 迁移到版本 2新增一个字段 query.exec(ALTER TABLE note ADD COLUMN tags TEXT DEFAULT ); query.exec(PRAGMA user_version 2); } }PRAGMA user_version是 SQLite 提供的一个可以由应用自定义的整数。迁移逻辑全部放到这个函数里新版本的代码可以直接让旧版本的数据库文件逐步升级到最新结构避免“删库重来”。基准测试这件事我放在最后说是因为它被很多人忽略。优化 SQLite 性能的帖子很多但真正动手之前最靠谱的做法是先用QElapsedTimer跑一段有代表性的数据量出当前方案的耗时基线。换一种写入策略、调一次PRAGMA配置都拿和之前相同场景的数据重测对比。比如批量插入一万行默认提交和开事务之间的差距量一次就再也不会忘记开事务了。我已经养成的习惯是每个 Qt 项目接数据库先写连接管理模块再写迁移函数然后才是业务查询代码。这个顺序帮我躲掉了无数次“跑得好好的换台机器就崩”的鬼故事。做技术方向的选择最怕的不是做得慢而是方向错了还在坚持。qt-sqlite-database 这条路适合本地单机数据场景它解决的是实际问题只要你不把它硬塞到高并发服务端场景里它能把你的桌面应用打磨得非常顺手。希望帮到你。本文还有配套的精品资源点击获取