QSqlQuery实战：从基础查询到事务处理的Qt数据库操作指南

1. 从“会用”到“用好”：QSqlQuery到底解决了什么问题

Qt的数据库模块里，QSqlQuery是绕不开的主角。前面两篇咱们聊过Qt SQL模块的整体架构，以及QSqlDatabase怎么建立连接，那篇结尾我留了个钩子——连接建好了，数据怎么读写？答案就是QSqlQuery。

简单说，QSqlQuery就是Qt帮你封装好的SQL执行器。它的定位很朴素：把SQL语句发给数据库，把结果拿回来。你可能会问，这玩意儿跟我直接写个ODBC或者调用MySQL C API有什么区别？区别在于，QSqlQuery屏蔽了不同数据库驱动的细节，你在Windows上写的代码，换到Linux上编译一遍就能跑，底层从ODBC换成MYSQL驱动，上层代码一行不用改。这个跨数据库能力，才是Qt数据库模块真正的价值所在。

这篇文章我不打算照着官方文档念一遍API，那玩意儿你自己也能翻。我重点讲的是实际开发里怎么用、什么时候该用prepare、事务怎么处理、还有那些文档里不会写的坑。内容主要面向已经把QSqlDatabase连接配好、想进一步掌握数据读写操作的开发者。如果你是完全零基础，建议先把前面两篇看了再来，不然有些上下文你接不上。

2. 核心细节解析与实操要点：QSqlQuery的查询模式

2.1 exec()、prepare()与bindValue()：三种基本操作方式

QSqlQuery的查询模式就三种：直接exec一条完整SQL、prepare预处理后绑定参数执行、以及通过bindValue动态传值。这三种写法各有适用场景，我一个个说。

第一种，直接exec完整SQL语句，最粗暴，也最直观：

cpp复制QSqlQuery query;
query.exec("SELECT * FROM user WHERE age > 18");

这种写法适合SQL语句完全固定、不含任何外部输入变量的场景。比如程序启动时加载常量配置表，或者某个固定条件的统计查询，一行exec就完事，代码最简洁。它的局限性也很明显——SQL语句是写死的，没法根据程序运行状态动态调整条件。

第二种，prepare预处理。这种模式我强烈推荐在实际项目里大面积使用：

cpp复制QSqlQuery query;
query.prepare("SELECT * FROM user WHERE age > ? AND city = ?");
query.addBindValue(18);
query.addBindValue("深圳");
query.exec();

?是占位符，后续通过addBindValue按顺序绑定值。prepare的好处有三个：第一，SQL语句结构固定，数据库可以对它做预编译和缓存，重复执行时效率高；第二，参数和SQL语句分开传递，从根本上杜绝了SQL注入，这个在接收用户输入的场景里是生死攸关的；第三，代码可读性好，语句结构和数据彻底分离。

第三种，bindValue带具名占位符。注意，这里有两种写法：

cpp复制// 写法一：冒号+名字，通过名字绑定
query.prepare("SELECT * FROM user WHERE age > :age AND city = :city");
query.bindValue(":age", 18);
query.bindValue(":city", "深圳");
query.exec();

// 写法二：省略冒号，直接写名字
query.prepare("SELECT * FROM user WHERE age > :age AND city = :city");
query.bindValue("age", 18);
query.bindValue("city", "深圳");
query.exec();

两种写法都合法，bindValue会自动匹配。我的经验是统一用一种风格，别混着来，不然代码review的时候真心累。具名占位符还有个优势，当你需要多次绑定同一个参数时，或者参数顺序经常调整时，代码的健壮性会好很多，不容易出现参数错位。

2.2 查询结果怎么取：size()、next()、value()与记录的遍历

查询执行完，结果就在QSqlQuery对象内部维护的一个结果集里，取数据靠的是那几个经典方法。先说新手最容易犯的错——以为query有size()就能直接拿来当行数用。

cpp复制QSqlQuery query;
query.exec("SELECT * FROM user");
int rowCount = query.size(); // 危险操作

size()这玩意儿，文档里写得明明白白：只在某些数据库里可靠。实测下来，SQLite驱动基本能返回正确结果，但MySQL驱动在某些情况下返回-1，说明它自己都不知道有多少行。所以千万别把size()当成通用API来依赖。

