@prisma-next/driver-postgres 0.3.0-dev.13 → 0.3.0-dev.146

package/src/exports/runtime.ts

@@ -1,38 +1,162 @@
 import type {
   RuntimeDriverDescriptor,
   RuntimeDriverInstance,
-} from '@prisma-next/core-execution-plane/types';
-import type { SqlDriver } from '@prisma-next/sql-relational-core/ast';
+} from '@prisma-next/framework-components/execution';
+import type {
+  SqlConnection,
+  SqlDriver,
+  SqlExecuteRequest,
+  SqlExplainResult,
+  SqlQueryResult,
+} from '@prisma-next/sql-relational-core/ast';
 import { postgresDriverDescriptorMeta } from '../core/descriptor-meta';
-import type { PostgresDriverOptions } from '../postgres-driver';
-import { createPostgresDriverFromOptions } from '../postgres-driver';
-
-/**
- * Postgres runtime driver instance interface.
- * SqlDriver provides SQL-specific methods (execute, explain, close).
- * RuntimeDriverInstance provides target identification (familyId, targetId).
- * We use intersection type to combine both interfaces.
- */
-export type PostgresRuntimeDriver = RuntimeDriverInstance<'sql', 'postgres'> & SqlDriver;
-
-/**
- * Postgres driver descriptor for runtime plane.
- */
+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: PostgresDriverOptions): PostgresRuntimeDriver {
-    return createPostgresDriverFromOptions(options) as PostgresRuntimeDriver;
+  create(options?: PostgresDriverCreateOptions): PostgresRuntimeDriver {
+    return new PostgresUnboundDriverImpl(options?.cursor);
   },
 };
 
 export default postgresRuntimeDriverDescriptor;
 export type {
-  CreatePostgresDriverOptions,
-  PostgresDriverOptions,
+  PostgresBinding,
+  PostgresDriverCreateOptions,
   QueryResult,
 } from '../postgres-driver';
-export { createPostgresDriver, createPostgresDriverFromOptions } from '../postgres-driver';

package/src/postgres-driver.ts

