db-sql-toolkit

library2.6.0jsnpmunverified

A library for building SQL statements with tagged templates, running database migrations, and bulk executing operations (insert, select, update, delete). Version 2.6.0, actively maintained on GitHub (atheck/db-sql-toolkit). Key differentiators: parameterized SQL via template literals (sql tag), nested SQL composition, sqlLiteral for raw literal insertion, and bulk functions that split operations based on database variable limits. Ships TypeScript definitions. No database driver included – requires user-supplied database adapter with run/query methods.

database

npm install db-sql-toolkit

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DB-SQL-TOOLKIT

db-sql-toolkit

databasejavascriptv2.6.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.

sql

✓ import { sql } from 'db-sql-toolkit'

✗ const sql = require('db-sql-toolkit').sql

ESM and CJS both supported, but named imports preferred with TypeScript.

applyMigrations

✓ import { applyMigrations } from 'db-sql-toolkit'

✗ import applyMigrations from 'db-sql-toolkit'

applyMigrations is a named export, not default.

Database

✓ import type { Database } from 'db-sql-toolkit'

✗ import { Database } from 'db-sql-toolkit' (when using value import)

Database is a TypeScript interface. Use type import to avoid runtime issues.

bulkInsertEntities

✓ import { bulkInsertEntities } from 'db-sql-toolkit'

✗ import { BulkInsertEntities } from 'db-sql-toolkit'

Function is camelCase, not PascalCase.

Shows bulk insert of entities using sql tagged template and bulkInsertEntities with a typed Database interface.

import { sql, bulkInsertEntities, Database } from 'db-sql-toolkit'; type Package = { id: number; name: string; version: string }; const database: Database = { run: async (sqlAndParams: [string, unknown[]]) => { /* e.g., mysql2 */ }, MaxVariableNumber: 999 }; const packages: Package[] = [ { id: 1, name: 'pkg1', version: '1.0.0' }, { id: 2, name: 'pkg2', version: '2.0.0' }, ]; const getParameters = (pkg: Package): unknown[] => [pkg.id, pkg.name, pkg.version]; const statement = sql` INSERT INTO packages (id, name, version) VALUES (${getParameters}) `; await bulkInsertEntities(database, packages, statement); console.log('Entities inserted in bulk.');

Debug

Known issues

gotchaThe sql tag returns a tuple [string, unknown[]], not a raw SQL string. Do not treat it as a string.

fix

Use the tuple directly with your database adapter (e.g., adapter.run(statement)).

affects: >=0.0.0

gotchabulkExecuteCommand: When the operation cannot be executed in one run, using NOT IN operator leads to wrong results.

fix

Avoid NOT IN in queries passed to bulkExecuteCommand. Use NOT EXISTS or join instead.

affects: >=0.0.0

gotchasqlLiteral inserts raw string into SQL – can cause SQL injection if used with user input. Use only for safe constants.

fix

Never pass user input to sqlLiteral. Use parameters via ${} instead.

affects: >=0.0.0

gotchabulkInsertEntities expects a function reference as the only parameter in the sql template, not an array literal.

fix

Pass a function that extracts parameters from an entity, as shown in docs.

affects: >=0.0.0

deprecatedNo deprecation warnings noted in current version. Check CHANGELOG for potential future deprecations.

fix

Stay updated with repository releases.

affects: 2.6.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'MaxVariableNumber')

Database object passed to bulk functions lacks MaxVariableNumber property.

fix

Ensure your Database object includes MaxVariableNumber (e.g., { run, MaxVariableNumber: 999 }).

Error: sql must be a tagged template literal

Called sql() as a regular function, not as a tagged template.

fix

Use sql`SELECT * FROM table` (with backticks).

No overload matches this call. Overload 1 of ..., gave the following error. Argument of type 'any[]' is not assignable to parameter of type '...'

Incorrect type for the function passed to sql in bulkInsertEntities – it expects a function returning unknown[], not an array.

fix

Pass a function: (entity: MyType) => unknown[], not an array literal.

Upgrade

Version history

2.6.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/atheck/db-sql-toolkit ↗

packagedb-sql-toolkit ↗

homepagehttps://github.com/atheck/db-sql-toolkit ↗