正确的遍历姿势是这样的：

cpp复制QSqlQuery query;
query.exec("SELECT id, name, age FROM user WHERE age > 18");
while (query.next()) {
    int id = query.value(0).toInt();
    QString name = query.value(1).toString();
    int age = query.value(2).toInt();
    qDebug() << id << name << age;
}

关键点有两个。第一，next()不只是判断有没有下一条记录，它还把内部指针移到下一条，执行成功返回true，走到末尾返回false，所以这个循环就能把整个结果集跑完。第二，value()参数可以传列索引（从0开始），也可以传字段名：

cpp复制QString name = query.value("name").toString();

按索引取效率略高，按名字取代码可读性好。我个人的习惯是，列少用索引，列多或者SQL语句容易变动时用字段名。

还有一个细节：结果集默认是不可滚动的，也就是指针只能往前走，不能回退。如果你需要随机访问结果集中的任意一行，需要在打开数据库连接后手动开启：

cpp复制// 需要在连接层设置
QSqlDatabase db = QSqlDatabase::database();
db.setForwardOnly(false);

setForwardOnly(true)是默认状态，查询结果只能顺序往前读，内存占用小、速度快。如果设成false，结果集就会缓存到内存里，你可以在记录间来回跳转。这个取舍要根据实际数据量来——要是查出来的结果集有几万行，还开随机访问，内存一下就爆了。

3. 实操过程与核心环节实现：增删改查四件套

3.1 最基础的增删改查代码模板

前面把原理讲完了，这里直接上代码。我以SQLite为例，因为Qt对SQLite的支持最完善、零配置。实际项目里换成MySQL、PostgreSQL都一个套路，改一下连接串就行。

先说建表。SQLite里你可以直接在Qt里执行CREATE TABLE语句：

cpp复制QSqlQuery query;
bool ok = query.exec("CREATE TABLE IF NOT EXISTS user ("
                     "id INTEGER PRIMARY KEY AUTOINCREMENT, "
                     "name TEXT NOT NULL, "
                     "age INTEGER, "
                     "city TEXT)");
if (!ok) {
    qDebug() << "建表失败：" << query.lastError().text();
}

AUTOINCREMENT自增主键，SQLite的特有写法，MySQL里对应AUTO_INCREMENT，PostgreSQL对应SERIAL，换库的时候记得改这个。

新增记录，用prepare最稳妥：

cpp复制QSqlQuery query;
query.prepare("INSERT INTO user (name, age, city) VALUES (?, ?, ?)");
query.addBindValue("张三");
query.addBindValue(25);
query.addBindValue("北京");
if (!query.exec()) {
    qDebug() << "插入失败：" << query.lastError().text();
    return;
}
// 拿回自增主键id
int newId = query.lastInsertId().toInt();

lastInsertId()是高频使用的API，插入之后需要拿新记录的ID，用它就行，不同数据库驱动都有实现。

删除和更新，没什么特殊的，就是SQL语句不同：

cpp复制// 更新
QSqlQuery query;
query.prepare("UPDATE user SET age = ?, city = ? WHERE id = ?");
query.addBindValue(26);
query.addBindValue("上海");
query.addBindValue(1);
if (!query.exec()) {
    qDebug() << "更新失败：" << query.lastError().text();
}

// 删除
query.prepare("DELETE FROM user WHERE id = ?");
query.addBindValue(1);
if (!query.exec()) {
    qDebug() << "删除失败：" << query.lastError().text();
}

这里有个看起来很基础、但很多人会踩的坑：执行增删改语句之后，影响的行数要用query.numRowsAffected()来拿，不是size()。size()在SELECT里都不完全可靠，在INSERT/UPDATE/DELETE里更是连用都不能用。numRowsAffected()才是为这些写操作准备的。

删除前最好先判断一下这个ID是否存在，不然删了个寂寞。更新同理，先SELECT查一遍再UPDATE，可以有效避免误操作。

3.2 查询一下：条件筛选、排序、分页与模糊搜索实战

实际开发里我们不可能只做全表SELECT，所以把最常见的几种查询场景都过一遍。

条件筛选，标准写法：

