@lenne.tech/nest-server 12.0.0 → 12.1.0

package/src/core/common/persistence/sql/sql-dialect.ts

@@ -0,0 +1,85 @@
+import type { LockStore } from '../lock-store.interface.js';
+import type { ModelDescriptor } from '../model-descriptor.interface.js';
+import { MysqlDataStore } from './mysql/mysql-data-store.js';
+import type { MysqlExecutor } from './mysql/mysql-executor.js';
+import { MysqlLockStore } from './mysql/mysql-lock-store.js';
+import {
+  applyMysqlSchema,
+  assertSafeMysqlApplicationAccount,
+  type MysqlSchemaOptions,
+  mysqlAccount,
+  verifyMysqlSchema,
+} from './mysql/mysql-schema.migrator.js';
+import type { MysqlVariant } from './mysql/mysql-session.js';
+import { PostgresLockStore } from './postgres/postgres-lock-store.js';
+import type { PostgresSchemaOptions } from './postgres/postgres-schema.compiler.js';
+import {
+  applyPostgresSchema,
+  assertSafeApplicationRole,
+  verifyPostgresSchema,
+} from './postgres/postgres-schema.migrator.js';
+import { SqlDataStore, type SqlDataStoreOptions } from './sql-data-store.js';
+import type { SqlExecutor } from './sql-executor.interface.js';
+import type { SchemaChange } from './sql-schema.shared.js';
+
+/**
+ * What differs between the SQL databases at the level of a data source: how its schema is brought up to date, which
+ * application role it accepts, and which store and lease implementation serve it. The runtime asks the dialect and
+ * never the driver name.
+ */
+export interface SqlDialect {
+  /** Shown in boot logs: `PostgreSQL`, `MySQL`, `MariaDB` */
+  readonly label: string;
+  /** Apply every automatic change as the OWNER (one locked run); refuses when a migration is needed */
+  applySchema(owner: SqlExecutor, app: SqlExecutor, models: ModelDescriptor[]): Promise<SchemaChange[]>;
+  /** Refuse an application role the database's protections cannot bind */
+  assertSafeApplication(app: SqlExecutor, tables: string[]): Promise<void>;
+  createLockStore(app: SqlExecutor): LockStore;
+  createStore(app: SqlExecutor, model: ModelDescriptor, options: SqlDataStoreOptions): SqlDataStore<any>;
+  /** How a tenant-isolated model's rows are protected, for the boot log */
+  isolation(isolated: boolean): string;
+  /** Without an owner connection: only check, and refuse to start on any pending change */
+  verifySchema(app: SqlExecutor, models: ModelDescriptor[]): Promise<SchemaChange[]>;
+}
+
+export interface SqlDialectContext {
+  /** The application role as the connection URL names it */
+  appRole: string;
+  driver: 'mariadb' | 'mysql' | 'postgres';
+  isTenantIsolated: (model: ModelDescriptor) => boolean;
+}
+
+export function sqlDialect(context: SqlDialectContext): SqlDialect {
+  return context.driver === 'postgres' ? postgresDialect(context) : mysqlDialect(context.driver);
+}
+
+function postgresDialect(context: SqlDialectContext): SqlDialect {
+  const options: PostgresSchemaOptions = { appRole: context.appRole, isTenantIsolated: context.isTenantIsolated };
+  return {
+    applySchema: (owner, _app, models) => applyPostgresSchema(owner, models, options),
+    assertSafeApplication: (app, tables) => assertSafeApplicationRole(app, tables),
+    createLockStore: (app) => new PostgresLockStore(app),
+    createStore: (app, model, storeOptions) => new SqlDataStore<any>(app, model, storeOptions),
+    isolation: (isolated) => (isolated ? ' (row-level security)' : ''),
+    label: 'PostgreSQL',
+    verifySchema: (app, models) => verifyPostgresSchema(app, models, options),
+  };
+}
+
+function mysqlDialect(variant: MysqlVariant): SqlDialect {
+  let account: Promise<string> | undefined;
+  // The account as the server matched it (`'user'@'host'`) — the name a grant needs, not the URL's user alone
+  const options = async (app: SqlExecutor): Promise<MysqlSchemaOptions> => {
+    account ??= mysqlAccount(app);
+    return { appAccount: await account, variant };
+  };
+  return {
+    applySchema: async (owner, app, models) => applyMysqlSchema(owner, models, await options(app)),
+    assertSafeApplication: (app) => assertSafeMysqlApplicationAccount(app, variant),
+    createLockStore: (app) => new MysqlLockStore(app),
+    createStore: (app, model, storeOptions) => new MysqlDataStore<any>(app as MysqlExecutor, model, storeOptions),
+    isolation: (isolated) => (isolated ? ' (tenant isolation in the application only)' : ''),
+    label: variant === 'mysql' ? 'MySQL' : 'MariaDB',
+    verifySchema: async (app, models) => verifyMysqlSchema(app, models, await options(app)),
+  };
+}

