sqlstack

library1.0.25jsnpmunverified

sqlstack (v1.0.25, monthly releases) is a SQL-first data access library for Node.js and TypeScript. It lets developers write real SQL in separate .sql files next to their repository classes, using decorators like @Query and @QueryBinder to bind parameters, execute queries, and shape results—without ORM complexity. Unlike Knex or Prisma, sqlstack keeps full control over SQL and supports Postgres (pg), MySQL (mysql2), and SQLite (better-sqlite3, sqlite3) via adapters. It is ESM-only, requires Node 18+, and ships TypeScript types.

database

npm install sqlstack

package ↗

INSTALL

IMPORT

SIG · SQLSTACK

sqlstack

databasejavascriptv1.0.25

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.

SqlStackDB

✓ import { SqlStackDB } from 'sqlstack/registry'

✗ import { SqlStackDB } from 'sqlstack'

SqlStackDB is exported from sqlstack/registry subpath, not from the main entry.

QueryBinder

✓ import { QueryBinder } from 'sqlstack'

✗ const QueryBinder = require('sqlstack').QueryBinder

Package is ESM-only; use import syntax. require() will fail.

Query

✓ import { Query } from 'sqlstack'

Named import from the main entry.

createPgDb

✓ import { createPgDb } from 'sqlstack/adapters'

✗ import { createPgDb } from 'sqlstack'

Adapter functions are in sqlstack/adapters subpath.

SqlStackError

✓ import { SqlStackError } from 'sqlstack'

Use this to throw in stub method bodies; it signals to the decorator that the body is placeholder.

Shows registration of a Postgres database, creation of a repository class with @QueryBinder/@Query decorators, and usage of a SQL file to query by email.

// boot.ts import { SqlStackDB } from "sqlstack/registry"; import { createPgDb } from "sqlstack/adapters"; SqlStackDB .register("primary", createPgDb(process.env.DATABASE_URL ?? "")) .setDefault("primary"); // src/users/repository.ts import { QueryBinder, Query, SqlStackError } from "sqlstack"; @QueryBinder() export class UsersRepository { @Query() async findByEmail(params: { email: string }): Promise<{ id: string; name: string }[]> { throw new SqlStackError("replaced by @Query"); } } // findByEmail.sql next to repository.ts: // SELECT id, name FROM users WHERE email = :email; // usage.ts const repo = new UsersRepository(); const users = await repo.findByEmail({ email: "alice@example.com" }); console.log(users);

Debug

Known issues

breakingPackage is ESM-only. Using require() will throw ERR_REQUIRE_ESM.

fix

Use import syntax instead of require().

affects: >=1.0.0

gotchaMethod bodies in @Query decorated methods must throw SqlStackError; they are never executed but required by TypeScript.

fix

Always throw new SqlStackError('replaced by @Query') in the stub body.

affects: >=1.0.0

gotcha.sql files must be in the same directory as the class by default. Custom paths require @QueryBinder({ dir: '...' }).

fix

Place .sql files next to your repository class, or specify a custom directory.

affects: >=1.0.0

deprecatedUsing sqlite3 adapter is deprecated; prefer better-sqlite3 for synchronous SQLite access.

fix

Install better-sqlite3 and use createBetterSqliteDb instead of createSqliteDb.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Project is not configured for ESM (e.g., no type: module in package.json or using .cjs extension).

fix

Add "type": "module" to your package.json or use .mjs extension for your files.

Error: No database found for name 'primary'

SqlStackDB.register() was not called or the database name is misspelled.

fix

Ensure you call SqlStackDB.register('primary', ...) before using the repository, and that the name matches.

TypeError: Class constructor UsersRepository cannot be invoked without 'new'

Attempting to call the class as a function instead of using new.

fix

Instantiate with new UsersRepository().

Upgrade

Version history

1.0.25latest on npm

Audit

Dependencies

pgoptionalRequired when using Postgres adapter

mysql2optionalRequired when using MySQL/MariaDB adapter

better-sqlite3optionalRequired when using SQLite adapter

sqlite3optionalAlternative SQLite adapter

Agent activity

13 hits · last 30 days

node