API

pg-sql2 provides a comprehensive API for building SQL queries safely and dynamically without risking SQL injection. All functions are available as methods on the main sql export. It's designed for use with PostgreSQL, but many features are applicable to other SQL databases as well.

Core functions

Template literal function

• sql`...` - The main template literal function for building SQL queries, supports embedding other SQL fragments (only! no raw values)

Compilation

• sql.compile(query, options?) - Compile SQL to text and values ready for execution

Value handling

• sql.value(val) - Embed user values using placeholders (avoid SQLi)
• sql.literal(val) - Embed simple values directly if safe; fall back to sql.value(val) otherwise

Common expressions

• sql.true - equivalent to sql`true`
• sql.false - equivalent to sql`false`
• sql.null - equivalent to sql`null`
• sql.blank - equivalent to sql``

Query building

• sql.join(fragments, delimiter) - Join multiple SQL fragments together
• sql.identifier(...names) - Create safely escaped SQL identifiers
• sql.parens(fragment, force?) - Add parentheses when needed
• sql.indent(fragment) - Indent SQL for readability
• sql.indentIf(condition, fragment) - Conditionally indent SQL

Advanced features

Most users won't need these, but they are available for advanced use cases:

• sql.comment(text) - Add SQL comments
• sql.placeholder(symbol, fallback?) - Create replaceable placeholders
• sql.withTransformer(transformer, callback) - Allow non-SQL values to be interpolated
• sql.isSQL(value) - Check if a value is a SQL fragment
• sql.isEquivalent(sql1, sql2, options?) - Compare SQL fragments for equivalence
• sql.symbolAlias(symbol1, symbol2) - Create symbol aliases (e.g. when merging fragments)
• sql.replaceSymbol(fragment, needle, replacement) - Replace symbols in SQL fragments

Escape hatch

HIGHLY DISCOURAGED

This method bypasses all SQL injection protections. There are almost always better solutions. If you use sql.raw you're defeating the purpose of the library and opening yourself up to SQL injection vulnerabilities.

EXTREME CAUTION ADVISED.

• sql.raw(text) - ⚠️ DANGER ⚠️ Embed raw, dynamic, SQL text