Database 手册 · Chapter 1

Database 教程开始

本教程通过随 QMachineStudio 一同分发的 SampleProject/Database/DB_Sqlite 项目,从头到尾走一遍,边走边掌握数据库功能。

示例使用单个 SQLite 连接,是一个在画面上注册 · 修改 · 删除 订单作业历史(order_history 表)的小工具。本教程出现的所有代码片段都来自该项目的 RunScript/*.xms 文件。

示例项目位置

SampleProject/Database/DB_Sqlite/
├── DB_Sqlite.xmp                  # 项目文件(含 DatabaseOption)
├── XDatabase/
│   ├── connections.json           # 连接设置(与 DB Studio 同步)
│   └── LocalDB.db                 # 实际 SQLite 文件(自动生成)
└── RunScript/
    ├── Data.xms                   # DB_* 函数 (Open/Refresh/Insert/Update/Delete/...)
    ├── ViewRun.xms                # 按钮事件 (OnOpenClick / OnAddClick / ...)
    ├── ModifyDlg.xms              # 记录修改对话框
    └── (其他 Init / Mon / Event / ViewMain ...)

画面构成 — ViewRun

运行页面(ViewRun)由 6 个按钮和 1 个 XDataGrid 组成。

按钮	调用函数	行为
Open	`Data::DB_Open()`	连接 +(为空时)插入 5 条示例 + 刷新 DataGrid
Add	`Data::DB_InsertSample()`	新增一条订单 INSERT
Update	`Data::DB_UpdateSelected()`	将选中行标记为完成(end_time / result)
Modify	`Data::DB_OpenModifyDlg()`	打开对话框自由编辑,OK 时 UPDATE
Delete	`Data::DB_DeleteSelected()`	删除选中行
Close	`Data::DB_Close()`	断开连接 + 清空 DataGrid

顶部 Data::DbStatusText 标签(● OPEN / ● CLOSED)显示当前连接状态。

核心关键字 — `DB["连接名"]`

脚本中,数据库总是通过连接名访问。本示例的连接名为 local。

// 打开连接
DB["local"].Open();
 
// SELECT 之后用 RowCount / GetRowArray 读取结果
DB["local"].RunSqlSelect("SELECT id, order_no, menu_name FROM order_history ORDER BY id ASC");
int rows = DB["local"].RowCount;
 
// 单值
int total = DB["local"].RunSqlScalarInt("SELECT COUNT(*) FROM order_history");
 
// 参数绑定(防止 SQL 注入)
array p[] = {""};  p.Clear();
p.Add("O1234"); p.Add("Latte"); p.Add(SYS.DateTimeString);
DB["local"].RunSqlQueryParam(
    "INSERT INTO order_history(order_no, menu_name, start_time) VALUES(?,?,?)",
    p);
 
// 事务
DB["local"].BeginTransaction();
DB["local"].RunSqlQueryParam(/* ... */);
if( DB["local"].Commit() == false ) DB["local"].Rollback();
 
// 关闭
DB["local"].Close();

与 IO["..."]、MOTOR["..."] 等同样的命名索引惯用法,首次接触也不陌生。

学习路径

章节	主题	涉及示例代码
2	连接设置 — `connections.json` 与项目选项	`DB_Sqlite.xmp` `DatabaseOption`
3	表结构 — `order_history`	`DB_InsertInitialSamples`
4	用 DB Studio 的 SQL · Data 选项卡验证	—
5	INSERT · UPDATE — 参数绑定与事务	`DB_InsertSample` · `DB_UpdateSelected`
6	SELECT — `RowCount` · `GetRowArray` · `RunSqlScalarInt`	`DB_Refresh`
7	DataGrid · ModifyDlg 绑定	`DispData` · `SelectIndex` · `Edit*`
8	按钮事件 — `ViewRun` 处理器	`OnOpenClick` 等 6 个
9	备份 · WAL · 运维检查点	`DatabaseOption.BackupFolder` 等

建议在运行示例的同时跟随章节,亲自验证结果。