ts-sql-query

library1.67.0jsnpmunverified

ts-sql-query is a type-safe SQL query builder for TypeScript, inspired by Java's QueryDSL and JOOQ, supporting MariaDB, MySQL, Oracle, PostgreSQL, SQLite, and SQL Server. Current stable version is 1.67.0, with regular releases following minor updates. It emphasizes compile-time type checking for SQL queries, dynamic query construction, and avoids ORM patterns, making it suitable for projects requiring full SQL control without string concatenation. Unlike Knex or TypeORM, it provides first-class TypeScript support with inferred result types and no runtime schema generation.

database

npm install ts-sql-query

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TS-SQL-QUERY

ts-sql-query

databasejavascriptv1.67.0

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.

Connection

✓ import { Connection } from 'ts-sql-query/Connection'

✗ import { Connection } from 'ts-sql-query'

ts-sql-query does not expose a global export; you must import from specific subpaths like 'ts-sql-query/Connection'.

Table

✓ import { Table } from 'ts-sql-query/Table'

✗ import { Table } from 'ts-sql-query/Table' (only correct)

Table is used to define database tables; import from 'ts-sql-query/Table'.

PostgreSqlConnection

✓ import { PostgreSqlConnection } from 'ts-sql-query/connections/PostgreSqlConnection'

✗ import { PostgreSqlConnection } from 'ts-sql-query'

Database-specific connections are in 'ts-sql-query/connections/' subpaths.

ConsumerQueryRunner

✓ import { ConsumerQueryRunner } from 'ts-sql-query/queryRunners/ConsumerQueryRunner'

✗ import { ConsumerQueryRunner } from 'ts-sql-query'

Query runners are in 'ts-sql-query/queryRunners/' subpaths.

Defines a customer table, creates a connection to PostgreSQL, and runs a type-safe select query with one result.

import { Table } from 'ts-sql-query/Table'; import { PostgreSqlConnection } from 'ts-sql-query/connections/PostgreSqlConnection'; import { ConsumerQueryRunner } from 'ts-sql-query/queryRunners/ConsumerQueryRunner'; class TCustomer extends Table { id = this.autogeneratedPrimaryKey('id', 'int'); firstName = this.column('first_name', 'string'); lastName = this.column('last_name', 'string'); birthday = this.optionalColumn('birthday', 'date'); constructor() { super('customer'); } } const tCustomer = new TCustomer(); async function example() { const connection = new PostgreSqlConnection(new ConsumerQueryRunner(async (query, params) => { console.log('SQL:', query, 'Params:', params); return { rows: [], affectedRows: 0 }; })); const customerId = 10; const customerWithId = await connection.selectFrom(tCustomer) .where(tCustomer.id.equals(customerId)) .select({ id: tCustomer.id, firstName: tCustomer.firstName, lastName: tCustomer.lastName, birthday: tCustomer.birthday }) .executeSelectOne(); console.log(customerWithId); } example().catch(console.error);

Debug

Known issues

breakingIn version 1.50.0, the import path for connections changed from 'ts-sql-query/Connection' to 'ts-sql-query/connections/<Database>Connection'.

fix

Update imports to use the new subpath, e.g., 'ts-sql-query/connections/PostgreSqlConnection'.

affects: <1.50.0

deprecatedUsing 'ts-sql-query/Connection' directly is deprecated in favor of 'ts-sql-query/connections/*'.

fix

Switch to importing from 'ts-sql-query/connections/<Database>Connection'.

affects: >=1.50.0

gotchaTable classes must extend the `Table` class and call `super(tableName)` with the actual database table name. Not doing so causes runtime errors.

fix

Ensure your table class extends `Table` and correctly passes the table name to `super()`.

affects: >=0.1.0

breakingIn version 1.60.0, the method `executeSelectOne` changed to throw an error if no row is found; previously it returned `undefined`.

fix

Use `executeSelectNoneOrOne()` if you expect no row, or catch the error.

affects: <1.60.0

gotchaImporting from 'ts-sql-query' (the root) does not export anything; you must use explicit subpaths. This is intentional to avoid naming conflicts.

fix

Always import from specific subpaths like 'ts-sql-query/Table', 'ts-sql-query/Connection', etc.

affects: >=0.1.0

Errors

Common errors & fixes

Cannot find module 'ts-sql-query' or its corresponding type declarations.

Importing from the root 'ts-sql-query' instead of a specific subpath like 'ts-sql-query/Table'.

fix

Change import to a specific subpath, e.g., import { Table } from 'ts-sql-query/Table'.

Property 'id' does not exist on type 'TCustomer'.

Table class not properly extending `Table` or not calling `super(tableName)`.

fix

Ensure the class extends `Table` and calls `super('table_name')`.

TypeError: Cannot read properties of undefined (reading 'selectFrom')

The connection object is not properly instantiated or the query runner is misconfigured.

fix

Check the query runner implementation; ensure it returns an object with `rows` and `affectedRows`.

No overload matches this call. Overload 1 of 2, '(query: string, params: any[]): Promise<...>', gave the following error.

Using a query runner that does not match the expected signature, e.g., passing wrong types.

fix

Check the query runner interface; it should be `(query: string, params: any[]) => Promise<{ rows: any[], affectedRows: number }>`.

Upgrade

Version history

1.67.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

OpenAI (training)