# simplest.db

> A simple SQLite database wrapper

Latest version **4.0.0** (published 2026-03-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install simplest.db
pnpm add simplest.db
yarn add simplest.db
bun add simplest.db
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2026-03-15 |
| First published | 2026-03-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 1 |
| Unpacked size | 64.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Fabricio-191 |
| Maintainers | fabricio-191 |
| Keywords | db, database, sqlite3, sqlite, simple |

## Links

- npm: https://www.npmjs.com/package/simplest.db
- Repository: https://github.com/Fabricio-191/simplest.db
- Issues: https://github.com/Fabricio-191/simplest.db/issues
- npm.io page: https://npm.io/package/simplest.db

## Dependencies (1)

- [better-sqlite3](https://npm.io/package/better-sqlite3.md) ^12.8.0

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [mongoose-typescript](https://npm.io/package/mongoose-typescript.md) — 85 weekly downloads

## Recent versions

- 4.0.0 (latest) — 2026-03-15

## README

<a href="https://github.com/Fabricio-191/simplest.db/actions/workflows/tests.yml" target="_blank">
	<img src="https://github.com/Fabricio-191/simplest.db/actions/workflows/tests.yml/badge.svg">
</a>
<a href="https://www.buymeacoffee.com/Fabricio191" target="_blank">
	<img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="20" width="100">
</a>

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

## Installation

```sh
npm install simplest.db
```

## Usage

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

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

```js
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

```ts
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:

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

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

```js
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

```ts
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

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

### Lifecycle

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

## Value types

Any JSON-serializable value is supported:

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

## Pattern matching

`getMany`, `deleteMany`, `keys`, `values`, and `entries` accept a [SQLite LIKE pattern](https://www.sqlite.org/lang_expr.html#like):

| 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:

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

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

setCleanupOnExit();
```

This registers handlers for `exit`, `SIGINT`, and `SIGTERM`.

---
_Source: https://npm.io/package/simplest.db · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._