sql

library0.78.0jsnpmunverified

SQL query string builder for Node.js supporting PostgreSQL, MySQL, MSSQL, Oracle, and SQLite. Current version 0.78.0 (as of 2019). Queries are parameterized by default to prevent SQL injection. Tables are defined in JavaScript, and query building is composable and chainable. Differentiates from other query builders by its simple API and support for multiple dialects with a single unified interface. Last stable release was over 5 years ago; the project appears to be in maintenance mode with no recent commits.

database

npm install sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL

sql

databasejavascriptv0.78.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 'sql'

✗ var sql = require('sql');

Package ships TypeScript types but CommonJS usage is still common; ESM works for Node >=16 with type: module or .mjs

sql.define

✓ import sql from 'sql'; const table = sql.define({ name: 'users', columns: ['id', 'name'] })

✗ const table = require('sql').define({...})

`sql.define` is static method on default import.

Table

✓ import { Table } from 'sql'

✗ import { Table as t } from 'sql'

TypeScript type for defined table. Not commonly used in JS, toQuery() returns object.

Defines a table, builds a SELECT query with WHERE, OR, ORDER BY, and outputs parameterized text and values.

import sql from 'sql'; sql.setDialect('postgres'); const user = sql.define({ name: 'user', columns: ['id', 'name', 'email', 'lastLogin'] }); const query = user .select(user.id, user.name) .from(user) .where(user.name.equals('John').and(user.id.equals(1))) .or(user.email.equals('john@example.com')) .order(user.lastLogin.descending) .toQuery(); console.log(query.text); // SELECT "user"."id", "user"."name" FROM "user" WHERE (("user"."name" = $1) AND ("user"."id" = $2)) OR ("user"."email" = $3) ORDER BY "user"."lastLogin" DESC console.log(query.values); // ['John', 1, 'john@example.com']

Debug

Known issues

breakingVersion 0.72.0 changed the default dialect from MySQL to PostgreSQL. Existing queries may break if dialect not set explicitly.

fix

Call sql.setDialect('mysql') at the start of your app if you use MySQL.

affects: <0.72.0

deprecatedThe `toKeyword()` and `toParameter()` functions are deprecated; use `toQuery()` instead.

fix

Replace `table.toKeyword()` with `toQuery().text` and `table.toParameter(column)` with parameterized `toQuery().values`.

affects: >=0.60.0

gotchaColumn property names are case-sensitive and must match exactly. Using wrong case will silently default to the property value.

fix

Ensure column names in `columns` array or object match exactly with property accessed.

affects: >=0.1.0

gotchaJoins without explicit ON clause may produce unexpected SQL. The package does not warn if ON is omitted.

fix

Always specify `.on(condition)` after `.join()` or `.leftJoin()`.

affects: >=0.1.0

breakingIn version 0.68.0, `sql.define` changed from accepting an object with `properties` to an object with `columns`. Old property definitions may break.

fix

Update table definitions to use `columns` array instead of `properties`.

affects: <0.68.0

gotchaThe `toQuery()` method returns an object with `text` and `values` properties, but `text` is not always a valid SQL string (e.g., missing semicolon).

fix

Use the `text` property directly; append semicolon if required by your database driver.

affects: >=0.1.0

Errors

Common errors & fixes

Cannot read property 'text' of undefined

Calling toQuery() on a query object that was not properly built (e.g., missing table definition).

fix

Ensure that you have defined the table with sql.define() and that the query chain is complete (e.g., .from(table) called).

TypeError: user.select is not a function

`sql.define` returns a Table object, but attempting to access `user.select` on a wrong import or typo.

fix

Verify that `const user = sql.define({...})` is called correctly and that you are using ES module import or CommonJS require correctly.

ReferenceError: sql is not defined

Missing require or import statement for the 'sql' package.

fix

Add `import sql from 'sql'` (ESM) or `const sql = require('sql')` (CommonJS) at the top of your file.

Dialect not supported: oracle

The 'oracle' dialect is not bundled by default; requires separate plugin.

fix

Use one of: 'postgres', 'mysql', 'mssql', 'sqlite' or install a dialect plugin (if available).

Upgrade

Version history

0.78.0latest on npm

Audit

Dependencies

sql-extraoptionalCommon companion package for auto-generating table definitions

Agent activity

14 hits · last 30 days

node