SQLite 数据库库

本文对标 lib/SQLite(tiepm.toml v1.0.0)。

玄铁 SQLite 数据库库，基于 SQLite3 amalgamation（包内置 sqlite3.o 与 SQLite桥.o，经 [原生] 对象机制链接，无需额外 C 环境）。

引入

引 "SQLite" 予 数据库

连接

调用	返回	说明
数据库.打开(路径)	结果	打开数据库；":memory:" 为内存库；成功时 .值 为连接句柄
数据库.关闭(库)	结果	关闭连接（幂等）
数据库.错误消息(库)	字	最近错误消息

连接句柄是 ARC 管理对象：不显式关闭也会在回收时自动关闭（sqlite3_close_v2）。打开后默认 5 秒 busy 超时。

执行与查询

调用	返回	说明
数据库.执行(库, SQL)	结果	非查询语句（建表/插入/更新/删除/事务）；成功时 .值 为影响行数
数据库.执行带参(库, SQL, 参数)	结果	带参数绑定的执行（占位符 ?，位置从 1 起）
数据库.查询(库, SQL)	结果	查询；成功时 .值 为 数组<字典>（每行一个字典：列名 → 值）
数据库.查询带参(库, SQL, 参数)	结果	带参数绑定的查询

参数类型：整 / 小数 / 字 / 字节（BLOB) / 布尔 / 空（NULL)。 列值映射:INTEGER→整、FLOAT→小数、TEXT→字、BLOB→字节、NULL→空。

数据库.执行(库, "CREATE TABLE 用户 (id INTEGER PRIMARY KEY, 名 TEXT, 分 REAL)")
数据库.执行带参(库, "INSERT INTO 用户 (名, 分) VALUES (?, ?)", ["玄铁", 98.5])
设 查 = 数据库.查询带参(库, "SELECT 名 FROM 用户 WHERE 分 > ? ORDER BY 分", [90])
若 查.成功 {
    遍历 行 于 查.值 { 示(行["名"]) }
}

一律用带参形式拼接用户输入——? 占位符由 SQLite 转义，是防注入的正道。

事务

调用	说明
数据库.开始事务(库)	BEGIN IMMEDIATE（立即取写锁）
数据库.提交事务(库)	COMMIT
数据库.回滚事务(库)	ROLLBACK

三个均返回 结果 容器（.值 为影响行数，事务语句恒为 0）。

注意

• 所有操作返回 结果 容器，失败不炸程序——养成 若 r.成功 的判定习惯；结果.错误 是 SQLite 的英文错误消息。
• 错误路径（语法错误/绑定个数不符/句柄已关闭）全部走 结果，不会异常退出。
• Windows 中文路径安全：数据库文件路径经 UTF-8 直通 SQLite（SQLite 内部即 UTF-8）。

[原生] 对象链接机制（包开发者向）

本包是 tiepm.toml [原生] 段的第一个用例：

[原生]
对象 = ["sqlite3.o", "SQLite桥.o"]

任何铁铺包都可在同目录 tiepm.toml 声明该段：编译器在引入模块时登记，链接期把这些 .o 并入（缺失即明确报错；非 ASCII 路径自动中转）。此前唯一的原生通道是编译器内对 渲染 的特判，[原生] 是其通用化。