sql-builder.js

library2.1.0jsnpmunverified

sql-builder.js v2.1.0 is a lightweight, zero-dependency SQL query builder for JavaScript and TypeScript with built-in SQL injection protection via parameterized queries and identifier validation. It supports ESM and CJS, provides a fluent chainable API for SELECT, INSERT, UPDATE, DELETE, and UPSERT, and includes advanced features like raw expressions, joins, and pagination. Compared to alternatives like knex.js, it is significantly smaller and simpler, with no external dependencies, but lacks database dialect-specific features and migration tooling. The package is released under the Anti 996 license, requires Node >=14, and follows an active release cadence.

database

npm install sql-builder.js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-BUILDER.JS

sql-builder.js

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

SQLBuilder

✓ import { SQLBuilder } from 'sql-builder.js'

✗ import SQLBuilder from 'sql-builder.js'

Named export only. CommonJS: const { SQLBuilder } = require('sql-builder.js').

raw

✓ import { raw } from 'sql-builder.js'

✗ const raw = require('sql-builder.js').raw

Named export for embedding raw SQL expressions. CommonJS: const { raw } = require('sql-builder.js').

SQLBuilderOptions

✓ import type { SQLBuilderOptions } from 'sql-builder.js'

✗ import { SQLBuilderOptions } from 'sql-builder.js'

TypeScript type export, not a runtime value. Use 'import type' to avoid runtime errors.

Create SQLBuilder instance, build a SELECT query with parameterized where clause, and demonstrate INSERT query.

import { SQLBuilder } from 'sql-builder.js'; const sqlBuilder = new SQLBuilder(); // Build a SELECT query const result = sqlBuilder .select('*') .from('users') .where('age', '>', 18) .build(); console.log(result.sql); // SELECT * FROM `users` WHERE `age` > ? console.log(result.params); // [18] console.log(result.toString()); // SELECT * FROM `users` WHERE `age` > 18 // INSERT example const insertResult = sqlBuilder .insert('users', { name: 'Alice', age: 25 }) .build(); console.log(insertResult.sql); // INSERT INTO `users` (`name`, `age`) VALUES (?, ?) console.log(insertResult.params); // ['Alice', 25]

Debug

Known issues

gotchaThe `raw()` function bypasses parameterization and can introduce SQL injection if user input is concatenated unsafely.

fix

Only use `raw()` with trusted inputs or heavily sanitized values. Prefer parameterized queries over raw expressions whenever possible.

affects: >=1.0.0

gotchaTable and column names are backtick-quoted by default. If you use dots or aliases (e.g., 'users u'), they may not be quoted correctly, leading to syntax errors.

fix

Use explicit aliases with AS keyword: 'users AS u'. For column-qualified names, use dot notation only when the alias is expected (e.g., 'u.id').

affects: >=1.0.0

gotchaThe `build()` method returns a new object each time, but the builder instance is mutated. Reusing the same builder for multiple queries can produce unintended results.

fix

Create a new SQLBuilder instance for each query, or clone the builder if supported (check docs).

affects: >=1.0.0

gotchaString values are always parameterized, but numeric values are also parameterized. If you need to embed a numeric literal directly, use `raw()`.

fix

Use `raw('1')` for literal numbers, but be aware of injection risks.

affects: >=1.0.0

deprecatedThe `raw()` function usage with `set()` in UPDATE may change in future versions. Currently, you can pass a raw object or a string to set().

fix

Always use `raw()` from the package for raw expressions, not plain strings.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: SQLBuilder is not a constructor

Using default import instead of named import.

fix

Use: import { SQLBuilder } from 'sql-builder.js'

Cannot find module 'sql-builder.js'

Package not installed or import path is wrong.

fix

Run: npm install sql-builder.js --save

SyntaxError: Unexpected token 'export'

Using ESM syntax in a CommonJS environment without transpilation.

fix

Use CommonJS: const { SQLBuilder } = require('sql-builder.js')

Column 'foo' is not allowed

Identifier validation is enabled by default; column name contains disallowed characters.

fix

Use the `raw()` function to bypass validation or adjust the column name to match allowed pattern.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/axetroy/sql-builder.js ↗

packagesql-builder.js ↗

homepagehttps://github.com/axetroy/sql-builder.js#readme ↗