如果你用 Qt 写过带列表页的桌面管理工具大概率经历过这种场景项目刚上线时表里只有几千条记录页面秒开翻页也顺滑跑了几个月后数据涨到几百万甚至上千万行某天你打开历史列表程序像被定住一样鼠标转圈两三秒才出数据翻到后面更是“一页比一页慢”。很多人这时候会把锅甩给 SQLite说它不适合千万级数据也有人怀疑是 Qt 表格控件性能太差。我的判断是在 Qt SQLite 这个组合里单表千万级并不算高危场景真正让 UI 卡死的往往是三件事叠加——查询没有走索引、用了大偏移分页、所有数据库操作都挤在 UI 线程。这篇文章围绕 Qt SQLite 的 CRUD 实战把这几件事讲透数据量大之后UI 卡顿的根因到底在哪为什么游标分页比传统LIMIT OFFSET更适合千万级数据在 Qt 里怎么写出可落地的分页、批量写入和异步查询代码。文中示例基于 Qt 5.15 / Qt 6 编写SQLite 是 Qt 自带的QSQLITE驱动不需要额外安装数据库服务。整体偏工程实践适合正在做桌面工具、数据管理系统、设备运维软件的开发者收藏备用。1. 先定位UI 卡顿到底卡在哪里很多项目一遇到“数据量大就卡”第一反应是换数据库、换控件、加缓存。但如果不先定位卡顿根因换什么都救不了。1.1 数据量大不是直接原因SQLite 作为一个嵌入式关系型数据库单表存千万行完全可行。1000 万行、每行平均 100 字节也就是 1GB 左右的文件按索引定位单行数据的时间仍然很快。真正的问题是很多人从来没有“按页取数”的意识而是把整张表一次性读进内存再交给表格控件显示。1000 万行数据哪怕只读字段、不渲染也要产生上千万个QVariant对象和QModelIndexUI 线程不被拖垮才奇怪。所以第一原则很简单列表页永远不要把全表数据一次性塞给 UI。1.2 大偏移 OFFSET 分页的代价入门数据库时分页写法基本都是SELECT id, device_id, record_time FROM trade_record ORDER BY id LIMIT 20 OFFSET 1000000;这条 SQL 看起来没问题但它的执行逻辑是数据库要把前 1000020 行都遍历一遍然后丢弃前 1000000 行只返回最后 20 行。这意味着OFFSET 越大扫描的无用行越多性能越差。当表里有千万行数据时翻到中间和后面单次查询可能要扫几十万甚至上百万行。索引在这里帮不上什么忙因为OFFSET本身就要求数据库“从头数到尾”。1.3 查询和 UI 放在同一个线程Qt 的QSqlQuery默认是同步执行。你在按钮槽函数里执行一次查询主线程会一直阻塞到数据库返回结果。即使你只取 20 条只要数据库内部发生了全表扫描界面就会卡顿。这也是很多新手最容易忽略的一点卡顿不一定来自渲染更可能来自查询本身。把这三条合起来看结论就很清晰了想流畅展示必须分页加载想分页稳定必须避免大偏移想 UI 不卡查询要么够快要么放到非 UI 线程。2. 游标分页原理与适用边界2.1 传统 OFFSET 分页的天然缺陷OFFSET 分页适合数据量小、翻页方式简单的场景。比如后台管理系统的前几页数据量只有几千条用LIMIT 20 OFFSET 40没有任何问题。但数据量一旦到百万、千万级OFFSET 的扫描成本就会成倍上升。核心问题可以概括为每次翻页都要重新“数行数”。2.2 游标分页的思路游标分页也叫 keyset pagination、seeking pagination核心思路是不使用“跳过多少行”而是记住“上一页最后一条记录的位置”下一页从该位置继续向后取。对于以自增主键id排序的列表游标分页的 SQL 非常简单SELECT id, device_id, record_time FROM trade_record WHERE id :lastId ORDER BY id ASC LIMIT :pageSize;首页时:lastId传0因为自增主键从 1 开始。查询后拿到本页最后一条记录的id作为下一页的:lastId。这个查询可以直接命中主键索引时间复杂度和数据总量无关只和“要跳过的目标位置”有关。这就像翻书时你记住上次看到哪一页下次直接翻到那一页继续读而不是每次都从第一页开始数。2.3 游标分页的限制游标分页不是万能的它有两个明显限制不支持随机跳页。你不知道第 100 页的第一条记录id是多少就无法直接跳到第 100 页。排序字段必须唯一且稳定。如果只用ORDER BY record_time而record_time有大量重复值游标就无法唯一定位下一页的起点。所以游标分页最适合的场景是列表连续往下翻、列表页自动加载更多、日志查询、交易流水展示。维度OFFSET 分页游标分页查询性能随页数增长下降稳定与总行数关系小随机跳页支持不支持实现复杂度简单中等适合场景小数据量、后台列表大量数据连续翻页数据库支持所有数据库所有数据库3. 表结构与索引设计游标分页能够高效运行前提是表结构和索引设计正确。这一段非常关键很多项目分页慢不是 SQL 写得不对而是表结构从一开始就没设计好。3.1 主键选择SQLite 中单列INTEGER PRIMARY KEY和“自动递增 AI”有特殊含义它会被当成表内隐藏的rowid的别名查询效率极高。推荐写法CREATE TABLE trade_record ( id INTEGER PRIMARY KEY AUTOINCREMENT, device_id TEXT NOT NULL, record_time INTEGER NOT NULL, status INTEGER NOT NULL DEFAULT 0, amount REAL NOT NULL DEFAULT 0, remark TEXT );如果你不需要严格保证“历史 id 永不复用”也可以去掉AUTOINCREMENTid INTEGER PRIMARY KEYSQLite 同样会自动分配自增 id写入性能略优于带AUTOINCREMENT的写法。在千万级数据场景下优先考虑不带AUTOINCREMENT的表结构。不建议用 UUID 字符串做主键。随机字符串会让索引页不断分裂占用空间大查询和写入都会变慢。业务上需要唯一标识可以单独建立唯一索引。3.2 二级索引设计游标分页只解决“翻页不动全表”的问题数据库仍然要为查询条件过滤数据。所以需要在真实查询条件上建索引。例如应用常见需求是“按设备查询 按时间排序”就可以建复合索引CREATE INDEX IF NOT EXISTS idx_trade_record_device_time ON trade_record(device_id, record_time);如果只是演示游标分页那就确保主键索引存在即可。索引不是越多越好每多一个索引插入时都要多维护一棵 B 树。3.3 开启 WAL 和 busy_timeoutSQLite 默认的日志模式在写并发场景下容易互相锁库。桌面应用推荐开启 WAL 模式PRAGMA journal_modeWAL; PRAGMA busy_timeout3000;WAL 模式允许读操作和写操作在一定程度上并行执行。busy_timeout则避免并发访问时立刻返回“database is locked”。4. 工程环境准备4.1 Qt 工程配置在 Qt 项目中使用 SQLite需要确保引入了 SQL 模块。.pro文件写法如下QT core gui sql widgets CONFIG c17 SOURCES \ main.cpp \ mainwindow.cpp HEADERS \ mainwindow.h在 CMake 工程中则使用find_package(Qt6 COMPONENTS Core Gui Sql Widgets REQUIRED) target_link_libraries(your_app PRIVATE Qt6::Core Qt6::Gui Qt6::Sql Qt6::Widgets)4.2 检查 QSQLITE 驱动如果运行时提示找不到驱动先检查编译环境是否带了 SQLite 驱动插件qDebug() QSqlDatabase::drivers();期望输出中至少包含QSQLITE。如果使用 Windows 发布程序需要把sqldrivers目录下的驱动插件拷贝到可执行文件同级的插件目录否则程序在用户机器上会报driver not loaded。4.3 初始化数据库打开数据库并执行必要的 PRAGMA可以使用下面的代码// 文件路径dbmanager.cpp #include QSqlDatabase #include QSqlQuery #include QSqlError #include QDebug bool initDatabase(const QString dbPath) { QSqlDatabase db QSqlDatabase::addDatabase(QSQLITE); db.setDatabaseName(dbPath); if (!db.open()) { qCritical() open database failed: db.lastError().text(); return false; } QSqlQuery query(db); query.exec(PRAGMA journal_modeWAL;); query.exec(PRAGMA busy_timeout3000;); query.exec(CREATE TABLE IF NOT EXISTS trade_record ( id INTEGER PRIMARY KEY, device_id TEXT NOT NULL, record_time INTEGER NOT NULL, status INTEGER NOT NULL DEFAULT 0, amount REAL NOT NULL DEFAULT 0, remark TEXT );); query.exec(CREATE INDEX IF NOT EXISTS idx_trade_record_device_time ON trade_record(device_id, record_time);); return true; }注意PRAGMA journal_modeWAL;执行后可以用QSqlQuery::value(0)查看返回结果正常应该是wal。不过在很多版本里即使不看返回值数据库文件旁边出现-wal后缀文件也说明 WAL 已生效。5. 游标分页核心代码实现这一段给出真正的核心代码。为提高可读性先用同步版本跑通流程再在后续章节讨论异步改造。5.1 分页结果结构体先定义一个简单的分页结果结构// 文件路径pagereader.h #pragma once #include QVector #include QVariant struct PageResult { QVectorQVectorQVariant rows; // 每行数据 qint64 nextCursor -1; // 下一页游标-1 表示没有更多数据 };5.2 分页查询函数这里的关键是使用主键id作为游标。cursor传入上一页最后一条记录的id首页传0。// 文件路径pagereader.cpp #include pagereader.h #include QSqlDatabase #include QSqlQuery #include QSqlError #include QDebug PageResult loadPageData(qint64 cursor, int pageSize) { PageResult result; QSqlDatabase db QSqlDatabase::database(); if (!db.isOpen()) { qWarning() database is not open; return result; } // pageSize 是程序内部整数不直接拼接用户输入 QString sql QString( SELECT id, device_id, record_time, status, amount, remark FROM trade_record WHERE id :cursor ORDER BY id ASC LIMIT %1).arg(pageSize); QSqlQuery query(db); query.prepare(sql); query.bindValue(:cursor, cursor); if (!query.exec()) { qWarning() query failed: query.lastError().text(); return result; } while (query.next()) { QVectorQVariant row; row query.value(0) query.value(1) query.value(2) query.value(3) query.value(4) query.value(5); result.rows.append(row); } if (!result.rows.isEmpty()) { result.nextCursor result.rows.last().at(0).toLongLong(); } return result; }这个函数完成了游标分页的核心逻辑。WHERE id :cursor让 SQLite 直接利用主键索引定位到游标位置然后向后读取pageSize行。5.3 在窗口类中维护翻页状态窗口类中维护三个状态m_currentCursor当前页的起始游标m_nextCursor当前页最后一条记录的idm_history历史游标栈用于“上一页”。// 文件路径mainwindow.h #pragma once #include QMainWindow #include QStandardItemModel #include QVector #include pagereader.h QT_BEGIN_NAMESPACE namespace Ui { class MainWindow; } QT_END_NAMESPACE class MainWindow : public QMainWindow { Q_OBJECT public: explicit MainWindow(QWidget *parent nullptr); ~MainWindow(); private slots: void onNextPage(); void onPrevPage(); private: void loadCurrentPage(); void showPage(const QVectorQVectorQVariant rows); Ui::MainWindow *ui; QStandardItemModel *m_model; qint64 m_currentCursor 0; qint64 m_nextCursor -1; QVectorqint64 m_history; int m_pageSize 50; bool m_loading false; };// 文件路径mainwindow.cpp #include mainwindow.h #include ui_mainwindow.h MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) , m_model(new QStandardItemModel(this)) { ui-setupUi(this); ui-tableView-setModel(m_model); connect(ui-nextButton, QPushButton::clicked, this, MainWindow::onNextPage); connect(ui-prevButton, QPushButton::clicked, this, MainWindow::onPrevPage); loadCurrentPage(); } MainWindow::~MainWindow() { delete ui; } void MainWindow::onNextPage() { if (m_loading || m_nextCursor 0) { return; } m_history.append(m_currentCursor); m_currentCursor m_nextCursor; loadCurrentPage(); } void MainWindow::onPrevPage() { if (m_loading || m_history.isEmpty()) { return; } m_currentCursor m_history.takeLast(); loadCurrentPage(); } void MainWindow::loadCurrentPage() { m_loading true; PageResult result loadPageData(m_currentCursor, m_pageSize); showPage(result.rows); m_nextCursor result.nextCursor; m_loading false; } void MainWindow::showPage(const QVectorQVectorQVariant rows) { m_model-clear(); m_model-setHorizontalHeaderLabels( {ID, 设备, 记录时间, 状态, 金额, 备注}); m_model-setRowCount(rows.size()); m_model-setColumnCount(6); for (int r 0; r rows.size(); r) { for (int c 0; c rows[r].size(); c) { m_model-setItem(r, c, new QStandardItem(rows[r][c].toString())); } } }这套逻辑的核心在于m_currentCursor是“上一页最后一条 id”而m_nextCursor是“当前页最后一条 id”。每次下一页把当前页的游标压入历史栈再让当前游标等于下一页的起始游标。5.4 为什么这个分页在千万级数据下依然稳定关键在WHERE id :cursor这个条件。SQLite 使用主键索引定位到大于cursor的第一行然后顺序读取pageSize行。这个过程不关心OFFSET是多少万也不关心全表有多少行。理论上只要主键索引存在第 1 页和第 10000 页的查询时间基本在同一量级。这也是游标分页在千万级数据下依然“流畅”的核心原因。6. 批量写入与事务CRUD 不只是查询写操作同样容易成为性能瓶颈。很多人第一次向 SQLite 批量插入数据时都会遇到“插入 3000 条数据竟然要十几秒”的情况。6.1 逐条插入为什么慢SQLite 默认情况下每一条 INSERT 语句都会被当作一个独立事务自动提交。这意味着每条记录都要做一次磁盘同步、一次日志写入、一次 B 树索引更新。正确做法是显式开启事务积累到一定数量再统一提交。6.2 批量插入示例下面是一个批量写入函数。先定义一条业务记录的简单结构struct TradeRecord { QString deviceId; QDateTime recordTime; int status 0; double amount 0.0; QString remark; };批量插入函数// 文件路径recordwriter.cpp #include QSqlDatabase #include QSqlQuery #include QSqlError #include QVector #include QDateTime bool batchInsertRecords(const QVectorTradeRecord records) { QSqlDatabase db QSqlDatabase::database(); if (!db.isOpen()) { return false; } if (!db.transaction()) { return false; } QSqlQuery query(db); query.prepare( INSERT INTO trade_record(device_id, record_time, status, amount, remark) VALUES(?, ?, ?, ?, ?)); for (const TradeRecord r : records) { query.addBindValue(r.deviceId); query.addBindValue(r.recordTime.toSecsSinceEpoch()); query.addBindValue(r.status); query.addBindValue(r.amount); query.addBindValue(r.remark); if (!query.exec()) { db.rollback(); return false; } } return db.commit(); }每次调用exec()时SQLite 实际使用的还是同一个 prepared statement不会重复解析 SQL。加上事务后插入速度往往会提升一个数量级。6.3 存在就更新不存在就新增UPSERT业务中经常遇到“存在就更新不存在就新增”的需求。在 SQLite 3.24 及以上版本可以写INSERT ... ON CONFLICT DO UPDATE。假设device_id有唯一索引CREATE UNIQUE INDEX IF NOT EXISTS ux_trade_record_device ON trade_record(device_id);那么增量写入可以写成INSERT INTO trade_record(device_id, record_time, status, amount, remark) VALUES(?, ?, ?, ?, ?) ON CONFLICT(device_id) DO UPDATE SET record_time excluded.record_time, status excluded.status, amount excluded.amount, remark excluded.remark;在 Qt 的QSqlQuery中同样使用prepare addBindValue exec。判断 SQLite 版本可以用SELECT sqlite_version();如果目标环境版本低于 3.24就需要先查一次记录是否存在再决定走 UPDATE 还是 INSERT这会影响性能但能保证兼容。7. 异步查询与 UI 刷新策略同步版本的游标分页在数据量千万级、单次查询几十毫秒以内时已经可以满足大部分桌面应用体验。但如果你想做到“完全无感知”就需要把查询挪到后台线程。7.1 子线程不能直接复用主线程的连接这是很多 Qt 新手必踩的坑。QSqlDatabase连接默认是主线程创建的如果直接在QtConcurrent::run里用同一个连接执行查询很可能出现QSqlDatabasePrivate::database: requested database does not belong to the calling thread正确做法是后台线程各自创建自己的数据库连接使用不同的连接名连接对象不要跨线程使用。7.2 使用 QThread Worker 的思路这里给出一个思路性示例重点是展示连接的生命周期。实际项目中可以封装成 Worker 类。class QueryWorker : public QObject { Q_OBJECT public slots: PageResult loadPage(qint64 cursor, int pageSize, const QString dbFile) { PageResult result; // 子线程内创建独立连接连接名唯一 QString connName QString(worker_%1).arg(reinterpret_castquintptr(QThread::currentThread())); { QSqlDatabase db QSqlDatabase::addDatabase(QSQLITE, connName); db.setDatabaseName(dbFile); if (!db.open()) { QSqlDatabase::removeDatabase(connName); return result; } QSqlQuery query(db); QString sql QString( SELECT id, device_id, record_time, status, amount, remark FROM trade_record WHERE id :cursor ORDER BY id ASC LIMIT %1).arg(pageSize); query.prepare(sql); query.bindValue(:cursor, cursor); if (query.exec()) { while (query.next()) { QVectorQVariant row; row query.value(0) query.value(1) query.value(2) query.value(3) query.value(4) query.value(5); result.rows.append(row); } } db.close(); } // 确保所有 QSqlQuery 对象销毁后再移除连接 QSqlDatabase::removeDatabase(connName); if (!result.rows.isEmpty()) { result.nextCursor result.rows.last().at(0).toLongLong(); } return result; } };使用QSignalMapper、QFutureWatcher或QThread Worker都可以。只要记住数据库连接不能跨线程共享自定义结构体跨线程传递时需要注册元类型 Qt+SQLite千万级数据卡顿优化：游标分页与高效查询实战
如果你用 Qt 写过带列表页的桌面管理工具大概率经历过这种场景项目刚上线时表里只有几千条记录页面秒开翻页也顺滑跑了几个月后数据涨到几百万甚至上千万行某天你打开历史列表程序像被定住一样鼠标转圈两三秒才出数据翻到后面更是“一页比一页慢”。很多人这时候会把锅甩给 SQLite说它不适合千万级数据也有人怀疑是 Qt 表格控件性能太差。我的判断是在 Qt SQLite 这个组合里单表千万级并不算高危场景真正让 UI 卡死的往往是三件事叠加——查询没有走索引、用了大偏移分页、所有数据库操作都挤在 UI 线程。这篇文章围绕 Qt SQLite 的 CRUD 实战把这几件事讲透数据量大之后UI 卡顿的根因到底在哪为什么游标分页比传统LIMIT OFFSET更适合千万级数据在 Qt 里怎么写出可落地的分页、批量写入和异步查询代码。文中示例基于 Qt 5.15 / Qt 6 编写SQLite 是 Qt 自带的QSQLITE驱动不需要额外安装数据库服务。整体偏工程实践适合正在做桌面工具、数据管理系统、设备运维软件的开发者收藏备用。1. 先定位UI 卡顿到底卡在哪里很多项目一遇到“数据量大就卡”第一反应是换数据库、换控件、加缓存。但如果不先定位卡顿根因换什么都救不了。1.1 数据量大不是直接原因SQLite 作为一个嵌入式关系型数据库单表存千万行完全可行。1000 万行、每行平均 100 字节也就是 1GB 左右的文件按索引定位单行数据的时间仍然很快。真正的问题是很多人从来没有“按页取数”的意识而是把整张表一次性读进内存再交给表格控件显示。1000 万行数据哪怕只读字段、不渲染也要产生上千万个QVariant对象和QModelIndexUI 线程不被拖垮才奇怪。所以第一原则很简单列表页永远不要把全表数据一次性塞给 UI。1.2 大偏移 OFFSET 分页的代价入门数据库时分页写法基本都是SELECT id, device_id, record_time FROM trade_record ORDER BY id LIMIT 20 OFFSET 1000000;这条 SQL 看起来没问题但它的执行逻辑是数据库要把前 1000020 行都遍历一遍然后丢弃前 1000000 行只返回最后 20 行。这意味着OFFSET 越大扫描的无用行越多性能越差。当表里有千万行数据时翻到中间和后面单次查询可能要扫几十万甚至上百万行。索引在这里帮不上什么忙因为OFFSET本身就要求数据库“从头数到尾”。1.3 查询和 UI 放在同一个线程Qt 的QSqlQuery默认是同步执行。你在按钮槽函数里执行一次查询主线程会一直阻塞到数据库返回结果。即使你只取 20 条只要数据库内部发生了全表扫描界面就会卡顿。这也是很多新手最容易忽略的一点卡顿不一定来自渲染更可能来自查询本身。把这三条合起来看结论就很清晰了想流畅展示必须分页加载想分页稳定必须避免大偏移想 UI 不卡查询要么够快要么放到非 UI 线程。2. 游标分页原理与适用边界2.1 传统 OFFSET 分页的天然缺陷OFFSET 分页适合数据量小、翻页方式简单的场景。比如后台管理系统的前几页数据量只有几千条用LIMIT 20 OFFSET 40没有任何问题。但数据量一旦到百万、千万级OFFSET 的扫描成本就会成倍上升。核心问题可以概括为每次翻页都要重新“数行数”。2.2 游标分页的思路游标分页也叫 keyset pagination、seeking pagination核心思路是不使用“跳过多少行”而是记住“上一页最后一条记录的位置”下一页从该位置继续向后取。对于以自增主键id排序的列表游标分页的 SQL 非常简单SELECT id, device_id, record_time FROM trade_record WHERE id :lastId ORDER BY id ASC LIMIT :pageSize;首页时:lastId传0因为自增主键从 1 开始。查询后拿到本页最后一条记录的id作为下一页的:lastId。这个查询可以直接命中主键索引时间复杂度和数据总量无关只和“要跳过的目标位置”有关。这就像翻书时你记住上次看到哪一页下次直接翻到那一页继续读而不是每次都从第一页开始数。2.3 游标分页的限制游标分页不是万能的它有两个明显限制不支持随机跳页。你不知道第 100 页的第一条记录id是多少就无法直接跳到第 100 页。排序字段必须唯一且稳定。如果只用ORDER BY record_time而record_time有大量重复值游标就无法唯一定位下一页的起点。所以游标分页最适合的场景是列表连续往下翻、列表页自动加载更多、日志查询、交易流水展示。维度OFFSET 分页游标分页查询性能随页数增长下降稳定与总行数关系小随机跳页支持不支持实现复杂度简单中等适合场景小数据量、后台列表大量数据连续翻页数据库支持所有数据库所有数据库3. 表结构与索引设计游标分页能够高效运行前提是表结构和索引设计正确。这一段非常关键很多项目分页慢不是 SQL 写得不对而是表结构从一开始就没设计好。3.1 主键选择SQLite 中单列INTEGER PRIMARY KEY和“自动递增 AI”有特殊含义它会被当成表内隐藏的rowid的别名查询效率极高。推荐写法CREATE TABLE trade_record ( id INTEGER PRIMARY KEY AUTOINCREMENT, device_id TEXT NOT NULL, record_time INTEGER NOT NULL, status INTEGER NOT NULL DEFAULT 0, amount REAL NOT NULL DEFAULT 0, remark TEXT );如果你不需要严格保证“历史 id 永不复用”也可以去掉AUTOINCREMENTid INTEGER PRIMARY KEYSQLite 同样会自动分配自增 id写入性能略优于带AUTOINCREMENT的写法。在千万级数据场景下优先考虑不带AUTOINCREMENT的表结构。不建议用 UUID 字符串做主键。随机字符串会让索引页不断分裂占用空间大查询和写入都会变慢。业务上需要唯一标识可以单独建立唯一索引。3.2 二级索引设计游标分页只解决“翻页不动全表”的问题数据库仍然要为查询条件过滤数据。所以需要在真实查询条件上建索引。例如应用常见需求是“按设备查询 按时间排序”就可以建复合索引CREATE INDEX IF NOT EXISTS idx_trade_record_device_time ON trade_record(device_id, record_time);如果只是演示游标分页那就确保主键索引存在即可。索引不是越多越好每多一个索引插入时都要多维护一棵 B 树。3.3 开启 WAL 和 busy_timeoutSQLite 默认的日志模式在写并发场景下容易互相锁库。桌面应用推荐开启 WAL 模式PRAGMA journal_modeWAL; PRAGMA busy_timeout3000;WAL 模式允许读操作和写操作在一定程度上并行执行。busy_timeout则避免并发访问时立刻返回“database is locked”。4. 工程环境准备4.1 Qt 工程配置在 Qt 项目中使用 SQLite需要确保引入了 SQL 模块。.pro文件写法如下QT core gui sql widgets CONFIG c17 SOURCES \ main.cpp \ mainwindow.cpp HEADERS \ mainwindow.h在 CMake 工程中则使用find_package(Qt6 COMPONENTS Core Gui Sql Widgets REQUIRED) target_link_libraries(your_app PRIVATE Qt6::Core Qt6::Gui Qt6::Sql Qt6::Widgets)4.2 检查 QSQLITE 驱动如果运行时提示找不到驱动先检查编译环境是否带了 SQLite 驱动插件qDebug() QSqlDatabase::drivers();期望输出中至少包含QSQLITE。如果使用 Windows 发布程序需要把sqldrivers目录下的驱动插件拷贝到可执行文件同级的插件目录否则程序在用户机器上会报driver not loaded。4.3 初始化数据库打开数据库并执行必要的 PRAGMA可以使用下面的代码// 文件路径dbmanager.cpp #include QSqlDatabase #include QSqlQuery #include QSqlError #include QDebug bool initDatabase(const QString dbPath) { QSqlDatabase db QSqlDatabase::addDatabase(QSQLITE); db.setDatabaseName(dbPath); if (!db.open()) { qCritical() open database failed: db.lastError().text(); return false; } QSqlQuery query(db); query.exec(PRAGMA journal_modeWAL;); query.exec(PRAGMA busy_timeout3000;); query.exec(CREATE TABLE IF NOT EXISTS trade_record ( id INTEGER PRIMARY KEY, device_id TEXT NOT NULL, record_time INTEGER NOT NULL, status INTEGER NOT NULL DEFAULT 0, amount REAL NOT NULL DEFAULT 0, remark TEXT );); query.exec(CREATE INDEX IF NOT EXISTS idx_trade_record_device_time ON trade_record(device_id, record_time);); return true; }注意PRAGMA journal_modeWAL;执行后可以用QSqlQuery::value(0)查看返回结果正常应该是wal。不过在很多版本里即使不看返回值数据库文件旁边出现-wal后缀文件也说明 WAL 已生效。5. 游标分页核心代码实现这一段给出真正的核心代码。为提高可读性先用同步版本跑通流程再在后续章节讨论异步改造。5.1 分页结果结构体先定义一个简单的分页结果结构// 文件路径pagereader.h #pragma once #include QVector #include QVariant struct PageResult { QVectorQVectorQVariant rows; // 每行数据 qint64 nextCursor -1; // 下一页游标-1 表示没有更多数据 };5.2 分页查询函数这里的关键是使用主键id作为游标。cursor传入上一页最后一条记录的id首页传0。// 文件路径pagereader.cpp #include pagereader.h #include QSqlDatabase #include QSqlQuery #include QSqlError #include QDebug PageResult loadPageData(qint64 cursor, int pageSize) { PageResult result; QSqlDatabase db QSqlDatabase::database(); if (!db.isOpen()) { qWarning() database is not open; return result; } // pageSize 是程序内部整数不直接拼接用户输入 QString sql QString( SELECT id, device_id, record_time, status, amount, remark FROM trade_record WHERE id :cursor ORDER BY id ASC LIMIT %1).arg(pageSize); QSqlQuery query(db); query.prepare(sql); query.bindValue(:cursor, cursor); if (!query.exec()) { qWarning() query failed: query.lastError().text(); return result; } while (query.next()) { QVectorQVariant row; row query.value(0) query.value(1) query.value(2) query.value(3) query.value(4) query.value(5); result.rows.append(row); } if (!result.rows.isEmpty()) { result.nextCursor result.rows.last().at(0).toLongLong(); } return result; }这个函数完成了游标分页的核心逻辑。WHERE id :cursor让 SQLite 直接利用主键索引定位到游标位置然后向后读取pageSize行。5.3 在窗口类中维护翻页状态窗口类中维护三个状态m_currentCursor当前页的起始游标m_nextCursor当前页最后一条记录的idm_history历史游标栈用于“上一页”。// 文件路径mainwindow.h #pragma once #include QMainWindow #include QStandardItemModel #include QVector #include pagereader.h QT_BEGIN_NAMESPACE namespace Ui { class MainWindow; } QT_END_NAMESPACE class MainWindow : public QMainWindow { Q_OBJECT public: explicit MainWindow(QWidget *parent nullptr); ~MainWindow(); private slots: void onNextPage(); void onPrevPage(); private: void loadCurrentPage(); void showPage(const QVectorQVectorQVariant rows); Ui::MainWindow *ui; QStandardItemModel *m_model; qint64 m_currentCursor 0; qint64 m_nextCursor -1; QVectorqint64 m_history; int m_pageSize 50; bool m_loading false; };// 文件路径mainwindow.cpp #include mainwindow.h #include ui_mainwindow.h MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) , m_model(new QStandardItemModel(this)) { ui-setupUi(this); ui-tableView-setModel(m_model); connect(ui-nextButton, QPushButton::clicked, this, MainWindow::onNextPage); connect(ui-prevButton, QPushButton::clicked, this, MainWindow::onPrevPage); loadCurrentPage(); } MainWindow::~MainWindow() { delete ui; } void MainWindow::onNextPage() { if (m_loading || m_nextCursor 0) { return; } m_history.append(m_currentCursor); m_currentCursor m_nextCursor; loadCurrentPage(); } void MainWindow::onPrevPage() { if (m_loading || m_history.isEmpty()) { return; } m_currentCursor m_history.takeLast(); loadCurrentPage(); } void MainWindow::loadCurrentPage() { m_loading true; PageResult result loadPageData(m_currentCursor, m_pageSize); showPage(result.rows); m_nextCursor result.nextCursor; m_loading false; } void MainWindow::showPage(const QVectorQVectorQVariant rows) { m_model-clear(); m_model-setHorizontalHeaderLabels( {ID, 设备, 记录时间, 状态, 金额, 备注}); m_model-setRowCount(rows.size()); m_model-setColumnCount(6); for (int r 0; r rows.size(); r) { for (int c 0; c rows[r].size(); c) { m_model-setItem(r, c, new QStandardItem(rows[r][c].toString())); } } }这套逻辑的核心在于m_currentCursor是“上一页最后一条 id”而m_nextCursor是“当前页最后一条 id”。每次下一页把当前页的游标压入历史栈再让当前游标等于下一页的起始游标。5.4 为什么这个分页在千万级数据下依然稳定关键在WHERE id :cursor这个条件。SQLite 使用主键索引定位到大于cursor的第一行然后顺序读取pageSize行。这个过程不关心OFFSET是多少万也不关心全表有多少行。理论上只要主键索引存在第 1 页和第 10000 页的查询时间基本在同一量级。这也是游标分页在千万级数据下依然“流畅”的核心原因。6. 批量写入与事务CRUD 不只是查询写操作同样容易成为性能瓶颈。很多人第一次向 SQLite 批量插入数据时都会遇到“插入 3000 条数据竟然要十几秒”的情况。6.1 逐条插入为什么慢SQLite 默认情况下每一条 INSERT 语句都会被当作一个独立事务自动提交。这意味着每条记录都要做一次磁盘同步、一次日志写入、一次 B 树索引更新。正确做法是显式开启事务积累到一定数量再统一提交。6.2 批量插入示例下面是一个批量写入函数。先定义一条业务记录的简单结构struct TradeRecord { QString deviceId; QDateTime recordTime; int status 0; double amount 0.0; QString remark; };批量插入函数// 文件路径recordwriter.cpp #include QSqlDatabase #include QSqlQuery #include QSqlError #include QVector #include QDateTime bool batchInsertRecords(const QVectorTradeRecord records) { QSqlDatabase db QSqlDatabase::database(); if (!db.isOpen()) { return false; } if (!db.transaction()) { return false; } QSqlQuery query(db); query.prepare( INSERT INTO trade_record(device_id, record_time, status, amount, remark) VALUES(?, ?, ?, ?, ?)); for (const TradeRecord r : records) { query.addBindValue(r.deviceId); query.addBindValue(r.recordTime.toSecsSinceEpoch()); query.addBindValue(r.status); query.addBindValue(r.amount); query.addBindValue(r.remark); if (!query.exec()) { db.rollback(); return false; } } return db.commit(); }每次调用exec()时SQLite 实际使用的还是同一个 prepared statement不会重复解析 SQL。加上事务后插入速度往往会提升一个数量级。6.3 存在就更新不存在就新增UPSERT业务中经常遇到“存在就更新不存在就新增”的需求。在 SQLite 3.24 及以上版本可以写INSERT ... ON CONFLICT DO UPDATE。假设device_id有唯一索引CREATE UNIQUE INDEX IF NOT EXISTS ux_trade_record_device ON trade_record(device_id);那么增量写入可以写成INSERT INTO trade_record(device_id, record_time, status, amount, remark) VALUES(?, ?, ?, ?, ?) ON CONFLICT(device_id) DO UPDATE SET record_time excluded.record_time, status excluded.status, amount excluded.amount, remark excluded.remark;在 Qt 的QSqlQuery中同样使用prepare addBindValue exec。判断 SQLite 版本可以用SELECT sqlite_version();如果目标环境版本低于 3.24就需要先查一次记录是否存在再决定走 UPDATE 还是 INSERT这会影响性能但能保证兼容。7. 异步查询与 UI 刷新策略同步版本的游标分页在数据量千万级、单次查询几十毫秒以内时已经可以满足大部分桌面应用体验。但如果你想做到“完全无感知”就需要把查询挪到后台线程。7.1 子线程不能直接复用主线程的连接这是很多 Qt 新手必踩的坑。QSqlDatabase连接默认是主线程创建的如果直接在QtConcurrent::run里用同一个连接执行查询很可能出现QSqlDatabasePrivate::database: requested database does not belong to the calling thread正确做法是后台线程各自创建自己的数据库连接使用不同的连接名连接对象不要跨线程使用。7.2 使用 QThread Worker 的思路这里给出一个思路性示例重点是展示连接的生命周期。实际项目中可以封装成 Worker 类。class QueryWorker : public QObject { Q_OBJECT public slots: PageResult loadPage(qint64 cursor, int pageSize, const QString dbFile) { PageResult result; // 子线程内创建独立连接连接名唯一 QString connName QString(worker_%1).arg(reinterpret_castquintptr(QThread::currentThread())); { QSqlDatabase db QSqlDatabase::addDatabase(QSQLITE, connName); db.setDatabaseName(dbFile); if (!db.open()) { QSqlDatabase::removeDatabase(connName); return result; } QSqlQuery query(db); QString sql QString( SELECT id, device_id, record_time, status, amount, remark FROM trade_record WHERE id :cursor ORDER BY id ASC LIMIT %1).arg(pageSize); query.prepare(sql); query.bindValue(:cursor, cursor); if (query.exec()) { while (query.next()) { QVectorQVariant row; row query.value(0) query.value(1) query.value(2) query.value(3) query.value(4) query.value(5); result.rows.append(row); } } db.close(); } // 确保所有 QSqlQuery 对象销毁后再移除连接 QSqlDatabase::removeDatabase(connName); if (!result.rows.isEmpty()) { result.nextCursor result.rows.last().at(0).toLongLong(); } return result; } };使用QSignalMapper、QFutureWatcher或QThread Worker都可以。只要记住数据库连接不能跨线程共享自定义结构体跨线程传递时需要注册元类型