本章重要 API 函数#

💡 Tips：最容易踩的”API 误用”是忘记给工程文件 .pro 加 QT += sql（qmake）或在 CMake 里 find_package(Qt6 COMPONENTS Sql)——不挂 SQL 模块，QSqlDatabase 连头文件都找不到，链接期报 undefined reference。另一个坑：addDatabase 的第二个参数（连接名）在多线程下必须显式区分，否则多个线程拿到同一个 defaultConnection 会互相踩踏。

本章目录#

点击条目可跳转到对应小节。

学习前后依赖#

💡 Tips：为什么把它放在最后？因为数据库操作本质是把”前面所有机制”串起来用——UI 显示靠 QWidget、交互靠信号槽、大数据渲染靠绘图、后台读写靠线程。先会前面 21 篇，这一篇自然就是”组合技”。

1. 概述#

SQLite 是一个进程内嵌入式关系数据库，整个数据库就是一个文件，不需要独立的数据库服务器进程，非常适合桌面/嵌入式 Qt 程序的本地持久化（配置、缓存、离线数据、小型业务库）。Qt 通过 Qt SQL 模块统一封装了对多种数据库（SQLite、MySQL、PostgreSQL、ODBC 等）的访问，且对 SQLite 提供开箱即用的驱动（QSQLITE）。

本篇要解决的不是”SQL 语法怎么写”，而是”在 Qt 里怎么正确地打开库、安全地填参数、可靠地读结果、避免连接与线程雷区”。

💡 Tips：概述里最该记住的一句话——QSqlDatabase 是”连接”的句柄，QSqlQuery 是”一次操作”的执行器；一个连接可以跑无数条 query，但 query 默认依附于当前默认连接的数据库。把二者关系搞混，是 90% 初学者报 “no such table” 的根源（query 跑到了错误的连接上）。

2. 核心概念 / 原理#

Qt SQL 的层次可以拆成四层：

1. 驱动层（QSqlDriver）：真正和数据库对话的底层适配器。SQLite 驱动由 Qt 内置，只要 QT += sql 即可用，不需要额外安装客户端库（这点与 MySQL/PostgreSQL 不同）。
2. 连接层（QSqlDatabase）：代表一条到数据库的连接。通过 QSqlDatabase::addDatabase("QSQLITE") 注册，同一个连接名全局唯一；用 setDatabaseName 指定文件，用 open() 真正建立。
3. 操作层（QSqlQuery）：执行 SQL、遍历结果。可以 exec(sql) 一步执行，也可以 prepare + bindValue + exec 做参数化（强烈推荐，防 SQL 注入 + 正确处理引号/二进制）。
4. 模型层（QSqlTableModel / QSqlQueryModel）：把查询结果包装成 Qt 的 model，直接 setModel() 挂到 QTableView 上，自动实现增删改与刷新，免手写表格绘制。

💡 Tips：原理上最容易误解的是”SQLite 是文件，所以随便哪个线程都能打开同一个文件读写”。错。SQLite 文件可以被多线程访问，但同一个 QSqlDatabase 连接对象不是线程安全的——每个线程必须拥有自己独立的连接（不同连接名）。Qt 会直接断言/报错如果你跨线程使用同一个连接。

3. Qt SQL 操作 SQLite 总体流程#

💡 Tips：流程里最关键的两个箭头是 C --> D（一定要判 open() 返回值，很多”打不开”其实是因为路径所在目录不存在或文件被占用）和 E（构造 QSqlQuery 时把 db 传进去，否则它默认用 defaultConnection，在多线程或你建了多个连接时就会跑错库）。另外 CREATE TABLE 几乎总是加 IF NOT EXISTS，否则第二次运行直接 exec 失败。

4. 核心代码解析#

说明：本仓库 qt22_tst_SQLite 文件夹实际只含 .idea IDE 配置、没有可参考的源码，以下采用 Qt 操作 SQLite 的标准示例写法，覆盖本篇全部要点，可直接照搬进任何 Qt Widgets 工程。

