Installation

Install the engine for direct SQL:

npm install @minnowdb/core

Minnow is plain JavaScript. It has no post-install step, native binary, or WebAssembly module to fetch at runtime.

Add the Kysely adapter if you want a type-safe query builder:

npm install @minnowdb/kysely kysely

Reactive React views and streaming files are separate, optional packages:

npm install @minnowdb/react @minnowdb/export

Minnow is 0.x, so breaking changes can land in minor releases: pin exact @minnowdb versions and upgrade them together. Engine-dependent adapters declare the compatible core range for npm; the React hook is structurally typed and has no core runtime dependency. See Versioning.

Open a database

A database combines the SQL engine with a storage adapter. Start with IndexedDB for durable data in any supported browser:

import { MinnowDatabase } from "@minnowdb/core";
import { IndexedDbBlockStore } from "@minnowdb/core/storage/indexeddb";

const store = await IndexedDbBlockStore.open({ name: "shop" });
const db = new MinnowDatabase(store);

Use OPFS in a worker for synchronous file access and log-based persistence:

import { OpfsBlockStore } from "@minnowdb/core/storage/opfs";

const db = new MinnowDatabase(await OpfsBlockStore.open({ name: "shop" }));

Use memory for tests and disposable data:

import { MemoryBlockStore } from "@minnowdb/core/storage/memory";

const db = new MinnowDatabase(new MemoryBlockStore());

See Storage for the availability, durability, and performance trade-offs.

Run it in a worker

Most interactive applications should put the engine in a worker so query execution does not compete with rendering. MinnowDatabaseClient exposes the same query, cursor, write, catalog, index, migration, live-query, snapshot, and maintenance calls on the main thread.

The worker guide includes the ready-made worker entry and bundler setup.

OPFS database deletion additionally requires Web Locks. Close every connection, including tabs running an older build, before deleting a store; see OPFS storage.

Browser requirements

Minnow needs CompressionStream and DecompressionStream plus a storage adapter. Current Chrome, Firefox, Safari, and Edge support IndexedDB in a window or worker. OPFS requires a dedicated worker and is unavailable in Safari private browsing.

Minnow targets browsers. It does not ship a Node.js engine build. Use MemoryBlockStore or fake-indexeddb for Node-based tests. The v1 support policy defines the tested browser line, OPFS qualification, and release-candidate checks.

Package entry points