简介

数据存储模块。提供基于 better-sqlite3 的 SqliteStorage 用于 SQLite 数据库操作。支持四种存储模式（内存、仅名称、相对路径、绝对路径），仅在调用 init() 时懒加载原生 better-sqlite3 绑定。

参见：类型 中的 Config.storage 相关类型

导入

// ESM
import { SqliteStorage } from 'ee-core/storage';

// CJS
const { SqliteStorage } = require('ee-core/storage');

SqliteStorage

SQLite 数据库存储类。构造函数仅计算路径；调用 init() 以懒加载 better-sqlite3 并打开数据库连接。

constructor(name)

创建 SqliteStorage 实例。仅路径计算——直到调用 init() 才打开数据库。

参数：

参数	类型	必填	说明
name	string	是	数据库名称或路径。支持四种格式（见下方模式）

存储模式：

模式	名称格式	文件位置	示例
memory	:memory:	仅内存（不持久化）	':memory:'
onlyName	app.db	{dataDir}/db/app.db	'myapp.db'
relative	sub/app.db	{dataDir}/db/sub/app.db	'data/app.db'
absolute	/tmp/app.db	/tmp/app.db	'C:\\data\\app.db'

安全

构造函数拒绝包含 .. 的名称以防止路径遍历攻击。

返回值：SqliteStorage 实例（db 属性尚未设置）。

示例：

const storage = new SqliteStorage('myapp.db');
// storage.db 尚不可用 — 先调用 init()

init(opt?)

通过动态 import() 懒加载 better-sqlite3 并打开数据库连接。这是加载原生 .node 绑定的唯一入口。

参数：

参数	类型	必填	说明
opt	Record<string, unknown>	否	better-sqlite3 数据库选项。默认合并 { timeout: 5000 }

返回值：Promise<this> — 返回 SqliteStorage 实例以支持链式调用。resolve 后 this.db 可用。

示例：

// 式调用
const storage = await new SqliteStorage('myapp.db').init();
storage.db.exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)');

// 分步调用
const storage = new SqliteStorage(':memory:');
await storage.init();
storage.db.prepare('INSERT INTO users (name) VALUES (?)').run('Alice');

懒加载

better-sqlite3 是需要 electron-rebuild 的原生模块。通过懒加载，不使用 SQLite 的项目永远不会加载原生绑定。使用 pnpm re-sqlite 为 Electron 重建。

getMode(name)

从数据库名称推断存储模式。

参数：

参数	类型	必填	说明
name	string	是	数据库名称或路径

返回值：string — 'memory'、'onlyName'、'relative' 或 'absolute'。

getDbDir()

获取包含数据库文件的目录的绝对路径。

返回值：string — 数据库目录路径。

getFilePath()

获取数据库文件的绝对路径。由 dbDir 和 fileName 拼接组成。仅对文件模式有意义（内存模式下此路径无实际用途）。

返回值：string — 完整数据库文件路径。

属性

属性	类型	说明
name	string	原始数据库名称输入
mode	string	存储模式（memory / onlyName / relative / absolute）
dbDir	string	绝对目录路径
fileName	string	数据库文件名（不含目录）
db	Database.Database	better-sqlite3 数据库实例（init() 后设置）