Database 手册 · Chapter 9

备份 · WAL · 运维检查点

示例项目的 DatabaseOption 块也包含运维所需的选项。脚本不会直接操作它们,但这些是 在量产环境中最能避免重大问题 的设置,单设一章。

DB_Sqlite.xmp 的运维选项

"DatabaseOption": {
  "Connections": [ /* ... */ ],
  "BackupFolder": "XDatabase/Backup",
  "AutoBackupEnabled": false,
  "AutoBackupIntervalHours": 24,
  "BackupKeepLast": 30,
  "JournalMode": "WAL"
}

按选项整理含义与推荐值。

1) JournalMode — 推荐 `WAL`

SQLite 的日志模式决定事务数据的记录方式。

值	特性	推荐
`DELETE`(默认)	每事务创建/删除日志文件。单用户可接受	小工具
`WAL`	Write-Ahead Logging — 写入期间其他进程仍可读	量产推荐
`MEMORY`	仅内存日志 — 断电时有损坏风险	临时缓存
`OFF`	不写日志 — 危险	严禁

示例设为 "WAL"。WAL 的效果:

设备时序持续 INSERT 的同时,DB Studio 或外部分析工具可同时进行 SELECT
事务提交更快 — 短事务多的模式(如示例)响应性更好
异常终止时自动恢复

更改只需修改 connections.json / .xmp 中 JournalMode 的值。结果可通过 XDatabase/ 目录下出现的两个辅助文件 LocalDB.db-wal、LocalDB.db-shm 来确认。

备份注意 — 将 WAL / SHM 一并复制,或事先用 PRAGMA wal_checkpoint(TRUNCATE) 把 WAL 内的变更刷入主文件后,只复制 .db 即可。

2) BackupFolder + 手动备份

SQLite 文件是单文件,运行中也可复制(尤其是 WAL 检查点之后)。

示例把 "XDatabase/Backup" 设为备份路径。该目录中实际产生备份文件的时机,是在自动备份开启时,或工具中手动执行备份时。

选项	推荐	含义
BackupFolder	`"XDatabase/Backup"`	备份文件目录(项目相对路径)
AutoBackupEnabled	量产: `true`	周期性自动备份
AutoBackupIntervalHours	24	备份间隔(小时)
BackupKeepLast	30	保留备份数,超出自动删除

自动备份文件名通常为 {db 名}_{YYYYMMDD_HHMMSS}.db — 目录中按字母顺序排序即时间顺序。

用外部脚本备份的模式

在操作系统层面单独安排备份调度时的推荐流程:

1. PRAGMA wal_checkpoint(TRUNCATE);   // 在 SQL 选项卡执行
2. LocalDB.db   →  复制到外部磁盘 / 网络
3. (按需)     验证文件完整性

3) ConnectionTimeout / CommandTimeout / Reconnect

Connections 数组中 4 个时间选项:

选项	推荐	含义
ConnectionTimeout	15 sec	`Open()` 无响应时的放弃时间
CommandTimeout	30 sec	单条 SQL 执行超时
PingIntervalSec	10 sec	连接存活周期检查(对网络 DB 有意义)
ReconnectRetries	3	断开时自动重试次数

对单文件 SQLite 大多影响小,但迁移到 MSSQL 时这些选项原样生效,因此示例预先填入了这些值。

4) 运维代码的 6 个检查点

示例所有 DB 函数共用的 6 段防御性代码。

A. `IsOpen` 守卫

if( DB["local"].IsOpen == false )
{
   ShowMessage(EB_Ok, "DB is not open. Press [Open] first.");
   return false;
}

B. 选中行守卫

if( SelectIndex < 0 || SelectIndex >= DB["local"].RowCount )
{
   ShowMessage(EB_Ok, "Select a row first.");
   return false;
}

C. `LastError` 日志

if( DB["local"].RunSqlQueryParam(sql, p) == false )
{
   LogError($"DB_xxx failed : {DB["local"].LastError}");
   ShowMessage(EB_Ok, $"DB xxx failed : {DB["local"].LastError}");
   return false;
}

D. 事务失败时 Rollback

if( DB["local"].RunSqlQueryParam(sql, p) == false )
{
   DB["local"].Rollback();
   // ...
}

E. Open 失败时同步状态标签

if( DB["local"].Open() == false )
{
   DbStatusText = "● CLOSED";
   return false;
}
DbStatusText = "● OPEN";

F. 变更后 Refresh

return DB_Refresh();

INSERT / UPDATE / DELETE 完成后总是 Refresh 重新填充画面,让 DB 状态与画面状态不会脱节。

5) 量产前检查清单

项目	确认
`JournalMode`	`"WAL"`
`AutoBackupEnabled`	`true`(运行)
`BackupFolder`	推荐独立磁盘
`BackupKeepLast`	考虑磁盘容量(通常 14 ~ 60)
`LastError` 日志	每个失败分支都有
`IsOpen` 守卫	每个 DB 函数首行
变更函数末尾的 `DB_Refresh`	缺失时画面会过时
外部备份调度	推荐 OS 层面的每周全量备份

至此,DB_Sqlite 示例展示的 可量产级的数据库集成 全部内容讲完。在真实量产项目中应用时,直接照搬这 9 章的模式,只把领域表换成你自己的即可。