@prisma-next/driver-postgres 0.3.0-dev.7 → 0.3.0-dev.70

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [Prisma Data, Inc]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -12,7 +12,7 @@ PostgreSQL driver for Prisma Next.
 
 The PostgreSQL driver provides transport and connection management for PostgreSQL databases. It implements the `SqlDriver` interface for executing SQL statements, explaining queries, and managing connections.
 
-Drivers are transport-agnostic: they own pooling, connection management, and transport protocol (TCP, HTTP, etc.), but contain no dialect-specific logic. All dialect behavior lives in adapters.
+In Prisma Next, "driver" refers to the Prisma Next interface (not the underlying `pg` library). Drivers are transport-agnostic: they own pooling, connection management, and transport protocol (TCP, HTTP, etc.), but contain no dialect-specific logic. All dialect behavior lives in adapters. Instantiation is separate from connection; `create()` returns an unbound driver, `connect(binding)` binds at the boundary ([ADR 159](../../../../docs/architecture%20docs/adrs/ADR%20159%20-%20Driver%20Terminology%20and%20Lifecycle.md)).
 
 This package spans multiple planes:
 - **Migration plane** (`src/exports/control.ts`): Control plane entry point for driver descriptors
@@ -74,7 +74,7 @@ flowchart TD
 
 ## Dependencies
 
-- **`@prisma-next/sql-target`**: Driver SPI and SQL types
+- **`@prisma-next/sql-contract`**: SQL contract types (via `@prisma-next/sql-contract/types`)
 
 ## Related Subsystems
 
@@ -82,32 +82,32 @@ flowchart TD
 
 ## Related ADRs
 
-- [ADR 005 - Thin Core Fat Targets](../../docs/architecture%20docs/adrs/ADR%20005%20-%20Thin%20Core%20Fat%20Targets.md)
-- [ADR 016 - Adapter SPI for Lowering](../../docs/architecture%20docs/adrs/ADR%20016%20-%20Adapter%20SPI%20for%20Lowering.md)
+- [ADR 159 — Driver Terminology and Lifecycle](../../../../docs/architecture%20docs/adrs/ADR%20159%20-%20Driver%20Terminology%20and%20Lifecycle.md)
+- [ADR 005 — Thin Core Fat Targets](../../../../docs/architecture%20docs/adrs/ADR%20005%20-%20Thin%20Core%20Fat%20Targets.md)
+- [ADR 016 — Adapter SPI for Lowering](../../../../docs/architecture%20docs/adrs/ADR%20016%20-%20Adapter%20SPI%20for%20Lowering.md)
 
 ## Usage
 
+Use the descriptor + connect lifecycle:
+
 ```typescript
-import { createPostgresDriver } from '@prisma-next/driver-postgres/runtime';
-import { createRuntime } from '@prisma-next/sql-runtime';
-
-const driver = createPostgresDriver({
-  connectionString: process.env.DATABASE_URL,
-});
-
-const runtime = createRuntime({
-  contract,
-  adapter: postgresAdapter,
-  driver,
-});
+import postgresDriver from '@prisma-next/driver-postgres/runtime';
+
+const driver = postgresDriver.create({ cursor: { batchSize: 100 } });
+await driver.connect({ kind: 'url', url: process.env.DATABASE_URL });
+// driver is now bound; use acquireConnection, query, execute, etc.
 ```
 
+Binding variants:
+- `{ kind: 'url', url }`: Driver creates a Pool from the connection string
+- `{ kind: 'pgPool', pool }`: Use an existing pg Pool
+- `{ kind: 'pgClient', client }`: Use an existing pg Client (direct connection)
+
 ## Exports
 
 - `./runtime`: Runtime entry point for driver implementation
