@prisma-next/driver-postgres 0.3.0-dev.4 → 0.3.0-dev.41

package/src/exports/runtime.ts

@@ -0,0 +1,162 @@
+import type {
+  RuntimeDriverDescriptor,
+  RuntimeDriverInstance,
+} from '@prisma-next/core-execution-plane/types';
+import type {
+  SqlConnection,
+  SqlDriver,
+  SqlExecuteRequest,
+  SqlExplainResult,
+  SqlQueryResult,
+} from '@prisma-next/sql-relational-core/ast';
+import { postgresDriverDescriptorMeta } from '../core/descriptor-meta';
+import {
+  createBoundDriverFromBinding,
+  type PostgresBinding,
+  type PostgresDriverCreateOptions,
+} from '../postgres-driver';
+
+export type PostgresRuntimeDriver = RuntimeDriverInstance<'sql', 'postgres'> &
+  SqlDriver<PostgresBinding>;
+
+const USE_BEFORE_CONNECT_MESSAGE =
+  'Postgres driver not connected. Call connect(binding) before acquireConnection or execute.';
+const ALREADY_CONNECTED_MESSAGE =
+  'Postgres driver already connected. Call close() before reconnecting with a new binding.';
+
+interface DriverRuntimeError extends Error {
+  readonly code: 'DRIVER.NOT_CONNECTED' | 'DRIVER.ALREADY_CONNECTED';
+  readonly category: 'RUNTIME';
+  readonly severity: 'error';
+  readonly details?: Record<string, unknown>;
+}
+
+function driverError(
+  code: DriverRuntimeError['code'],
+  message: string,
+  details?: Record<string, unknown>,
+): DriverRuntimeError {
+  const error = new Error(message) as DriverRuntimeError;
+  Object.defineProperty(error, 'name', {
+    value: 'RuntimeError',
+    configurable: true,
+  });
+  return Object.assign(error, {
+    code,
+    category: 'RUNTIME' as const,
+    severity: 'error' as const,
+    message,
+    details,
+  });
+}
+
+function unboundExecute<Row>(): AsyncIterable<Row> {
+  return {
+    [Symbol.asyncIterator]() {
+      return {
+        async next() {
+          throw driverError('DRIVER.NOT_CONNECTED', USE_BEFORE_CONNECT_MESSAGE);
+        },
+      };
+    },
+  };
+}
+
+class PostgresUnboundDriverImpl implements PostgresRuntimeDriver {
+  readonly familyId = 'sql' as const;
+  readonly targetId = 'postgres' as const;
+
+  #delegate: SqlDriver<PostgresBinding> | null = null;
+  #closed = false;
+  #cursorOpts: PostgresDriverCreateOptions['cursor'];
+
+  constructor(cursorOpts?: PostgresDriverCreateOptions['cursor']) {
+    this.#cursorOpts = cursorOpts;
+  }
+
+  get state(): 'unbound' | 'connected' | 'closed' {
+    if (this.#delegate !== null) {
+      return 'connected';
+    }
+    if (this.#closed) {
+      return 'closed';
+    }
+    return 'unbound';
+  }
+
+  #requireDelegate(): SqlDriver<PostgresBinding> {
+    const delegate = this.#delegate;
+    if (delegate === null) {
+      throw driverError('DRIVER.NOT_CONNECTED', USE_BEFORE_CONNECT_MESSAGE);
+    }
+    return delegate;
+  }
+
+  async connect(binding: PostgresBinding): Promise<void> {
+    if (this.#delegate !== null) {
+      throw driverError('DRIVER.ALREADY_CONNECTED', ALREADY_CONNECTED_MESSAGE, {
+        bindingKind: binding.kind,
+      });
+    }
+    this.#delegate = createBoundDriverFromBinding(binding, this.#cursorOpts);
+    this.#closed = false;
+  }
+
+  async acquireConnection(): Promise<SqlConnection> {
+    const delegate = this.#requireDelegate();
+    return delegate.acquireConnection();
+  }
+
+  async close(): Promise<void> {
+    const delegate = this.#delegate;
+    if (delegate !== null) {
+      this.#delegate = null;
+      await delegate.close();
+    }
+    this.#closed = true;
+  }
+
+  execute<Row = Record<string, unknown>>(request: SqlExecuteRequest): AsyncIterable<Row> {
+    const delegate = this.#delegate;
+    if (delegate === null) {
+      return unboundExecute<Row>();
+    }
+    return delegate.execute<Row>(request);
+  }
+
+  async explain(request: SqlExecuteRequest): Promise<SqlExplainResult> {
+    const delegate = this.#requireDelegate();
+    const explain = delegate.explain;
+    if (explain === undefined) {
+      throw driverError('DRIVER.NOT_CONNECTED', USE_BEFORE_CONNECT_MESSAGE);
+    }
+    return explain.call(delegate, request);
+  }
+
+  async query<Row = Record<string, unknown>>(
+    sql: string,
+    params?: readonly unknown[],
+  ): Promise<SqlQueryResult<Row>> {
+    const delegate = this.#requireDelegate();
+    return delegate.query<Row>(sql, params);
+  }
+}
+
+const postgresRuntimeDriverDescriptor: RuntimeDriverDescriptor<
+  'sql',
+  'postgres',
+  PostgresDriverCreateOptions,
+  PostgresRuntimeDriver
+> = {
+  ...postgresDriverDescriptorMeta,
+  create(options?: PostgresDriverCreateOptions): PostgresRuntimeDriver {
+    return new PostgresUnboundDriverImpl(options?.cursor);
+  },
+};
+
+export default postgresRuntimeDriverDescriptor;
+export type {
+  PostgresBinding,
+  PostgresDriverCreateOptions,
+  QueryResult,
+} from '../postgres-driver';

