Registry / database / better-sqlite3-helper

better-sqlite3-helper

library3.1.7jsnpmunverified

A Node.js wrapper around better-sqlite3 providing shorthand query methods, automatic migration support, and a singleton pattern for simple server apps. Version 3.x (latest 3.1.7) uses better-sqlite3 v7, drops Node <10, and requires @types/better-sqlite3 as a peer dependency for TypeScript support. It simplifies database access with methods like query(), queryFirstRow(), insert(), and update(), and includes a migration system that runs SQL files on startup. Compared to better-sqlite3 alone, it reduces boilerplate by managing a global instance and handling migrations automatically. Release cadence is irregular; last release was Sep 2023.

database

npm install better-sqlite3-helper

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BETTER-SQLITE3-HEL

better-sqlite3-helper

databasejavascriptv3.1.7

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.

DB (default)

✓ const DB = require('better-sqlite3-helper');

✗ import DB from 'better-sqlite3-helper';

The package uses CommonJS and does not provide a default ESM export. Using import may work with bundlers but is not officially supported.

DB (default, with options)

✓ const DB = require('better-sqlite3-helper'); const db = DB({ path: './db.sqlite' });

✗ const db = new DB({ path: './db.sqlite' });

DB() returns a singleton instance; calling new will throw an error. Options are passed only on first call.

query method

✓ const DB = require('better-sqlite3-helper'); let rows = DB().query('SELECT * FROM users');

✗ let rows = DB.query('SELECT * FROM users');

DB() must be called (even with no arguments) to get the database instance; DB itself is not the instance.

TypeScript import

✓ import DB from 'better-sqlite3-helper';

✗ import { DB } from 'better-sqlite3-helper';

TypeScript declarations export a default function type. Named import does not work.

Shows core usage: configuring the singleton, executing DDL, inserting, and querying with shorthand methods.

// Install: npm i better-sqlite3-helper const DB = require('better-sqlite3-helper'); // First call configures the global instance (optional, defaults work) DB({ path: './data/sqlite3.db', migrate: { migrationsPath: './migrations' } }); // In another file or later, just use DB() to get the instance const db = DB(); // Create table (add migration file first) db.execute(` CREATE TABLE IF NOT EXISTS users ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, email TEXT UNIQUE ) `); // Insert let info = db.insert('INSERT INTO users (name, email) VALUES (?, ?)', 'Alice', 'alice@example.com'); console.log('Inserted user ID:', info.lastInsertRowid); // Query let rows = db.query('SELECT * FROM users'); console.log(rows); // Query first row let user = db.queryFirstRow('SELECT * FROM users WHERE id = ?', 1); console.log(user.name);

Debug

Known issues

breakingVersion 3.0 drops Node.js <10 support and removes the 'memory' option (use path ':memory:' instead).

fix

Upgrade Node.js version to >=10 and use ':memory:' as path for in-memory databases.

affects: <3.0

gotchaDB() must always be called (even without arguments) to access the database instance. DB itself is a function, not an object with query methods.

fix

Use DB().query(...) or const db = DB(); db.query(...).

affects: all

breakingVersion 2.0 removed commands for better-sqlite3 v4; only v5+ is supported.

fix

Ensure better-sqlite3 >=5 is installed if using better-sqlite3-helper v2.

affects: >=2.0 <3.0

deprecatedThe first call to DB() cannot be used to get the instance; it returns the result of configuration and undefined.

fix

Either chain configuration and usage: DB(options); const db = DB(). Or use a two-step pattern.

affects: all

gotchaMigration files must be named with a numeric prefix (e.g., 001-init.sql) and placed in the migrationsPath directory. The migration table defaults to 'migration'.

fix

Ensure migration files are named sequentially and exist at the configured path.

affects: all

Errors

Common errors & fixes

DB is not a constructor

Attempting to instantiate DB with 'new' instead of calling as a function.

fix

Replace 'new DB()' with 'DB()'.

Cannot read property 'query' of undefined

Calling DB().query() before the global instance has been configured (first call returned undefined).

fix

Ensure the first call to DB() includes configuration options, then subsequent calls return the instance. Or call DB() without arguments after configuration.

TypeError: db.prepare is not a function

Using better-sqlite3's native methods directly on the DB() instance instead of through shorthand methods.

fix

Use db.query(), db.execute(), db.insert() etc. For direct access, use db.raw property to get the underlying better-sqlite3 Database object.

Error: cannot find module './migrations/...' but file exists

Migrations path is relative to process.cwd(), not the module's directory.

fix

Use an absolute path or ensure the migrations directory is at the application root.

Upgrade

Version history

3.1.7latest on npm

Audit

Dependencies

better-sqlite3requiredpeer dependency via @types/better-sqlite3; the underlying synchronous SQLite3 driver.

@types/better-sqlite3optionalrequired for TypeScript type declarations; peer dependency.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Kauto/better-sqlite3-helper ↗

packagebetter-sqlite3-helper ↗

homepagehttp://intergenies.com/programs/nodejs/better-sqlite3-helper ↗