{"id":18457,"library":"jsharmony-db","title":"jsharmony-db","description":"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.","status":"active","version":"1.14.2","language":"javascript","source_language":"en","source_url":"https://github.com/apHarmony/jsharmony-db","tags":["javascript","jsHarmony","Database","Library"],"install":[{"cmd":"npm install jsharmony-db","lang":"bash","label":"npm"},{"cmd":"yarn add jsharmony-db","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsharmony-db","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides SQL Server connectivity and driver. jsharmony-db wraps mssql for query execution.","package":"mssql","optional":false}],"imports":[{"note":"This package is CJS-only, not ESM. Use require().","wrong":"import DB from 'jsharmony-db'","symbol":"DB","correct":"const DB = require('jsharmony-db')"},{"note":"Access types via the DB object. There is no separate export for types.","wrong":"require('jsharmony-db').types.BigInt","symbol":"DB.types","correct":"DB.types.BigInt"},{"note":"DB.Connection is the class for establishing database connections. Do not use DB.ConnectionPool (undocumented).","wrong":"new DB.ConnectionPool(config)","symbol":"DB.Connection","correct":"const conn = new DB.Connection(config)"},{"note":"Query requires a connection instance; there is no static query method.","wrong":"DB.query('SELECT 1')","symbol":"DB.Query","correct":"const query = new DB.Query(conn).sql('SELECT 1')"}],"quickstart":{"code":"const DB = require('jsharmony-db');\n\nconst config = {\n  server: 'localhost',\n  database: 'testdb',\n  user: 'sa',\n  password: process.env.DB_PASSWORD ?? '',\n  port: 1433\n};\n\nconst conn = new DB.Connection(config);\nconn.open(function(err) {\n  if (err) { console.error(err); return; }\n  const query = new DB.Query(conn);\n  query.sql('SELECT * FROM Users WHERE id = @id')\n       .param('id', 1)\n       .execute(function(err, results) {\n         if (err) { console.error(err); return; }\n         console.log('User:', results[0]);\n         conn.close();\n       });\n});","lang":"javascript","description":"Establishes a SQL Server connection, runs a parameterized SELECT query, logs the first result, and closes the connection."},"warnings":[{"fix":"Always provide a callback (function(err) { ... }) to .open(). Remove any .openSync() usage.","message":"From version 1.9.0, DB.Connection no longer supports synchronous .open() without a callback.","severity":"breaking","affected_versions":">=1.9.0"},{"fix":"Replace new DB.ConnectionPool(config) with new DB.Connection(config).","message":"DB.ConnectionPool was removed in version 1.5.0; use DB.Connection directly.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Use DB.types.NVarChar(DB.types.MAX) for large strings.","message":"DB.types.NChar and DB.types.NText are deprecated since 1.12.0. Prefer NVarChar.","severity":"deprecated","affected_versions":">=1.12.0"},{"fix":"Always use @paramName in SQL strings and .param('paramName', value).","message":"When using parameters, the @param syntax is required. Do not use ? or $1 placeholders.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Implement retry logic manually or use a connection pool manager.","message":"DB.Connection does not automatically retry on connection failure. It returns error string directly.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure you are using const DB = require('jsharmony-db'); and version >=1.0.0. Try npm install jsharmony-db@latest.","cause":"Incorrect import or older version installed.","error":"TypeError: DB.Connection is not a constructor"},{"fix":"Use DB.types.BigInt, not types.BigInt alone.","cause":"Accessing types on a different object, not on the DB object.","error":"Cannot read property 'BigInt' of undefined"},{"fix":"Call conn.open(function(err) { ... }).","cause":"Using .open() without a callback in version >=1.9.0.","error":"Error: Callback is required for open"},{"fix":"Verify that every @param in SQL has a corresponding .param('param', value).","cause":"Parameter in SQL does not match .param() call, or parameter is missing.","error":"RequestError: Must declare the scalar variable \"@param\""}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}