SQLQueryHelperjs

1.2.6 verified Fri May 01 auth: no javascript

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.

Common errors

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

cause 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).

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

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

fix

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

error error:0308010C:digital envelope routines::unsupported ↓

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

fix

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

Warnings

breaking Schema 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.

gotcha Entity 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().

deprecated Legacy 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({...}) }'

gotcha ESM 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.

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

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

Install

npm install sqlqueryhelperjs

yarn add sqlqueryhelperjs

pnpm add sqlqueryhelperjs

Imports

SqliteReflector
wrong
```
const { SqliteReflector } = require('sqlqueryhelperjs')
```
correct
```
import { SqliteReflector } from 'sqlqueryhelperjs'
```
Works with both ESM import and CJS require. The correct import in ESM is the named import shown.

column

wrong

import column from 'sqlqueryhelperjs'

correct

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.

Quickstart

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);