cpp复制QSqlQuery query;
query.prepare("SELECT * FROM user WHERE age > ? AND city = ? ORDER BY age DESC");
query.addBindValue(18);
query.addBindValue("北京");
query.exec();
while (query.next()) {
    // 处理每条记录
}

排序用ORDER BY，注意DESC降序、ASC升序，默认ASC。多字段排序直接在后面逗号接就行，比如ORDER BY age DESC, id ASC，年龄相同的再按ID升序，逻辑清晰。

分页查询，不同数据库语法不同，这里必须分开说：

cpp复制// SQLite / MySQL / PostgreSQL 都支持 LIMIT
query.prepare("SELECT * FROM user LIMIT ? OFFSET ?");
query.addBindValue(pageSize);   // 每页多少条
query.addBindValue(page * pageSize); // 跳过多少条

// SQL Server 不支持 LIMIT，得用 OFFSET FETCH
// SELECT * FROM user ORDER BY id OFFSET ? ROWS FETCH NEXT ? ROWS ONLY

分页有个性能陷阱，数据量一大，OFFSET越大查询越慢。因为数据库要把前面的记录全部扫一遍然后丢掉。如果表很大，实际工程里常用“键集分页”，也就是用上次查询最后一条记录的ID来定位：

cpp复制query.prepare("SELECT * FROM user WHERE id > ? ORDER BY id ASC LIMIT ?");
query.addBindValue(lastId);
query.addBindValue(pageSize);

这种写法效率高出好几个量级，缺点是跳页不方便，只能一页一页往下翻。

模糊搜索，SQL标准写法是LIKE加通配符：

cpp复制QString keyword = "%" + searchText + "%";
query.prepare("SELECT * FROM user WHERE name LIKE ?");
query.addBindValue(keyword);
query.exec();

注意，%是SQL通配符，表示任意长度字符。LIKE '张%'匹配以“张”开头的所有值，LIKE '%张%'匹配包含“张”的所有值。下划线_匹配单个任意字符。如果你的搜索文本里本身就包含%或_，需要转义，这个后面在常见问题里细说。

3.3 事务操作：批量数据处理的安全底座

事务，是数据库操作里最容易被初学者无视、但实际开发中最能救命的机制。试想一个场景：你在做一个转账功能，A账户扣钱，B账户加钱，两条UPDATE语句，第一条执行成功，第二条因为网络波动挂了。如果没有事务，A的钱扣了，B的钱没到，这个账目就永远平不了。

QSqlQuery配合事务操作的标准流程如下：

cpp复制QSqlDatabase db = QSqlDatabase::database();
bool ok = db.transaction(); // 开启事务
if (!ok) {
    qDebug() << "开启事务失败";
    return;
}

QSqlQuery query;
query.prepare("UPDATE account SET balance = balance - ? WHERE id = ?");
query.addBindValue(100);
query.addBindValue(1);
if (!query.exec()) {
    db.rollback(); // 出错回滚，所有操作作废
    qDebug() << "扣款失败，已回滚：" << query.lastError().text();
    return;
}

query.prepare("UPDATE account SET balance = balance + ? WHERE id = ?");
query.addBindValue(100);
query.addBindValue(2);
if (!query.exec()) {
    db.rollback(); // 出错回滚
    qDebug() << "入账失败，已回滚：" << query.lastError().text();
    return;
}

db.commit(); // 全部成功，提交

事务还有一个隐藏福利：性能。大批量插入时，每一条INSERT单独执行，开销是巨大的，因为每次exec都要跟数据库交互一次，还有隐式事务的提交开销。把一批插入包在事务里，速度能提升一个数量级以上。我来给个实测数据：SQLite下插入一万条记录，逐条插入耗时几十秒，包在事务里批量插入耗时不到一秒。这个差距，我相信你见过一次就再也忘不掉了。

批量插入的推荐写法：

cpp复制QSqlDatabase db = QSqlDatabase::database();
db.transaction();
QSqlQuery query;
query.prepare("INSERT INTO user (name, age, city) VALUES (?, ?, ?)");

