Qt SQL模块核心类QSqlDatabase与QSqlQuery实战详解-平芜编程栈

在 Qt C++ 项目中，数据库操作是连接业务逻辑与持久化存储的核心桥梁。无论是开发桌面应用、嵌入式系统还是需要本地数据缓存的服务端工具，掌握 Qt SQL 模块都是进阶开发者的必备技能。然而，许多开发者在初次接触QSqlDatabase和QSqlQuery时，常常陷入连接配置繁琐、SQL 语句执行混乱、错误处理不完善的困境，导致项目在数据层就埋下隐患。

本文将系统性地拆解 Qt SQL 模块中这两个最核心的类：QSqlDatabase和QSqlQuery。我们将从驱动加载、连接管理的基础讲起，深入到参数化查询、事务控制、结果集遍历等高级用法，并最终构建一个可复用的数据库操作工具类。文章包含大量可直接运行的代码示例，并会详细解释每一步背后的原理和最佳实践，确保无论是 Qt 新手还是有经验的开发者，都能构建出健壮、高效的数据访问层。

1. Qt SQL 模块核心概念与环境准备

在深入代码之前，我们首先需要理解 Qt SQL 模块的架构和基本组件。Qt SQL 模块提供了一套平台无关的数据库访问 API，它通过数据库驱动（Driver）来屏蔽不同数据库（如 SQLite, MySQL, PostgreSQL, ODBC 等）的底层差异。

核心类简介：

QSqlDatabase：代表一个数据库连接。它负责管理连接的创建、配置、打开和关闭。一个应用程序可以同时维护多个到不同数据库或同一数据库的连接，每个连接由一个唯一的连接名（Connection Name）标识。
QSqlQuery：用于执行 SQL 语句并遍历其结果集。它是执行SELECT,INSERT,UPDATE,DELETE等操作的主要工具。一个QSqlQuery实例通常与一个特定的QSqlDatabase连接关联。
QSqlDriver：底层数据库驱动的抽象接口，由 Qt 或第三方提供。我们通常不直接操作它。
QSqlError：封装了数据库操作过程中产生的错误信息。
QSqlRecord：代表数据库表中的一条记录或查询结果中的一行。
QSqlTableModel/QSqlQueryModel：用于将数据库数据与 Qt 的 Model/View 组件（如QTableView）绑定的高级类，本文重点在于底层 API，对此仅做提及。

环境准备与版本说明：本文示例基于以下环境，但核心 API 在 Qt 5 和 Qt 6 中保持高度一致，请根据你的实际环境调整。

操作系统：Windows 10/11, macOS, 或 Linux (Ubuntu 20.04+)
Qt 版本：Qt 5.15 或 Qt 6.2+
开发环境：Qt Creator 或 Visual Studio + Qt VS Tools
数据库：SQLite（无需额外安装，Qt 内置驱动）和 MySQL（用于演示外部数据库连接）
项目配置：在项目文件（.pro）中，必须添加sql模块。

# 在你的 .pro 文件中添加 QT += core gui sql

如果你的项目使用 CMake，则在CMakeLists.txt中需要找到Qt5或Qt6组件并添加Sql。

# 例如，对于 Qt6 find_package(Qt6 COMPONENTS Core Gui Sql REQUIRED) target_link_libraries(your_target PRIVATE Qt6::Core Qt6::Gui Qt6::Sql)

验证环境是否就绪的一个简单方法是，在代码中包含头文件<QSqlDatabase>和<QSqlQuery>并编译，如果没有报错，则说明 SQL 模块已正确引入。

2. QSqlDatabase：数据库连接的管理者

QSqlDatabase是通往数据库的“门户”。所有数据库操作都始于建立一个有效的连接。

2.1 加载驱动与创建连接

Qt 支持多种数据库，但并非所有驱动默认都可用。SQLite 驱动通常是内置的，而 MySQL、PostgreSQL 等则需要手动确保驱动插件可用（在 Windows 上，对应的qsqlmysql.dll,qsqlpsql.dll等需要放在plugins/sqldrivers目录下）。

创建连接的基本流程：