package/src/normalize-error.ts

@@ -0,0 +1,219 @@
+import { SqlConnectionError, SqlQueryError } from '@prisma-next/sql-errors';
+
+/**
+ * Postgres error shape from the pg library.
+ *
+ * Note: The pg library doesn't export a DatabaseError type or interface, but errors
+ * thrown by pg.query() and pg.Client have this shape at runtime. We define this
+ * interface to match the actual runtime structure documented in the pg library
+ * (https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/errors.js).
+ *
+ * The @types/pg package also doesn't provide comprehensive error type definitions,
+ * so we define our own interface based on the runtime error properties.
+ */
+interface PostgresError extends Error {
+  readonly code?: string;
+  readonly constraint?: string;
+  readonly table?: string;
+  readonly column?: string;
+  readonly detail?: string;
+  readonly hint?: string;
+  readonly position?: string;
+  readonly internalPosition?: string;
+  readonly internalQuery?: string;
+  readonly where?: string;
+  readonly schema?: string;
+  readonly file?: string;
+  readonly line?: string;
+  readonly routine?: string;
+}
+
+/**
+ * Checks if an error is a connection-related error.
+ */
+function isConnectionError(error: Error): boolean {
+  const code = (error as { code?: string }).code;
+  if (code) {
+    // Node.js error codes for connection issues
+    if (
+      code === 'ECONNRESET' ||
+      code === 'ETIMEDOUT' ||
+      code === 'ECONNREFUSED' ||
+      code === 'ENOTFOUND' ||
+      code === 'EHOSTUNREACH'
+    ) {
+      return true;
+    }
+  }
+
+  // Check error message for connection-related strings
+  const message = error.message.toLowerCase();
+  if (
+    message.includes('connection terminated') ||
+    message.includes('connection closed') ||
+    message.includes('connection refused') ||
+    message.includes('connection timeout') ||
+    message.includes('connection reset')
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Checks if a connection error is transient (might succeed on retry).
+ */
+function isTransientConnectionError(error: Error): boolean {
+  const code = (error as { code?: string }).code;
+  if (code) {
+    // Timeouts and connection resets are often transient
+    if (code === 'ETIMEDOUT' || code === 'ECONNRESET') {
+      return true;
+    }
+    // Connection refused is usually not transient (server is down)
+    if (code === 'ECONNREFUSED') {
+      return false;
+    }
+  }
+
+  const message = error.message.toLowerCase();
+  if (message.includes('timeout') || message.includes('connection reset')) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * PostgreSQL-specific error properties that indicate an error originated from pg library.
+ * These properties are not present on Node.js system errors.
+ * Excludes generic properties like 'detail', 'file', 'line', and 'position' that could appear on any error.
+ */
+const PG_ERROR_PROPERTIES = [
+  'constraint',
+  'table',
+  'column',
+  'hint',
+  'internalPosition',
+  'internalQuery',
+  'where',
+  'schema',
+  'routine',
+] as const;
+
+/**
+ * Type predicate to check if an error is a Postgres error from the pg library.
+ *
+ * Distinguishes pg library errors from Node.js system errors by checking for:
+ * - SQLSTATE codes (5-character alphanumeric codes like '23505', '42601')
+ * - pg-specific properties (constraint, table, column, hint, etc.) that Node.js errors don't have
+ *
+ * Node.js system errors (ECONNREFUSED, ETIMEDOUT, etc.) are excluded to prevent false positives.
+ */
+export function isPostgresError(error: unknown): error is PostgresError {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  const pgError = error as PostgresError;
+
+  // Check for SQLSTATE code (5-character alphanumeric) - primary indicator of pg errors
+  if (pgError.code && isPostgresSqlState(pgError.code)) {
+    return true;
+  }
+
+  // Check for pg-specific properties that Node.js system errors don't have
+  // These properties indicate the error originated from pg library query execution
+  return PG_ERROR_PROPERTIES.some((prop) => pgError[prop] !== undefined);
+}
+
+/**
+ * Checks if an error is an "already connected" error from pg.Client.connect().
+ * When calling connect() on an already-connected client, pg throws an error that can be safely ignored.
+ */
+export function isAlreadyConnectedError(error: unknown): error is Error {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const message = error.message.toLowerCase();
+  return message.includes('already') && message.includes('connected');
+}
+
+/**
+ * Checks if an error code is a Postgres SQLSTATE (5-character alphanumeric code).
+ * SQLSTATE codes are standardized SQL error codes (e.g., '23505' for unique violation).
+ */
+function isPostgresSqlState(code: string | undefined): boolean {
+  if (!code) {
+    return false;
+  }
+  // Postgres SQLSTATE codes are 5-character alphanumeric strings
+  // Examples: '23505' (unique violation), '42501' (insufficient privilege), '42601' (syntax error)
+  return /^[A-Z0-9]{5}$/.test(code);
+}
+
+/**
+ * Normalizes a Postgres error into a SQL-shared error type.
+ *
+ * - Postgres SQLSTATE errors (5-char codes like '23505') → SqlQueryError
+ * - Connection errors (ECONNRESET, ETIMEDOUT, etc.) → SqlConnectionError
+ * - Unknown errors → returns the original error as-is
+ *
+ * The original error is preserved via Error.cause to maintain stack traces.
+ *
+ * @param error - The error to normalize (typically from pg library)
+ * @returns SqlQueryError for query-related failures
+ * @returns SqlConnectionError for connection-related failures
+ * @returns The original error if it cannot be normalized
+ */
+export function normalizePgError(error: unknown): SqlQueryError | SqlConnectionError | Error {
+  if (!(error instanceof Error)) {
+    // Wrap non-Error values in an Error object
+    return new Error(String(error));
+  }
+
+  const pgError = error as PostgresError;
+
+  // Check for Postgres SQLSTATE (query errors)
+  if (isPostgresSqlState(pgError.code)) {
+    // isPostgresSqlState ensures code is defined and is a valid SQLSTATE
+    // biome-ignore lint/style/noNonNullAssertion: isPostgresSqlState guarantees code is defined
+    const sqlState = pgError.code!;
+    const options: {
+      cause: Error;
+      sqlState: string;
+      constraint?: string;
+      table?: string;
+      column?: string;
+      detail?: string;
+    } = {
+      cause: error,
+      sqlState,
+    };
+    if (pgError.constraint !== undefined) {
+      options.constraint = pgError.constraint;
+    }
+    if (pgError.table !== undefined) {
+      options.table = pgError.table;
+    }
+    if (pgError.column !== undefined) {
+      options.column = pgError.column;
+    }
+    if (pgError.detail !== undefined) {
+      options.detail = pgError.detail;
+    }
+    return new SqlQueryError(error.message, options);
+  }
+
+  // Check for connection errors
+  if (isConnectionError(error)) {
+    return new SqlConnectionError(error.message, {
+      cause: error,
+      transient: isTransientConnectionError(error),
+    });
+  }
+
+  // Unknown error - return as-is to preserve original error and stack trace
+  return error;
+}