@@ -1,8 +1,12 @@
 import type {
+  SqlConnection,
   SqlDriver,
+  SqlDriverState,
   SqlExecuteRequest,
   SqlExplainResult,
+  SqlQueryable,
   SqlQueryResult,
+  SqlTransaction,
 } from '@prisma-next/sql-relational-core/ast';
 import type {
   Client,
@@ -18,47 +22,69 @@ import { isAlreadyConnectedError, isPostgresError, normalizePgError } from './no
 
 export type QueryResult<T extends QueryResultRow = QueryResultRow> = PgQueryResult<T>;
 
-export interface PostgresDriverOptions {
+export type PostgresBinding =
+  | { readonly kind: 'url'; readonly url: string }
+  | { readonly kind: 'pgPool'; readonly pool: PoolType }
+  | { readonly kind: 'pgClient'; readonly client: Client };
+
+export interface PostgresCursorOptions {
+  readonly batchSize?: number;
+  readonly disabled?: boolean;
+}
+
+interface PostgresDriverOptions {
   readonly connect: { client: Client } | { pool: PoolType };
-  readonly cursor?:
-    | {
-        readonly batchSize?: number;
-        readonly disabled?: boolean;
-      }
-    | undefined;
+  readonly cursor?: PostgresCursorOptions | undefined;
 }
 
+export type PostgresDriverCreateOptions = Omit<PostgresDriverOptions, 'connect'>;
+
 const DEFAULT_BATCH_SIZE = 100;
 
-class PostgresDriverImpl implements SqlDriver {
-  private readonly pool: PoolType | undefined;
-  private readonly directClient: Client | undefined;
-  private readonly cursorBatchSize: number;
-  private readonly cursorDisabled: boolean;
-
-  constructor(options: PostgresDriverOptions) {
-    if ('client' in options.connect) {
-      this.directClient = options.connect.client;
-    } else if ('pool' in options.connect) {
-      this.pool = options.connect.pool;
-    } else {
-      throw new Error('PostgresDriver requires a pool or client');
-    }
+type ConnectionOptions =
+  | { readonly cursorDisabled: true }
+  | { readonly cursorBatchSize: number; readonly cursorDisabled: false };
+
+class AsyncMutex {
+  #queue = Promise.resolve();
 
-    this.cursorBatchSize = options.cursor?.batchSize ?? DEFAULT_BATCH_SIZE;
-    this.cursorDisabled = options.cursor?.disabled ?? false;
+  async lock(): Promise<() => void> {
+    const previous = this.#queue;
+    let releaseLock: (() => void) | undefined;
+    this.#queue = new Promise<void>((resolve) => {
+      releaseLock = resolve;
+    });
+    await previous;
+    return () => {
+      releaseLock?.();
+      releaseLock = undefined;
+    };
   }
+}
+
+abstract class PostgresQueryable<C extends PoolClient | Client = PoolClient | Client>
+  implements SqlQueryable
+{
+  abstract acquireClient(): Promise<C>;
+  abstract releaseClient(client: C): Promise<void>;
 
-  async connect(): Promise<void> {
-    // No-op: caller controls connecting the underlying client or pool
+  protected readonly options: ConnectionOptions;
+
+  constructor(options: ConnectionOptions) {
+    this.options = options;
   }
 
   async *execute<Row = Record<string, unknown>>(request: SqlExecuteRequest): AsyncIterable<Row> {
     const client = await this.acquireClient();
     try {
-      if (!this.cursorDisabled) {
+      if (!this.options.cursorDisabled) {
         try {
-          for await (const row of this.executeWithCursor(client, request.sql, request.params)) {
+          for await (const row of this.executeWithCursor(
+            client,
+            request.sql,
+            request.params,
+            this.options.cursorBatchSize,
+          )) {
             yield row as Row;
           }
           return;
@@ -86,13 +112,15 @@ class PostgresDriverImpl implements SqlDriver {
   }
 
   async explain(request: SqlExecuteRequest): Promise<SqlExplainResult> {
+    // SQL is generated by Prisma Next planners (or validated raw paths), so
+    // EXPLAIN prefixing preserves the same statement semantics.
     const text = `EXPLAIN (FORMAT JSON) ${request.sql}`;
     const client = await this.acquireClient();
     try {
-      const result = await client.query(text, request.params as unknown[] | undefined);
+      const result = await client
+        .query(text, request.params as unknown[] | undefined)
+        .catch(rethrowNormalizedError);
       return { rows: result.rows as ReadonlyArray<Record<string, unknown>> };
-    } catch (error) {
-      throw normalizePgError(error);
     } finally {
       await this.releaseClient(client);
     }
@@ -104,80 +132,26 @@ class PostgresDriverImpl implements SqlDriver {
   ): Promise<SqlQueryResult<Row>> {
     const client = await this.acquireClient();
     try {
-      const result = await client.query(sql, params as unknown[] | undefined);
+      const result = await client
+        .query(sql, params as unknown[] | undefined)
+        .catch(rethrowNormalizedError);
       return result as unknown as SqlQueryResult<Row>;
-    } catch (error) {
-      throw normalizePgError(error);
     } finally {
       await this.releaseClient(client);
     }
   }
 
-  async close(): Promise<void> {
-    if (this.pool) {
-      // Check if pool is already closed to avoid "Called end on pool more than once" error
-      // pg Pool has an 'ended' property that indicates if the pool has been closed
-      if (!(this.pool as { ended?: boolean }).ended) {
-        await this.pool.end();
-      }
-    }
-    if (this.directClient) {
-      const client = this.directClient as Client & { _ending?: boolean };
-      if (!client._ending) {
-        await client.end();
-      }
-    }
-  }
-
-  private async acquireClient(): Promise<PoolClient | Client> {
-    if (this.pool) {
-      return this.pool.connect();
-    }
-    if (this.directClient) {
-      // Check if client is already connected before attempting to connect
-      // This prevents hanging when the database only supports a single connection
-      // pg's Client has internal connection state that we can check
-      const client = this.directClient as Client & {
-        _ending?: boolean;
-        _connection?: unknown;
-      };
-      const isConnected =
-        client._connection !== undefined && client._connection !== null && !client._ending;
-
-      // Only connect if not already connected
-      // If caller provided a connected client (e.g., in tests), use it as-is
-      if (!isConnected) {
-        try {
-          await this.directClient.connect();
-        } catch (error: unknown) {
-          // If already connected, pg throws an error - ignore it and proceed
-          // Re-throw other errors (actual connection failures)
-          if (!isAlreadyConnectedError(error)) {
-            throw error;
-          }
-        }
-      }
-      return this.directClient;
-    }
-    throw new Error('PostgresDriver requires a pool or client');
-  }
-
-  private async releaseClient(client: PoolClient | Client): Promise<void> {
-    if (this.pool) {
-      (client as PoolClient).release();
-    }
-  }
-
   private async *executeWithCursor(
     client: PoolClient | Client,
     sql: string,
     params: readonly unknown[] | undefined,
+    cursorBatchSize: number,
   ): AsyncIterable<Record<string, unknown>> {
     const cursor = client.query(new Cursor(sql, params as unknown[] | undefined));
 
     try {
       while (true) {
-        const rows = await readCursor(cursor, this.cursorBatchSize);
+        const rows = await readCursor(cursor, cursorBatchSize);
         if (rows.length === 0) {
           break;
         }
@@ -203,25 +177,215 @@ class PostgresDriverImpl implements SqlDriver {
   }
 }
 
-export interface CreatePostgresDriverOptions {
-  readonly cursor?: PostgresDriverOptions['cursor'];
-  readonly poolFactory?: typeof Pool;
+class PostgresConnectionImpl extends PostgresQueryable implements SqlConnection {
+  #connection: PoolClient | Client;
+  #onRelease: (() => void) | undefined;
+
+  constructor(connection: PoolClient | Client, options: ConnectionOptions, onRelease?: () => void) {
+    super(options);
+    this.#connection = connection;
+    this.#onRelease = onRelease;
+  }
+
+  override acquireClient(): Promise<PoolClient | Client> {
+    return Promise.resolve(this.#connection);
+  }
+
+  override releaseClient(_client: PoolClient | Client): Promise<void> {
+    return Promise.resolve();
+  }
+
+  async beginTransaction(): Promise<SqlTransaction> {
+    await this.#connection.query('BEGIN').catch(rethrowNormalizedError);
+    return new PostgresTransactionImpl(this.#connection, this.options);
+  }
+
+  async release(): Promise<void> {
+    if ('release' in this.#connection) {
+      this.#connection.release();
+    }
+    this.#onRelease?.();
+    this.#onRelease = undefined;
+  }
 }
 
-export function createPostgresDriver(
-  connectionString: string,
-  options?: CreatePostgresDriverOptions,
-): SqlDriver {
-  const PoolImpl: typeof Pool = options?.poolFactory ?? Pool;
-  const pool = new PoolImpl({ connectionString });
-  return new PostgresDriverImpl({
-    connect: { pool },
-    cursor: options?.cursor,
-  });
+class PostgresTransactionImpl extends PostgresQueryable implements SqlTransaction {
+  #connection: PoolClient | Client;
+
+  constructor(connection: PoolClient | Client, options: ConnectionOptions) {
+    super(options);
+    this.#connection = connection;
+  }
+
+  override acquireClient(): Promise<PoolClient | Client> {
+    return Promise.resolve(this.#connection);
+  }
+
+  override releaseClient(_client: PoolClient | Client): Promise<void> {
+    return Promise.resolve();
+  }
+
+  async commit(): Promise<void> {
+    await this.#connection.query('COMMIT').catch(rethrowNormalizedError);
+  }
+
+  async rollback(): Promise<void> {
+    await this.#connection.query('ROLLBACK').catch(rethrowNormalizedError);
+  }
 }
 
-export function createPostgresDriverFromOptions(options: PostgresDriverOptions): SqlDriver {
-  return new PostgresDriverImpl(options);
+class PostgresPoolDriverImpl
+  extends PostgresQueryable<PoolClient>
+  implements SqlDriver<PostgresBinding>
+{
+  private readonly pool: PoolType;
+  #closed = false;
+
+  constructor(options: PostgresDriverOptions & { connect: { pool: PoolType } }) {
+    super({
+      cursorBatchSize: options.cursor?.batchSize ?? DEFAULT_BATCH_SIZE,
+      cursorDisabled: options.cursor?.disabled ?? false,
+    });
+    this.pool = options.connect.pool;
+  }
+
+  get state(): SqlDriverState {
+    return this.#closed ? 'closed' : 'connected';
+  }
+
+  // Bound drivers are created via createBoundDriverFromBinding with pool already
+  // configured; connect is intentionally no-op.
+  async connect(_binding: PostgresBinding): Promise<void> {}
+
+  async acquireConnection(): Promise<SqlConnection> {
+    const client = await this.acquireClient();
+    return new PostgresConnectionImpl(client, this.options);
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
+    await this.pool.end();
+  }
+
+  async acquireClient(): Promise<PoolClient> {
+    return this.pool.connect();
+  }
+
+  async releaseClient(client: PoolClient): Promise<void> {
+    client.release();
+  }
+}
+
+class PostgresDirectDriverImpl
+  extends PostgresQueryable<Client>
+  implements SqlDriver<PostgresBinding>
+{
+  private readonly directClient: Client;
+  readonly #connectionMutex = new AsyncMutex();
+  #closed = false;
+  #connected = false;
+  #connectPromise: Promise<void> | undefined;
+
+  constructor(options: PostgresDriverOptions & { connect: { client: Client } }) {
+    super({
+      cursorBatchSize: options.cursor?.batchSize ?? DEFAULT_BATCH_SIZE,
+      cursorDisabled: options.cursor?.disabled ?? false,
+    });
+    this.directClient = options.connect.client;
+  }
+
+  get state(): SqlDriverState {
+    return this.#closed ? 'closed' : 'connected';
+  }
+
+  // Bound drivers are created via createBoundDriverFromBinding with client already
+  // configured; connect is intentionally no-op.
+  async connect(_binding: PostgresBinding): Promise<void> {}
+
+  async acquireConnection(): Promise<SqlConnection> {
+    const releaseLease = await this.#connectionMutex.lock();
+    try {
+      const client = await this.acquireClient();
+      return new PostgresConnectionImpl(client, this.options, releaseLease);
+    } catch (error) {
+      releaseLease();
+      throw error;
+    }
+  }
+
+  async close(): Promise<void> {
+    const releaseLease = await this.#connectionMutex.lock();
+    try {
+      if (this.#closed) {
+        return;
+      }
+      this.#closed = true;
+      await this.directClient.end();
+      this.#connected = false;
+    } finally {
+      releaseLease();
+    }
+  }
+
+  async acquireClient(): Promise<Client> {
+    if (this.#connected) {
+      return this.directClient;
+    }
+    if (this.#connectPromise !== undefined) {
+      await this.#connectPromise;
+      return this.directClient;
+    }
+
+    this.#connectPromise = (async () => {
+      try {
+        await this.directClient.connect();
+      } catch (error: unknown) {
+        if (!isAlreadyConnectedError(error)) {
+          throw error;
+        }
+      } finally {
+        this.#connectPromise = undefined;
+      }
+      this.#connected = true;
+    })();
+    await this.#connectPromise;
+
+    return this.directClient;
+  }
+
+  async releaseClient(_client: Client): Promise<void> {}
+}
+
+export function createBoundDriverFromBinding(
+  binding: PostgresBinding,
+  cursorOpts: PostgresDriverCreateOptions['cursor'],
+): SqlDriver<PostgresBinding> {
+  switch (binding.kind) {
+    case 'url': {
+      const pool = new Pool({
+        connectionString: binding.url,
+        connectionTimeoutMillis: 20_000,
+        idleTimeoutMillis: 30_000,
+      });
+      return new PostgresPoolDriverImpl({
+        connect: { pool },
+        cursor: cursorOpts,
+      });
+    }
+    case 'pgPool':
+      return new PostgresPoolDriverImpl({
+        connect: { pool: binding.pool },
+        cursor: cursorOpts,
+      });
+    case 'pgClient':
+      return new PostgresDirectDriverImpl({
+        connect: { client: binding.client },
+        cursor: cursorOpts,
+      });
+  }
 }
 
 function readCursor<Row>(cursor: Cursor<Row>, size: number): Promise<Row[]> {
@@ -233,3 +397,7 @@ function readCursor<Row>(cursor: Cursor<Row>, size: number): Promise<Row[]> {
 function closeCursor(cursor: Cursor<unknown>): Promise<void> {
   return callbackToPromise((cb) => cursor.close(cb));
 }
+
+function rethrowNormalizedError(error: unknown): never {
+  throw normalizePgError(error);
+}

package/dist/callback-to-promise.d.ts

@@ -1,7 +0,0 @@
-/**
- * Wraps a Node-style callback function into a Promise.
- * Supports both (err) => void and (err, result) => void patterns.
- */
-export declare function callbackToPromise(fn: (callback: (err: Error | null | undefined) => void) => void): Promise<void>;
-export declare function callbackToPromise<T>(fn: (callback: (err: Error | null | undefined, result: T) => void) => void): Promise<T>;
-//# sourceMappingURL=callback-to-promise.d.ts.map

package/dist/callback-to-promise.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"callback-to-promise.d.ts","sourceRoot":"","sources":["../src/callback-to-promise.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,KAAK,IAAI,KAAK,IAAI,GAC9D,OAAO,CAAC,IAAI,CAAC,CAAC;AACjB,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,CAAC,KAAK,IAAI,KAAK,IAAI,GACzE,OAAO,CAAC,CAAC,CAAC,CAAC"}