soul-orm

library1.2.0jsnpmunverified

soul-orm is a lightweight, promise-based ORM for Node.js that supports MySQL, PostgreSQL, SQLite, and MSSQL. Version 1.2.0 is the latest stable release, with monthly releases. It features a fluent query builder with chainable methods like where, order, limit, and field, and provides a simple transaction API via beginTx/commit/rollback. Unlike heavy ORMs like Sequelize or TypeORM, Soul ORM focuses on a minimal API surface and zero-config setup, but it lacks advanced features like relations and migrations. It ships TypeScript types.

database

npm install soul-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SOUL-ORM

soul-orm

databasejavascriptv1.2.0

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 soul from 'soul-orm'

✗ const soul = require('soul-orm')

ESM-only since v1.0; the package does not export a default for CJS.

✓ import { createConnection } from 'soul-orm'; const db = createConnection(options)

✗ import { db } from 'soul-orm'

db is not a named export; you must call createConnection to obtain a db instance.

createConnection

✓ import { createConnection } from 'soul-orm'

✗ import createConnection from 'soul-orm'

createConnection is a named export, not the default.

Demonstrates creating a connection, querying with where/order/select, inserting, and deleting.

import { createConnection } from 'soul-orm'; import { config } from 'dotenv'; config(); const db = createConnection({ host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'root', password: process.env.DB_PASS ?? '', database: process.env.DB_NAME ?? 'test' }); async function main() { const users = await db.table('user') .where({ name: 'jake' }) .order('age', 'desc') .select(); console.log(users); await db.table('user').insert({ name: 'new', age: 25 }); await db.table('user').where({ name: 'new' }).delete(); await db.close(); } main().catch(console.error);

Debug

Known issues

breakingThe package dropped support for callbacks; all methods return promises.

fix

Use async/await or .then() instead of callbacks.

affects: >=1.0

deprecatedThe .field() method is deprecated in 1.2.0; use .columns() instead.

fix

Replace .field('name','age') with .columns('name','age').

affects: >=1.2.0

gotchaThe query builder methods mutate internal state; reusing a query builder instance may cause unexpected behavior.

fix

Create a new table instance for each query: db.table('user') every time.

affects: >=0.x

gotchaTransactions require calling beginTx() on the db instance; nested transactions are not supported.

fix

Use a single level of transaction; commit or rollback before starting another.

affects: >=1.0

breakingThe .findOrEmpty() method was added in 1.2.0; in 1.1.x it does not exist.

fix

Upgrade to 1.2.0 or use .find() with a null check.

affects: 1.1.x

Errors

Common errors & fixes

Error: createConnection is not a function

Using default import instead of named import.

fix

Change to: import { createConnection } from 'soul-orm';

TypeError: db.table(...).where(...).select is not a function

Missing await or using callback pattern.

fix

Add await before the query call: const users = await db.table('user').where({...}).select();

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node