simplest.db

A simple SQLite key-value store for Node.js. Supports ESM and CommonJS.

Installation

npm install simplest.db

Usage

// ESM
import { SQLiteDatabase } from 'simplest.db';

// CommonJS
const { SQLiteDatabase } = require('simplest.db');

const db = new SQLiteDatabase({ path: './data.sqlite' });

db.set('user:1', { name: 'Alice', age: 30 });
db.set('user:2', { name: 'Bob', age: 25 });

db.get('user:1');         // { name: 'Alice', age: 30 }
db.has('user:1');         // true
db.delete('user:1');

db.keys('user:%');        // ['user:2']
db.values('user:%');      // [{ name: 'Bob', age: 25 }]
db.entries('user:%');     // [['user:2', { name: 'Bob', age: 25 }]]
db.getMany('user:%');     // { 'user:2': { name: 'Bob', age: 25 } }
db.deleteMany('user:%');

db.close();

Constructor

new SQLiteDatabase(options?)

Option	Type	Default	Description
path	string	'./db.sqlite'	Path to the SQLite file
name	string	'default_table'	Table name inside the file

You can also pass a string directly as the path:

const db = new SQLiteDatabase('./data.sqlite');

Multiple databases can share the same file using different table names:

const users = new SQLiteDatabase({ path: './data.sqlite', name: 'users' });
const posts  = new SQLiteDatabase({ path: './data.sqlite', name: 'posts' });

Database Files

When you create a database, SQLite automatically creates additional files alongside it:

• .sqlite - The main database file
• .sqlite-wal - Temporary transaction log (automatically managed)
• .sqlite-shm - Shared memory file (automatically managed)

Do not manually delete, move, or edit these files while the database is running. SQLite manages them automatically for data integrity. If you need to backup or move the database, close the connection first using db.close().

Methods

Read

db.get(key: string): Value | null
db.has(key: string): boolean
db.getMany(pattern: string): Record<string, Value>
db.keys(pattern?: string): string[]
db.values(pattern?: string): Value[]
db.entries(pattern?: string): Array<[string, Value]>

Write

db.set(key: string, value: Value): void
db.delete(key: string): void
db.deleteMany(pattern: string): void

Lifecycle

db.close(): void    // Close connection and optimize the file
SQLiteDatabase.cleanup(): void  // Close all active databases

Value types

Any JSON-serializable value is supported:

type Value = string | number | boolean | null | Value[] | { [key: string]: Value }

Pattern matching

getMany, deleteMany, keys, values, and entries accept a SQLite LIKE pattern:

Pattern	Matches
'%'	everything
'user:%'	keys starting with user:
'%:active'	keys ending with :active
'%foo%'	keys containing foo

Cleanup on exit

To automatically close all databases when the process exits:

// ESM
import { setCleanupOnExit } from 'simplest.db';

// CommonJS
const { setCleanupOnExit } = require('simplest.db');

setCleanupOnExit();

This registers handlers for exit, SIGINT, and SIGTERM.