-  - `createPostgresDriver(connectionString, options?)`: Create driver from connection string
-  - `createPostgresDriverFromOptions(options)`: Create driver from options object
-  - Types: `PostgresDriverOptions`, `QueryResult`
+  - Default: `postgresRuntimeDriverDescriptor` — use `create()` for unbound driver, then `connect(binding)`
+  - Types: `PostgresBinding`, `PostgresDriverCreateOptions`, `QueryResult`
 - `./control`: Control plane entry point for driver descriptors
   - Default export: `DriverDescriptor` for use in `prisma-next.config.ts`
 

package/dist/control.d.mts

@@ -0,0 +1,30 @@
+import { Client } from "pg";
+import { ControlDriverDescriptor, ControlDriverInstance } from "@prisma-next/core-control-plane/types";
+
+//#region src/exports/control.d.ts
+
+/**
+ * Postgres control driver instance for control-plane operations.
+ * Implements ControlDriverInstance<'sql', 'postgres'> for database queries.
+ */
+declare class PostgresControlDriver implements ControlDriverInstance<'sql', 'postgres'> {
+  private readonly client;
+  readonly familyId: "sql";
+  readonly targetId: "postgres";
+  /**
+   * @deprecated Use targetId instead
+   */
+  readonly target: "postgres";
+  constructor(client: Client);
+  query<Row = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<{
+    readonly rows: Row[];
+  }>;
+  close(): Promise<void>;
+}
+/**
+ * Postgres driver descriptor for CLI config.
+ */
+declare const postgresDriverDescriptor: ControlDriverDescriptor<'sql', 'postgres', PostgresControlDriver>;
+//#endregion
+export { PostgresControlDriver, postgresDriverDescriptor as default };
+//# sourceMappingURL=control.d.mts.map

package/dist/control.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.mts","names":[],"sources":["../src/exports/control.ts"],"sourcesContent":[],"mappings":";;;;;;;AAgBA;;AAUoB,cAVP,qBAAA,YAAiC,qBAU1B,CAAA,KAAA,EAAA,UAAA,CAAA,CAAA;EAGU,iBAAA,MAAA;EAAzB,SAAA,QAAA,EAAA,KAAA;EASY,SAAA,QAAA,EAAA,UAAA;EAtB6B;;AAyB7C;;sBAjBsC;cAEnB,oEAGf;mBAAyB;;WASb;;;;;cAQX,0BAA0B,2CAA2C"}

package/dist/control.mjs

@@ -0,0 +1,68 @@
+import { i as postgresDriverDescriptorMeta, r as normalizePgError } from "./normalize-error-BU6yV-XB.mjs";
+import { errorRuntime } from "@prisma-next/core-control-plane/errors";
+import { SqlQueryError } from "@prisma-next/sql-errors";
+import { ifDefined } from "@prisma-next/utils/defined";
+import { redactDatabaseUrl } from "@prisma-next/utils/redact-db-url";
+import { Client } from "pg";
+
+//#region src/exports/control.ts
+/**
+* Postgres control driver instance for control-plane operations.
+* Implements ControlDriverInstance<'sql', 'postgres'> for database queries.
+*/
+var PostgresControlDriver = class {
+	familyId = "sql";
+	targetId = "postgres";
+	/**
+	* @deprecated Use targetId instead
+	*/
+	target = "postgres";
+	constructor(client) {
+		this.client = client;
+	}
+	async query(sql, params) {
+		try {
+			return { rows: (await this.client.query(sql, params)).rows };
+		} catch (error) {
+			throw normalizePgError(error);
+		}
+	}
+	async close() {
+		await this.client.end();
+	}
+};
+/**
+* Postgres driver descriptor for CLI config.
+*/
+const postgresDriverDescriptor = {
+	...postgresDriverDescriptorMeta,
+	async create(url) {
+		const client = new Client({ connectionString: url });
+		try {
+			await client.connect();
+			return new PostgresControlDriver(client);
+		} catch (error) {
+			const normalized = normalizePgError(error);
+			const redacted = redactDatabaseUrl(url);
+			try {
+				await client.end();
+			} catch {}
+			const codeFromSqlState = SqlQueryError.is(normalized) ? normalized.sqlState : void 0;
+			const causeCode = "cause" in normalized && normalized.cause ? normalized.cause.code : void 0;
+			const code = codeFromSqlState ?? causeCode;
+			throw errorRuntime("Database connection failed", {
+				why: normalized.message,
+				fix: "Verify the database URL, ensure the database is reachable, and confirm credentials/permissions",
+				meta: {
+					...ifDefined("code", code),
+					...redacted
+				}
+			});
+		}
+	}
+};
+var control_default = postgresDriverDescriptor;
+
+//#endregion
+export { PostgresControlDriver, control_default as default };
+//# sourceMappingURL=control.mjs.map

