Code Monkey home page Code Monkey logo

pg-sql2's Introduction

pg-sql2

Create SQL in a powerful and flexible manner without opening yourself to SQL injection attacks using the power of ES6 tagged template literals.

A key aim of this library is to be very fast, if you think you can improve performance further please open a PR!

const sql = require("pg-sql2");
// or import sql from 'pg-sql2';

const tableName = "user";
const fields = ["name", "age", "height"];

// sql.join is used to join fragments with a common separator, NOT to join tables!
const sqlFields = sql.join(
  // sql.identifier safely escapes arguments and joins them with dots
  fields.map(fieldName => sql.identifier(tableName, fieldName)),
  ", "
);

// sql.value will store the value and instead add a placeholder to the SQL
// statement, to ensure that no SQL injection can occur.
const sqlConditions = sql.query`created_at > NOW() - interval '3 years' and age > ${sql.value(
  22
)}`;

// This could be a full query, but we're going to embed it in another query safely
const innerQuery = sql.query`select ${sqlFields} from ${sql.identifier(
  tableName
)} where ${sqlConditions}`;

// Symbols are automatically assigned unique identifiers
const sqlAlias = sql.identifier(Symbol());

const query = sql.query`
with ${sqlAlias} as (${innerQuery})
select
  (select json_agg(row_to_json(${sqlAlias})) from ${sqlAlias}) as all_data,
  (select max(age) from ${sqlAlias}) as max_age
`;

// sql.compile compiles the query into an SQL statement and a list of values
const { text, values } = sql.compile(query);

console.log(text);
/* ->
with __local_0__ as (select "user"."name", "user"."age", "user"."height" from "user" where created_at > NOW() - interval '3 years' and age > $1)
select
  (select json_agg(row_to_json(__local_0__)) from __local_0__) as all_data,
  (select max(age) from __local_0__) as max_age
*/

console.log(values); // [ 22 ]

// Then to run the query using `pg` module, do something like:
// const { rows } = await pg.query(text, values);

API

sql.query`...`

Builds part of (or the whole of) an SQL query, safely interpretting the embedded expressions. If a non sql.* expression is passed in, e.g.:

sql.query`select ${1}`;

then an error will be thrown.

sql.identifier(ident, ...)

Represents a safely escaped SQL identifier; if multiple arguments are passed then each will be escaped and then they will be joined with dots (e.g. "schema"."table"."column").

sql.value(val)

Represents an SQL value, will be replaced with a placeholder and the value collected up at compile time.

sql.literal(val)

As sql.value, but in the case of very simple values may write them directly to the SQL statement (correctly escaped) rather than using a placeholder. Should only be used with data that is not sensitive and is trusted (not user-provided data), e.g. for the key arguments to json_build_object(key, val, key, val, ...) which you have produced.

sql.join(arrayOfFragments, delimeter)

Joins an array of sql.query values using the delimeter (which is treated as a raw SQL string); e.g.

const arrayOfSqlFields = ["a", "b", "c", "d"].map(n => sql.identifier(n));
sql.query`select ${sql.join(arrayOfSqlFields, ", ")}`; // -> select "a", "b", "c", "d"

const arrayOfSqlConditions = [
  sql.query`a = 1`,
  sql.query`b = 2`,
  sql.query`c = 3`
];
sql.query`where (${sql.join(arrayOfSqlConditions, ") and (")})`; // -> where (a = 1) and (b = 2) and (c = 3)

const fragments = [
  { alias: "name", sqlFragment: sql.identifier("user", "name") },
  { alias: "age", sqlFragment: sql.identifier("user", "age") }
];
sql.query`
  json_build_object(
    ${sql.join(
      fragments.map(
        ({ sqlFragment, alias }) =>
          sql.query`${sql.literal(alias)}, ${sqlFragment}`
      ),
      ",\n"
    )}
  )`;

const arrayOfSqlInnerJoins = [
  sql.query`inner join bar on (bar.foo_id = foo.id)`,
  sql.query`inner join baz on (baz.bar_id = bar.id)`
];
sql.query`select * from foo ${sql.join(arrayOfSqlInnerJoins, " ")}`;
// select * from foo inner join bar on (bar.foo_id = foo.id) inner join baz on (baz.bar_id = bar.id)

DANGEROUS: sql.raw(val)

DO NOT USE THIS. This is an escape hatch, and it should not be necessary, there is almost always a better way. Directly injects the value provided into the generated SQL statement as raw SQL with no escaping whatsoever. This opens your SQL statement up to SQL injection attacks if you use it with untrusted data. DO NOT USE THIS.

sql.compile(query)

Compiles the query into an SQL statement and a list of values, ready to be executed

const query = sql.query`...`;
const { text, values } = sql.compile(query);

// const { rows } = await pg.query(text, values);

History

This is a replacement for @calebmer's pg-sql, combining the additional work that was done to it in postgraphql and offering the following enhancements:

  • Better development experience for people not using Flow/TypeScript (throws errors a lot earlier allowing you to catch issues at the source)
  • Slightly more helpful error messages
  • Uses a symbol-key on the query nodes to protect against an object accidentally being inserted verbatim and being treated as valid (because every Symbol is unique an attacker would need control of the code to get a reference to the Symbol in order to set it on an object (it cannot be serialised/deserialised via JSON or any other medium), and if the attacker has control of the code then you've already lost)
  • Adds sql.literal which is similar to sql.value but when used with simple values can write the valid direct to the SQL statement. USE WITH CAUTION. The purpose for this is if you are using trusted values (e.g. for the keys to json_build_object(...)) then debugging your SQL becomes a lot easier because fewer placeholders are used.

pg-sql2's People

Contributors

benjie avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar

pg-sql2's Issues

Add support for Symbol#description

__local_0__ is pragmatic; but lets make it nicer! In Node v12+ we can use symbol.description to get the symbol description, make it unique, and use that instead. For Node 10 and below it's equivalent to a symbol not having a description, so we can just stick with the status quo.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.