mongo-sql

library6.2.0jsnpmunverified

Mongo-sql is a Node.js library that converts JSON-style query definitions into SQL strings, with a focus on PostgreSQL syntax. As of version 6.2.0 (stable, with irregular releases), it supports SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, JOINs, subqueries, and more. Unlike chain-style SQL builders, mongo-sql uses plain JavaScript objects to represent queries, making them easy to manipulate programmatically. It generates parameterized queries with `$N` placeholders to prevent SQL injection. Designed for extensibility and semantic clarity, it is ideal for developers who want a declarative, data-driven approach to SQL generation.

database

npm install mongo-sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGO-SQL

mongo-sql

databasejavascriptv6.2.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.

default export (sql function)

✓ const mongoSql = require('mongo-sql');

✗ import mongoSql from 'mongo-sql';

The package uses CommonJS; ESM import may fail or require default interop.

sql function

✓ const { sql } = require('mongo-sql');

✗ const sql = require('mongo-sql').sql;

Both are valid in CommonJS, but the destructured import is more idiomatic.

helpers (e.g., helpers.expression)

✓ const { helpers } = require('mongo-sql');

✗ const helpers = require('mongo-sql/helpers');

Helpers are exported as a property of the main module, not as a submodule.

Shows how to build a SELECT query with an OR condition using mongo-sql's JSON syntax, then execute the SQL generation to get parameterized query string and values.

const { sql } = require('mongo-sql'); const query = { type: 'select', table: 'users', where: { $or: { id: 5, name: 'Bob' } } }; const result = sql(query); console.log(result.toString()); // SELECT "users".* FROM "users" WHERE "users"."id" = $1 OR "users"."name" = $2 console.log(result.values); // [5, 'Bob']

Debug

Known issues

breakingIn v6.0.0, the API changed from `require('mongo-sql').sql()` to `require('mongo-sql')()` (default export is now the sql function). Also removed legacy helper methods.

fix

If migrating from v5, replace `var builder = require('mongo-sql'); builder.sql(query)` with `var mongoSql = require('mongo-sql'); mongoSql(query)`.

affects: >=6.0.0 <7.0.0

deprecatedThe `mongo-sql` package is deprecated in favor of its successor `mosql`. Future development will occur under the new package name.

fix

Consider migrating to `mosql` (npm package) which has an identical API.

affects: >=6.2.0

gotchaWhen using `returning` clause in INSERT/UPDATE/DELETE, the column names must be quoted correctly. The library auto-quotes but may produce incorrect syntax for expressions.

fix

Use explicit string quotes for column names, e.g., `returning: ['"id"', '"createdAt"']` instead of `returning: ['id', 'createdAt']` if you need case-sensitive handling.

affects: >=4.0.0

gotchaThe `$or` operator only supports an object with multiple keys; it does not accept an array of conditions. Using an array will throw an error.

fix

Use the object form: `{ $or: { cond1: val1, cond2: val2 } }` instead of `{ $or: [{ cond1: val1 }, { cond2: val2 }] }`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: mongoSql is not a function

Incorrect import style or version mismatch (v6 changed default export).

fix

Use `const mongoSql = require('mongo-sql');` then call `mongoSql(query)`. For v5, use `require('mongo-sql').sql(query)`.

SyntaxError: Unexpected token $or

Using `$or` inside a `where` clause incorrectly (not an object).

fix

Ensure `$or` is an object, not an array: `{ $or: { id: 5, name: 'Bob' } }`.

Error: No 'type' property on query object

Missing required 'type' field in the query object.

fix

Add a 'type' property with value 'select', 'insert', 'update', 'delete', etc.

Error: Invalid column reference: returning

Using `returning` with uppercase letters or incorrect quoting.

fix

Use lowercase column names or quote them: `returning: ['"MyColumn"']`.

Upgrade

Version history

6.2.0latest on npm

Audit

Dependencies

lodashrequiredUsed internally for object manipulation

mongo-sql-query-builderoptionalOptional companion package for additional query building utilities

Agent activity

6 hits · last 30 days

node

Resources

githubgit://github.com/goodybag/mongo-sql ↗

packagemongo-sql ↗

homepagehttps://github.com/goodybag/mongo-sql#readme ↗