pipework 0.251.0 → 0.252.1

package/src/data/query/postgres-js/driver-error-boundary.ts

@@ -0,0 +1,149 @@
+/**
+ * Keeps a statement observer from widening what a query error serializes.
+ *
+ * postgres.js defines `stack`/`query`/`parameters`/`args`/`types` on every
+ * query error it raises, and makes them ENUMERABLE exactly when its `debug`
+ * option is truthy (`connection.js`, `queryError`). Pipework sets `debug` to
+ * install a per-statement observer — so, absent this boundary, merely observing
+ * statements would start leaking bind parameters into every log drain that
+ * serializes errors. Observation must not change what an error exposes.
+ *
+ * Why this is a closed set rather than a best-effort sweep: enumerability only
+ * changes where `debug` is truthy, and only three sites in pipework construct a
+ * connection carrying the observer — `createManagedConnection`,
+ * `createIsolatedConnection`, and `createSetupConnection`. Every other
+ * `postgres()` in the codebase (migrations, CLI, startup validation, reaper,
+ * `tap()`) leaves `debug` unset, so its errors keep these fields
+ * non-enumerable already and need no treatment.
+ *
+ * The one gap, deliberate and announced: `ManagedConnection.client` is the
+ * sanctioned raw-driver door, and errors from queries issued through it do not
+ * pass this boundary. Reading `.client` on an observed connection logs a
+ * one-time warning saying so. Wrapping the `Sql` to close that gap was
+ * considered and REJECTED: it means proxying a callable tagged-template whose
+ * `begin`/`savepoint` hand out fresh client instances needing recursive
+ * re-wrapping, on the hottest path in the system — more risk than the narrow,
+ * documented gap it would close. Do not "clean this up" by adding one.
+ */
+
+/**
+ * postgres.js properties whose enumerability its `debug` option flips — all
+ * five defined in one `Object.defineProperties` call, so requiring the whole
+ * set is a precise signature for "this error was decorated by the driver".
+ * `stack` is included because an enumerable own `stack` is itself a departure
+ * from ordinary Error semantics, and it carries the query origin.
+ */
+const DRIVER_ADDED_FIELDS = ['stack', 'query', 'parameters', 'args', 'types'] as const
+
+/**
+ * Connections whose `debug` hook exists ONLY to drive a statement observer.
+ * Keyed on the options object, which is stable for the lifetime of one
+ * `postgres()` client. `logAllQueries` connections are deliberately absent:
+ * that mode already opted into verbose errors, and its behavior is unchanged.
+ */
+const observedOptions = new WeakSet<object>()
+
+/**
+ * The identity a client is tracked under: its options object where it has one,
+ * else the client itself. Transaction- and savepoint-scoped clients — the ones
+ * postgres.js hands to a `begin`/`savepoint` callback — expose no `options`, so
+ * they are tracked directly and marked by `propagateObserved` as they are made.
+ */
+function identity(client: unknown): object | undefined {
+  if (client === null || typeof client !== 'object' && typeof client !== 'function') return undefined
+  const options = (client as { options?: unknown }).options
+  return typeof options === 'object' && options !== null ? options : (client as object)
+}
+
+/** Records that this client's `debug` hook came from a statement observer alone. */
+export function markObservedConnection(client: unknown): void {
+  const key = identity(client)
+  if (key !== undefined) observedOptions.add(key)
+}
+
+/** True when this client's `debug` hook came from a statement observer alone. */
+export function isObservedConnection(client: unknown): boolean {
+  const key = identity(client)
+  return key !== undefined && observedOptions.has(key)
+}
+
+/** Carries observed-ness onto a transaction- or savepoint-scoped client. */
+export function propagateObserved(from: unknown, to: unknown): void {
+  if (isObservedConnection(from)) markObservedConnection(to)
+}
+
+/**
+ * Identifies an error postgres.js decorated because `debug` was installed.
+ * Keyed on the full set it adds together, so drizzle's own wrapper — which
+ * carries `query` and `params` but never `parameters`/`args`/`types` — is left
+ * alone. That wrapper's exposure predates this feature and is not ours to
+ * change here.
+ */
+function hasDriverAddedFields(err: Error): boolean {
+  return DRIVER_ADDED_FIELDS.every(field => {
+    const descriptor = Object.getOwnPropertyDescriptor(err, field)
+    return descriptor?.enumerable === true
+  })
+}
+
+/**
+ * postgres.js defines these with `Object.defineProperties` and no descriptor
+ * flags, which makes them non-configurable — their enumerability cannot be
+ * flipped in place. So the error is rebuilt: same prototype, same own
+ * properties and values, with the driver-added four defined non-enumerable.
+ * `instanceof`, `message`, `stack`, `code` and every server field survive; only
+ * what a serializer walks changes.
+ */
+function withDriverFieldsHidden(err: Error): Error {
+  const clone = Object.create(Object.getPrototypeOf(err) as object) as Error
+  for (const key of Reflect.ownKeys(err)) {
+    const descriptor = Object.getOwnPropertyDescriptor(err, key)!
+    const hide = typeof key === 'string' && (DRIVER_ADDED_FIELDS as readonly string[]).includes(key)
+    Object.defineProperty(clone, key, hide ? { ...descriptor, enumerable: false, configurable: true } : descriptor)
+  }
+  return clone
+}
+
+/**
+ * Returns the error to propagate with the driver-added fields hidden from
+ * serialization, following `cause` because the driver error usually arrives
+ * wrapped by drizzle. Returns the original untouched when there is nothing to
+ * hide.
+ */
+export function withoutDriverAddedFields(err: unknown): unknown {
+  if (!(err instanceof Error)) return err
+
+  const root = hasDriverAddedFields(err) ? withDriverFieldsHidden(err) : err
+
+  for (let current: Error = root, depth = 0; depth < 8; depth++) {
+    const cause: unknown = current.cause
+    if (!(cause instanceof Error)) break
+
+    if (hasDriverAddedFields(cause)) {
+      const hidden = withDriverFieldsHidden(cause)
+      const descriptor = Object.getOwnPropertyDescriptor(current, 'cause')
+      if (descriptor?.writable === true || descriptor?.configurable === true) {
+        Object.defineProperty(current, 'cause', { ...descriptor, value: hidden })
+      }
+      current = hidden
+    } else {
+      current = cause
+    }
+  }
+
+  return root
+}
+
+/**
+ * Runs driver work, hiding the fields postgres.js only exposed because a
+ * statement observer is attached. Pure pass-through when the connection is not
+ * observed, and never alters the error itself — only what it serializes.
+ */
+export async function throughErrorBoundary<T>(client: unknown, run: () => Promise<T>): Promise<T> {
+  if (!isObservedConnection(client)) return run()
+  try {
+    return await run()
+  } catch (err) {
+    throw withoutDriverAddedFields(err)
+  }
+}