1
#include <QSqlDatabase>
2
#include <QSqlQuery>
3
#include <QSqlError>
4
#include <QVariant>
5
#include <QDebug>
6

7
void demoSqlite()
8
{
9
    // 1) 注册并打开连接（显式给连接名，便于多线程扩展）
10
    QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE", "conn1");
11
    db.setDatabaseName("demo.db");          // 文件库；换成 ":memory:" 即内存库
12
    if (!db.open()) {                        // ⚠️ 必须判返回值
13
        qDebug() << "打开失败:" << db.lastError().text();
14
        return;
15
    }
16

17
    // 2) 建表（IF NOT EXISTS 避免重复运行报错）
18
    QSqlQuery query(db);                     // ⚠️ 把 db 传进去，确保跑在这条连接上
19
    query.exec("CREATE TABLE IF NOT EXISTS user ("
20
               "id INTEGER PRIMARY KEY AUTOINCREMENT, "
21
               "name TEXT NOT NULL, age INTEGER)");
22

23
    // 3) 参数化插入（? 占位，bindValue 位置从 0 开始）
24
    query.prepare("INSERT INTO user(name, age) VALUES(?, ?)");
25
    query.bindValue(0, "Alice");
26
    query.bindValue(1, 20);
27
    if (!query.exec()) qDebug() << "插入失败:" << query.lastError().text();
28

29
    // 4) 查询并遍历
30
    if (query.exec("SELECT id, name, age FROM user")) {
31
        while (query.next()) {
32
            int id   = query.value(0).toInt();
33
            QString n = query.value(1).toString();
34
            int age  = query.value(2).toInt();
35
            qDebug() << id << n << age;
36
        }
37
    }
38

39
    // 5) 命名绑定 + 更新
40
    query.prepare("UPDATE user SET age = :age WHERE name = :name");
41
    query.bindValue(":age", 21);
42
    query.bindValue(":name", "Alice");
43
    query.exec();
44

45
    db.close();   // 析构时也会自动关闭
46
}

💡 Tips：这段代码里藏着 4 个细节——① addDatabase 的第二个参数 "conn1" 在多线程时是救命稻草；② QSqlQuery query(db) 的 db 实参，漏写就会默认连到 defaultConnection，若你之前用默认连接打开过别的库就会串库；③ AUTOINCREMENT 让 id 自增，查询回来用 value(0).toInt() 取；④ bindValue 对 ? 用数字下标（从 0），对 :name 用字符串名——两套不能混用，否则绑定不生效、SQL 里留着 ? 直接报错。

5. 运行效果 / 验证#

正确运行后：控制台按行打印 1 Alice 20（插入后查询），执行 UPDATE 后再次查询应为 1 Alice 21；工程目录下出现 demo.db 文件（用 DB Browser for SQLite / sqlite3 命令行打开能看到 user 表与数据）。若用 :memory:，则程序退出后库消失，文件不会留下。

最低验证步骤：

1. .pro 加 QT += sql 或 CMake find_package(Qt6 COMPONENTS Sql REQUIRED) + target_link_libraries(xx Qt6::Sql)；
2. 编译运行，观察 qDebug 输出与 open() 是否成功；
3. 用外部 SQLite 工具打开 demo.db 确认表真实写入。

💡 Tips：验证时最容易误判”成功”的假象是——代码没崩、也没打印 lastError，就以为写入了。其实 exec() 返回 false 但你可能没检查返回值，数据根本没进库。务必养成”每个 exec/写入后查 lastError 或判返回值”的习惯；更稳妥的是用外部工具打开 .db 文件做”双保险”验证。

容易踩坑（注意点）#