package/dist/control.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.mjs","names":["client: Client","postgresDriverDescriptor: ControlDriverDescriptor<'sql', 'postgres', PostgresControlDriver>"],"sources":["../src/exports/control.ts"],"sourcesContent":["import { errorRuntime } from '@prisma-next/core-control-plane/errors';\nimport type {\n  ControlDriverDescriptor,\n  ControlDriverInstance,\n} from '@prisma-next/core-control-plane/types';\nimport { SqlQueryError } from '@prisma-next/sql-errors';\nimport { ifDefined } from '@prisma-next/utils/defined';\nimport { redactDatabaseUrl } from '@prisma-next/utils/redact-db-url';\nimport { Client } from 'pg';\nimport { postgresDriverDescriptorMeta } from '../core/descriptor-meta';\nimport { normalizePgError } from '../normalize-error';\n\n/**\n * Postgres control driver instance for control-plane operations.\n * Implements ControlDriverInstance<'sql', 'postgres'> for database queries.\n */\nexport class PostgresControlDriver implements ControlDriverInstance<'sql', 'postgres'> {\n  readonly familyId = 'sql' as const;\n  readonly targetId = 'postgres' as const;\n  /**\n   * @deprecated Use targetId instead\n   */\n  readonly target = 'postgres' as const;\n\n  constructor(private readonly client: Client) {}\n\n  async query<Row = Record<string, unknown>>(\n    sql: string,\n    params?: readonly unknown[],\n  ): Promise<{ readonly rows: Row[] }> {\n    try {\n      const result = await this.client.query(sql, params as unknown[] | undefined);\n      return { rows: result.rows as Row[] };\n    } catch (error) {\n      throw normalizePgError(error);\n    }\n  }\n\n  async close(): Promise<void> {\n    await this.client.end();\n  }\n}\n\n/**\n * Postgres driver descriptor for CLI config.\n */\nconst postgresDriverDescriptor: ControlDriverDescriptor<'sql', 'postgres', PostgresControlDriver> =\n  {\n    ...postgresDriverDescriptorMeta,\n    async create(url: string): Promise<PostgresControlDriver> {\n      const client = new Client({ connectionString: url });\n      try {\n        await client.connect();\n        return new PostgresControlDriver(client);\n      } catch (error) {\n        const normalized = normalizePgError(error);\n        const redacted = redactDatabaseUrl(url);\n        try {\n          await client.end();\n        } catch {\n          // ignore\n        }\n\n        const codeFromSqlState = SqlQueryError.is(normalized) ? normalized.sqlState : undefined;\n        const causeCode =\n          'cause' in normalized && normalized.cause\n            ? (normalized.cause as { code?: unknown }).code\n            : undefined;\n        const code = codeFromSqlState ?? causeCode;\n\n        throw errorRuntime('Database connection failed', {\n          why: normalized.message,\n          fix: 'Verify the database URL, ensure the database is reachable, and confirm credentials/permissions',\n          meta: {\n            ...ifDefined('code', code),\n            ...redacted,\n          },\n        });\n      }\n    },\n  };\n\nexport default postgresDriverDescriptor;\n"],"mappings":";;;;;;;;;;;;AAgBA,IAAa,wBAAb,MAAuF;CACrF,AAAS,WAAW;CACpB,AAAS,WAAW;;;;CAIpB,AAAS,SAAS;CAElB,YAAY,AAAiBA,QAAgB;EAAhB;;CAE7B,MAAM,MACJ,KACA,QACmC;AACnC,MAAI;AAEF,UAAO,EAAE,OADM,MAAM,KAAK,OAAO,MAAM,KAAK,OAAgC,EACtD,MAAe;WAC9B,OAAO;AACd,SAAM,iBAAiB,MAAM;;;CAIjC,MAAM,QAAuB;AAC3B,QAAM,KAAK,OAAO,KAAK;;;;;;AAO3B,MAAMC,2BACJ;CACE,GAAG;CACH,MAAM,OAAO,KAA6C;EACxD,MAAM,SAAS,IAAI,OAAO,EAAE,kBAAkB,KAAK,CAAC;AACpD,MAAI;AACF,SAAM,OAAO,SAAS;AACtB,UAAO,IAAI,sBAAsB,OAAO;WACjC,OAAO;GACd,MAAM,aAAa,iBAAiB,MAAM;GAC1C,MAAM,WAAW,kBAAkB,IAAI;AACvC,OAAI;AACF,UAAM,OAAO,KAAK;WACZ;GAIR,MAAM,mBAAmB,cAAc,GAAG,WAAW,GAAG,WAAW,WAAW;GAC9E,MAAM,YACJ,WAAW,cAAc,WAAW,QAC/B,WAAW,MAA6B,OACzC;GACN,MAAM,OAAO,oBAAoB;AAEjC,SAAM,aAAa,8BAA8B;IAC/C,KAAK,WAAW;IAChB,KAAK;IACL,MAAM;KACJ,GAAG,UAAU,QAAQ,KAAK;KAC1B,GAAG;KACJ;IACF,CAAC;;;CAGP;AAEH,sBAAe"}

package/dist/normalize-error-BU6yV-XB.mjs

@@ -0,0 +1,125 @@
+import { SqlConnectionError, SqlQueryError } from "@prisma-next/sql-errors";
+
+//#region src/core/descriptor-meta.ts
+const postgresDriverDescriptorMeta = {
+	kind: "driver",
+	familyId: "sql",
+	targetId: "postgres",
+	id: "postgres",
+	version: "0.0.1",
+	capabilities: {}
+};
+
+//#endregion
+//#region src/normalize-error.ts
+/**
+* Checks if an error is a connection-related error.
+*/
+function isConnectionError(error) {
+	const code = error.code;
+	if (code) {
+		if (code === "ECONNRESET" || code === "ETIMEDOUT" || code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EHOSTUNREACH") return true;
+	}
+	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) {
+	const code = error.code;
+	if (code) {
+		if (code === "ETIMEDOUT" || code === "ECONNRESET") return true;
+		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"
+];
+/**
+* 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.
+*/
+function isPostgresError(error) {
+	if (!(error instanceof Error)) return false;
+	const pgError = error;
+	if (pgError.code && isPostgresSqlState(pgError.code)) return true;
+	return PG_ERROR_PROPERTIES.some((prop) => pgError[prop] !== void 0);
+}
+/**
+* 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.
+*/
+function isAlreadyConnectedError(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) {
+	if (!code) return false;
+	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
+*/
+function normalizePgError(error) {
+	if (!(error instanceof Error)) return new Error(String(error));
+	const pgError = error;
+	if (isPostgresSqlState(pgError.code)) {
+		const options = {
+			cause: error,
+			sqlState: pgError.code
+		};
+		if (pgError.constraint !== void 0) options.constraint = pgError.constraint;
+		if (pgError.table !== void 0) options.table = pgError.table;
+		if (pgError.column !== void 0) options.column = pgError.column;
+		if (pgError.detail !== void 0) options.detail = pgError.detail;
+		return new SqlQueryError(error.message, options);
+	}
+	if (isConnectionError(error)) return new SqlConnectionError(error.message, {
+		cause: error,
+		transient: isTransientConnectionError(error)
+	});
+	return error;
+}
+
+//#endregion
+export { postgresDriverDescriptorMeta as i, isPostgresError as n, normalizePgError as r, isAlreadyConnectedError as t };
+//# sourceMappingURL=normalize-error-BU6yV-XB.mjs.map

package/dist/normalize-error-BU6yV-XB.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-error-BU6yV-XB.mjs","names":["options: {\n      cause: Error;\n      sqlState: string;\n      constraint?: string;\n      table?: string;\n      column?: string;\n      detail?: string;\n    }"],"sources":["../src/core/descriptor-meta.ts","../src/normalize-error.ts"],"sourcesContent":["export const postgresDriverDescriptorMeta = {\n  kind: 'driver',\n  familyId: 'sql',\n  targetId: 'postgres',\n  id: 'postgres',\n  version: '0.0.1',\n  capabilities: {},\n} as const;\n","import { SqlConnectionError, SqlQueryError } from '@prisma-next/sql-errors';\n\n/**\n * Postgres error shape from the pg library.\n *\n * Note: The pg library doesn't export a DatabaseError type or interface, but errors\n * thrown by pg.query() and pg.Client have this shape at runtime. We define this\n * interface to match the actual runtime structure documented in the pg library\n * (https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/errors.js).\n *\n * The @types/pg package also doesn't provide comprehensive error type definitions,\n * so we define our own interface based on the runtime error properties.\n */\ninterface PostgresError extends Error {\n  readonly code?: string;\n  readonly constraint?: string;\n  readonly table?: string;\n  readonly column?: string;\n  readonly detail?: string;\n  readonly hint?: string;\n  readonly position?: string;\n  readonly internalPosition?: string;\n  readonly internalQuery?: string;\n  readonly where?: string;\n  readonly schema?: string;\n  readonly file?: string;\n  readonly line?: string;\n  readonly routine?: string;\n}\n\n/**\n * Checks if an error is a connection-related error.\n */\nfunction isConnectionError(error: Error): boolean {\n  const code = (error as { code?: string }).code;\n  if (code) {\n    // Node.js error codes for connection issues\n    if (\n      code === 'ECONNRESET' ||\n      code === 'ETIMEDOUT' ||\n      code === 'ECONNREFUSED' ||\n      code === 'ENOTFOUND' ||\n      code === 'EHOSTUNREACH'\n    ) {\n      return true;\n    }\n  }\n\n  // Check error message for connection-related strings\n  const message = error.message.toLowerCase();\n  if (\n    message.includes('connection terminated') ||\n    message.includes('connection closed') ||\n    message.includes('connection refused') ||\n    message.includes('connection timeout') ||\n    message.includes('connection reset')\n  ) {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Checks if a connection error is transient (might succeed on retry).\n */\nfunction isTransientConnectionError(error: Error): boolean {\n  const code = (error as { code?: string }).code;\n  if (code) {\n    // Timeouts and connection resets are often transient\n    if (code === 'ETIMEDOUT' || code === 'ECONNRESET') {\n      return true;\n    }\n    // Connection refused is usually not transient (server is down)\n    if (code === 'ECONNREFUSED') {\n      return false;\n    }\n  }\n\n  const message = error.message.toLowerCase();\n  if (message.includes('timeout') || message.includes('connection reset')) {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * PostgreSQL-specific error properties that indicate an error originated from pg library.\n * These properties are not present on Node.js system errors.\n * Excludes generic properties like 'detail', 'file', 'line', and 'position' that could appear on any error.\n */\nconst PG_ERROR_PROPERTIES = [\n  'constraint',\n  'table',\n  'column',\n  'hint',\n  'internalPosition',\n  'internalQuery',\n  'where',\n  'schema',\n  'routine',\n] as const;\n\n/**\n * Type predicate to check if an error is a Postgres error from the pg library.\n *\n * Distinguishes pg library errors from Node.js system errors by checking for:\n * - SQLSTATE codes (5-character alphanumeric codes like '23505', '42601')\n * - pg-specific properties (constraint, table, column, hint, etc.) that Node.js errors don't have\n *\n * Node.js system errors (ECONNREFUSED, ETIMEDOUT, etc.) are excluded to prevent false positives.\n */\nexport function isPostgresError(error: unknown): error is PostgresError {\n  if (!(error instanceof Error)) {\n    return false;\n  }\n\n  const pgError = error as PostgresError;\n\n  // Check for SQLSTATE code (5-character alphanumeric) - primary indicator of pg errors\n  if (pgError.code && isPostgresSqlState(pgError.code)) {\n    return true;\n  }\n\n  // Check for pg-specific properties that Node.js system errors don't have\n  // These properties indicate the error originated from pg library query execution\n  return PG_ERROR_PROPERTIES.some((prop) => pgError[prop] !== undefined);\n}\n\n/**\n * Checks if an error is an \"already connected\" error from pg.Client.connect().\n * When calling connect() on an already-connected client, pg throws an error that can be safely ignored.\n */\nexport function isAlreadyConnectedError(error: unknown): error is Error {\n  if (!(error instanceof Error)) {\n    return false;\n  }\n  const message = error.message.toLowerCase();\n  return message.includes('already') && message.includes('connected');\n}\n\n/**\n * Checks if an error code is a Postgres SQLSTATE (5-character alphanumeric code).\n * SQLSTATE codes are standardized SQL error codes (e.g., '23505' for unique violation).\n */\nfunction isPostgresSqlState(code: string | undefined): boolean {\n  if (!code) {\n    return false;\n  }\n  // Postgres SQLSTATE codes are 5-character alphanumeric strings\n  // Examples: '23505' (unique violation), '42501' (insufficient privilege), '42601' (syntax error)\n  return /^[A-Z0-9]{5}$/.test(code);\n}\n\n/**\n * Normalizes a Postgres error into a SQL-shared error type.\n *\n * - Postgres SQLSTATE errors (5-char codes like '23505') → SqlQueryError\n * - Connection errors (ECONNRESET, ETIMEDOUT, etc.) → SqlConnectionError\n * - Unknown errors → returns the original error as-is\n *\n * The original error is preserved via Error.cause to maintain stack traces.\n *\n * @param error - The error to normalize (typically from pg library)\n * @returns SqlQueryError for query-related failures\n * @returns SqlConnectionError for connection-related failures\n * @returns The original error if it cannot be normalized\n */\nexport function normalizePgError(error: unknown): SqlQueryError | SqlConnectionError | Error {\n  if (!(error instanceof Error)) {\n    // Wrap non-Error values in an Error object\n    return new Error(String(error));\n  }\n\n  const pgError = error as PostgresError;\n\n  // Check for Postgres SQLSTATE (query errors)\n  if (isPostgresSqlState(pgError.code)) {\n    // isPostgresSqlState ensures code is defined and is a valid SQLSTATE\n    // biome-ignore lint/style/noNonNullAssertion: isPostgresSqlState guarantees code is defined\n    const sqlState = pgError.code!;\n    const options: {\n      cause: Error;\n      sqlState: string;\n      constraint?: string;\n      table?: string;\n      column?: string;\n      detail?: string;\n    } = {\n      cause: error,\n      sqlState,\n    };\n    if (pgError.constraint !== undefined) {\n      options.constraint = pgError.constraint;\n    }\n    if (pgError.table !== undefined) {\n      options.table = pgError.table;\n    }\n    if (pgError.column !== undefined) {\n      options.column = pgError.column;\n    }\n    if (pgError.detail !== undefined) {\n      options.detail = pgError.detail;\n    }\n    return new SqlQueryError(error.message, options);\n  }\n\n  // Check for connection errors\n  if (isConnectionError(error)) {\n    return new SqlConnectionError(error.message, {\n      cause: error,\n      transient: isTransientConnectionError(error),\n    });\n  }\n\n  // Unknown error - return as-is to preserve original error and stack trace\n  return error;\n}\n"],"mappings":";;;AAAA,MAAa,+BAA+B;CAC1C,MAAM;CACN,UAAU;CACV,UAAU;CACV,IAAI;CACJ,SAAS;CACT,cAAc,EAAE;CACjB;;;;;;;AC0BD,SAAS,kBAAkB,OAAuB;CAChD,MAAM,OAAQ,MAA4B;AAC1C,KAAI,MAEF;MACE,SAAS,gBACT,SAAS,eACT,SAAS,kBACT,SAAS,eACT,SAAS,eAET,QAAO;;CAKX,MAAM,UAAU,MAAM,QAAQ,aAAa;AAC3C,KACE,QAAQ,SAAS,wBAAwB,IACzC,QAAQ,SAAS,oBAAoB,IACrC,QAAQ,SAAS,qBAAqB,IACtC,QAAQ,SAAS,qBAAqB,IACtC,QAAQ,SAAS,mBAAmB,CAEpC,QAAO;AAGT,QAAO;;;;;AAMT,SAAS,2BAA2B,OAAuB;CACzD,MAAM,OAAQ,MAA4B;AAC1C,KAAI,MAAM;AAER,MAAI,SAAS,eAAe,SAAS,aACnC,QAAO;AAGT,MAAI,SAAS,eACX,QAAO;;CAIX,MAAM,UAAU,MAAM,QAAQ,aAAa;AAC3C,KAAI,QAAQ,SAAS,UAAU,IAAI,QAAQ,SAAS,mBAAmB,CACrE,QAAO;AAGT,QAAO;;;;;;;AAQT,MAAM,sBAAsB;CAC1B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;AAWD,SAAgB,gBAAgB,OAAwC;AACtE,KAAI,EAAE,iBAAiB,OACrB,QAAO;CAGT,MAAM,UAAU;AAGhB,KAAI,QAAQ,QAAQ,mBAAmB,QAAQ,KAAK,CAClD,QAAO;AAKT,QAAO,oBAAoB,MAAM,SAAS,QAAQ,UAAU,OAAU;;;;;;AAOxE,SAAgB,wBAAwB,OAAgC;AACtE,KAAI,EAAE,iBAAiB,OACrB,QAAO;CAET,MAAM,UAAU,MAAM,QAAQ,aAAa;AAC3C,QAAO,QAAQ,SAAS,UAAU,IAAI,QAAQ,SAAS,YAAY;;;;;;AAOrE,SAAS,mBAAmB,MAAmC;AAC7D,KAAI,CAAC,KACH,QAAO;AAIT,QAAO,gBAAgB,KAAK,KAAK;;;;;;;;;;;;;;;;AAiBnC,SAAgB,iBAAiB,OAA4D;AAC3F,KAAI,EAAE,iBAAiB,OAErB,QAAO,IAAI,MAAM,OAAO,MAAM,CAAC;CAGjC,MAAM,UAAU;AAGhB,KAAI,mBAAmB,QAAQ,KAAK,EAAE;EAIpC,MAAMA,UAOF;GACF,OAAO;GACP,UAVe,QAAQ;GAWxB;AACD,MAAI,QAAQ,eAAe,OACzB,SAAQ,aAAa,QAAQ;AAE/B,MAAI,QAAQ,UAAU,OACpB,SAAQ,QAAQ,QAAQ;AAE1B,MAAI,QAAQ,WAAW,OACrB,SAAQ,SAAS,QAAQ;AAE3B,MAAI,QAAQ,WAAW,OACrB,SAAQ,SAAS,QAAQ;AAE3B,SAAO,IAAI,cAAc,MAAM,SAAS,QAAQ;;AAIlD,KAAI,kBAAkB,MAAM,CAC1B,QAAO,IAAI,mBAAmB,MAAM,SAAS;EAC3C,OAAO;EACP,WAAW,2BAA2B,MAAM;EAC7C,CAAC;AAIJ,QAAO"}

package/dist/runtime.d.mts

@@ -0,0 +1,36 @@
+import { Client, Pool, QueryResult as QueryResult$1, QueryResultRow } from "pg";
+import { RuntimeDriverDescriptor, RuntimeDriverInstance } from "@prisma-next/core-execution-plane/types";
+import { SqlDriver } from "@prisma-next/sql-relational-core/ast";
+
+//#region src/postgres-driver.d.ts
+type QueryResult<T extends QueryResultRow = QueryResultRow> = QueryResult$1<T>;
+type PostgresBinding = {
+  readonly kind: 'url';
+  readonly url: string;
+} | {
+  readonly kind: 'pgPool';
+  readonly pool: Pool;
+} | {
+  readonly kind: 'pgClient';
+  readonly client: Client;
+};
+interface PostgresCursorOptions {
+  readonly batchSize?: number;
+  readonly disabled?: boolean;
+}
+interface PostgresDriverOptions {
+  readonly connect: {
+    client: Client;
+  } | {
+    pool: Pool;
+  };
+  readonly cursor?: PostgresCursorOptions | undefined;
+}
+type PostgresDriverCreateOptions = Omit<PostgresDriverOptions, 'connect'>;
+//#endregion
+//#region src/exports/runtime.d.ts
+type PostgresRuntimeDriver = RuntimeDriverInstance<'sql', 'postgres'> & SqlDriver<PostgresBinding>;
+declare const postgresRuntimeDriverDescriptor: RuntimeDriverDescriptor<'sql', 'postgres', PostgresDriverCreateOptions, PostgresRuntimeDriver>;
+//#endregion
+export { type PostgresBinding, type PostgresDriverCreateOptions, PostgresRuntimeDriver, type QueryResult, postgresRuntimeDriverDescriptor as default };
+//# sourceMappingURL=runtime.d.mts.map

package/dist/runtime.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/postgres-driver.ts","../src/exports/runtime.ts"],"sourcesContent":[],"mappings":";;;;;KAsBY,sBAAsB,iBAAiB,kBAAkB,cAAc;KAEvE,eAAA;;EAFA,SAAA,GAAA,EAAW,MAAA;CAAW,GAAA;EAAiB,SAAA,IAAA,EAAA,QAAA;EAAgC,SAAA,IAAA,EAIrC,IAJqC;CAAd,GAAA;EAAa,SAAA,IAAA,EAAA,UAAA;EAEtE,SAAA,MAAA,EAGsC,MAHvB;AAK3B,CAAA;AAKU,UALO,qBAAA,CAKc;EACD,SAAA,SAAA,CAAA,EAAA,MAAA;EAAmB,SAAA,QAAA,CAAA,EAAA,OAAA;;UADvC,qBAAA,CAE+B;EAG7B,SAAA,OAAA,EAAA;YAJkB;;UAAmB;ECjBrC,CAAA;EAAwB,SAAA,MAAA,CAAA,EDkBhB,qBClBgB,GAAA,SAAA;;AAClC,KDoBU,2BAAA,GAA8B,ICpBxC,CDoB6C,qBCpB7C,EAAA,SAAA,CAAA;;;KADU,qBAAA,GAAwB,2CAClC,UAAU;cA6HN,iCAAiC,2CAGrC,6BACA"}