sqlite-executor

library4.0.6jsnpmunverified

A lightweight, zero-dependency SQLite wrapper for Node.js that communicates with the sqlite3 CLI via stdin/stdout — no native addons, no node-gyp, no ABI headaches. Version 4.0.6 requires Node.js >= 18 and the sqlite3 CLI executable on the system. Key differentiators: pure JavaScript, no compilation needed; long-lived single sqlite3 process for the entire app lifecycle; Promise-based API with execute(), query(), and stream() methods; automatic transaction support with concurrent caller serialization; dedicated reader pool for concurrent read queries; per-statement timeout with process-level failure recovery; auto-restart on crash; runtime metrics (QPS, avg query time, timeout count, restarts). Includes full TypeScript types and dual ESM/CommonJS module support.

database

npm install sqlite-executor

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQLITE-EXECUTOR

sqlite-executor

databasejavascriptv4.0.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

SQLiteExecutor

✓ import { SQLiteExecutor } from 'sqlite-executor'

✗ import SQLiteExecutor from 'sqlite-executor'

The default export is not available; must use named import.

SQLiteExecutor

✓ const { SQLiteExecutor } = require('sqlite-executor')

✗ const SQLiteExecutor = require('sqlite-executor')

CommonJS requires destructured require.

Metrics

✓ import { Metrics } from 'sqlite-executor'

✗ import { Metric } from 'sqlite-executor'

The class is named 'Metrics', not 'Metric'.

Logger

✓ import type { Logger } from 'sqlite-executor'

Logger is a TypeScript interface, not a value. Use type import for type-only usage.

SQLiteExecutorOptions

✓ import type { SQLiteExecutorOptions } from 'sqlite-executor'

✗ import { SQLiteExecutorOptions } from 'sqlite-executor'

Options interface is not exported as a value; only available as a type.

Creates an in-memory SQLite database, creates a table, inserts two rows, queries them, and closes the connection.

import { SQLiteExecutor } from 'sqlite-executor'; const db = new SQLiteExecutor({ database: ':memory:' }); await db.execute( `CREATE TABLE IF NOT EXISTS users ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT )` ); await db.execute('INSERT INTO users (name) VALUES (?)', ['Alice']); await db.execute('INSERT INTO users (name) VALUES (?)', ['Bob']); const rows = await db.query('SELECT * FROM users ORDER BY id ASC'); console.log(rows); // [ { id: 1, name: 'Alice' }, { id: 2, name: 'Bob' } ] await db.close();

Debug

Known issues

breakingMinimum Node.js version changed to 18 in v4.0.0

fix

Upgrade Node.js to v18 or later, or stick with v3.x if you need older Node support.

affects: >=4.0.0

breakingAPI changed from callback-based to Promise-based in v3.0.0

fix

Replace callbacks with async/await or .then(). The constructor and method signatures changed.

affects: >=3.0.0

breakingDefault export removed in v3.0.0

fix

Use named import: import { SQLiteExecutor } from 'sqlite-executor' instead of import SQLiteExecutor from 'sqlite-executor'.

affects: >=3.0.0

gotchasqlite3 CLI must be installed and available in PATH

fix

Install sqlite3 (e.g., apt install sqlite3, brew install sqlite3, choco install sqlite). The npm package 'sqlite3' is not required.

affects: >=1.0.0

gotchaReader pool (poolSize > 0) only works with file databases, not :memory:

fix

Specify a database file path when using poolSize > 0, or set poolSize to 0 for in-memory databases.

affects: >=3.0.0

gotchaTransactions serialize concurrent callers; long transactions block other operations

fix

Keep transactions short. For heavy batch operations, consider using execute() without explicit transactions.

affects: >=3.0.0

deprecatedCallback-style methods (e.g., db.all(), db.run()) removed in v3.0.0

fix

Use the Promise-based methods: query() for SELECT, execute() for INSERT/UPDATE/DELETE.

affects: >=3.0.0

Errors

Common errors & fixes

ERR_MODULE_NOT_FOUND: Cannot find package 'sqlite-executor'

Package not installed or wrong directory.

fix

Run 'npm install sqlite-executor' in your project root.

Error: spawn sqlite3 ENOENT

sqlite3 CLI not installed or not in PATH.

fix

Install sqlite3 via system package manager (apt, brew, choco) or specify custom binary path via 'binary' option.

TypeError: db.query is not a function

Using an older version that only has callback-based methods.

fix

Upgrade to v3.0.0 or later, or use db.all() (callback) in v2.x.

SQLITE_ERROR: no such table: users

CREATE TABLE statement not executed or rolled back.

fix

Ensure db.execute('CREATE TABLE...') runs before querying, and that the database file is not read-only or missing.

Upgrade

Version history

4.0.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node