litedbmodel

library1.2.7jsnpmunverified

A lightweight, SQL-friendly TypeScript ORM for PostgreSQL, MySQL, and SQLite (v1.2.7, released monthly). Designed for production systems requiring predictable SQL, explicit performance control, and operational safety (replication-lag-aware reader/writer routing, automatic N+1 prevention, configurable hard limits). Uses Active Record pattern with symbol-based columns, tuple conditions, and raw SQL escape hatches. Unlike Prisma or TypeORM, it prioritizes SQL visibility and explicit transaction boundaries over magic. Requires Node >=18 and peer dependencies for each database driver.

database

npm install litedbmodel

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LITEDBMODEL

litedbmodel

databasejavascriptv1.2.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.

Model

✓ import { Model } from 'litedbmodel'

✗ const Model = require('litedbmodel')

Default import is not available. Use named import.

DBModel

✓ import { DBModel } from 'litedbmodel'

DBModel is the base class for models. Export available since v1.0.

sql

✓ import { sql } from 'litedbmodel'

Tagged template for raw SQL conditions, e.g., sql`${column} > ?`.

Shows how to define a model, connect to PostgreSQL, create a user, find by email, and execute raw SQL.

import { DBModel, Model, sql } from 'litedbmodel'; import pg from 'pg'; const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL ?? '' }); class User extends DBModel { static tableName = 'users'; static columns = { id: Model.number.primaryKey(), name: Model.string, email: Model.string.unique() }; } async function main() { const db = Model.connect(pool, 'pg'); await db.transaction(async (tx) => { const user = await User.create(tx, { name: 'Alice', email: 'alice@example.com' }); console.log('Created user:', user.id); const found = await User.find(tx, { where: [[User.columns.email, 'alice@example.com']] }); console.log('Found:', found); // Raw SQL const rows = await User.query(tx, sql`SELECT * FROM users WHERE name = ${'Alice'}`); console.log('Raw query:', rows); }); await db.close(); } main().catch(console.error);

Debug

Known issues

breakingModel.find() and other read methods require a transaction object for writer reads by default (replica safety).

fix

Pass a transaction (tx) from db.transaction() or use db.query() for reader-only reads.

affects: >=1.0.0

deprecatedModel.find() with no transaction will throw an error since v1.0.

fix

Wrap reads in db.transaction() or use db.query() for explicit reader access.

affects: >=1.0.0

gotchaSymbol-based columns must be used with Model.columns, not strings, for type safety and refactoring support.

fix

Use Model.columns.columnName (symbol) instead of 'column_name' string.

affects: >=1.0.0

gotchaN+1 is prevented automatically via batch loading, but lazy relations still require explicit eager loading via 'include' option.

fix

Use Model.find({ include: ['posts'] }) to eagerly load relations and avoid per-relation queries.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Callback must be a function for transaction

Missing async callback function in db.transaction() call.

fix

db.transaction(async (tx) => { ... })

TypeError: Cannot read properties of undefined (reading 'column')

Used Model.column instead of Model.columns.columnName (symbol).

fix

Use Model.columns.columnName (e.g., User.columns.name) instead of User.column.

Error: No pool configured for database 'pg'

Missing peer dependency 'pg' or pool not connected.

fix

Install pg (npm install pg) and create a pool before calling Model.connect().

Upgrade

Version history

1.2.7latest on npm

Audit

Dependencies

better-sqlite3optionalSQLite driver (peer dependency)

mysql2optionalMySQL driver (peer dependency)

pgoptionalPostgreSQL driver (peer dependency)

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/foo-ogawa/litedbmodel.ts ↗

packagelitedbmodel ↗

homepagehttps://github.com/foo-ogawa/litedbmodel.ts#readme ↗