package/src/core/common/persistence/sql/sql-errors.ts

@@ -0,0 +1,49 @@
+import { BadRequestException } from '@nestjs/common';
+
+/**
+ * Errors of the SQL persistence layer.
+ *
+ * Neither message carries the offending VALUE: a filter value can be anything a request sent, including a
+ * credential, and these messages travel into logs.
+ */
+
+/**
+ * A filter, sort or update the SQL store cannot express. Thrown instead of dropping a condition (plan §3.2) —
+ * a condition that silently disappears widens a query, which on a tenant- or owner-scoped read is a data leak.
+ */
+export class UnsupportedQueryError extends Error {
+  override readonly name = 'UnsupportedQueryError';
+}
+
+/**
+ * A filter value that cannot be cast to its field's type — the SQL counterpart of Mongoose's `CastError`, with the
+ * same casting rules, so a value MongoDB refuses is refused on SQL too.
+ */
+export class QueryCastError extends Error {
+  override readonly name = 'QueryCastError';
+
+  /** The value that failed — not enumerable, so it never reaches a serialized error or a log line by accident */
+  declare readonly value: unknown;
+
+  constructor(
+    readonly path: string,
+    readonly kind: string,
+    value?: unknown,
+  ) {
+    super(`Cast to ${kind} failed at path "${path}"`);
+    Object.defineProperty(this, 'value', { enumerable: false, value });
+  }
+}
+
+/**
+ * A unique constraint refused a write — answered with 400. Carries MongoDB's duplicate-key code and message prefix,
+ * because callers in the framework and in projects recognise a duplicate by `error.code === 11000` or by `E11000`.
+ */
+export class DuplicateKeyError extends BadRequestException {
+  override readonly name = 'DuplicateKeyError';
+  readonly code = 11000;
+
+  constructor(readonly model: string) {
+    super(`E11000 duplicate key error: a unique value of ${model} already exists`);
+  }
+}

package/src/core/common/persistence/sql/sql-executor.factory.ts