for (int i = 0; i < 10000; ++i) {
    query.addBindValue(QString("用户%1").arg(i));
    query.addBindValue(20 + (i % 50));
    query.addBindValue("深圳");
    if (!query.exec()) {
        db.rollback();
        qDebug() << "批量插入中断于第" << i << "条：" << query.lastError().text();
        return;
    }
}
db.commit();

事务期间别忘了一个原则：只要其中一条失败，整个事务内的所有修改全部作废。所以错误处理必须放在每条exec后面，一旦失败立刻rollback，不能让它继续往下执行。

3.4 不同数据库的SQL方言差异：如何写出可移植的代码

QSqlQuery虽然帮你屏蔽了驱动的差异，但SQL语法本身在不同数据库之间还是有不小的区别。这里整理几个最常见的差异点，都是我实际项目里遇到过并踩过坑的。

自增主键的写法：SQLite是INTEGER PRIMARY KEY AUTOINCREMENT，MySQL是INT AUTO_INCREMENT PRIMARY KEY，PostgreSQL是SERIAL PRIMARY KEY，SQL Server是IDENTITY(1,1)。建表语句没法统一，只能按数据库区分。

分页语法：前面已经提过，SQLite/MySQL/PostgreSQL用LIMIT OFFSET，SQL Server用OFFSET FETCH，Oracle用ROWNUM或者FETCH FIRST。这个在框架层就得封装好，别写在业务代码里到处复制。

字符串拼接：MySQL用CONCAT('a', 'b')，SQL Server用'表达式' + '另一个'，PostgreSQL和SQLite用||操作符。你要是写了个SQL Server风格的拼接语句丢到MySQL里执行，直接报语法错误。

日期函数：MySQL有NOW()、DATE_FORMAT()，SQLite没有专门的日期类型只有字符串和Unix时间戳，SQL Server用GETDATE()。跨库的时候日期处理是最让人头疼的环节之一。

布尔值：SQLite里用0和1，MySQL里TRUE/FALSE和1/0都能用，PostgreSQL有真正的boolean类型。插入时统一用0和1最省事。

我的建议是，如果项目有跨数据库的硬性需求，尽量把SQL集中在单独的DAO层，不要散落在业务代码里。每种数据库一个实现文件，通过工厂模式按连接类型创建对应的DAO。这样就算以后要换库，也只动一个模块，不至于全项目乱飞。

4. 常见问题与排查技巧实录

4.1 查询结果为空、value()取不到值、类型转换失败

这类问题太常见了，几乎每隔几天就有人在群里问。先给标准排查路径。

第一，exec()执行完，先看返回值。如果返回false，看lastError().text()。注意一个细节，QSqlQuery的lastError()只在exec失败时才有有效信息，成功时不保证内容的正确性。

第二，exec返回true但查不到数据。区分两种情况：表里真的没数据，还是SQL条件写得有问题。可以先把SQL语句用qDebug()打出来，拿到数据库客户端里手动跑一遍。最常见的坑是，prepare里绑定的参数类型和数据库字段类型不匹配，比如字段是INTEGER，你addBindValue传了个字符串"18"，某些数据库不会帮你隐式转换，直接匹配不上返回空结果。

第三，value()取出来的QVariant转类型报错。value(0).toInt()返回0，可能是这个字段真的是0，也可能是转换失败。QVariant有个很坑的特性，转换失败不会报错，而是返回默认值。排查方法是先value(0).type()看看实际类型，或者value(0).toString()打出来看看原始值。

还有个我见过很多次的问题：SQL语句里用了保留字做字段名，比如order、group、select之类。这些词在SQL里有特殊含义，直接当字段名用，数据库解析SQL时就报错了。解决办法是给字段名加反引号（MySQL）、双引号（PostgreSQL/SQLite）或者方括号（SQL Server）。命名时尽量避开保留字是最省心的方案。

4.2 参数绑定与类型问题：为什么我的语句执行失败

参数绑定最常见的报错，是“parameter count mismatch”或者“no such column”。前者发生在占位符数量和绑定值数量不一致时，后者通常是你写的字段名在表里根本不存在。

检查清单如下：