package/src/data/query/postgres-js/driver.ts

@@ -0,0 +1,163 @@
+import pgClient, { type Options, type PostgresType, type Sql } from 'postgres';
+import { parseArrayLiteral } from './array-parser.js';
+import { entityKind } from '../entity.js';
+import { DefaultLogger } from '../logger.js';
+import { PgDatabase } from '../pg-core/db.js';
+import { PgDialect } from '../pg-core/dialect.js';
+import {
+	createTableRelationsHelpers,
+	extractTablesRelationalConfig,
+	type RelationalSchemaConfig,
+	type TablesRelationalConfig,
+} from '../relations.js';
+import { type DrizzleConfig, isConfig } from '../utils.js';
+import type { PostgresJsQueryResultHKT } from './session.js';
+import { PostgresJsSession } from './session.js';
+
+export class PostgresJsDatabase<
+	TSchema extends Record<string, unknown> = Record<string, never>,
+> extends PgDatabase<PostgresJsQueryResultHKT, TSchema> {
+	static override readonly [entityKind]: string = 'PostgresJsDatabase';
+}
+
+const arrayParserInstalled = Symbol('arrayParserInstalled');
+
+/**
+ * postgres.js builds each array type's parser as it learns the type (`addArrayType`) and records it in
+ * `options.shared.typeArrayMap`, which it reads fresh each time. Watching that map lets us pin our own
+ * array parser (unquoted NULL -> null) for every array type, enums and domains included.
+ */
+function installArrayParser(client: Sql): void {
+	const shared = (client.options as any).shared as { typeArrayMap?: Record<number, number> } | undefined;
+	const parsers = client.options.parsers as Record<number, any>;
+	if (!shared?.typeArrayMap || (shared.typeArrayMap as any)[arrayParserInstalled]) return;
+	const known = shared.typeArrayMap;
+	shared.typeArrayMap = new Proxy(known, {
+		get: (target, key, receiver) => (key === arrayParserInstalled ? true : Reflect.get(target, key, receiver)),
+		set(target, key, typarray) {
+			target[key as any] = typarray;
+			const element = parsers[Number(key)];
+			const delimiter = typarray === 1020 ? ';' : ',';
+			const parse: any = (xs: string) => parseArrayLiteral(xs, element, delimiter);
+			parse.array = true;
+			// the driver assigns its own parser right after this; keep ours
+			Object.defineProperty(parsers, typarray, { get: () => parse, set: () => {}, enumerable: true, configurable: true });
+			return true;
+		},
+	});
+}
+
+function construct<TSchema extends Record<string, unknown> = Record<string, never>>(
+	client: Sql,
+	config: DrizzleConfig<TSchema> = {},
+): PostgresJsDatabase<TSchema> & {
+	$client: Sql;
+} {
+	const transparentParser = (val: any) => val;
+
+	// Override postgres.js default date parsers: https://github.com/porsager/postgres/discussions/761
+	for (const type of ['1184', '1082', '1083', '1114', '1182', '1185', '1115', '1231']) {
+		// 1231 (numeric[]) is left to the driver's array parser so a NULL element reads as null, not the text '{..,NULL}'.
+		if (type !== '1231') client.options.parsers[type as any] = transparentParser;
+		client.options.serializers[type as any] = transparentParser;
+	}
+	installArrayParser(client);
+	client.options.serializers['114'] = transparentParser;
+	client.options.serializers['3802'] = transparentParser;
+
+	const dialect = new PgDialect({ casing: config.casing });
+	let logger;
+	if (config.logger === true) {
+		logger = new DefaultLogger();
+	} else if (config.logger !== false) {
+		logger = config.logger;
+	}
+
+	let schema: RelationalSchemaConfig<TablesRelationalConfig> | undefined;
+	if (config.schema) {
+		const tablesConfig = extractTablesRelationalConfig(
+			config.schema,
+			createTableRelationsHelpers,
+		);
+		schema = {
+			fullSchema: config.schema,
+			schema: tablesConfig.tables,
+			tableNamesMap: tablesConfig.tableNamesMap,
+		};
+	}
+
+	const session = new PostgresJsSession(client, dialect, schema, { logger, cache: config.cache, watch: config.statementWatch });
+	const db = new PostgresJsDatabase(dialect, session, schema as any) as PostgresJsDatabase<TSchema>;
+	(<any> db).$client = client;
+	(<any> db).$cache = config.cache;
+	if ((<any> db).$cache) {
+		(<any> db).$cache['invalidate'] = config.cache?.onMutate;
+	}
+
+	return db as any;
+}
+
+export function drizzle<
+	TSchema extends Record<string, unknown> = Record<string, never>,
+	TClient extends Sql = Sql,
+>(
+	...params: [
+		TClient | string,
+	] | [
+		TClient | string,
+		DrizzleConfig<TSchema>,
+	] | [
+		(
+			& DrizzleConfig<TSchema>
+			& ({
+				connection: string | ({ url?: string } & Options<Record<string, PostgresType>>);
+			} | {
+				client: TClient;
+			})
+		),
+	]
+): PostgresJsDatabase<TSchema> & {
+	$client: TClient;
+} {
+	if (typeof params[0] === 'string') {
+		const instance = pgClient(params[0] as string);
+
+		return construct(instance, params[1]) as any;
+	}
+
+	if (isConfig(params[0])) {
+		const { connection, client, ...drizzleConfig } = params[0] as {
+			connection?: { url?: string } & Options<Record<string, PostgresType>>;
+			client?: TClient;
+		} & DrizzleConfig<TSchema>;
+
+		if (client) return construct(client, drizzleConfig) as any;
+
+		if (typeof connection === 'object' && connection.url !== undefined) {
+			const { url, ...config } = connection;
+
+			const instance = pgClient(url, config);
+			return construct(instance, drizzleConfig) as any;
+		}
+
+		const instance = pgClient(connection);
+		return construct(instance, drizzleConfig) as any;
+	}
+
+	return construct(params[0] as TClient, params[1] as DrizzleConfig<TSchema> | undefined) as any;
+}
+
+export namespace drizzle {
+	export function mock<TSchema extends Record<string, unknown> = Record<string, never>>(
+		config?: DrizzleConfig<TSchema>,
+	): PostgresJsDatabase<TSchema> & {
+		$client: '$client is not available on drizzle.mock()';
+	} {
+		return construct({
+			options: {
+				parsers: {},
+				serializers: {},
+			},
+		} as any, config) as any;
+	}
+}