检查驱动：使用QSqlDatabase::drivers()获取可用驱动列表。
添加数据库连接：使用QSqlDatabase::addDatabase()静态函数。你需要指定驱动类型和可选的连接名。
配置连接参数：设置数据库名、主机、端口、用户名、密码等。
打开连接：调用open()方法。务必检查其返回值或后续的lastError()。

#include <QSqlDatabase> #include <QSqlError> #include <QDebug> #include <QCoreApplication> bool createConnection() { // 1. 检查驱动 QStringList drivers = QSqlDatabase::drivers(); qDebug() << "Available drivers:" << drivers; if (!drivers.contains("QSQLITE")) { qCritical() << "SQLite driver not available!"; return false; } // 2. 添加一个 SQLite 数据库连接，使用默认连接名（“qt_sql_default_connection”） QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE"); // 如果你想指定连接名，可以这样做： // QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE", "my_connection"); // 3. 配置连接参数 // SQLite 使用文件路径作为数据库名 db.setDatabaseName(":memory:"); // 内存数据库，仅用于测试 // 对于文件数据库：db.setDatabaseName("/path/to/your/database.db"); // 4. 打开连接 if (!db.open()) { qCritical() << "Failed to open database:" << db.lastError().text(); return false; } qDebug() << "Database opened successfully!"; return true; } int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); if (createConnection()) { qDebug() << "Connection established."; // ... 后续数据库操作 } else { qDebug() << "Connection failed."; } return a.exec(); }

连接 MySQL 数据库示例：

