Skip to main content

PostgreSQL

@sqb/postgres is the SQB adapter for PostgreSQL. It's built on top of PostgreJS, a pure-JavaScript PostgreSQL driver from the same Panates organization — no native build step or libpq is required.

Install​

npm install @sqb/postgres postgrejs

@sqb/connect and @sqb/builder are peer dependencies pulled in transitively if you already depend on them directly; otherwise install them alongside.

Registering the adapter​

Importing @sqb/postgres registers it as a side effect — there's nothing else to wire up:

import '@sqb/postgres';
import { SqbClient } from '@sqb/connect';

const client = new SqbClient({
  dialect: 'postgres', // or driver: 'postgrejs'
  host: 'localhost',
  database: 'mydb',
  user: 'myuser',
  password: 'mypassword',
});

Under the hood, @sqb/postgres's entry point imports @sqb/postgres-dialect (which teaches @sqb/builder PostgreSQL's SQL syntax) and registers a PgAdapter instance with AdapterRegistry:

import '@sqb/postgres-dialect';
import { AdapterRegistry } from '@sqb/connect';
import { PgAdapter } from './pg-adapter.js';

AdapterRegistry.register(new PgAdapter());

PgAdapter reports driver: 'postgrejs' and dialect: 'postgres' — either can be used to select it via ClientConfiguration.driver/.dialect.

Configuration​

host, port, user, password, database, and schema from ClientConfiguration map directly onto PostgreJS's own connection options. Anything set in driverOptions is spread onto that same PostgreJS ConnectionConfiguration object first, so it can carry any option the driver supports (e.g. TLS settings) that isn't already covered by the standard fields:

new SqbClient({
  dialect: 'postgres',
  host: 'localhost',
  database: 'mydb',
  driverOptions: {
    ssl: true,
  },
});

Feature notes​

  • Cursors: supported (features.cursor: true) — see Cursors & Streaming.
  • Schemas: supported (features.schema: true) — setSchema()/getSchema() are implemented via SET search_path — see Schemas.
  • Named parameters: SQB's :paramName placeholders are normalized to PostgreSQL's positional $1, $2, ... syntax before being sent to the driver.
  • fetchAsString: DATE, TIMESTAMP, and TIMESTAMPTZ columns can be fetched as strings instead of being parsed into Date objects, avoiding timezone-conversion surprises.

Migrator support​

Supported — see Running migrations. PgMigrationAdapter is the reference implementation the other dialect adapters mirror: it auto-creates infoSchema (CREATE SCHEMA IF NOT EXISTS, owned by the connecting role), runs a whole multi-statement script in one call, and serializes concurrent runs with a session-level pg_advisory_lock.

See also​