sqlqueryhelperjs

library1.2.6jsnpmunverified

Runtime database evolution engine for SQL systems (SQLite, PostgreSQL, MySQL) that lets you define schemas in code, reflect existing databases, and synchronize structure automatically. Version 1.2.6 (stable, active development) combines ORM-like schema definitions, automatic migration-less evolution, fluent SQL builder with joins/CTEs/window functions, and legacy DB inspection into one package. Unlike typical ORMs, it preserves full SQL control while handling schema changes safely. Ships TypeScript types and supports both ESM and CommonJS.

database serialization

npm install sqlqueryhelperjs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQLQUERYHELPERJS

sqlqueryhelperjs

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

SqliteReflector

✓ import { SqliteReflector } from 'sqlqueryhelperjs'

✗ const { SqliteReflector } = require('sqlqueryhelperjs')

Works with both ESM import and CJS require. The correct import in ESM is the named import shown.

column

✓ import { column } from 'sqlqueryhelperjs'

✗ import column from 'sqlqueryhelperjs'

column is a named export, not default. Do not use default import.

entity

✓ import { entity } from 'sqlqueryhelperjs'

Value export used to define entity metadata on a class.

primaryKey

✓ import { primaryKey } from 'sqlqueryhelperjs'

Function to define primary keys with options like autoIncrement.

PostgresReflector

✓ import { PostgresReflector } from 'sqlqueryhelperjs'

For PostgreSQL engine. Requires 'pg' package.

MysqlReflector

✓ import { MysqlReflector } from 'sqlqueryhelperjs'

For MySQL engine. Requires 'mysql2' package.

Defines a User entity with auto-incrementing id and non-null email, reflects it to synchronize the database, then queries all rows.

import { SqliteReflector, column, entity, primaryKey } from 'sqlqueryhelperjs'; class User { static entity = entity({ table: 'users', columns: { id: column.integer(), email: column.text({ nullable: false }), }, primaryKey: primaryKey('id', { autoIncrement: true }), }); } const db = new SqliteReflector({ filename: process.env.DB_PATH ?? 'app.db' }); db.reflect(User); const rows = db.select(['id', 'email']).from('users').all(); console.log(rows);

Debug

Known issues

breakingSchema synchronization may ALTER or DROP columns. Always review destructive changes before applying in production.

fix

Use db.planReflect() to preview changes and set confirmDestructive: true in engine options to require explicit approval.

affects: >=0.1.0

gotchaEntity class must have static 'entity' property. Forgetting it will result in runtime error.

fix

Define 'static entity = entity({...})' on every class passed to db.reflect().

affects: >=0.1.0

deprecatedLegacy entity definition using 'Entity' base class is deprecated. Use static entity property instead.

fix

Replace 'class User extends Entity { ... }' with 'class User { static entity = entity({...}) }'

affects: >=1.0.0

gotchaESM and CJS modules are bundled; however, using require() in an ESM project may cause issues.

fix

Ensure you use the appropriate module system consistently: ESM with import and CJS with require.

affects: >=1.2.0

breakingMySQL engine now includes returning() support for DML; old code using 'output' may break.

fix

Migrate from .output() to .returning() when using MySQL reflector.

affects: >=1.2.0

Errors

Common errors & fixes

Error: No engine loaded. Did you call .reflect(...) with an entity class?

Missing static entity property on class or class not passed to reflect().

fix

Ensure class has a static entity property defined with entity({...}) and call db.reflect(YourClass).

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

Entity class does not have a static 'entity' property, or the class is undefined.

fix

Add 'static entity = entity({...})' to the class definition.

error:0308010C:digital envelope routines::unsupported

OpenSSL version mismatch in Node.js 17+ when using legacy crypto.

fix

Set NODE_OPTIONS=--openssl-legacy-provider environment variable.

Upgrade

Version history

1.2.6latest on npm

Audit

Dependencies

better-sqlite3optionalRequired for SQLite runtime engine

mysql2optionalRequired for MySQL runtime engine

pgoptionalRequired for PostgreSQL runtime engine

Agent activity

14 hits · last 30 days

node