Database 手册 · Chapter 2

连接设置

DB_Sqlite 示例使用单个 SQLite 连接运行。连接信息同时存在于两个位置 — 一个是单一真实来源(SoT),另一个是同步副本。

位置	角色
`DB_Sqlite.xmp → "DatabaseOption"` 块	SoT — 项目构建 / 部署时一并打包
`XDatabase/connections.json`	DB Studio 所看的同步副本 — 用工具编辑时自动更新

脚本中(Data.xms 等),只需 DB["local"] 一行即可访问该连接。

示例的实际设置

下面是从 DB_Sqlite.xmp 摘录的 DatabaseOption 块。

"DatabaseOption": {
  "Connections": [
    {
      "Name": "local",
      "Type": "sqlite",
      "Path": "XDatabase/LocalDB.db",
      "Server": "",
      "Database": "",
      "User": "",
      "PasswordEnc": "",
      "ConnectionTimeout": 15,
      "CommandTimeout": 30,
      "PingIntervalSec": 10,
      "ReconnectRetries": 3,
      "Description": "测试用 db"
    }
  ],
  "BackupFolder": "XDatabase/Backup",
  "AutoBackupEnabled": false,
  "AutoBackupIntervalHours": 24,
  "BackupKeepLast": 30,
  "JournalMode": "WAL"
}

connections.json 拥有相同的内容。从 DB Studio 的图形界面编辑时,两边都会同步更新。

字段详解

连接主体

键	值 / 含义
Name	`"local"` — 脚本中通过 `DB["local"]` 访问的标识符。建议使用英文小写
Type	`"sqlite"`(可选: `"mssql"`)
Path	`"XDatabase/LocalDB.db"` — SQLite 文件路径(相对于项目根)
Server / Database / User / PasswordEnc	SQLite 留空。仅 MSSQL 使用
ConnectionTimeout	连接尝试超时(秒)。默认 15
CommandTimeout	单条 SQL 执行超时(秒)。默认 30
PingIntervalSec	连接状态检查周期(秒)。默认 10。SQLite 中影响很小
ReconnectRetries	断开时自动重连次数。默认 3
Description	人类可读的说明。仅在 UI 显示,不影响动作

选项(Connections 数组外)

键	含义
BackupFolder	自动 / 手动备份文件保存目录。第 9 章详述
AutoBackupEnabled	`true` 时定期执行备份
AutoBackupIntervalHours	备份间隔(小时)。默认 24
BackupKeepLast	保留备份数。超出部分自动删除
JournalMode	SQLite 日志模式。推荐 `"WAL"`。第 9 章详述

SQLite 与 MSSQL 的差异 — 一表对照

项目	SQLite	MSSQL
`Type`	`"sqlite"`	`"mssql"`
必填键	`Path`	`Server`、`Database`、`User`、`PasswordEnc`
备注	单文件自足,部署简单	需外部服务器,并发能力强

同一段脚本代码(DB[...].RunSqlSelect(...))在两种引擎上都能正常工作。

注册新连接的两种方法

A. DB Studio(推荐)

Solution Explorer
└── Data Editor Pages
    └── Database
        └── Database Connections

[+ Add] → 按上表填入字段并保存。connections.json 与 .xmp 的 DatabaseOption 同步更新。

B. 直接编辑

也可用文本编辑器打开 DB_Sqlite.xmp 或 XDatabase/connections.json,在 Connections 数组中增加对象。必须同时更新两个文件 — 否则不同工具看到的信息会不一致。

连接设置完成后,下一步是创建表。示例用 order_history 一张表完成全部演示。