package
Generate safe Postgres-compliant SQL with tagged template literals
npm install pg-sql2GitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Latest published Oct 30, 2026
latest
snapshot-next
Create highly dynamic SQL in a powerful and flexible manner without opening yourself to SQL injection attacks.
A key aim of this library is to be very fast, if you think you can improve performance further please open a PR!
To help us develop this software sustainably, we ask all individuals and businesses that use it to help support its ongoing maintenance and development via sponsorship.
And please give some love to our featured sponsors 🤩:
* Sponsors the entire Graphile suite
const { default: 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`created_at > NOW() - interval '3 years' and age > ${
sql`...`Builds part of (or the whole of) an SQL query, safely interpreting the embedded
expressions. If a non sql expression is passed in, e.g.:
sql`select ${1}`;then an error will be thrown. This prevents SQL injection, as all values must go through an allowed API.
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 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, delimiter)Joins an array of sql values using the delimiter (which is treated as a raw
SQL string); e.g.
const arrayOfSqlFields = ["a", "b", "c", "d"].map((n) => sql.identifier(n));
sql`select ${sql.join(arrayOfSqlFields, ", ")}`; // -> select "a", "b", "c", "d"
const arrayOfSqlConditions = [sql`a = 1`, sql`b = 2`, sql`c = 3`];
sql`where (${sql.join(arrayOfSqlConditions, ") and (")})`; // -> where (a = 1) and (b = 2) and (c = 3)
const fragments = [
{ alias:
sql.compile(query)Compiles the query into an SQL statement and a list of values, ready to be executed
const query = sql`...`;
const { text, values } = sql.compile(query);
// const { rows } = await pg.query(text, values);sql.compile(query, options)An advanced form of sql.compile that can be used to provide the placeholders
when you're using sql.placeholder.
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:
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.Estimated unpacked size across 3 packages.
201.9 kB
Includes dependencies.