@pgsql/quotes

@pgsql/quotes

PostgreSQL identifier quoting and keyword classification utilities. A faithful TypeScript port of PostgreSQL's quote_identifier() from ruleutils.c, with full keyword classification from kwlist.h.

Installation

npm install @pgsql/quotes

Usage

Quoting Identifiers

import { QuoteUtils } from '@pgsql/quotes';

// Simple identifiers are not quoted
QuoteUtils.quoteIdentifier('my_table');      // 'my_table'

// Reserved keywords are quoted
QuoteUtils.quoteIdentifier('select');        // '"select"'
QuoteUtils.quoteIdentifier('table');         // '"table"'

// Unreserved keywords are not quoted
QuoteUtils.quoteIdentifier('schema');        // 'schema'

// Identifiers with uppercase or special chars are quoted
QuoteUtils.quoteIdentifier('MyTable');       // '"MyTable"'
QuoteUtils.quoteIdentifier('my-table');      // '"my-table"'

// Embedded double quotes are escaped
QuoteUtils.quoteIdentifier('a"b');           // '"a""b"'

Qualified Names

import { QuoteUtils } from '@pgsql/quotes';

// Schema-qualified names
QuoteUtils.quoteQualifiedIdentifier('public', 'my_table');
// 'public.my_table'

// Dotted names (first part strict, rest relaxed)
QuoteUtils.quoteDottedName(['public', 'my_table']);
// 'public.my_table'

// Keywords after dot don't need quoting (PostgreSQL grammar rule)
QuoteUtils.quoteDottedName(['select', 'select']);
// '"select".select'

Type Names

import { QuoteUtils } from '@pgsql/quotes';

// Type names allow col_name and type_func_name keywords unquoted
QuoteUtils.quoteIdentifierTypeName('json');       // 'json'
QuoteUtils.quoteIdentifierTypeName('integer');    // 'integer'
QuoteUtils.quoteIdentifierTypeName('boolean');    // 'boolean'

// Only reserved keywords are quoted in type position
QuoteUtils.quoteIdentifierTypeName('select');     // '"select"'

// Schema-qualified type names
QuoteUtils.quoteTypeDottedName(['public', 'json']); // 'public.json'

String Escaping

import { QuoteUtils } from '@pgsql/quotes';

// Escape string literals
QuoteUtils.escape('hello');        // "'hello'"
QuoteUtils.escape("it's");        // "'it''s'"

// E-string formatting (auto-detects need for E prefix)
QuoteUtils.formatEString('a\\b'); // "E'a\\\\b'"
QuoteUtils.formatEString('hello'); // "'hello'"

Keyword Classification

import { keywordKindOf } from '@pgsql/quotes';
import type { KeywordKind } from '@pgsql/quotes';

keywordKindOf('select');  // 'RESERVED_KEYWORD'
keywordKindOf('schema');  // 'UNRESERVED_KEYWORD'
keywordKindOf('json');    // 'COL_NAME_KEYWORD'
keywordKindOf('join');    // 'TYPE_FUNC_NAME_KEYWORD'
keywordKindOf('foo');     // 'NO_KEYWORD'

Raw Keyword Sets

import {
  RESERVED_KEYWORDS,
  UNRESERVED_KEYWORDS,
  COL_NAME_KEYWORDS,
  TYPE_FUNC_NAME_KEYWORDS,
} from '@pgsql/quotes';

RESERVED_KEYWORDS.has('select');   // true
COL_NAME_KEYWORDS.has('json');     // true

API

QuoteUtils

Method	Description
escape(literal)	Wraps a string in single quotes, escaping embedded quotes
escapeEString(value)	Escapes backslashes and single quotes for E-string literals
formatEString(value)	Auto-detects and formats E-prefixed string literals
needsEscapePrefix(value)	Checks if a value needs E-prefix escaping
quoteIdentifier(ident)	Quotes an identifier if needed (port of PG's quote_identifier)
quoteIdentifierAfterDot(ident)	Quotes for lexical reasons only (post-dot position)
quoteDottedName(parts)	Quotes a multi-part dotted name (e.g., schema.table)
quoteQualifiedIdentifier(qualifier, ident)	Quotes a two-part qualified name
quoteIdentifierTypeName(ident)	Quotes an identifier in type-name context
quoteTypeDottedName(parts)	Quotes a multi-part dotted type name

keywordKindOf(word)

Returns the keyword classification for a given word. Case-insensitive.

Returns one of: 'NO_KEYWORD', 'UNRESERVED_KEYWORD', 'COL_NAME_KEYWORD', 'TYPE_FUNC_NAME_KEYWORD', 'RESERVED_KEYWORD'.

Updating Keywords

To regenerate the keyword list from a PostgreSQL source tree:

npm run keywords -- ~/path/to/postgres/src/include/parser/kwlist.h

This parses PostgreSQL's kwlist.h and regenerates src/kwlist.ts.

🛠 Built by the Constructive team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on GitHub.

Related

• pgpm: A Postgres Package Manager that brings modular development to PostgreSQL with reusable packages, deterministic migrations, recursive dependency resolution, and tag-aware versioning.
• pgsql-test: Instant, isolated PostgreSQL databases for each test with automatic transaction rollbacks, context switching, and clean seeding for fast, reliable database testing.
• pgsql-seed: PostgreSQL seeding utilities for CSV, JSON, SQL data loading, and pgpm deployment.
• pgsql-parser: The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.
• pgsql-deparser: A streamlined tool designed for converting PostgreSQL ASTs back into SQL queries, focusing solely on deparser functionality to complement pgsql-parser.
• @pgsql/parser: Multi-version PostgreSQL parser with dynamic version selection at runtime, supporting PostgreSQL 15, 16, and 17 in a single package.
• @pgsql/types: Offers TypeScript type definitions for PostgreSQL AST nodes, facilitating type-safe construction, analysis, and manipulation of ASTs.
• @pgsql/enums: Provides TypeScript enum definitions for PostgreSQL constants, enabling type-safe usage of PostgreSQL enums and constants in your applications.
• @pgsql/utils: A comprehensive utility library for PostgreSQL, offering type-safe AST node creation and enum value conversions, simplifying the construction and manipulation of PostgreSQL ASTs.
• @pgsql/traverse: PostgreSQL AST traversal utilities for pgsql-parser, providing a visitor pattern for traversing PostgreSQL Abstract Syntax Tree nodes, similar to Babel's traverse functionality but specifically designed for PostgreSQL AST structures.
• pg-proto-parser: A TypeScript tool that parses PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
• libpg-query: The real PostgreSQL parser exposed for Node.js, used primarily in pgsql-parser for parsing and deparsing SQL queries.

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating Software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the Software code or Software CLI, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.