o2sql

library4.0.20jsnpmunverified

o2sql is a lightweight JavaScript library for programmatically generating PostgreSQL queries with parameterized values. It provides a fluent API to build SELECT, INSERT, UPDATE, and DELETE statements, abstracting the SQL generation into an AST (Abstract Syntax Tree) that can be converted to `{ sql, values }` objects compatible with node-postgres (`pg`). Version 4.0.20 has no known breaking changes from earlier v4 releases. Key differentiators: simple, minimal API; automatic identifier quoting; direct integration with the `pg` library via `.toParams()`. It does not support MySQL despite the keyword.

database

npm install o2sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · O2SQL

o2sql

databasejavascriptv4.0.20

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

✓ const o2sql = new (require('o2sql'))();

✗ const o2sql = require('o2sql');

Must instantiate with `new`. Also available as ESM import: `import O2Sql from 'o2sql'`.

Ast

✓ import type { Ast } from 'o2sql'

TypeScript type; not a runtime export.

select/from

✓ const q = new (require('o2sql'))(); q.select(['id']).from('users').toParams();

✗ o2sql.select('id').from('users').toParams();

`select`, `from`, etc. are instance methods, not static.

Generate a parameterized SELECT query with filtering, ordering, and limit.

const o2sql = new (require('o2sql'))(); const params = o2sql .select(['id', 'name', 'email']) .from('users') .where({ active: true, age: { $gt: 18 } }) .orderBy('name', 'asc') .limit(5) .toParams(); console.log(params.sql); // 'select "id", "name", "email" from "users" where "active" = $1 and "age" > $2 order by "name" asc limit $3' console.log(params.values); // [true, 18, 5]

Debug

Known issues

gotchao2sql always double-quotes identifiers (table/column names). If you use case-sensitive names or reserved words, this is correct; otherwise, it adds unnecessary quotes.

fix

This is by design; the generated SQL is valid and works with PostgreSQL despite the extra quotes.

affects: >=4.0.0

gotchaThe `where` method does not accept raw SQL strings; it only accepts objects or primitive values. Using a string will be treated as a parameterized value, not as SQL.

fix

Use `o2sql.e()` or `o2sql.i()` to build complex conditions.

affects: >=4.0.0

deprecatedThe `o2sql.function` (or `o2sql.f`) method's first argument is the function name, but it does not quote the function name. This may cause issues if the function name is a reserved word or contains special characters.

fix

Manually quote the function name using `o2sql.i()` if needed.

affects: >=4.0.0 <5.0.0

gotchaUnrecognized operators in `.op()` are passed through as-is into the SQL string, which could lead to SQL injection if user input is used as the operator.

fix

Validate or whitelist operators before passing to `.op()`.

affects: >=4.0.0

Errors

Common errors & fixes

Cannot find module 'o2sql'

Package not installed or wrong import syntax

fix

Run `npm install o2sql` and use `const o2sql = new (require('o2sql'))();` (CommonJS) or `import O2Sql from 'o2sql'; const o2sql = new O2Sql();` (ESM).

o2sql.select is not a function

Attempting to call `select` statically instead of on an instance

fix

Create an instance first: `const o2sql = new (require('o2sql'))();` then `o2sql.select(...)`.

TypeError: o2sql(...).where(...) is not a function

Chaining methods incorrectly or using `where` without a valid argument

fix

Ensure you call `select` and `from` before `where`. Example: `o2sql.select(['id']).from('users').where({id: 1}).toParams()`.

Upgrade

Version history

4.0.20latest on npm

Audit

Dependencies

pgoptionalThe library outputs `{sql, values}` objects designed for node-postgres, but it does not require it as a peer dependency.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/qdechochen/o2sql ↗

packageo2sql ↗

homepagehttps://github.com/qdechochen/o2sql#readme ↗