• 占位符是?类型时，addBindValue的顺序必须和?出现的顺序完全一致，一个都不能多、一个都不能少。
• 具名占位符以:开头，但bindValue里写不写冒号都行。系统内部是做了兼容处理的，别自己搞混。
• 同一个具名占位符在SQL里出现多次时，bindValue只需绑定一次。QSqlQuery会自动把这个值填到所有同名位置上。
• 参数类型不匹配时，最好显式指定类型，比如query.bindValue(":age", 18, QSql::Out)，不，这个Out是存储过程输出参数用的，日常查询别乱加第三个参数。日常就用addBindValue默认重载就行。

关于参数类型的坑，另一个记忆点：QVariant在addBindValue时推断类型。整数默认是int，如果你绑定的是long long或者qint64，某些驱动可能精度丢失。大整数建议先toLongLong()再绑定。

4.3 SQLite数据库被锁、MySQL连接丢失，这些运行时错误怎么办

SQLite是嵌入式数据库，并发读写能力有限。多线程同时写同一个SQLite库文件，很容易报“database is locked”。解决思路有几个方向：

• 写操作加锁串行化，不要让多个线程同时写。
• 开启WAL模式，读写并行能力会好很多。SQLite在WAL模式下，读操作不阻塞写操作，写操作也不阻塞读操作：

cpp复制QSqlQuery query;
query.exec("PRAGMA journal_mode=WAL");

• 设置合理的busy_timeout，让SQLite在遇到锁时等待而不是立即报错：

cpp复制query.exec("PRAGMA busy_timeout=5000"); // 5秒

MySQL这边，最常见的运行时错误是“MySQL server has gone away”。原因通常是连接空闲太久被服务端断开了，或者执行了超大SQL把连接搞崩。解决方法是遇到这个错误时重新连接再执行一次，或者定期发心跳保持连接活跃。

前面说过的setForwardOnly，再提一次，因为它和内存相关。查大表时如果忘了保持默认的forwardOnly=true，结果集全量缓存，内存容易爆，程序直接OOM崩溃。如果遇到“程序运行一段时间后内存暴涨”的问题，优先检查是不是哪个查询把forwardOnly设成了false还没关。

5. 一些经验之谈：把QSqlQuery用得干净利落

文章最后，我把这几年用QSqlQuery的一些习惯和心得整理出来，希望能帮后来的人少走点弯路。

第一，SQL语句一定要单独封装。不管项目大小，SQL语句不要散落在按钮点击事件、定时器回调这些地方。集中到一个数据访问层，用常量或者函数管理起来。好处很明显：出了问题你只需要找一个文件，数据库迁移你只需要改一个文件，代码review时其他人也能快速定位。

第二，prepare是默认选项，exec直接拼SQL是例外。我的习惯是，哪怕SQL语句里没有外部变量，只要这个语句会执行多次，就用prepare。因为预编译语句在数据库端有缓存，第二次执行开始性能就有优势。更关键的是，养成这个习惯之后，就不会在某个需要绑定的场景里忘了用prepare，把自己暴露在SQL注入风险里。

第三，每条exec之后都检查返回值。这个习惯看着繁琐，但真的能救命。实际项目里，数据库报错通常不是你写错了代码，而是环境变了——表被删了、字段被改了、连接断了、磁盘满了。你不检查返回值，程序就会在不知道什么地方以莫名其妙的方式崩溃，排查成本高得多。而每条语句都检查，错误能在第一时间暴露出来，并且带上lastError().text()，定位问题基本就是看日志的事。

第四，QVariant和实际类型要心里有数。Qt的QVariant什么都装得下，但数据库驱动在传输时对类型有要求。INSERT一个INTEGER字段时，你传个QString进去，某些数据库驱动会帮你转，有些直接报错，有些静默写成0。最稳的做法是，取值时显式转换，存值时传对应类型的QVariant，别图省事全用toString()传递。

第五，调试时多利用lastQuery()。QSqlQuery有个lastQuery()方法，返回最后执行的SQL语句。结合绑定的参数值，你可以手动还原出完整的SQL，直接复制到数据库客户端里跑。这个技巧在排查复杂查询时特别有用，比对着代码猜半天快多了。

QSqlQuery本身不复杂，复杂的是它连接的那一整个数据库世界。把基础API用熟练，再摸清你所用的具体数据库的脾气，剩下的就是熟能生巧的问题了。希望这篇能给你省下一些试错的时间。