package/src/data/query/postgres-js/index.ts

@@ -0,0 +1,2 @@
+export * from './driver.js';
+export * from './session.js';

package/src/data/query/postgres-js/session.ts

@@ -0,0 +1,234 @@
+import type { Row, RowList, Sql, TransactionSql } from 'postgres';
+import { type Cache, NoopCache } from '../cache/core/index.js';
+import type { WithCacheConfig } from '../cache/core/types.js';
+import { entityKind } from '../entity.js';
+import type { Logger } from '../logger.js';
+import { NoopLogger } from '../logger.js';
+import type { PgDialect } from '../pg-core/dialect.js';
+import { PgTransaction } from '../pg-core/index.js';
+import type { SelectedFieldsOrdered } from '../pg-core/query-builders/select.types.js';
+import type { PgQueryResultHKT, PgTransactionConfig, PreparedQueryConfig } from '../pg-core/session.js';
+import { PgPreparedQuery, PgSession } from '../pg-core/session.js';
+import type { RelationalSchemaConfig, TablesRelationalConfig } from '../relations.js';
+import { fillPlaceholders, type Query } from '../sql/sql.js';
+import { tracer } from '../tracing.js';
+import { type Assume, mapResultRow } from '../utils.js';
+import { propagateObserved, throughErrorBoundary } from './driver-error-boundary.js';
+
+/** Wraps one statement's execution; installed by the pool to time it and report it while it runs. */
+export type StatementWatch = <T>(query: string, run: () => Promise<T>) => Promise<T>;
+
+function watched<T>(watch: StatementWatch | undefined, query: string, run: () => Promise<T>): Promise<T> {
+	return watch === undefined ? run() : watch(query, run);
+}
+
+export class PostgresJsPreparedQuery<T extends PreparedQueryConfig> extends PgPreparedQuery<T> {
+	static override readonly [entityKind]: string = 'PostgresJsPreparedQuery';
+
+	constructor(
+		private client: Sql,
+		private queryString: string,
+		private params: unknown[],
+		private logger: Logger,
+		cache: Cache,
+		queryMetadata: {
+			type: 'select' | 'update' | 'delete' | 'insert';
+			tables: string[];
+		} | undefined,
+		cacheConfig: WithCacheConfig | undefined,
+		private fields: SelectedFieldsOrdered | undefined,
+		private _isResponseInArrayMode: boolean,
+		private customResultMapper?: (rows: unknown[][]) => T['execute'],
+		private watch?: StatementWatch,
+	) {
+		super({ sql: queryString, params }, cache, queryMetadata, cacheConfig);
+	}
+
+	async execute(placeholderValues: Record<string, unknown> | undefined = {}): Promise<T['execute']> {
+		return tracer.startActiveSpan('drizzle.execute', async (span) => {
+			const params = fillPlaceholders(this.params, placeholderValues);
+
+			span?.setAttributes({
+				'drizzle.query.text': this.queryString,
+				'drizzle.query.params': JSON.stringify(params),
+			});
+
+			this.logger.logQuery(this.queryString, params);
+
+			const { fields, queryString: query, client, joinsNotNullableMap, customResultMapper, watch } = this;
+			if (!fields && !customResultMapper) {
+				return tracer.startActiveSpan('drizzle.driver.execute', () => {
+					return throughErrorBoundary(client, () => watched(watch, query, () => this.queryWithCache(query, params, async () => {
+						return await client.unsafe(query, params as any[]);
+					})));
+				});
+			}
+
+			const rows = await tracer.startActiveSpan('drizzle.driver.execute', () => {
+				span?.setAttributes({
+					'drizzle.query.text': query,
+					'drizzle.query.params': JSON.stringify(params),
+				});
+				return throughErrorBoundary(client, () => watched(watch, query, () => this.queryWithCache(query, params, async () => {
+					return await client.unsafe(query, params as any[]).values();
+				})));
+			});
+
+			return tracer.startActiveSpan('drizzle.mapResponse', () => {
+				return customResultMapper
+					? customResultMapper(rows)
+					: rows.map((row) => mapResultRow<T['execute']>(fields!, row, joinsNotNullableMap));
+			});
+		});
+	}
+
+	all(placeholderValues: Record<string, unknown> | undefined = {}): Promise<T['all']> {
+		return tracer.startActiveSpan('drizzle.execute', async (span) => {
+			const params = fillPlaceholders(this.params, placeholderValues);
+			span?.setAttributes({
+				'drizzle.query.text': this.queryString,
+				'drizzle.query.params': JSON.stringify(params),
+			});
+			this.logger.logQuery(this.queryString, params);
+			return tracer.startActiveSpan('drizzle.driver.execute', () => {
+				span?.setAttributes({
+					'drizzle.query.text': this.queryString,
+					'drizzle.query.params': JSON.stringify(params),
+				});
+				return throughErrorBoundary(this.client, () => watched(this.watch, this.queryString, () => this.queryWithCache(this.queryString, params, async () => {
+					return this.client.unsafe(this.queryString, params as any[]);
+				})));
+			});
+		});
+	}
+
+	/** @internal */
+	isResponseInArrayMode(): boolean {
+		return this._isResponseInArrayMode;
+	}
+}
+
+export interface PostgresJsSessionOptions {
+	logger?: Logger | undefined;
+	cache?: Cache | undefined;
+	watch?: StatementWatch | undefined;
+}
+
+export class PostgresJsSession<
+	TSQL extends Sql,
+	TFullSchema extends Record<string, unknown>,
+	TSchema extends TablesRelationalConfig,
+> extends PgSession<PostgresJsQueryResultHKT, TFullSchema, TSchema> {
+	static override readonly [entityKind]: string = 'PostgresJsSession';
+
+	logger: Logger;
+	private cache: Cache;
+
+	constructor(
+		public client: TSQL,
+		dialect: PgDialect,
+		private schema: RelationalSchemaConfig<TSchema> | undefined,
+		/** @internal */
+		readonly options: PostgresJsSessionOptions = {},
+	) {
+		super(dialect);
+		this.logger = options.logger ?? new NoopLogger();
+		this.cache = options.cache ?? new NoopCache();
+	}
+
+	prepareQuery<T extends PreparedQueryConfig = PreparedQueryConfig>(
+		query: Query,
+		fields: SelectedFieldsOrdered | undefined,
+		name: string | undefined,
+		isResponseInArrayMode: boolean,
+		customResultMapper?: (rows: unknown[][]) => T['execute'],
+		queryMetadata?: {
+			type: 'select' | 'update' | 'delete' | 'insert';
+			tables: string[];
+		},
+		cacheConfig?: WithCacheConfig,
+	): PgPreparedQuery<T> {
+		return new PostgresJsPreparedQuery(
+			this.client,
+			query.sql,
+			query.params,
+			this.logger,
+			this.cache,
+			queryMetadata,
+			cacheConfig,
+			fields,
+			isResponseInArrayMode,
+			customResultMapper,
+			this.options.watch,
+		);
+	}
+
+	query(query: string, params: unknown[]): Promise<RowList<Row[]>> {
+		this.logger.logQuery(query, params);
+		return throughErrorBoundary(this.client, () => watched(this.options.watch, query, () => this.client.unsafe(query, params as any[]).values()));
+	}
+
+	queryObjects<T extends Row>(
+		query: string,
+		params: unknown[],
+	): Promise<RowList<T[]>> {
+		return throughErrorBoundary(this.client, () => watched(this.options.watch, query, () => this.client.unsafe(query, params as any[])));
+	}
+
+	override transaction<T>(
+		transaction: (tx: PostgresJsTransaction<TFullSchema, TSchema>) => Promise<T>,
+		config?: PgTransactionConfig,
+	): Promise<T> {
+		return throughErrorBoundary(this.client, () => this.client.begin(async (client) => {
+			propagateObserved(this.client, client);
+			const session = new PostgresJsSession<Sql, TFullSchema, TSchema>(
+				client as unknown as Sql,
+				this.dialect,
+				this.schema,
+				this.options,
+			);
+			const tx = new PostgresJsTransaction(this.dialect, session, this.schema);
+			if (config) {
+				await tx.setTransaction(config);
+			}
+			return transaction(tx);
+		})) as Promise<T>;
+	}
+}
+
+export class PostgresJsTransaction<
+	TFullSchema extends Record<string, unknown>,
+	TSchema extends TablesRelationalConfig,
+> extends PgTransaction<PostgresJsQueryResultHKT, TFullSchema, TSchema> {
+	static override readonly [entityKind]: string = 'PostgresJsTransaction';
+
+	constructor(
+		dialect: PgDialect,
+		/** @internal */
+		override readonly session: PostgresJsSession<Sql, TFullSchema, TSchema>,
+		schema: RelationalSchemaConfig<TSchema> | undefined,
+		nestedIndex = 0,
+	) {
+		super(dialect, session, schema, nestedIndex);
+	}
+
+	override transaction<T>(
+		transaction: (tx: PostgresJsTransaction<TFullSchema, TSchema>) => Promise<T>,
+	): Promise<T> {
+		return throughErrorBoundary(this.session.client, () => (this.session.client as unknown as TransactionSql).savepoint((client) => {
+			propagateObserved(this.session.client, client);
+			const session = new PostgresJsSession<Sql, TFullSchema, TSchema>(
+				client as unknown as Sql,
+				this.dialect,
+				this.schema,
+				this.session.options,
+			);
+			const tx = new PostgresJsTransaction<TFullSchema, TSchema>(this.dialect, session, this.schema);
+			return transaction(tx);
+		})) as Promise<T>;
+	}
+}
+
+export interface PostgresJsQueryResultHKT extends PgQueryResultHKT {
+	type: RowList<Assume<this['row'], Row>[]>;
+}

package/src/data/query/primary-key.ts

@@ -0,0 +1,11 @@
+import { entityKind } from './entity.js';
+import type { AnyColumn } from './column.js';
+import type { Table } from './table.js';
+
+export abstract class PrimaryKey {
+	static readonly [entityKind]: string = 'PrimaryKey';
+
+	declare protected $brand: 'PrimaryKey';
+
+	constructor(readonly table: Table, readonly columns: AnyColumn[]) {}
+}

package/src/data/query/query-builders/query-builder.ts

@@ -0,0 +1,19 @@
+import { entityKind } from '../entity.js';
+import type { SQL, SQLWrapper } from '../sql/index.js';
+
+export abstract class TypedQueryBuilder<TSelection, TResult = unknown, TConfig = unknown> implements SQLWrapper {
+	static readonly [entityKind]: string = 'TypedQueryBuilder';
+
+	declare _: {
+		selectedFields: TSelection;
+		result: TResult;
+		config?: TConfig;
+	};
+
+	/** @internal */
+	getSelectedFields(): TSelection {
+		return this._.selectedFields;
+	}
+
+	abstract getSQL(): SQL;
+}