sql-render

library0.3.4jsnpmunverified

Type-safe {{variable}} templating for .sql files with built-in SQL injection protection. Current stable version is 0.3.4, released under MIT license. Zero runtime dependencies, ships TypeScript types. Supports schema-based validation with type inference, custom schema types (identifier, enum, ISO date, UUID, S3 path, arrays, nullable), and compatibility with SQL engines that treat backslash as literal in strings (Athena, Trino, PostgreSQL). Differentiates from other SQL template libraries by focusing on safety and validation, not just interpolation.

database

npm install sql-render

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-RENDER

sql-render

databasejavascriptv0.3.4

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.

defineQuery

✓ import { defineQuery } from 'sql-render'

✗ const { defineQuery } = require('sql-render')

ESM-only package; require() will not work. Package type: module.

schema

✓ import { schema } from 'sql-render'

✗ import { Schema } from 'sql-render'

schema is a named export, not a default export. TypeScript exports are included.

inferSchemaParams

✓ import { inferSchemaParams } from 'sql-render'

✗ import { inferSchema } from 'sql-render'

Utility type to infer parameter types from schema object. Rarely imported directly but useful for complex types.

Shows how to define a query with schema validation and execute it with typed parameters.

import { defineQuery, schema } from 'sql-render'; // Create a parametrized query from a .sql file const getEvents = defineQuery('./queries/getEvents.sql', { tableName: schema.identifier, status: schema.enum('active', 'pending', 'done'), startDate: schema.isoDate, orderBy: schema.identifier, limit: schema.positiveInt, }); const { sql, errors } = getEvents({ tableName: 'prod_events', status: 'active', startDate: '2022-02-22', orderBy: 'created_at', limit: 99, }); if (errors) { console.error('Validation errors:', errors); } else { console.log(sql); }

Debug

Known issues

gotchaSQL file path resolution: The path provided to defineQuery is relative to the current working directory, not the source file, which can cause hard-to-debug issues in monorepos or when running from different directories.

fix

Use absolute paths or ensure consistent CWD. Alternatively, use a tool like path-finding to resolve relative to __dirname.

affects: >=0.1.0

gotchaEmpty array for array schema: schema.array rejects empty arrays by design. If empty arrays are valid in your use case, you must handle them before passing to the query.

fix

Check for empty array before calling getEvents, or use a conditional to omit the clause.

affects: >=0.1.0

gotchaSchema validation errors are returned as an array in the result, not thrown. Developers may forget to check the errors field and assume the query succeeded.

fix

Always check the errors property on the result object before using sql.

affects: >=0.1.0

breakingIn version 0.3.0, the import path for type inference changed: inferSchemaParams was moved from 'sql-render/types' to 'sql-render'. Old imports will break.

fix

Update imports to 'sql-render' or use the newer API.

affects: <0.3.0

Errors

Common errors & fixes

Error: Cannot find module 'sql-render'

Package not installed or incorrect import path (e.g., using CommonJS require()).

fix

Install the package: npm install sql-render. Use ESM import syntax: import { defineQuery } from 'sql-render'.

TypeError: getEvents is not a function

Calling getEvents without defining it via defineQuery, or mixing up default vs named export.

fix

Ensure you call defineQuery and use the returned function: const getEvents = defineQuery(...). Do not import getEvents directly.

Expected identifier but got ...

Passing a non-identifier value to a field declared as schema.identifier (e.g., contains spaces or special characters).

fix

Use a valid SQL identifier (e.g., table_name or schema.table).

Upgrade

Version history

0.3.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node