• 坑 1：没加 QT += sql。现象：编译报 QSqlDatabase: No such file or directory 或链接 undefined reference to QSqlDatabase。原因：SQL 模块未引入。规避：qmake 工程 .pro 加 QT += sql；CMake 工程 find_package(Qt6 COMPONENTS Sql) 并链接 Qt6::Sql。
• 坑 2：open() 不判返回值。现象：后面 exec 全部失败、lastError 显示 “out of memory” 或空。原因：连接根本没打开（路径目录不存在、文件被别的进程锁住、权限不足）。规避：永远 if (!db.open()) { qDebug() << db.lastError().text(); return; }。
• 坑 3：跨线程共用同一连接。现象：偶发崩溃或 QSqlDatabasePrivate::removeDatabase 断言。原因：QSqlDatabase 非线程安全。规避：每个线程 addDatabase("QSQLITE", uniqueName) 各自建连接，不要传递连接对象跨线程。
• 坑 4：参数绑定混用 ? 与 :name。现象：SQL 执行报错 “near ?: syntax error” 或值没写进去。原因：bindValue 下标与占位符类型不匹配。规避：? 用 bindValue(int, val)（从 0），:name 用 bindValue(":name", val)，二选一保持一致。
• 坑 5：忘记给 QSqlQuery 传连接。现象：no such table（表确实建了，但 query 跑在另一条连接上）。原因：没把 db 传给 QSqlQuery 构造。规避：QSqlQuery query(db); 显式绑定。
• 坑 6：文件路径用相对路径结果找不到库。现象：每次运行都像”新建空库”。原因：相对路径相对于程序工作目录（调试时往往是构建目录而非源码目录）。规避：用 QCoreApplication::applicationDirPath() + "/demo.db" 或绝对路径，或用 :memory: 明确语义。

学习要点总结#

Q&A（常见问题）#

Q1：为什么我 exec("INSERT ...") 没报错，但数据库里却没有数据？ A1：最常见两种原因——① 没检查 exec() 返回值，实际返回 false，错误被你忽略了（务必 if(!query.exec()) qDebug()<<query.lastError().text();）；② 你 QSqlQuery 没传 db，它跑在了默认的空连接上，根本没写进你打开的那个库。用外部 SQLite 工具打开 .db 文件做二次确认最稳妥。

Q2：QSqlDatabase::addDatabase 的”连接名”到底有什么用？ A2：Qt 维护一个”连接名 → 连接对象”的全局映射，默认名是 defaultConnection。单线程单库时不用管；但当你需要同时开多个库，或多线程各开一条连接时，必须给不同连接名（如 "conn1"、"conn2"），否则后 addDatabase 的会覆盖前面的，导致旧连接失效甚至断言崩溃。QSqlQuery 构造时传入对应 QSqlDatabase 对象，才能精确指定跑在哪条连接上。

Q3：? 和 :name 两种占位符能混着用吗？ A3：不能。一条 SQL 里要么全用 ?（位置绑定，bindValue(0, v)、bindValue(1, v)……从 0 开始），要么全用 :name（命名绑定，bindValue(":name", v)）。混用会导致绑定顺序错位或根本不生效，exec 报错。推荐用 :name，可读性更好、参数顺序不易错。

Q4：SQLite 在 Qt 里是线程安全的吗？可以直接在子线程读写吗？ A4：SQLite 文件本身支持多线程访问，但 Qt 的 QSqlDatabase 连接对象不是线程安全的。正确做法：在子线程里重新 addDatabase("QSQLITE", 该线程专属名) 并建立自己的连接，再通过信号槽把结果回传主线程更新 UI（见 19 线程）。绝对不要把一个在主线程建立的 QSqlDatabase 直接丢给子线程用。

Q5：内存数据库 :memory: 和文件数据库有什么区别？ A5：:memory: 整个库存在 RAM，进程退出即销毁，常用于单元测试、临时计算；文件库（如 demo.db）持久化到磁盘。注意：每个 :memory: 连接是相互独立的私有库，即使连接名相同，两个 :memory: 连接也看不到彼此的表——想要共享内存库，需要同一个连接对象或 file::memory:?cache=shared。

Tips（全局速记）#