@snomiao/keyv-sqlite

SQLite store for keyv

A high-performance SQLite cache store for keyv with support for multiple SQLite drivers.

Note: This is a fork of @resolid/keyv-sqlite by @huijiewei with multi-driver support for node:sqlite, bun:sqlite, and better-sqlite3. See comparison below.

Installation

npm i @snomiao/keyv-sqlite

Usage

Basic Usage

import KeyvSqlite from "@snomiao/keyv-sqlite"; // or: import { KeyvSqlite } from '...'
import Keyv from "keyv";

// Simple file path (recommended), note: WAL mode is enabled by default
const store = new KeyvSqlite("./cache.db");
const keyv = new Keyv({ store });

// In-memory cache
const store = new KeyvSqlite(":memory:");
const keyv = new Keyv({ store });

// Default (in-memory)
const store = new KeyvSqlite();
const keyv = new Keyv({ store });

Helper Function

import { createKeyv } from "@snomiao/keyv-sqlite";

// Simple file path
const keyv = createKeyv("./cache.db");

// With options
const keyv = createKeyv({ uri: "cache.sqlite" });

With Options

const store = new KeyvSqlite({
  uri: "./cache.db",
  table: "my_cache", // Custom table name
  wal: true, // WAL mode (default: true)
  busyTimeout: 10000, // Busy timeout in ms
  iterationLimit: 100, // Iterator batch size
});

Features

• Synchronous API: No await needed for instantiation
• Auto-detection: Automatically uses the best available SQLite driver
• Multiple drivers: Supports node:sqlite, bun:sqlite, and better-sqlite3
• Cross-runtime: Works in Node.js, Bun, and Deno
• WAL mode: Enabled by default for better performance
• 100% test coverage and production ready

API

Constructor

new KeyvSqlite(options?: KeyvSqliteOptions | string)

Pass a string for the file path, or an options object for advanced configuration.

Methods

All methods are async to match the Keyv interface:

• get(key) - Get a value
• getMany(keys) - Get multiple values
• set(key, value, ttl?) - Set a value with optional TTL
• delete(key) - Delete a value
• deleteMany(keys) - Delete multiple values
• clear() - Clear all values
• iterator(namespace?) - Async iterator over entries
• disconnect() - Close the database connection

Advanced Usage

Using Specific Drivers

// Use node:sqlite explicitly
const store = new KeyvSqlite({
  uri: "cache.sqlite",
  driver: "node:sqlite",
});

// Use bun:sqlite explicitly
const store = new KeyvSqlite({
  uri: "cache.sqlite",
  driver: "bun:sqlite",
});

// Use better-sqlite3 explicitly
const store = new KeyvSqlite({
  uri: "cache.sqlite",
  driver: "better-sqlite3",
});

Custom Driver Module

import Database from "better-sqlite3";

const store = new KeyvSqlite({
  uri: "cache.sqlite",
  driver: Database, // Pass the driver constructor directly
});

Supported Drivers

The library auto-detects and uses the best available driver for your runtime:

Native Drivers (First-class support)

• node:sqlite - Built into Node.js 22.5.0+ (requires --experimental-sqlite flag)
• bun:sqlite - Built into Bun runtime

NPM Packages

• better-sqlite3 - Requires installation: npm install better-sqlite3

Native drivers are pre-loaded at module initialization using top-level await, making the constructor fully synchronous.

Requirements

• Node.js 18+ (Node.js 22.5.0+ for native node:sqlite support)
• Or Bun runtime for native bun:sqlite support
• Or better-sqlite3 package installed

Configuration Options

type KeyvSqliteOptions = {
  uri?: string; // Database file path (default: ":memory:")
  driver?: DriverType | DriverModule; // Driver selection (default: "auto")
  table?: string; // Table name (default: "caches")
  wal?: boolean; // Enable WAL mode (default: true)
  busyTimeout?: number; // Busy timeout in ms (default: 5000)
  iterationLimit?: number; // Iterator batch size (default: 10)
};

Fork Differences

This fork (@snomiao/keyv-sqlite) differs from the original @resolid/keyv-sqlite in the following ways:

Feature	Original (@resolid)	This Fork (@snomiao)
SQLite drivers	✅ better-sqlite3 only	✅ Multi-driver (node:sqlite, bun:sqlite, better-sqlite3)
Native drivers	❌ No	✅ node:sqlite (Node 22.5+), bun:sqlite
Cross-runtime	⚠️ Node.js only	✅ Node.js, Bun, Deno
WAL mode	⚠️ Opt-in (off by default)	✅ Enabled by default
String parameter	❌ No	✅ Yes (new KeyvSqlite('./db'))
Benchmark workflow	❌ No	✅ Comprehensive multi-driver benchmarks

Key Innovation

The main difference is multi-driver support with automatic runtime detection:

Upstream approach:

import Database from "better-sqlite3"; // ← Hardcoded, must have better-sqlite3

This fork approach:

// Pre-loads native drivers at module initialization (top-level await)
let nodeSqliteDriver = await import("node:sqlite"); // ← Zero dependencies!
let bunSqliteDriver = await import("bun:sqlite"); // ← Zero dependencies!
let betterSqlite3 = await import("better-sqlite3"); // ← Fallback

// Auto-selects best available driver
// OR accepts custom driver: new KeyvSqlite({ driver: MyCustomDriver })

This allows the fork to:

• Prefer native drivers (zero dependencies, no compilation)
• Fall back gracefully to better-sqlite3 if needed
• Accept custom drivers for maximum flexibility
• Work across runtimes (Node.js, Bun, Deno) seamlessly

Migration from Original

If migrating from @resolid/keyv-sqlite:

- npm install @resolid/keyv-sqlite
+ npm install @snomiao/keyv-sqlite

The API is backwards compatible. Simply change the package name - your existing code will continue to work!

Optional improvements:

• Option name change: enableWALMode → wal (both work)
• Can now use string parameter: new KeyvSqlite('./db')
• Will auto-detect best driver (or specify with driver option)

Credits

This fork is based on the excellent work by @huijiewei in keyv-sqlite. The multi-driver support and cross-runtime compatibility were built on top of their solid foundation.

License

MIT.

Thanks

Thanks to JetBrains for the OSS development license.