pqb

library0.66.6jsnpmunverified

pqb is a TypeScript-first query builder for PostgreSQL, part of the Orchid ORM ecosystem. Current stable version is 0.66.6. It focuses on providing full type safety for queries and results, with support for dynamic queries, joins, subqueries, and transactions. Compared to knex or kysely, pqb integrates tightly with Orchid ORM but can also be used standalone. The package ships its own TypeScript types and is actively maintained with weekly releases.

database

npm install pqb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PQB

pqb

databasejavascriptv0.66.6

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.

createDb

✓ import { createDb } from 'pqb'

✗ const createDb = require('pqb')

ESM-only since the package ships ESM. CommonJS require will not work.

table

✓ import { table } from 'pqb'

✗ import table from 'pqb'

table is a named export, not default.

sql

✓ import { sql } from 'pqb'

Tagged template literal for raw SQL. Type-safe since v0.50.

Connects to a PostgreSQL database, defines a 'users' table with columns, inserts a row, queries it, and uses raw SQL to get a count.

import { createDb, sql } from 'pqb'; const db = createDb({ connectionString: process.env.DATABASE_URL ?? 'postgres://user:pass@localhost:5432/mydb', }); // Create a table helper const users = db('users', (t) => ({ id: t.serial().primaryKey(), name: t.text(), email: t.text().unique(), })); // Insert and select async function main() { await users.insert({ name: 'Alice', email: 'alice@example.com' }); const result = await users.select('id', 'name').where({ email: 'alice@example.com' }); console.log(result); // [{ id: 1, name: 'Alice' }] // Raw SQL const count = await db.get(sql<{ count: number }>`SELECT count(*) as count FROM users`); console.log(count); // { count: 1 } await db.close(); } main().catch(console.error);

Debug

Known issues

breakingIn version 0.50, the `createDb` API changed to accept an options object instead of separate arguments. Old code using `createDb(connectionString)` will break.

fix

Update to `createDb({ connectionString: '...' })`.

affects: <0.50

breakingThe `table` helper no longer returns a query builder directly since v0.60; now returns a table definition object. Use `db('users', ...)` instead.

fix

Wrap table definitions with `db(tableName, columns)`.

affects: >=0.60 <0.66

deprecatedThe `raw` method is deprecated; use `sql` tagged template literal instead.

fix

Replace `raw('SELECT * FROM users')` with `sql<...>'SELECT * FROM users'`.

affects: >=0.55

gotchaWhen using TypeScript strict mode, you must explicitly type the shape of raw SQL results using `sql<{ col: type }>`. Omitting the generic may result in `any` or type errors.

fix

Always provide a type parameter to `sql` when used for queries: `sql<{ count: number }>`SHOW count(*) FROM users`.

affects: >=0.50

breakingIn v0.55, the `insert` method changed to return the inserted rows array; previously it returned the row count.

fix

Update code expecting a number to handle an array of rows.

affects: <0.55

gotchaPeer dependencies `pg` or `postgres` are required but not automatically installed. Running without either will cause runtime errors.

fix

Install one: `npm install pg` or `npm install postgres`.

affects: all

Errors

Common errors & fixes

Cannot find module 'pg'

Missing peer dependency `pg` not installed.

fix

Run `npm install pg` to install the PostgreSQL client.

TypeError: createDb is not a function

Using CommonJS require with ESM-only package. Since v0.50 pqb is ESM-only.

fix

Switch to import syntax: `import { createDb } from 'pqb'`. If you must use CommonJS, upgrade to Node 22+ with `--experimental-require-module`.

Property 'id' does not exist on type 'Promise<unknown>'

Trying to access properties on a promise without awaiting.

fix

Await the query: `const result = await users.find(1);` then access `result.id`.

TS2339: Property 'select' does not exist on type '{ id: ... }'

Using table definition object directly instead of calling `db('users', ...)` which returns the query builder.

fix

Define table via `const users = db('users', ...);` then use `users.select(...)`.

Upgrade

Version history

0.66.6latest on npm

Audit

Dependencies

pgoptionalRequired at runtime to connect to PostgreSQL (peer dependency). Optional if using 'postgres' client instead.

postgresoptionalAlternative PostgreSQL client (peer dependency). Optional if using 'pg' client instead.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/romeerez/orchid-orm ↗

packagepqb ↗

homepagehttps://orchid-orm.netlify.app/guide/orm-and-query-builder.html ↗