@@ -0,0 +1,282 @@
+import type { DatabaseSqlEngine } from '../../interfaces/server-options.interface.js';
+import type {
+  SqlExecutor,
+  SqlQueryResult,
+  SqlStatement,
+  SqlTenantScope,
+  SqlTransaction,
+} from './sql-executor.interface.js';
+import { createMysqlExecutor } from './mysql/mysql-executor.js';
+import { APPLY_SCOPE_SQL, guardPool, runInOwnTransaction, scopeParams } from './sql-session.js';
+
+/**
+ * The SQL engine adapters (plan §3.10). The per-operation path is identical for every engine — node-postgres,
+ * pipelined, on a guarded pool — so switching the engine cannot change what a store operation does. Engines
+ * differ only in how they run a multi-statement transaction and in the native API they hand to projects.
+ *
+ * Every engine is an OPTIONAL peer dependency and loaded on first use (`import()` with a literal specifier: these
+ * are dual packages, so they are loaded lazily everywhere — see `.claude/rules/architecture.md`).
+ */
+
+export interface SqlExecutorOptions {
+  /** Shown as `application_name` in `pg_stat_activity`. */
+  applicationName?: string;
+  engine: DatabaseSqlEngine;
+  /** Pool size. @default 10 */
+  maxConnections?: number;
+  /** Client-side statement timeout in milliseconds (node-postgres `query_timeout`). @default none */
+  queryTimeoutMs?: number;
+  /** Connection URL of the APPLICATION role */
+  url: string;
+}
+
+export async function createSqlExecutor(options: SqlExecutorOptions): Promise<SqlExecutor> {
+  // The URL's scheme picks the dialect: MySQL and MariaDB have adapters of their own (phase 6)
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(options.url)?.[1]?.toLowerCase();
+  if (scheme === 'mysql' || scheme === 'mariadb') {
+    return createMysqlExecutor({
+      engine: options.engine,
+      maxConnections: options.maxConnections,
+      url: options.url,
+      variant: scheme,
+    });
+  }
+  switch (options.engine) {
+    case 'drizzle':
+      return createDrizzleExecutor(options);
+    case 'kysely':
+      return createKyselyExecutor(options);
+    case 'typeorm':
+      return createTypeOrmExecutor(options);
+    default:
+      throw new Error(`Unknown SQL engine "${String(options.engine)}"`);
+  }
+}
+
+/**
+ * The first SQL engine the project has installed, in the framework's order (`typeorm`, `kysely`, `drizzle`) — for a
+ * caller that runs outside the application and has no `database.sqlEngine` to read, such as the migrate CLI. A project
+ * installs only the engine it chose, so assuming the default there would fail every call of a project on another one.
+ */
+export async function installedSqlEngine(): Promise<DatabaseSqlEngine> {
+  const candidates: [DatabaseSqlEngine, () => Promise<unknown>][] = [
+    ['typeorm', () => import('typeorm')],
+    ['kysely', () => import('kysely')],
+    ['drizzle', () => import('drizzle-orm')],
+  ];
+  for (const [engine, load] of candidates) {
+    try {
+      await load();
+      return engine;
+    } catch {
+      // Not installed — try the next one
+    }
+  }
+  throw new Error(
+    'A SQL connection needs one of the optional SQL engines, none is installed. Run: pnpm add typeorm pg ' +
+      '(PostgreSQL) or pnpm add typeorm mysql2 (MySQL / MariaDB)',
+  );
+}
+
+function missingPeer(name: string): Error {
+  return new Error(
+    `A SQL data source is configured but the optional peer dependency "${name}" is not installed. Run: pnpm add ${name}`,
+  );
+}
+
+/** Pool options shared by every engine: pipelining for the per-operation path, the guard against poisoned clients. */
+function poolOptions(options: SqlExecutorOptions): Record<string, unknown> {
+  return {
+    max: options.maxConnections ?? 10,
+    pipeline: true,
+    ...(options.applicationName ? { application_name: options.applicationName } : {}),
+    ...(options.queryTimeoutMs ? { query_timeout: options.queryTimeoutMs } : {}),
+  };
+}
+
+/**
+ * The node-postgres error behind an engine's wrapper (TypeORM `QueryFailedError.driverError`, Drizzle
+ * `DrizzleQueryError.cause`), so every engine fails with the same error and SQLSTATE as the per-operation path. It
+ * also keeps the statement's parameters out of the message: Drizzle's wrapper prints them.
+ */
+function driverErrorOf(error: unknown): unknown {
+  const wrapped = (error as { cause?: unknown; driverError?: unknown } | undefined) ?? {};
+  for (const inner of [wrapped.driverError, wrapped.cause]) {
+    if (inner instanceof Error && typeof (inner as { code?: unknown }).code === 'string') {
+      return inner;
+    }
+  }
+  return error;
+}
+
+/** Run `step`, rethrowing an engine's wrapped error as the driver error underneath. */
+async function unwrapped<T>(step: () => Promise<T>): Promise<T> {
+  try {
+    return await step();
+  } catch (error) {
+    throw driverErrorOf(error);
+  }
+}
+
+async function createPgPool(options: SqlExecutorOptions): Promise<any> {
+  let pg: any;
+  try {
+    pg = await import('pg');
+  } catch {
+    throw missingPeer('pg');
+  }
+  const Pool = pg.Pool ?? pg.default?.Pool;
+  return guardPool(new Pool({ connectionString: options.url, ...poolOptions(options) }));
+}
+
+function resultOf<R>(rows: R[] | undefined, rowCount: null | number | undefined): SqlQueryResult<R> {
+  const list = rows ?? [];
+  return { rowCount: typeof rowCount === 'number' ? rowCount : list.length, rows: list };
+}
+
+// ---------------------------------------------------------------------------------------------
+// TypeORM (default)
+// ---------------------------------------------------------------------------------------------
+
+async function createTypeOrmExecutor(options: SqlExecutorOptions): Promise<SqlExecutor> {
+  let typeorm: any;
+  try {
+    typeorm = await import('typeorm');
+  } catch {
+    throw missingPeer('typeorm');
+  }
+  const DataSource = typeorm.DataSource ?? typeorm.default?.DataSource;
+  // The framework owns the schema (plan §3.12): TypeORM never synchronizes or runs migrations of its own.
+  const dataSource = new DataSource({
+    entities: [],
+    extra: poolOptions(options),
+    migrationsRun: false,
+    synchronize: false,
+    type: 'postgres',
+    url: options.url,
+  });
+  await dataSource.initialize();
+  const pool = guardPool(dataSource.driver.master);
+
+  return {
+    close: () => dataSource.destroy(),
+    driverPool: pool,
+    engine: 'typeorm',
+    native: <N>() => dataSource as N,
+    run: <R>(statement: SqlStatement, scope: SqlTenantScope) => runInOwnTransaction<R>(pool, statement, scope),
+    transaction: async <T>(fn: (tx: SqlTransaction) => Promise<T>): Promise<T> => {
+      const runner = dataSource.createQueryRunner();
+      await runner.connect();
+      await runner.startTransaction();
+      try {
+        const value = await fn({
+          native: <N>() => runner.manager as N,
+          run: <R>(statement: SqlStatement, scope: SqlTenantScope) =>
+            unwrapped(async () => {
+              await runner.query(APPLY_SCOPE_SQL, scopeParams(scope));
+              const result = await runner.query(statement.text, [...statement.params], true);
+              return resultOf<R>(result.records, result.affected);
+            }),
+        });
+        await unwrapped(() => runner.commitTransaction());
+        return value;
+      } catch (error) {
+        if (runner.isTransactionActive) {
+          await runner.rollbackTransaction().catch(() => undefined);
+        }
+        throw error;
+      } finally {
+        await runner.release();
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Kysely
+// ---------------------------------------------------------------------------------------------
+
+async function createKyselyExecutor(options: SqlExecutorOptions): Promise<SqlExecutor> {
+  let kysely: any;
+  try {
+    kysely = await import('kysely');
+  } catch {
+    throw missingPeer('kysely');
+  }
+  const { CompiledQuery, Kysely, PostgresDialect } = kysely;
+  const pool = await createPgPool(options);
+  const db = new Kysely({ dialect: new PostgresDialect({ pool }) });
+
+  return {
+    close: () => db.destroy(),
+    driverPool: pool,
+    engine: 'kysely',
+    native: <N>() => db as N,
+    run: <R>(statement: SqlStatement, scope: SqlTenantScope) => runInOwnTransaction<R>(pool, statement, scope),
+    transaction: <T>(fn: (tx: SqlTransaction) => Promise<T>): Promise<T> =>
+      db.transaction().execute((trx: any) =>
+        fn({
+          native: <N>() => trx as N,
+          run: async <R>(statement: SqlStatement, scope: SqlTenantScope) => {
+            await trx.executeQuery(CompiledQuery.raw(APPLY_SCOPE_SQL, scopeParams(scope)));
+            const result = await trx.executeQuery(CompiledQuery.raw(statement.text, [...statement.params]));
+            const affected = result.numAffectedRows === undefined ? undefined : Number(result.numAffectedRows);
+            return resultOf<R>(result.rows, affected);
+          },
+        }),
+      ),
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Drizzle
+// ---------------------------------------------------------------------------------------------
+
+async function createDrizzleExecutor(options: SqlExecutorOptions): Promise<SqlExecutor> {
+  let drizzleOrm: any;
+  let drizzlePg: any;
+  try {
+    drizzleOrm = await import('drizzle-orm');
+    drizzlePg = await import('drizzle-orm/node-postgres');
+  } catch {
+    throw missingPeer('drizzle-orm');
+  }
+  const { sql } = drizzleOrm;
+  const pool = await createPgPool(options);
+  const db = drizzlePg.drizzle({ client: pool });
+
+  // Positional statement → Drizzle SQL with the values bound as parameters again. Only `$<digits>` placeholders
+  // are split, and the framework's compilers never emit one inside a literal. `sql.param()`, not `sql\`${value}\``:
+  // the template expands an array into a list of parameters, which turns a `text[]` into a row.
+  const toSql = (text: string, params: readonly unknown[]) =>
+    sql.join(
+      text.split(/\$(\d+)/).map((part, index) => (index % 2 ? sql.param(params[Number(part) - 1]) : sql.raw(part))),
+      sql.raw(''),
+    );
+
+  return {
+    close: () => pool.end(),
+    driverPool: pool,
+    engine: 'drizzle',
+    native: <N>() => db as N,
+    run: <R>(statement: SqlStatement, scope: SqlTenantScope) => runInOwnTransaction<R>(pool, statement, scope),
+    // Drizzle runs the COMMIT inside `db.transaction()`; only that statement's wrapper is unwrapped here, an error
+    // `fn` raised through Drizzle's own API stays Drizzle's.
+    transaction: <T>(fn: (tx: SqlTransaction) => Promise<T>): Promise<T> =>
+      db
+        .transaction((tx: any) =>
+          fn({
+            native: <N>() => tx as N,
+            run: <R>(statement: SqlStatement, scope: SqlTenantScope) =>
+              unwrapped(async () => {
+                await tx.execute(toSql(APPLY_SCOPE_SQL, scopeParams(scope)));
+                const result = await tx.execute(toSql(statement.text, statement.params));
+                return resultOf<R>(result.rows, result.rowCount);
+              }),
+          }),
+        )
+        .catch((error: unknown) => {
+          throw (error as { query?: unknown })?.query === 'commit' ? driverErrorOf(error) : error;
+        }),
+  };
+}

package/src/core/common/persistence/sql/sql-executor.interface.ts

@@ -0,0 +1,57 @@
+/**
+ * The SQL executor port: what the framework needs from a SQL engine (plan §3.10).
+ *
+ * The framework compiles every statement, policy and schema change itself; an engine only executes and
+ * offers its own API for native access. Import-free on purpose (types only).
+ */
+import type { DatabaseSqlEngine } from '../../interfaces/server-options.interface.js';
+
+/**
+ * The tenant scope of ONE statement, written into the transaction with `set_config(…, true)` and read by the
+ * RLS guard function (plan §3.4, §3.8).
+ *
+ * - `system`: no tenant filter (system work, `runWithBypassTenantGuard()`, or a platform admin without tenant)
+ * - `tenant`: exactly `tenantId`
+ * - `tenants`: any of `tenantIds` (header-less read of a member)
+ * - `none`: no valid tenant context — the guard function refuses every tenant-scoped row (42501)
+ */
+export type SqlTenantScope =
+  | { kind: 'none' }
+  | { kind: 'system' }
+  | { kind: 'tenant'; tenantId: string }
+  | { kind: 'tenants'; tenantIds: readonly string[] };
+
+export interface SqlQueryResult<R = Record<string, any>> {
+  rowCount: number;
+  rows: R[];
+}
+
+/** A statement and its positional parameters (`$1`, `$2`, …). */
+export interface SqlStatement {
+  params: readonly unknown[];
+  text: string;
+}
+
+/** Statements inside one transaction, on one connection. */
+export interface SqlTransaction {
+  /** The engine's own API, bound to this transaction's connection. */
+  native<N = unknown>(): N;
+  /** Run a statement after applying `scope` to the transaction. */
+  run<R = Record<string, any>>(statement: SqlStatement, scope: SqlTenantScope): Promise<SqlQueryResult<R>>;
+}
+
+export interface SqlExecutor {
+  close(): Promise<void>;
+  /** The node-postgres pool the executor runs on — for Better-Auth's own adapter. */
+  readonly driverPool: unknown;
+  readonly engine: DatabaseSqlEngine;
+  /** The engine's own API, outside any framework transaction. */
+  native<N = unknown>(): N;
+  /**
+   * Run ONE statement in its own transaction with `scope` applied — `BEGIN`, `set_config`, statement, `COMMIT`
+   * pipelined into a single round trip (plan §3.8, A13).
+   */
+  run<R = Record<string, any>>(statement: SqlStatement, scope: SqlTenantScope): Promise<SqlQueryResult<R>>;
+  /** Several statements in one transaction, on one connection; rolled back when `fn` throws. */
+  transaction<T>(fn: (tx: SqlTransaction) => Promise<T>): Promise<T>;
+}

package/src/core/common/persistence/sql/sql-naming.ts

@@ -0,0 +1,133 @@
+import { UnsupportedQueryError } from './sql-errors.js';
+
+/**
+ * Identifier rules shared by the query compiler and the schema compiler: one mapping from a model's field name to
+ * its column, and one place that decides what may become an identifier at all.
+ *
+ * Identifiers never come from a request: every name is looked up in the model descriptor first. This module is the
+ * second line — whatever reaches `quoteIdentifier()` must still look like an identifier, or it is refused.
+ */
+
+const IDENTIFIER = /^[A-Za-z_]\w*$/;
+/** Postgres truncates longer identifiers silently, which would let two names address one column */
+const MAX_IDENTIFIER_LENGTH = 63;
+
+/**
+ * Names that address JavaScript's object machinery rather than data. Mongoose ignores them in a path; a compiler that
+ * builds an object from path segments would otherwise reach `Object.prototype` through them
+ */
+const RESERVED_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/** A field-name or path segment as the query language accepts it: no dots, no `$`, no leading digit, no prototype name. */
+export function isPathSegment(segment: string): boolean {
+  return IDENTIFIER.test(segment) && !RESERVED_SEGMENTS.has(segment);
+}
+
+/** The column of a field: `_id` / `id` → `id`, camelCase → snake_case (`createdAt` → `created_at`, `userID` → `user_id`). */
+export function columnName(field: string): string {
+  if (field === '_id' || field === 'id') {
+    return 'id';
+  }
+  if (!IDENTIFIER.test(field)) {
+    throw new UnsupportedQueryError(`"${field}" cannot be mapped to a column`);
+  }
+  return field
+    .replace(/([a-z\d])([A-Z])/g, '$1_$2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .toLowerCase();
+}
+
+/** Double-quote an identifier after checking it is one. */
+export function quoteIdentifier(name: string): string {
+  if (!IDENTIFIER.test(name) || name.length > MAX_IDENTIFIER_LENGTH) {
+    throw new UnsupportedQueryError(`"${name}" is not a valid SQL identifier`);
+  }
+  return `"${name}"`;
+}
+
+/**
+ * Backtick-quote an identifier for MySQL / MariaDB after checking it is one — with the same limit as PostgreSQL's
+ * (MySQL allows 64), so a model's names are valid on every SQL database alike.
+ */
+export function quoteMysqlIdentifier(name: string): string {
+  if (!IDENTIFIER.test(name) || name.length > MAX_IDENTIFIER_LENGTH) {
+    throw new UnsupportedQueryError(`"${name}" is not a valid SQL identifier`);
+  }
+  return `\`${name}\``;
+}
+
+/** Where a compiler puts a value: a bound parameter, or — for DDL, which has none — a literal. */
+export interface SqlParamSink {
+  /** Returns the SQL that stands for `value` */
+  add(value: unknown): string;
+}
+
+/** Positional parameters of one statement (`$1`, `$2`, …), shared by every part that contributes to it. */
+export class SqlParams implements SqlParamSink {
+  readonly values: unknown[] = [];
+
+  add(value: unknown): string {
+    this.values.push(value);
+    return `$${this.values.length}`;
+  }
+}
+
+/**
+ * Values as SQL literals, for the one place that cannot bind parameters: DDL (a partial index predicate, a column
+ * default). Only values the code declares reach it — schema options, never request data — and every literal is an
+ * escape-string (`E'…'`), so backslashes and quotes mean the same whatever `standard_conforming_strings` says.
+ */
+export class SqlLiterals implements SqlParamSink {
+  add(value: unknown): string {
+    return sqlLiteral(value);
+  }
+}
+
+export function sqlLiteral(value: unknown): string {
+  if (value === null || value === undefined) {
+    return 'NULL';
+  }
+  if (typeof value === 'boolean') {
+    return value ? 'TRUE' : 'FALSE';
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new UnsupportedQueryError('A literal number must be finite');
+    }
+    return String(value);
+  }
+  if (typeof value === 'bigint') {
+    return value.toString();
+  }
+  if (value instanceof Date) {
+    return escapeString(value.toISOString());
+  }
+  if (Array.isArray(value)) {
+    return escapeString(`{${value.map(arrayElement).join(',')}}`);
+  }
+  if (typeof value === 'string') {
+    return escapeString(value);
+  }
+  throw new UnsupportedQueryError('A value of this type cannot be written as a SQL literal');
+}
+
+function arrayElement(value: unknown): string {
+  if (value === null || value === undefined) {
+    return 'NULL';
+  }
+  if (typeof value === 'number' || typeof value === 'bigint' || typeof value === 'boolean') {
+    return String(value);
+  }
+  const text = value instanceof Date ? value.toISOString() : value;
+  if (typeof text !== 'string') {
+    throw new UnsupportedQueryError('Only scalar arrays can be written as a SQL literal');
+  }
+  return `"${text.replace(/[\\"]/g, (char) => `\\${char}`)}"`;
+}
+
+function escapeString(text: string): string {
+  if (text.includes('\0')) {
+    throw new UnsupportedQueryError('A SQL literal cannot contain a NUL character');
+  }
+  return `E'${text.replace(/[\\']/g, (char) => `\\${char}`)}'`;
+}