QC++ / Qt 学习之路

数据库 SQL

用 Qt SQL 连接数据库,完成绑定查询、事务与增删改查

进阶第 31 / 48 章第四篇 · Qt 进阶

#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
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),不给名字就是默认连接。

C++
#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:执行与绑定

C++
#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() 而非比较值。

#事务:保证一致性

事务把多个操作打包成"要么全成功,要么全回滚"。典型场景:转账、订单创建、批量导入。

C++
#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();                                  // 提交
}

两个要点:

  1. 事务期间必须用同一个 QSqlQuery 且绑定同一个连接。构造 QSqlQuery(db) 显式传入连接是好习惯;默认构造用的是默认连接,多线程或多连接场景下会出错。
  2. 任何失败路径都要 rollback()。用 RAII 封装(构造时 transaction(),析构时若未 commit() 则 rollback())能杜绝遗漏。

事务还有性能意义:SQLite 默认每条 INSERT 都单独 fsync,一万条要几秒;包在事务里只需一次刷盘,通常快几十倍。

#模型绑定:让 View 直接显示数据表

手写循环把查询结果塞进 QTableWidget 是低效且易错的。Qt SQL 提供了三个模型:

模型读写特点
QSqlQueryModel只读执行任意 SELECT,结果集缓存
QSqlTableModel可读写绑定单张表,自动生成 INSERT/UPDATE/DELETE
QSqlRelationalTableModel可读写支持外键,用下拉框显示关联字段
C++
#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():

C++
#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 收拢到一个类里,是工程化的第一步:

C++
// 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;
};
C++
// 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()。

#小结

  1. Qt SQL 是驱动/连接/执行/模型四层抽象,换库只需改 addDatabase() 的驱动名。
  2. 参数必须绑定(bindValue / prepare),既防注入又避免引号转义错误;LIKE 的通配符要放进绑定值。
  3. QVariant 为 NULL 时用 isNull() 判断,不要比较转换后的值。
  4. QSqlTableModel 用 OnManualSubmit 策略,配合 submitAll()/revertAll() 和事务,实现"保存/撤销"。
  5. 所有环节都要检查返回值与 lastError();DELETE/UPDATE 后可用 numRowsAffected() 确认命中。

#练习

  1. 在 StudentRepository 中加入按班级统计人数与平均年龄的方法,用 QSqlQuery 执行 GROUP BY 查询并返回结果。
  2. 实现批量导入 1000 条学生记录,对比"逐条提交"与"事务 + prepare 复用"的耗时差异。
  3. 用 QSqlRelationalTableModel 建立 student 与 class 表的外键关联,使"班级"列在 QTableView 中显示为下拉框。
  4. 给 CRUD 界面加上错误处理:连接失败、主键冲突、字段超长分别给出不同的中文提示,并保证事务回滚后数据一致。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。