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​

@sqb/migrator currently only implements its migration adapter for PostgreSQL — see Running migrations.

See also​