Introduction

Data storage module. Provides SqliteStorage for SQLite database operations based on better-sqlite3. Supports four storage modes (memory, name-only, relative path, absolute path) and lazy-loads the native better-sqlite3 binding only when init() is called.

See also: Types for Config.storage related types

Import

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

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

SqliteStorage

SQLite database storage class. The constructor only computes paths; call init() to lazily load better-sqlite3 and open the database connection.

constructor(name)

Create a SqliteStorage instance. Path computation only — the database is not opened until init() is called.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Database name or path. Supports four formats (see modes below)

Storage modes:

Mode	Name Format	File Location	Example
memory	:memory:	In-memory only (not persisted)	':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'

Security

The constructor rejects names containing .. to prevent path traversal attacks.

Returns: SqliteStorage instance (without db property set).

Example:

const storage = new SqliteStorage('myapp.db');
// storage.db is NOT available yet — call init() first

init(opt?)

Lazily import better-sqlite3 via dynamic import() and open the database connection. This is the only point where the native .node binding is loaded.

Parameters:

Parameter	Type	Required	Description
opt	Record<string, unknown>	No	better-sqlite3 database options. Default merged with { timeout: 5000 }

Returns: Promise<this> — Returns the SqliteStorage instance for chaining. After resolution, this.db is available.

Example:

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

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

Lazy Loading

better-sqlite3 is a native module requiring electron-rebuild. By lazy-loading, projects that don't use SQLite never load the native binding. Use pnpm re-sqlite to rebuild for Electron.

getMode(name)

Infer storage mode from the database name.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Database name or path

Returns: string — 'memory', 'onlyName', 'relative', or 'absolute'.

getDbDir()

Get the absolute path of the directory containing the database file.

Returns: string — Database directory path.

getFilePath()

Get the absolute path of the database file. Composed by joining dbDir and fileName. Only meaningful for file modes (in memory mode, this path has no practical use).

Returns: string — Full database file path.

Properties

Property	Type	Description
name	string	Original database name input
mode	string	Storage mode (memory / onlyName / relative / absolute)
dbDir	string	Absolute directory path
fileName	string	Database filename (without directory)
db	Database.Database	better-sqlite3 database instance (set after init())