数据库 SQL
用 Qt SQL 连接数据库,完成绑定查询、事务与增删改查
#Qt SQL 的分层
先说清楚一件事:Qt SQL 不是 ORM。它不会把一行数据映射成一个 C++ 对象,也不会帮你生成迁移脚本。它是一层统一的数据库访问抽象——屏蔽掉各数据库 C API 的差异,让你用同一套类操作 SQLite、MySQL、PostgreSQL。
这意味着你仍然要自己写 SQL、自己设计表结构。换来的是可移植性,以及三个开箱即用的"模型类",可以把查询结果直接喂给 QTableView。模块由四部分组成:
| 层 | 类 | 职责 |
|---|---|---|
| 驱动层 | QSqlDriver | 与具体数据库通信(QSQLITE、QMYSQL、QPSQL…) |
| 连接层 | QSqlDatabase | 代表一个数据库连接 |
| 执行层 | QSqlQuery | 执行 SQL、绑定参数、遍历结果 |
| 模型层 | QSqlQueryModel / QSqlTableModel | 直接喂给 View 显示 |
这个设计带来一个巨大优势:换数据库只改一行代码(addDatabase("QSQLITE") → addDatabase("QMYSQL")),上层代码几乎不动。代价是它不做对象映射,你仍然要自己写 SQL。
#CMake 与模块
cmake_minimum_required(VERSION 3.16)
project(SqlDemo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(Qt6 REQUIRED COMPONENTS Widgets Sql)
qt_standard_project_setup()
qt_add_executable(SqlDemo
main.cpp
mainwindow.cpp
mainwindow.h
mainwindow.ui
)
target_link_libraries(SqlDemo PRIVATE Qt6::Widgets Qt6::Sql)编译后可用 QSqlDatabase::drivers() 打印当前支持的驱动列表。如果 QSQLITE 缺失,说明 Qt 安装时没有编译 SQLite 插件(Qt 通常自带 SQLite,MySQL 驱动则需自行编译)。
#建立连接
QSqlDatabase::addDatabase() 的第一个参数是驱动名,第二个是连接名。连接名很重要:Qt 支持多个并发连接,默认连接名为 QLatin1String(defaultConnection),不给名字就是默认连接。
#include <QSqlDatabase>
#include <QSqlError>
#include <QSqlQuery>
#include <QDebug>
#include <QDir>
#include <QStandardPaths>
bool openSqlite(const QString &file)
{
QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE"); // 同一连接名不可重复 add
db.setDatabaseName(file); // SQLite 就是文件名
if (!db.open()) {
qWarning() << "打开失败:" << db.lastError().text();
return false;
}
// 开启外键约束(SQLite 默认关闭!)
QSqlQuery q;
q.exec("PRAGMA foreign_keys = ON");
return true;
}
bool openMysql()
{
QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL", "mysql_conn");
db.setHostName("127.0.0.1");
db.setPort(3306);
db.setDatabaseName("testdb");
db.setUserName("root");
db.setPassword("secret");
db.setConnectOptions("MYSQL_OPT_RECONNECT=1"); // 可选:断线重连
if (!db.open()) {
qWarning() << "MySQL 连接失败:" << db.lastError().text();
return false;
}
return true;
}两个高频坑:
第一,重复调用 addDatabase()。同一个连接名第二次调用会让 Qt 输出警告并覆盖原连接,旧连接上的 QSqlQuery 会突然失效。正确做法是先用 QSqlDatabase::contains("name") 检查,存在就 QSqlDatabase::database("name") 取出复用。
第二,连接对象的生命周期。QSqlDatabase 是值类(隐式共享),拷贝它只是共享同一个底层连接。当最后一个 QSqlDatabase 实例析构时连接自动关闭,因此常见做法是把连接保存为成员或在 main 中长期持有,绝不能用局部变量建完就丢。
另外,QSqlDatabase 的连接不能跨线程直接使用:每个线程必须建立自己的连接,并且连接名要各不相同。
#QSqlQuery:执行与绑定
#include <QSqlQuery>
#include <QSqlError>
#include <QSqlRecord>
#include <QVariant>
#include <QDebug>
bool createTable()
{
QSqlQuery q;
// SQLite 的自增主键写法;MySQL 用 INT AUTO_INCREMENT
const QString sql = R"(
CREATE TABLE IF NOT EXISTS student (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
age INTEGER NOT NULL DEFAULT 0,
grade TEXT,
created DATETIME DEFAULT CURRENT_TIMESTAMP
)
)";
if (!q.exec(sql)) {
qWarning() << "建表失败:" << q.lastError().text();
return false;
}
return true;
}
// 命名占位符绑定(推荐)
bool insertStudent(const QString &name, int age, const QString &grade)
{
QSqlQuery q;
q.prepare("INSERT INTO student (name, age, grade) VALUES (:name, :age, :grade)");
q.bindValue(":name", name);
q.bindValue(":age", age);
q.bindValue(":grade", grade);
if (!q.exec()) {
qWarning() << "插入失败:" << q.lastError().text();
return false;
}
// 获取自增 ID
qDebug() << "新记录 ID:" << q.lastInsertId().toInt();
return true;
}
// 查询结果遍历
void listStudents()
{
QSqlQuery q("SELECT id, name, age, grade FROM student ORDER BY id");
while (q.next()) {
// 方式一:按索引(最快)
const int id = q.value(0).toInt();
// 方式二:按字段名(可读性最好)
const QString name = q.value("name").toString();
qDebug() << id << name << q.value("age").toInt() << q.value("grade").toString();
}
}
// 位置占位符(ODBC 风格)
bool updateAge(int id, int newAge)
{
QSqlQuery q;
q.prepare("UPDATE student SET age = ? WHERE id = ?");
q.addBindValue(newAge);
q.addBindValue(id);
return q.exec();
}
bool deleteStudent(int id)
{
QSqlQuery q;
q.prepare("DELETE FROM student WHERE id = :id");
q.bindValue(":id", id);
if (!q.exec()) {
return false;
}
return q.numRowsAffected() > 0; // 确认真的删到了
}必须使用绑定,禁止字符串拼接。这不只是安全问题(SQL 注入),更是正确性问题:名字里有个单引号 O'Brien 就会让拼接的 SQL 语法错误。绑定让驱动负责转义和类型转换,你也省去手写引号的麻烦。
q.value() 返回 QVariant。字段为 NULL 时返回无效 QVariant,isNull() 为 true,.toInt() 得 0——判断"字段是否有值"要用 isNull() 而非比较值。
#事务:保证一致性
事务把多个操作打包成"要么全成功,要么全回滚"。典型场景:转账、订单创建、批量导入。
#include <QSqlDatabase>
#include <QSqlQuery>
#include <QSqlError>
#include <QDebug>
bool batchImport(const QList<QStringList> &rows)
{
QSqlDatabase db = QSqlDatabase::database(); // 取默认连接
if (!db.transaction()) { // 开启事务
qWarning() << "不支持事务:" << db.lastError().text();
return false;
}
QSqlQuery q(db); // 绑定连接!
q.prepare("INSERT INTO student (name, age) VALUES (:n, :a)");
for (const QStringList &row : rows) {
if (row.size() < 2) {
db.rollback();
return false;
}
q.bindValue(":n", row.at(0));
q.bindValue(":a", row.at(1).toInt());
if (!q.exec()) {
qWarning() << "导入中断:" << q.lastError().text();
db.rollback(); // 回滚
return false;
}
}
return db.commit(); // 提交
}两个要点:
- 事务期间必须用同一个
QSqlQuery且绑定同一个连接。构造QSqlQuery(db)显式传入连接是好习惯;默认构造用的是默认连接,多线程或多连接场景下会出错。 - 任何失败路径都要
rollback()。用 RAII 封装(构造时transaction(),析构时若未commit()则rollback())能杜绝遗漏。
事务还有性能意义:SQLite 默认每条 INSERT 都单独 fsync,一万条要几秒;包在事务里只需一次刷盘,通常快几十倍。
#模型绑定:让 View 直接显示数据表
手写循环把查询结果塞进 QTableWidget 是低效且易错的。Qt SQL 提供了三个模型:
| 模型 | 读写 | 特点 |
|---|---|---|
QSqlQueryModel | 只读 | 执行任意 SELECT,结果集缓存 |
QSqlTableModel | 可读写 | 绑定单张表,自动生成 INSERT/UPDATE/DELETE |
QSqlRelationalTableModel | 可读写 | 支持外键,用下拉框显示关联字段 |
#include <QApplication>
#include <QTableView>
#include <QSqlTableModel>
#include <QSqlQueryModel>
#include <QSqlError>
#include <QHeaderView>
#include <QPushButton>
#include <QLineEdit>
#include <QVBoxLayout>
#include <QHBoxLayout>
#include <QWidget>
#include <QMessageBox>
#include <QDebug>
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE");
db.setDatabaseName("school.db");
if (!db.open()) {
qWarning() << db.lastError().text();
return 1;
}
// 可编辑模型:绑定 student 表
auto *model = new QSqlTableModel(nullptr, db);
model->setTable("student");
model->setEditStrategy(QSqlTableModel::OnManualSubmit); // 手动提交
model->setHeaderData(1, Qt::Horizontal, "姓名");
model->setHeaderData(2, Qt::Horizontal, "年龄");
model->setHeaderData(3, Qt::Horizontal, "班级");
model->select(); // 执行查询
auto *view = new QTableView();
view->setModel(model);
view->setColumnHidden(0, true); // 隐藏 id 列
view->horizontalHeader()->setSectionResizeMode(QHeaderView::Stretch);
// 过滤:等价于 WHERE 子句
auto *filterEdit = new QLineEdit();
filterEdit->setPlaceholderText("按姓名过滤…");
QObject::connect(filterEdit, &QLineEdit::textChanged, model, [model](const QString &t) {
model->setFilter(QString("name LIKE '%%1%'").arg(t));
model->select();
});
auto *submitBtn = new QPushButton("保存修改");
auto *revertBtn = new QPushButton("撤销");
auto *addBtn = new QPushButton("新增一行");
auto *delBtn = new QPushButton("删除选中");
QObject::connect(submitBtn, &QPushButton::clicked, view, [model, view] {
if (!model->submitAll()) {
QMessageBox::critical(view, "保存失败", model->lastError().text());
}
});
QObject::connect(revertBtn, &QPushButton::clicked, model, [model] {
model->revertAll();
});
QObject::connect(addBtn, &QPushButton::clicked, model, [model] {
QSqlRecord rec = model->record();
rec.setValue("name", "新学生");
rec.setValue("age", 18);
model->insertRecord(-1, rec); // -1 = 追加到末尾
});
QObject::connect(delBtn, &QPushButton::clicked, view, [model, view] {
const int row = view->currentIndex().row();
if (row >= 0) {
model->removeRow(row);
}
});
auto *w = new QWidget();
auto *lay = new QVBoxLayout(w);
lay->addWidget(filterEdit);
lay->addWidget(view);
auto *hl = new QHBoxLayout();
hl->addWidget(addBtn);
hl->addWidget(delBtn);
hl->addWidget(submitBtn);
hl->addWidget(revertBtn);
lay->addLayout(hl);
w->resize(600, 400);
w->show();
return app.exec();
}#编辑策略的选择
QSqlTableModel 的 setEditStrategy() 决定了修改何时写库:
| 策略 | 行为 | 适用 |
|---|---|---|
OnFieldChange | 每次编辑完成立即 UPDATE | 单机小工具,实时生效 |
OnRowChange | 切换行时提交该行 | 折中方案 |
OnManualSubmit | 只有 submitAll() 才写库 | 推荐:支持"保存/撤销",可包事务 |
生产环境几乎都应该用 OnManualSubmit + 事务:用户在界面上改了十行,点"保存"才批量提交,中途可以"撤销"回到初始状态。
#只读模型与自定义列
QSqlQueryModel 适合复杂联表查询,但它是只读的。若想加一列"操作"按钮,需要子类化重写 data() 和 columnCount():
#include <QSqlQueryModel>
class StudentQueryModel : public QSqlQueryModel
{
Q_OBJECT
public:
explicit StudentQueryModel(QObject *parent = nullptr) : QSqlQueryModel(parent) {}
int columnCount(const QModelIndex & = QModelIndex()) const override
{
return QSqlQueryModel::columnCount() + 1; // 多加一列
}
QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override
{
if (index.column() < QSqlQueryModel::columnCount()) {
return QSqlQueryModel::data(index, role);
}
if (role != Qt::DisplayRole) {
return {};
}
// 用第 2 列的年龄派生出"是否成年"
const int age = QSqlQueryModel::data(
this->index(index.row(), 2), Qt::DisplayRole).toInt();
return age >= 18 ? "成年" : "未成年";
}
};这里有个易错点:this->index(row, col) 是 QAbstractItemModel::index(),属于子类模型的列空间;而 QSqlQueryModel::data() 需要源模型的列索引。因此派生列计算时必须用 this->index(index.row(), 2),绝不能用 index.siblingAtColumn(2) 之后直接传给基类——因为 index 已经带上了子模型的列信息。
#错误处理清单
数据库操作几乎每一环都可能失败,而且失败原因往往在运行时才暴露(磁盘满、锁超时、字段超长)。不要假设任何一次调用会成功,下面这张表就是上线前逐条自查用的清单:
| 环节 | 检查方式 |
|---|---|
| 连接 | db.open() 返回值 + db.lastError().text() |
| 建表/插入/更新 | q.exec() 返回值 + q.lastError() |
| 影响行数 | q.numRowsAffected()(DELETE/UPDATE 后判断是否真的命中) |
| 模型刷新 | model->select() 后检查 model->lastError() |
| 事务 | transaction() / commit() 的返回值都可能是 false |
| 驱动缺失 | QSqlDatabase::drivers() 打印可用驱动 |
#完整 CRUD 小结:StudentRepository
把散落的 SQL 收拢到一个类里,是工程化的第一步:
// studentrepository.h —— 精简版,展示结构
#include <QString>
#include <QList>
#include <QSqlDatabase>
struct Student {
int id = 0;
QString name;
int age = 0;
QString grade;
};
class StudentRepository
{
public:
explicit StudentRepository(QSqlDatabase db = QSqlDatabase::database());
bool createTable();
bool add(const Student &s);
bool update(const Student &s);
bool remove(int id);
QList<Student> all();
QList<Student> findByName(const QString &keyword);
private:
QSqlDatabase m_db;
};// studentrepository.cpp 关键实现
#include "studentrepository.h"
#include <QSqlQuery>
#include <QSqlError>
#include <QDebug>
StudentRepository::StudentRepository(QSqlDatabase db) : m_db(db) {}
bool StudentRepository::add(const Student &s)
{
QSqlQuery q(m_db); // 显式绑定连接
q.prepare("INSERT INTO student (name, age, grade) VALUES (:n, :a, :g)");
q.bindValue(":n", s.name);
q.bindValue(":a", s.age);
q.bindValue(":g", s.grade);
return q.exec();
}
bool StudentRepository::update(const Student &s)
{
QSqlQuery q(m_db);
q.prepare("UPDATE student SET name=:n, age=:a, grade=:g WHERE id=:id");
q.bindValue(":n", s.name);
q.bindValue(":a", s.age);
q.bindValue(":g", s.grade);
q.bindValue(":id", s.id);
return q.exec();
}
bool StudentRepository::remove(int id)
{
QSqlQuery q(m_db);
q.prepare("DELETE FROM student WHERE id=:id");
q.bindValue(":id", id);
return q.exec();
}
QList<Student> StudentRepository::all()
{
QList<Student> list;
QSqlQuery q(m_db);
if (!q.exec("SELECT id, name, age, grade FROM student ORDER BY id")) {
qWarning() << q.lastError().text();
return list;
}
while (q.next()) {
list.push_back({q.value("id").toInt(), q.value("name").toString(),
q.value("age").toInt(), q.value("grade").toString()});
}
return list;
}
QList<Student> StudentRepository::findByName(const QString &keyword)
{
QList<Student> list;
QSqlQuery q(m_db);
q.prepare("SELECT id, name, age, grade FROM student WHERE name LIKE :kw");
// 注意:LIKE 的通配符要拼在绑定值里,不是 SQL 里
q.bindValue(":kw", QString("%%1%").arg(keyword));
if (!q.exec()) {
return list;
}
while (q.next()) {
list.push_back({q.value("id").toInt(), q.value("name").toString(),
q.value("age").toInt(), q.value("grade").toString()});
}
return list;
}findByName() 里那行注释值得记住:LIKE :kw 而不是 LIKE '%:kw%'。因为占位符在引号内不会被识别,通配符必须作为绑定值的一部分传入。这是初学者最常卡住的地方之一。
Qt 5 提示:Qt 6 中
QStringLiteral("book")与QStringLiteral系列 API 一致;两代在 SQL 模块上的差异主要是 Qt 6 默认不再提供部分老旧驱动(如 QODBC 需单独安装),以及QSqlQuery::exec()的批量模式 API 名称统一为execBatch()。
#小结
- Qt SQL 是驱动/连接/执行/模型四层抽象,换库只需改
addDatabase()的驱动名。 - 参数必须绑定(
bindValue/prepare),既防注入又避免引号转义错误;LIKE的通配符要放进绑定值。 QVariant为NULL时用isNull()判断,不要比较转换后的值。QSqlTableModel用OnManualSubmit策略,配合submitAll()/revertAll()和事务,实现"保存/撤销"。- 所有环节都要检查返回值与
lastError();DELETE/UPDATE后可用numRowsAffected()确认命中。
#练习
- 在
StudentRepository中加入按班级统计人数与平均年龄的方法,用QSqlQuery执行GROUP BY查询并返回结果。 - 实现批量导入 1000 条学生记录,对比"逐条提交"与"事务 + prepare 复用"的耗时差异。
- 用
QSqlRelationalTableModel建立student与class表的外键关联,使"班级"列在QTableView中显示为下拉框。 - 给 CRUD 界面加上错误处理:连接失败、主键冲突、字段超长分别给出不同的中文提示,并保证事务回滚后数据一致。