{"id":43693,"library":"pqb","title":"pqb","description":"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.","status":"active","version":"0.66.6","language":"javascript","source_language":"en","source_url":"https://github.com/romeerez/orchid-orm","tags":["javascript","pg","postgres","query-builder","typescript"],"install":[{"cmd":"npm install pqb","lang":"bash","label":"npm"},{"cmd":"yarn add pqb","lang":"bash","label":"yarn"},{"cmd":"pnpm add pqb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required at runtime to connect to PostgreSQL (peer dependency). Optional if using 'postgres' client instead.","package":"pg","optional":true},{"reason":"Alternative PostgreSQL client (peer dependency). Optional if using 'pg' client instead.","package":"postgres","optional":true}],"imports":[{"note":"ESM-only since the package ships ESM. CommonJS require will not work.","wrong":"const createDb = require('pqb')","symbol":"createDb","correct":"import { createDb } from 'pqb'"},{"note":"table is a named export, not default.","wrong":"import table from 'pqb'","symbol":"table","correct":"import { table } from 'pqb'"},{"note":"Tagged template literal for raw SQL. Type-safe since v0.50.","wrong":null,"symbol":"sql","correct":"import { sql } from 'pqb'"}],"quickstart":{"code":"import { createDb, sql } from 'pqb';\n\nconst db = createDb({\n  connectionString: process.env.DATABASE_URL ?? 'postgres://user:pass@localhost:5432/mydb',\n});\n\n// Create a table helper\nconst users = db('users', (t) => ({\n  id: t.serial().primaryKey(),\n  name: t.text(),\n  email: t.text().unique(),\n}));\n\n// Insert and select\nasync function main() {\n  await users.insert({ name: 'Alice', email: 'alice@example.com' });\n  const result = await users.select('id', 'name').where({ email: 'alice@example.com' });\n  console.log(result); // [{ id: 1, name: 'Alice' }]\n  \n  // Raw SQL\n  const count = await db.get(sql<{ count: number }>`SELECT count(*) as count FROM users`);\n  console.log(count); // { count: 1 }\n  \n  await db.close();\n}\nmain().catch(console.error);","lang":"typescript","description":"Connects to a PostgreSQL database, defines a 'users' table with columns, inserts a row, queries it, and uses raw SQL to get a count."},"warnings":[{"fix":"Update to `createDb({ connectionString: '...' })`.","message":"In version 0.50, the `createDb` API changed to accept an options object instead of separate arguments. Old code using `createDb(connectionString)` will break.","severity":"breaking","affected_versions":"<0.50"},{"fix":"Wrap table definitions with `db(tableName, columns)`.","message":"The `table` helper no longer returns a query builder directly since v0.60; now returns a table definition object. Use `db('users', ...)` instead.","severity":"breaking","affected_versions":">=0.60 <0.66"},{"fix":"Replace `raw('SELECT * FROM users')` with `sql<...>'SELECT * FROM users'`.","message":"The `raw` method is deprecated; use `sql` tagged template literal instead.","severity":"deprecated","affected_versions":">=0.55"},{"fix":"Always provide a type parameter to `sql` when used for queries: `sql<{ count: number }>`SHOW count(*) FROM users`.","message":"When 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.","severity":"gotcha","affected_versions":">=0.50"},{"fix":"Update code expecting a number to handle an array of rows.","message":"In v0.55, the `insert` method changed to return the inserted rows array; previously it returned the row count.","severity":"breaking","affected_versions":"<0.55"},{"fix":"Install one: `npm install pg` or `npm install postgres`.","message":"Peer dependencies `pg` or `postgres` are required but not automatically installed. Running without either will cause runtime errors.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'0.66.6':22 'activ':69 'also':56 'builder':9,79 'compar':43 'current':18 'dynam':37 'ecosystem':17 'first':7 'focus':24 'full':27 'integr':49 'javascript':74 'join':39 'knex':45 'kyse':47 'maintain':70 'orchid':15,52 'orm':16,53 'packag':61 'part':12 'pg':75 'postgr':76 'postgresql':11 'pqb':1,2,48 'provid':26 'queri':8,31,38,78 'query-build':77 'releas':73 'result':33 'safeti':29 'ship':62 'stabl':19 'standalon':59 'subqueri':40 'support':35 'tight':50 'transact':42 'type':28,66 'typescript':6,65,80 'typescript-first':5 'use':58 'version':20 'week':72","created_at":"2026-06-05T17:01:01.532637+00:00","updated_at":"2026-06-05T17:01:01.532637+00:00","problems":[{"fix":"Run `npm install pg` to install the PostgreSQL client.","cause":"Missing peer dependency `pg` not installed.","error":"Cannot find module 'pg'"},{"fix":"Switch to import syntax: `import { createDb } from 'pqb'`. If you must use CommonJS, upgrade to Node 22+ with `--experimental-require-module`.","cause":"Using CommonJS require with ESM-only package. Since v0.50 pqb is ESM-only.","error":"TypeError: createDb is not a function"},{"fix":"Await the query: `const result = await users.find(1);` then access `result.id`.","cause":"Trying to access properties on a promise without awaiting.","error":"Property 'id' does not exist on type 'Promise<unknown>'"},{"fix":"Define table via `const users = db('users', ...);` then use `users.select(...)`.","cause":"Using table definition object directly instead of calling `db('users', ...)` which returns the query builder.","error":"TS2339: Property 'select' does not exist on type '{ id: ... }'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://orchid-orm.netlify.app/guide/orm-and-query-builder.html","github":"https://github.com/romeerez/orchid-orm","docs":null,"changelog":null,"pypi":null,"npm":"pqb","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}