jsharmony-db

1.14.2 verified Sat Apr 25 auth: no javascript

jsHarmony Database Core library providing an ORM-like interface for database operations, focusing on SQL Server with support for schema definition, CRUD operations, and stored procedures. The current stable version is 1.14.2, released with periodic updates. Key differentiators include a flexible type system (DB.types) for column definitions, built-in connection pooling, and compatibility with jsHarmony framework. Unlike general ORMs, it emphasizes direct SQL control and integration with jsHarmony's application structure. It also provides utilities for database metadata scanning and migration.

Common errors

error TypeError: DB.Connection is not a constructor ↓

cause Incorrect import or older version installed.

fix

Ensure you are using const DB = require('jsharmony-db'); and version >=1.0.0. Try npm install jsharmony-db@latest.

error Cannot read property 'BigInt' of undefined ↓

cause Accessing types on a different object, not on the DB object.

fix

Use DB.types.BigInt, not types.BigInt alone.

error Error: Callback is required for open ↓

cause Using .open() without a callback in version >=1.9.0.

fix

Call conn.open(function(err) { ... }).

error RequestError: Must declare the scalar variable "@param" ↓

cause Parameter in SQL does not match .param() call, or parameter is missing.

fix

Verify that every @param in SQL has a corresponding .param('param', value).

Warnings

breaking From version 1.9.0, DB.Connection no longer supports synchronous .open() without a callback. ↓

fix Always provide a callback (function(err) { ... }) to .open(). Remove any .openSync() usage.

breaking DB.ConnectionPool was removed in version 1.5.0; use DB.Connection directly. ↓

fix Replace new DB.ConnectionPool(config) with new DB.Connection(config).

deprecated DB.types.NChar and DB.types.NText are deprecated since 1.12.0. Prefer NVarChar. ↓

fix Use DB.types.NVarChar(DB.types.MAX) for large strings.

gotcha When using parameters, the @param syntax is required. Do not use ? or $1 placeholders. ↓

fix Always use @paramName in SQL strings and .param('paramName', value).

gotcha DB.Connection does not automatically retry on connection failure. It returns error string directly. ↓

fix Implement retry logic manually or use a connection pool manager.

Install

npm install jsharmony-db

yarn add jsharmony-db

pnpm add jsharmony-db

Imports

wrong

import DB from 'jsharmony-db'

correct

const DB = require('jsharmony-db')

This package is CJS-only, not ESM. Use require().

DB.types
wrong
```
require('jsharmony-db').types.BigInt
```
correct
```
DB.types.BigInt
```
Access types via the DB object. There is no separate export for types.
DB.Connection
wrong
```
new DB.ConnectionPool(config)
```
correct
```
const conn = new DB.Connection(config)
```
DB.Connection is the class for establishing database connections. Do not use DB.ConnectionPool (undocumented).
DB.Query
wrong
```
DB.query('SELECT 1')
```
correct
```
const query = new DB.Query(conn).sql('SELECT 1')
```
Query requires a connection instance; there is no static query method.

Quickstart

Establishes a SQL Server connection, runs a parameterized SELECT query, logs the first result, and closes the connection.

const DB = require('jsharmony-db');

const config = {
  server: 'localhost',
  database: 'testdb',
  user: 'sa',
  password: process.env.DB_PASSWORD ?? '',
  port: 1433
};

const conn = new DB.Connection(config);
conn.open(function(err) {
  if (err) { console.error(err); return; }
  const query = new DB.Query(conn);
  query.sql('SELECT * FROM Users WHERE id = @id')
       .param('id', 1)
       .execute(function(err, results) {
         if (err) { console.error(err); return; }
         console.log('User:', results[0]);
         conn.close();
       });
});