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.
sql
✓ import { sql } from 'sqlx-ts'
✗ const sql = require('sqlx-ts').sql
sql is a named export; default import does not exist.
Database
✓ import { Database } from 'sqlx-ts'
✗ import Database from 'sqlx-ts'
Database is a named export exposed for type use; not a default export.
DbConnection
✓ import { DbConnection } from 'sqlx-ts'
✗ const { DbConnection } = require('sqlx-ts')
DbConnection is a type helper interface; can be used in both ESM and CJS, but ESM preferred.
Shows installation, generating types from a SQL file via CLI, and using the sql tagged template literal for type-safe query creation.
// 1. Install the package
// npm install sqlx-ts
// 2. Create a SQL file (e.g., queries/users.sql)
// -- @name: getUserById
// SELECT id, name, email FROM users WHERE id = $1;
// 3. Run the CLI to generate types
// npx sqlx-ts generate -d postgres://user:pass@localhost/db
// 4. Use in code
import { sql } from 'sqlx-ts';
const userId = 1;
const query = sql`SELECT id, name, email FROM users WHERE id = ${userId}`;
// query is now a type-safe Query object with inferred parameter names and result types
console.log(query.sql); // SELECT id, name, email FROM users WHERE id = $1
console.log(query.params); // { 0: 'number' }
Debug
Known issues
breakingIn sqlx-ts v0.45+, the generated type files now use ES module syntax (.mjs/.d.mts) and import maps have changed. Projects using CommonJS or older Node.js versions may break.fixUpdate tsconfig to include "module": "ESNext" or re-run sqlx-ts generate with --cjs flag.
affects: >=0.45.0
deprecatedThe `query` function from earlier versions (v0.20-v0.30) is deprecated. Use `sql` tagged template literal instead.fixReplace `query('SELECT * FROM users WHERE id = $1', [id])` with `sql\`SELECT * FROM users WHERE id = ${id}\``. affects: >=0.20.0 <0.31.0
breakingsqlx-ts v0.40 dropped support for Node.js 14 and earlier. The minimum Node.js version is now 16.fixUpgrade Node.js to version 16 or later.
affects: >=0.40.0
gotchaThe `sql` template tag cannot be used with dynamic table names or column names (e.g., `sql\`SELECT * FROM ${tableName}\``). This is not a bug; it is by design for compile-time safety.fixUse string interpolation only for values, not identifiers. For dynamic identifiers, consider using the SQL file approach with annotations.
affects: >=0.0.0
Errors
Common errors & fixes
Error: Cannot find module 'sqlx-ts' after npm install
Missing npm install or incorrect working directory.
fixRun `npm install sqlx-ts` from the project root and ensure node_modules contains sqlx-ts.
TypeError: sqlx_ts_1.sql is not a function
Using default import instead of named import: `import sqlx from 'sqlx-ts'`.
fixChange to `import { sql } from 'sqlx-ts'`. sqlx-ts: No configuration file found. Run 'sqlx-ts init' to create one.
Missing sqlx-ts.json or .sqlx-ts.json in project root.
fixRun `npx sqlx-ts init` to generate a default configuration file.
error: The 'database' argument is required for 'generate' command
Running `sqlx-ts generate` without specifying a database connection.
fixProvide a database URL: `npx sqlx-ts generate -d postgres://user:pass@localhost/db` or add a config file.
Audit
Dependencies
No dependency data recorded yet.