bool connectToMySQL() { // 确保 QMYSQL 驱动可用 if (!QSqlDatabase::drivers().contains("QMYSQL")) { qCritical() << "QMYSQL driver not loaded!"; return false; } QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL", "mysql_conn"); db.setHostName("localhost"); // 数据库服务器地址 db.setPort(3306); // 端口，默认3306 db.setDatabaseName("test_db"); // 数据库名 db.setUserName("root"); // 用户名 db.setPassword("your_password"); // 密码 // 可选：设置连接选项，比如字符集 db.setConnectOptions("MYSQL_OPT_CONNECT_TIMEOUT=3;CLIENT_IGNORE_SPACE=1"); if (!db.open()) { qCritical() << "MySQL Connection failed:" << db.lastError().text(); // 常见错误：驱动未正确部署、服务器未启动、用户名密码错误、防火墙阻挡 return false; } qDebug() << "Connected to MySQL!"; return true; }

2.2 连接名与多连接管理

当你的应用需要同时连接多个数据库（例如，一个主业务库和一个日志库）时，连接名就变得至关重要。默认情况下，addDatabase()不指定连接名会使用一个默认连接。通过指定唯一的连接名，你可以创建和管理多个独立的连接。

// 创建两个独立的连接 QSqlDatabase dbLog = QSqlDatabase::addDatabase("QSQLITE", "log_connection"); dbLog.setDatabaseName("log.db"); QSqlDatabase dbMain = QSqlDatabase::addDatabase("QMYSQL", "main_connection"); dbMain.setHostName("prod-server"); dbMain.setDatabaseName("production"); // 后续使用特定连接时，需要通过连接名获取 QSqlDatabase targetDb = QSqlDatabase::database("main_connection"); QSqlQuery query(targetDb); // 查询将使用 main_connection

2.3 关闭连接与资源清理

数据库连接是系统资源，使用完毕后应及时关闭。对于QSqlDatabase对象，当它离开作用域被销毁时，其底层的连接并不会自动关闭。你必须显式调用close()。此外，可以使用QSqlDatabase::removeDatabase()来移除一个连接。注意：在移除连接前，必须确保所有关联的QSqlQuery对象都已销毁，并且该连接已关闭。

// 正确关闭和清理的流程 { QSqlDatabase db = QSqlDatabase::database("my_connection"); if (db.isOpen()) { db.close(); } } // 此时，与“my_connection”关联的所有查询对象都应已销毁 QSqlDatabase::removeDatabase("my_connection"); // 从全局连接池中移除

一个常见的错误是在多线程环境中共享同一个连接。QSqlDatabase和QSqlQuery不是线程安全的。每个线程应该创建自己的数据库连接（使用不同的连接名）。

3. QSqlQuery：SQL 语句的执行者

成功建立连接后，我们就可以通过QSqlQuery来执行 SQL 命令了。它是 Qt SQL 模块中最灵活、最常用的类。

3.1 执行 SQL 语句

QSqlQuery可以执行任何 SQL 语句，包括数据定义语言（DDL，如CREATE TABLE）、数据操作语言（DML，如INSERT,SELECT）等。

执行非查询语句（DDL, INSERT, UPDATE, DELETE）：使用exec()方法。它返回一个bool值指示执行是否成功。

QSqlQuery query; bool success = query.exec("CREATE TABLE IF NOT EXISTS person (" "id INTEGER PRIMARY KEY AUTOINCREMENT, " "name TEXT NOT NULL, " "age INTEGER)"); if (!success) { qDebug() << "Create table failed:" << query.lastError().text(); } success = query.exec("INSERT INTO person (name, age) VALUES ('Alice', 30)"); if (success) { qDebug() << "Insert successful, affected rows:" << query.numRowsAffected(); qDebug() << "Last insert ID:" << query.lastInsertId().toString(); } else { qDebug() << "Insert failed:" << query.lastError().text(); }

执行查询语句（SELECT）并遍历结果：对于SELECT语句，exec()执行成功后，查询对象会处于一个“活动”状态，并定位在结果集的第一行之前。你需要使用next()方法来遍历每一行。

QSqlQuery query; if (query.exec("SELECT id, name, age FROM person")) { while (query.next()) { // 通过列索引（从0开始）获取值 int id = query.value(0).toInt(); QString name = query.value(1).toString(); int age = query.value(2).toInt(); // 或者通过列名获取值（推荐，更清晰） // int id = query.value("id").toInt(); // QString name = query.value("name").toString(); // int age = query.value("age").toInt(); qDebug() << "ID:" << id << "Name:" << name << "Age:" << age; } // 遍历完成后，可以调用 query.first() 回到第一行，或 query.seek() 定位 } else { qDebug() << "Query failed:" << query.lastError().text(); }

value()方法返回一个QVariant，你需要根据列的数据类型将其转换为相应的 C++ 类型（toInt(),toString(),toDouble()等）。

3.2 参数化查询（预处理语句）

这是防止 SQL 注入攻击和提升性能的关键技术！绝对不要通过字符串拼接来构造 SQL 语句。

Qt 支持两种占位符语法：

命名占位符（:name）：更易读。
位置占位符（?）：更简洁。

使用prepare()方法来准备一个带占位符的 SQL 语句，然后用bindValue()或addBindValue()来绑定实际的值，最后调用exec()。

// 使用命名占位符 QSqlQuery query; query.prepare("INSERT INTO person (name, age) VALUES (:name, :age)"); query.bindValue(":name", "Bob"); query.bindValue(":age", 25); if (!query.exec()) { qDebug() << "Insert failed:" << query.lastError(); } // 使用位置占位符 query.prepare("UPDATE person SET age = ? WHERE name = ?"); query.addBindValue(31); // 绑定第一个问号的值 query.addBindValue("Alice"); // 绑定第二个问号的值 if (!query.exec()) { qDebug() << "Update failed:" << query.lastError(); } // 参数化查询同样适用于 SELECT query.prepare("SELECT * FROM person WHERE age > :minAge"); query.bindValue(":minAge", 20); if (query.exec()) { while (query.next()) { // ... 处理结果 } }

为什么必须使用参数化查询？

安全：用户输入的值被当作数据而非 SQL 代码的一部分，从根本上杜绝了 SQL 注入。
性能：数据库服务器可以对预处理语句进行编译和缓存，当多次执行相同结构的语句时（仅值不同），效率更高。
便利：自动处理了字符串中的引号转义等问题。

3.3 事务处理

事务用于确保一系列数据库操作要么全部成功，要么全部失败，保证数据的一致性。Qt 通过QSqlDatabase来管理事务。

QSqlDatabase db = QSqlDatabase::database(); // 获取当前连接 if (db.transaction()) { // 开始事务 QSqlQuery query; bool ok = true; ok = ok && query.exec("UPDATE account SET balance = balance - 100 WHERE id = 1"); ok = ok && query.exec("UPDATE account SET balance = balance + 100 WHERE id = 2"); if (ok) { if (!db.commit()) { // 提交事务 qCritical() << "Commit failed:" << db.lastError().text(); db.rollback(); // 提交失败，回滚 } else { qDebug() << "Transaction committed successfully."; } } else { qCritical() << "One of the operations failed, rolling back."; db.rollback(); // 操作失败，回滚 } } else { qCritical() << "Failed to start transaction:" << db.lastError().text(); }

关键点：

在调用transaction()后，所有通过该连接执行的 SQL 语句都处于同一个事务中。
只有调用commit()后，更改才会永久生效。
如果任何操作失败，或者在commit()之前发生异常，必须调用rollback()来撤销所有未提交的更改。
某些数据库（如 SQLite）在非显式事务下，每条语句都默认在一个自动提交的事务中执行，但显式事务对于批量操作和保证原子性至关重要。

3.4 查询元数据与结果集信息

QSqlQuery提供了一些方法来获取查询结果的信息。

QSqlQuery query("SELECT id, name, age FROM person"); if (query.exec()) { // 获取查询结果的记录（行）格式 QSqlRecord record = query.record(); int columnCount = record.count(); for (int i = 0; i < columnCount; ++i) { QString columnName = record.fieldName(i); QVariant::Type columnType = record.field(i).type(); qDebug() << "Column" << i << ":" << columnName << "Type:" << columnType; } // 判断查询是否有效（是否有结果） if (query.isActive() && query.isSelect()) { qDebug() << "Query is a SELECT and is active."; // 获取结果集大小（注意：并非所有驱动都支持，可能返回-1） int size = query.size(); qDebug() << "Result size (may be -1 if unknown):" << size; } // 判断查询是否位于结果集的有效位置 if (query.isValid()) { // 当前行是有效的（例如，在 next() 之后且未越界） } }

4. 完整实战案例：构建一个简单的通讯录管理程序

现在，我们将综合运用QSqlDatabase和QSqlQuery，构建一个命令行下的简易通讯录管理程序。这个案例将涵盖数据库初始化、增删改查（CRUD）操作、以及错误处理。

4.1 项目结构与数据库设计

我们创建一个简单的Contact类来表示联系人，并使用 SQLite 数据库存储。

数据库表设计 (contacts表)：

id(INTEGER PRIMARY KEY AUTOINCREMENT)
name(TEXT NOT NULL)
phone(TEXT NOT NULL)
email(TEXT)

4.2 核心代码实现

头文件contactdb.h：

#ifndef CONTACTDB_H #define CONTACTDB_H #include <QString> #include <QSqlDatabase> #include <QSqlQuery> #include <QVector> struct Contact { int id; QString name; QString phone; QString email; Contact() : id(-1) {} Contact(const QString &name, const QString &phone, const QString &email = QString()) : id(-1), name(name), phone(phone), email(email) {} }; class ContactDB { public: ContactDB(); ~ContactDB(); bool initDatabase(const QString &dbPath = "contacts.db"); bool addContact(const Contact &contact); bool updateContact(const Contact &contact); bool deleteContact(int id); QVector<Contact> getAllContacts(); Contact findContactById(int id); QVector<Contact> findContactsByName(const QString &name); QString lastError() const { return m_lastError; } private: QSqlDatabase m_db; QString m_lastError; bool executeQuery(QSqlQuery &query); // 辅助函数，执行并检查错误 }; #endif // CONTACTDB_H

源文件contactdb.cpp：

#include "contactdb.h" #include <QDebug> #include <QSqlError> ContactDB::ContactDB() { // 构造函数中不打开连接，由 initDatabase 负责 } ContactDB::~ContactDB() { if (m_db.isOpen()) { m_db.close(); } // 注意：我们使用默认连接名，通常不需要手动 removeDatabase， // 除非在程序生命周期内需要多次销毁和重建连接。 // QSqlDatabase::removeDatabase(QSqlDatabase::defaultConnection); } bool ContactDB::initDatabase(const QString &dbPath) { // 如果已经打开，先关闭 if (m_db.isOpen()) { m_db.close(); } // 添加 SQLite 驱动并配置 m_db = QSqlDatabase::addDatabase("QSQLITE"); m_db.setDatabaseName(dbPath); if (!m_db.open()) { m_lastError = m_db.lastError().text(); qCritical() << "Failed to open database:" << m_lastError; return false; } // 创建表 QSqlQuery query(m_db); QString createTableSQL = R"( CREATE TABLE IF NOT EXISTS contacts ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, phone TEXT NOT NULL, email TEXT ) )"; if (!query.exec(createTableSQL)) { m_lastError = query.lastError().text(); qCritical() << "Failed to create table:" << m_lastError; return false; } qDebug() << "Database initialized successfully at" << dbPath; return true; } bool ContactDB::executeQuery(QSqlQuery &query) { if (!query.exec()) { m_lastError = query.lastError().text(); qDebug() << "Query failed:" << m_lastError << "\nExecuted SQL:" << query.lastQuery(); return false; } return true; } bool ContactDB::addContact(const Contact &contact) { QSqlQuery query(m_db); query.prepare("INSERT INTO contacts (name, phone, email) VALUES (:name, :phone, :email)"); query.bindValue(":name", contact.name); query.bindValue(":phone", contact.phone); query.bindValue(":email", contact.email); if (!executeQuery(query)) { return false; } // 如果需要获取自增ID，可以在这里 query.lastInsertId().toInt(); return true; } bool ContactDB::updateContact(const Contact &contact) { if (contact.id <= 0) { m_lastError = "Invalid contact ID for update."; return false; } QSqlQuery query(m_db); query.prepare("UPDATE contacts SET name = :name, phone = :phone, email = :email WHERE id = :id"); query.bindValue(":name", contact.name); query.bindValue(":phone", contact.phone); query.bindValue(":email", contact.email); query.bindValue(":id", contact.id); return executeQuery(query); } bool ContactDB::deleteContact(int id) { QSqlQuery query(m_db); query.prepare("DELETE FROM contacts WHERE id = :id"); query.bindValue(":id", id); return executeQuery(query); } QVector<Contact> ContactDB::getAllContacts() { QVector<Contact> contacts; QSqlQuery query("SELECT id, name, phone, email FROM contacts ORDER BY name", m_db); if (executeQuery(query)) { while (query.next()) { Contact c; c.id = query.value("id").toInt(); c.name = query.value("name").toString(); c.phone = query.value("phone").toString(); c.email = query.value("email").toString(); contacts.append(c); } } return contacts; } Contact ContactDB::findContactById(int id) { Contact contact; QSqlQuery query(m_db); query.prepare("SELECT id, name, phone, email FROM contacts WHERE id = :id"); query.bindValue(":id", id); if (executeQuery(query) && query.next()) { contact.id = query.value("id").toInt(); contact.name = query.value("name").toString(); contact.phone = query.value("phone").toString(); contact.email = query.value("email").toString(); } return contact; // 如果没找到，id 会是 -1 } QVector<Contact> ContactDB::findContactsByName(const QString &name) { QVector<Contact> contacts; QSqlQuery query(m_db); query.prepare("SELECT id, name, phone, email FROM contacts WHERE name LIKE :name ORDER BY name"); query.bindValue(":name", "%" + name + "%"); // 使用 LIKE 进行模糊查询 if (executeQuery(query)) { while (query.next()) { Contact c; c.id = query.value("id").toInt(); c.name = query.value("name").toString(); c.phone = query.value("phone").toString(); c.email = query.value("email").toString(); contacts.append(c); } } return contacts; }

主程序main.cpp：

#include <QCoreApplication> #include <QDebug> #include "contactdb.h" int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); ContactDB dbManager; if (!dbManager.initDatabase()) { qCritical() << "Cannot initialize database. Exiting."; return -1; } // 1. 添加联系人 Contact alice("Alice Johnson", "123-456-7890", "alice@example.com"); Contact bob("Bob Smith", "987-654-3210"); Contact charlie("Charlie Brown", "555-123-4567", "charlie@brown.org"); if (dbManager.addContact(alice) && dbManager.addContact(bob) && dbManager.addContact(charlie)) { qDebug() << "Contacts added successfully."; } // 2. 查询所有联系人 qDebug() << "\n--- All Contacts ---"; QVector<Contact> allContacts = dbManager.getAllContacts(); for (const Contact &c : allContacts) { qDebug() << QString("ID:%1, Name:%2, Phone:%3, Email:%4") .arg(c.id).arg(c.name).arg(c.phone).arg(c.email); } // 3. 按名称查找（模糊查询） qDebug() << "\n--- Contacts with 'a' in name ---"; QVector<Contact> found = dbManager.findContactsByName("a"); for (const Contact &c : found) { qDebug() << c.name << "-" << c.phone; } // 4. 更新联系人 Contact toUpdate = dbManager.findContactById(2); // 假设 Bob 的 ID 是 2 if (toUpdate.id > 0) { toUpdate.email = "bob.smith@newdomain.com"; if (dbManager.updateContact(toUpdate)) { qDebug() << "\nUpdated Bob's email."; } } // 5. 再次查询所有，查看更新结果 qDebug() << "\n--- All Contacts After Update ---"; allContacts = dbManager.getAllContacts(); for (const Contact &c : allContacts) { qDebug() << QString("ID:%1, Name:%2, Phone:%3, Email:%4") .arg(c.id).arg(c.name).arg(c.phone).arg(c.email); } // 6. 删除一个联系人 if (dbManager.deleteContact(3)) { // 假设 Charlie 的 ID 是 3 qDebug() << "\nDeleted Charlie."; } qDebug() << "\n--- Final Contact List ---"; allContacts = dbManager.getAllContacts(); for (const Contact &c : allContacts) { qDebug() << c.name; } qDebug() << "\nDemo finished."; // 程序结束，ContactDB 析构函数会关闭数据库连接 return 0; }

4.3 运行与验证

将上述三个文件放在同一个目录，并创建一个简单的.pro文件：

QT += core sql QT -= gui CONFIG += c++17 console CONFIG -= app_bundle TARGET = ContactManager TEMPLATE = app SOURCES += \ main.cpp \ contactdb.cpp HEADERS += \ contactdb.h

在 Qt Creator 中打开项目并构建运行，或者在命令行中使用qmake和make。程序运行后，你将在当前目录看到一个contacts.db文件，并且控制台会输出完整的 CRUD 操作日志。

5. 常见问题与排查思路

在使用QSqlDatabase和QSqlQuery时，你可能会遇到以下典型问题：

问题现象	常见原因	解决思路
`QSqlDatabase: QSQLITE driver not loaded`	1. 项目`.pro`文件未添加`QT += sql`。 2. SQLite 驱动插件未正确编译或部署。	1. 检查`.pro`或`CMakeLists.txt`，确保已添加 SQL 模块。 2. 对于 SQLite，它通常是内置的。对于其他驱动（如 MySQL），确保对应的`.dll`(Windows) 或`.so`(Linux) 文件存在于 Qt 安装目录的`plugins/sqldrivers`子目录下，并且应用程序能访问到它。
`QSqlDatabase: QMYSQL driver not loaded`	MySQL 驱动未正确部署或依赖的客户端库（如`libmysql.dll`）缺失。	1. 确认`qsqlmysql.dll`(或`libqsqlmysql.so`) 存在。 2. 将 MySQL 的客户端库（如`libmysql.dll`）复制到应用程序可执行文件同级目录或系统 PATH 路径下。 3. 在 Windows 上，可能需要安装 MySQL Connector/C。
`Database connection not open`或`QSqlQuery::exec: database not open`	在创建`QSqlQuery`对象时未指定有效的数据库连接，或者连接已关闭。	1. 确保在创建`QSqlQuery`前，对应的`QSqlDatabase`对象已成功调用`open()`。 2. 如果使用多连接，创建`QSqlQuery`时需传入对应的`QSqlDatabase`对象：`QSqlQuery query(specificDb);`。 3. 检查连接是否因异常被关闭。
`Parameter count mismatch`	`prepare()`语句中的占位符数量与`bindValue()`或`addBindValue()`提供的值数量不匹配。	仔细检查 SQL 语句中的占位符（`:name`或`?`）数量，并确保绑定了相同数量的值。命名占位符要确保名称完全一致（包括前面的冒号）。
`Unable to fetch row`或`QSqlQuery::value: not positioned on a valid record`	在调用`value()`获取数据前，没有调用`next()`将查询定位到有效的行，或者已经遍历完所有行。	1. 在执行`SELECT`查询后，必须先调用`query.next()`才能访问第一行数据。 2. 在循环遍历时，每次迭代前用`while(query.next())`判断。 3. 调用`query.first()`可以回到第一行（如果驱动支持）。
中文乱码	数据库、连接、Qt 应用程序三者的字符编码不统一。	1. 对于 MySQL，在连接后执行`SET NAMES 'utf8mb4'`语句：`query.exec("SET NAMES 'utf8mb4'");`。 2. 确保数据库表的字符集为 UTF-8。 3. 在 Qt 中，字符串使用`QString`，它内部是 Unicode，通常能正确处理。
事务不起作用或自动提交	1. 某些数据库（如 SQLite 在某些配置下）默认是自动提交模式。 2. 事务操作（`transaction()`,`commit()`,`rollback()`）没有在同一个连接对象上调用。	1. 确保在开始事务（`db.transaction()`）后，所有相关查询都使用同一个`db`连接。 2. 查阅数据库文档，确认其默认事务行为。
查询性能慢	1. 未使用索引。 2. 频繁打开关闭连接。 3. 未使用参数化查询导致语句无法被数据库缓存。	1. 对经常用于`WHERE`,`JOIN`,`ORDER BY`的列创建索引。 2. 复用数据库连接（连接池在大型应用中考虑）。 3.始终使用参数化查询。 4. 对于大量数据插入，考虑使用事务包裹。

6. 最佳实践与工程建议

掌握了基础用法后，遵循以下最佳实践能让你的数据库代码更加健壮和高效。

始终使用参数化查询：这是安全性和性能的基石，再强调也不为过。永远不要拼接用户输入来构造 SQL 字符串。
集中管理数据库连接：像我们实战案例中的ContactDB类一样，将数据库连接、初始化、错误处理封装在一个专门的类中。避免在业务代码中散落着连接字符串和裸QSqlQuery调用。
实施严谨的错误处理：不要仅仅检查exec()的返回值。利用QSqlQuery::lastError()和QSqlDatabase::lastError()获取详细的错误信息并记录日志。在生产环境中，错误信息应记录到文件或监控系统，而非仅打印到控制台。
管理连接生命周期：
- 在应用程序启动时初始化连接池或主连接。
- 在长时间空闲时，考虑连接的健康检查或重连机制。
- 在应用程序关闭时，有序地关闭所有连接。
考虑使用连接池（对于多线程服务器应用）：Qt 本身不提供内置的连接池，但你可以自己实现一个简单的池，或者使用第三方库。基本原则是每个线程拥有独立的数据库连接。
合理使用事务：
- 将相关的多个更新操作放在一个事务中。
- 事务范围应尽可能小，尽快提交或回滚，以减少锁竞争。
- 处理异常时，确保在catch块或作用域退出前进行回滚。
优化查询：
- 只选择需要的列（SELECT column1, column2而非SELECT *）。
- 使用WHERE子句和索引来限制结果集大小。
- 对于复杂的、频繁使用的查询，可以考虑在数据库中创建视图（View）。
资源清理：QSqlQuery对象在析构时会自动清理其持有的结果集资源。但显式地调用QSqlQuery::finish()或QSqlQuery::clear()在长期持有查询对象的场景下可能有助于及时释放资源。
面向模型编程：对于有 GUI 且需要表格展示数据的应用，优先考虑使用QSqlTableModel或QSqlQueryModel。它们能自动与QTableView等视图组件同步，大大简化开发。本文聚焦底层 API，但在实际项目中，模型类是提高开发效率的利器。
日志与监控：记录重要的数据库操作（特别是更新和删除）的日志，包括操作者、时间、影响行数等，便于审计和问题排查。

通过本文的系统学习，你应该已经掌握了QSqlDatabase和QSqlQuery从基础连接到高级事务管理的核心用法。关键在于理解连接的生命周期、安全地执行 SQL 语句、以及妥善地处理错误。将这些知识融入到你自己的项目封装中，就能构建出稳定可靠的数据访问层。接下来，你可以进一步探索QSqlTableModel如何简化 GUI 开发，或者研究如何将这套模式应用到更复杂的数据库如 PostgreSQL 或 Oracle 中。