ts-pg-orm

library5.1.7jsnpmunverified

ts-pg-orm is a TypeScript-first PostgreSQL ORM that provides fully type-enforced queries for CRUD operations, relations, and custom SQL. Current stable version is 5.1.7, released with moderate cadence. It differentiates by offering zero guess-work TypeScript inference, recursive relation queries, and automatic store provisioning. Built entirely in TypeScript with no runtime peer dependencies, it supports ESM and CJS. The library is actively maintained with CI/CD and coverage reporting.

database

npm install ts-pg-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TS-PG-ORM

ts-pg-orm

databasejavascriptv5.1.7

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.

createTsPgOrm

✓ import { createTsPgOrm } from 'ts-pg-orm'

✗ import createTsPgOrm from 'ts-pg-orm'

Named export only, no default export.

createDataFormat

✓ import { createDataFormat } from 'ts-pg-orm'

✗ const createDataFormat = require('ts-pg-orm').createDataFormat

CJS require may work but ESM import is recommended for tree-shaking.

ToRecord

✓ import { ToRecord } from 'ts-pg-orm'

✗ import { ToRecord } from 'ts-pg-orm/types'

Type exports are included in main module, no separate types package needed.

Operator

✓ import { Operator } from 'ts-pg-orm'

Enum exported as named export.

Shows setup, connection, provisioning, and a simple create operation with ts-pg-orm.

import { createDataFormat, createTsPgOrm, Operator } from 'ts-pg-orm' const userDF = createDataFormat('users', { columns: { id: { type: 'serial', primaryKey: true }, name: { type: 'varchar(255)', nullable: false }, email: { type: 'varchar(255)', nullable: false, unique: true } }, store: { name: 'user' } }) const ORM = createTsPgOrm([userDF] as const) async function main() { const orm = await ORM.connect({ host: process.env.PGHOST ?? 'localhost', port: parseInt(process.env.PGPORT ?? '5432'), database: process.env.PGDATABASE ?? 'test', user: process.env.PGUSER ?? 'postgres', password: process.env.PGPASSWORD ?? '' }) await orm.provisionStores() const created = await orm.stores.user.create({ name: 'Alice', email: 'alice@example.com' }) console.log('Created:', created) await orm.disconnect() } main().catch(console.error)

Debug

Known issues

breakingIn version 5.0.0, the `connect` function signature changed to accept an object with `host`, `port`, `database`, `user`, `password` instead of individual string arguments.

fix

Update connection calls to use an options object: `ORM.connect({ host, port, database, user, password })`.

affects: <5.0.0

breakingThe `provisionStores` method was added in 5.0.0 and is required after connection before performing CRUD. Previous versions automatically created stores.

fix

Add `await orm.provisionStores()` after `ORM.connect()`.

affects: <5.0.0

deprecatedThe `Operator` enum values like `EQUALS` are being deprecated in favor of string literals in future versions. Use `'='` directly instead of `Operator.EQUALS`.

fix

Replace `Operator.EQUALS` with `'='`, `Operator.NOT_EQUALS` with `'!='`, etc.

affects: >=5.0.0

gotchaWhen using relations, you must wrap the query object in an array literal with `as const` to preserve type inference.

fix

Use `[userDF] as const` when calling `createTsPgOrm` and define relations using `as const`.

affects: >=4.0.0

gotchaThe `createDataFormat` function requires `store.name` to be singular; it will be automatically pluralized for the table name.

fix

Set `store: { name: 'user' }` to create a table named `users`.

affects: >=4.0.0

Errors

Common errors & fixes

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

Missing `store.name` in data format definition.

fix

Ensure every `createDataFormat` call includes `store: { name: 'yourName' }`.

Error: No connection pool. Call ORM.connect() first.

Performing CRUD without calling `orm.connect()`.

fix

Add `await ORM.connect({...})` before accessing `orm.stores`.

TypeError: ORM.provisionStores is not a function

Using version <5.0.0 where `provisionStores` did not exist.

fix

Upgrade to v5 and add `await orm.provisionStores()` after connect.

Argument of type 'string' is not assignable to parameter of type 'never'

Data format array not properly typed with `as const`.

fix

Use `createTsPgOrm([userDF] as const)` to infer exact literal types.

Upgrade

Version history

5.1.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node