supple-sql

library0.7.2jsnpmunverified

A minimal, PostgreSQL-only ORM for Node.js (v0.7.2) that emphasizes simplicity and explicit control over magic. It provides a Record class for table mapping with field definitions, primary keys, and automatic change tracking. Connections are managed via a default pool or explicit pool/connection passing, with helpers for transactions and single-connection scopes. Unlike full-featured ORMs like Sequelize or TypeORM, Supple SQL has no migrations, no associations, and uses raw SQL for queries beyond basic CRUD. Release cadence is sporadic; the library is stable but not actively developed. Requires Node >=16.3.0 and a PostgreSQL client (e.g., 'pg' module).

database

npm install supple-sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SUPPLE-SQL

supple-sql

databasejavascriptv0.7.2

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.

default

✓ import SQL from 'supple-sql'

✗ const SQL = require('supple-sql')

Library is ESM-only; CommonJS require() still works via default export but is not recommended for new code.

Record

✓ const { Record } = SQL; // or import SQL from 'supple-sql'; then SQL.Record

✗ import { Record } from 'supple-sql'

Record is a named property on the default export, not a separate named export.

type

✓ import SQL from 'supple-sql'; const { type } = SQL;

✗ import { type } from 'supple-sql'

type is a namespace on the default export; it provides column types like text, serial, timestamptz.

Shows setting up a pool, defining a Record, inserting, and querying by primary key.

import SQL from 'supple-sql'; import pg from 'pg'; import process from 'process'; const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL ?? 'postgres://user:pass@localhost:5432/mydb' }); SQL.setDefaultPool(pool); class User extends SQL.Record { static fields = { id: { type: SQL.type.serial, primaryKey: true }, email: { type: SQL.type.text, nullable: false, unique: true }, displayName: { type: SQL.type.text, nullable: false }, createdAt: { type: SQL.type.timestamptz, nullable: false, defaultValue: SQL.valueNow } }; static primaryKeyFields = ['id']; static table = 'users'; } async function main() { const user = new User({ email: 'test@example.com', displayName: 'Test' }); await user.save(); const found = await User.findByPk(1); console.log('Found:', found?.email); await pool.end(); } main().catch(console.error);

Debug

Known issues

gotchaRecord.load() does NOT populate fields from the query object if no row is found; the object remains empty.

fix

Check return value of load() or use findOne() which returns null on miss.

affects: >=0.0.0 <1.0.0

gotchasave() returns false if no changes were made; it does not throw.

fix

Always check the boolean return value to confirm the save actually happened.

affects: >=0.0.0 <1.0.0

gotchaOnly field names defined in static fields are tracked; extra properties on the instance are ignored.

fix

Ensure all database columns are declared in fields.

affects: >=0.0.0 <1.0.0

gotchaTransactions require explicit pass of the connection object to all Record operations; it is not automatic.

fix

Use SQL.transaction() callback and pass conn as first argument to constructors.

affects: >=0.0.0 <1.0.0

Errors

Common errors & fixes

Cannot find module 'supple-sql'

Package not installed or wrong import style.

fix

Run `npm install supple-sql`. Use `import SQL from 'supple-sql'` for ESM or `const SQL = require('supple-sql')` for CJS.

TypeError: SQL.setDefaultPool is not a function

Importing named export instead of default.

fix

Use `import SQL from 'supple-sql'` not `import { SQL } from 'supple-sql'`.

error: relation "users" does not exist

Table not created in database.

fix

Run `CREATE TABLE users (...)` manually; Supple SQL does not auto-migrate.

Upgrade

Version history

0.7.2latest on npm

Audit

Dependencies

pgoptionalRequired for PostgreSQL connection; user must provide a Pool instance.

Agent activity

18 hits · last 30 days

node