sqlite-level

library1.2.1jsnpmunverified

sqlite-level is a Node.js library that provides an `abstract-level` compliant interface, backed by a SQLite database. It leverages `better-sqlite3` for its underlying SQLite operations, offering a synchronous-like API while maintaining `abstract-level` compatibility. This allows developers familiar with the LevelDB API to utilize a durable, file-based store without needing to manage separate database processes or complex setups typical of other embedded databases. Currently stable at version 1.2.1, its release cadence is tied to the needs of the TinaCMS project, ensuring ongoing maintenance and updates. A key differentiator is its use of SQLite, offering ACID properties and wide tooling support, contrasting with LevelDB's LSM-tree design. It's particularly useful for server-side applications requiring a lightweight, transactional key-value store with data persistence for development or smaller deployments.

database

npm install sqlite-level

github ↗package ↗

INSTALL

IMPORT

SIG · SQLITE-LEVEL

sqlite-level

databasejavascriptv1.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Level

✓ import { Level } from 'sqlite-level';

✗ const { Level } = require('sqlite-level');

sqlite-level is an ESM-first package. Use `import` syntax. CommonJS `require` will result in a runtime error or require an import shim.

LevelOptions

✓ import type { LevelOptions } from 'sqlite-level';

✗ import { LevelOptions } from 'sqlite-level';

When importing types in TypeScript, explicitly use `import type` for clarity and to prevent bundling issues in environments that do not support type stripping.

Demonstrates opening a SQLite-backed LevelDB, performing basic put, get, delete operations, and iterating over stored keys and values, ensuring proper database closure.

import { Level } from 'sqlite-level'; import { join } from 'path'; import { tmpdir } from 'os'; async function runExample() { const dbPath = join(tmpdir(), 'my_sqlite_level_db.sqlite'); const db = new Level(dbPath); try { console.log(`Opening database at: ${dbPath}`); await db.open(); console.log('Database opened.'); await db.put('name', 'Alice'); await db.put('age', '30'); const name = await db.get('name'); const age = await db.get('age'); console.log(`Name: ${name}, Age: ${age}`); // Iterate over entries console.log('Iterating over entries:'); for await (const [key, value] of db.iterator({ gte: 'a', lt: 'z' })) { console.log(` Key: ${key}, Value: ${value}`); } await db.del('age'); const newAge = await db.get('age'); console.log(`Age after deletion: ${newAge}`); // Should be undefined } catch (error) { console.error('An error occurred:', error); } finally { if (!db.isClosed()) { await db.close(); console.log('Database closed.'); } } } runExample();

Debug

Known issues

gotchaInstallation issues can occur due to the native bindings of `better-sqlite3`, which `sqlite-level` relies on. Users may encounter compilation errors on certain platforms or specific Node.js versions.

fix

Ensure you have C++ build tools installed (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, or Visual Studio Build Tools on Windows). Consider using a Docker environment for consistent builds.

affects: >=1.0.0

gotchaAs `sqlite-level` uses SQLite internally, it inherits SQLite's concurrency model. While WAL (Write-Ahead Logging) can improve read concurrency, writes are still serialized. Aggressive concurrent writes can lead to `SQLITE_BUSY` errors if not handled properly.

fix

Implement retry logic for write operations, or design your application to minimize concurrent writes to the same database. Consider moving to a more robust database solution if high-volume, concurrent writes are a core requirement.

affects: >=1.0.0

breaking`sqlite-level` is distributed as an ECMAScript Module (ESM). Direct `require()` statements in CommonJS environments will fail with a runtime error, indicating it's an ESM module.

fix

For Node.js projects, ensure your `package.json` specifies `"type": "module"` or use dynamic `import()` for `sqlite-level`. If using TypeScript, configure `"module": "NodeNext"` or `"ESNext"` in `tsconfig.json`.

affects: >=1.0.0

gotchaForgetting to `await db.close()` can lead to data corruption or locks on the SQLite database file, especially if the application exits abruptly. This is critical for persistent, file-based databases.

fix

Always ensure `db.close()` is called and awaited in a `finally` block or on application shutdown hooks. For long-running processes, consider implementing graceful shutdown procedures.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module ...sqlite-level/build/index.js from ... not supported.

Attempting to `require()` an ESM-only package from a CommonJS module.

fix

Change your importing code from `const { Level } = require('sqlite-level');` to `import { Level } from 'sqlite-level';`. Ensure your `package.json` for the consuming project has `"type": "module"` or dynamically import with `const { Level } = await import('sqlite-level');`.

Error: SQLITE_BUSY: database is locked

Multiple concurrent write operations or an active read transaction holding a lock prevents other operations from proceeding.

fix

This often occurs in concurrent environments. Implement basic retry logic with a short delay for write operations. Ensure database connections are managed properly and closed when not in use. Consider using WAL mode if not already active.

Error: Database is closed

An attempt was made to perform an operation (put, get, iterate) on a `Level` instance that has already been `close()`d or failed to `open()`.

fix

Ensure all database operations are completed before `db.close()` is called. Use `db.isOpen()` to check the database state if you suspect it might be closed prematurely. Wrap operations in `try...finally` to ensure `db.close()` is called only when needed.

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

sucraseoptionalPeer dependency, often required for on-the-fly TypeScript or ESM compilation in some build environments, especially when integrated into larger frameworks. Not strictly required for runtime if transpilation is handled separately.

better-sqlite3requiredRuntime dependency for SQLite database interactions. Its native bindings can sometimes cause installation issues on specific platforms or environments.

Agent activity

20 hits · last 30 days

node