@prisma-next/postgres 0.3.0-dev.43 → 0.3.0-dev.45

package/README.md

@@ -1,23 +1,26 @@
 # @prisma-next/postgres
 
-One-liner lazy Postgres client for Prisma Next runtime composition.
+Composition-root Postgres helper that builds a Prisma Next runtime client and exposes SQL, ORM, schema, and Kysely-integrated query access.
 
 ## Package Classification
 
-- **Domain**: targets
-- **Layer**: clients
+- **Domain**: extensions
+- **Layer**: adapters
 - **Plane**: runtime
 
 ## Overview
 
-`@prisma-next/postgres` (or `@prisma-next/postgres/runtime`) exposes a single `postgres(...)` helper that composes the SQL execution stack for Postgres and returns static query roots immediately:
+`@prisma-next/postgres/runtime` exposes a single `postgres(...)` helper that composes the Postgres execution stack and returns query/runtime roots:
 
 - `db.sql`
+- `db.kysely(runtime)`
 - `db.schema`
+- `db.orm`
 - `db.context`
 - `db.stack`
 
-Runtime and connection resources are deferred until `await db.runtime()` is called. The getter returns `Promise<Runtime>`.
+Runtime resources are deferred until `db.runtime()` or `db.connect(...)` is called.
+Connection binding can be provided up front (`url`, `pg`, `binding`) or deferred via `db.connect(...)`.
 
 When URL binding is used, pool timeouts are configurable via `poolOptions`:
 
@@ -27,11 +30,12 @@ When URL binding is used, pool timeouts are configurable via `poolOptions`:
 ## Responsibilities
 
 - Build a static Postgres execution stack from target, adapter, and driver descriptors
-- Build static query roots from the execution context
+- Build typed SQL and Kysely lane instances from the same execution context
+- Build static schema and ORM roots from the execution context
 - Normalize runtime binding input (`binding`, `url`, `pg`)
-- Lazily instantiate stack and driver on first `await db.runtime()` call
-- Connect driver with resolved binding before creating runtime
-- Memoize runtime so repeated `await db.runtime()` calls return one instance
+- Lazily instantiate runtime resources on first `db.runtime()` or `db.connect(...)` call
+- Connect the internal Postgres driver through `db.connect(...)` or from initial binding options
+- Memoize runtime so repeated `db.runtime()` calls return one instance
 
 ## Dependencies
 
@@ -41,23 +45,26 @@ When URL binding is used, pool timeouts are configurable via `poolOptions`:
 - `@prisma-next/adapter-postgres` for adapter descriptor
 - `@prisma-next/driver-postgres` for driver descriptor
 - `@prisma-next/sql-lane` for `sql(...)`
+- `@prisma-next/integration-kysely` for `KyselyPrismaDialect` and contract-to-Kysely typing
 - `@prisma-next/sql-relational-core` for `schema(...)`
+- `@prisma-next/sql-orm-client` for `orm(...)`
 - `@prisma-next/sql-contract` for `validateContract(...)` and contract types
-- `pg` for binding validation when using `pg` (Pool or Client) input
+- `kysely` for query-builder API surface
+- `pg` for lazy `Pool` construction when using URL binding
 
 ## Architecture
 
 ```mermaid
 flowchart TD
     App[App Code] --> Client[postgres(...)]
-    Client --> Static[Static roots: sql schema context stack]
+    Client --> Static[Roots: sql kysely(runtime) schema orm context stack]
     Client --> Lazy[runtime()]
 
     Lazy --> Instantiate[instantiateExecutionStack]
     Lazy --> Bind[Resolve binding: url or pg]
-    Bind --> Assert[Assert stackInstance.driver]
-    Assert --> Connect[driver.connect binding]
-    Connect --> Runtime[createRuntime]
+    Bind --> Pool[pg.Pool for url binding]
+    Bind --> Reuse[Reuse Pool or Client for pg binding]
+    Lazy --> Runtime[createRuntime]
 
     Runtime --> Target[@prisma-next/target-postgres]
     Runtime --> Adapter[@prisma-next/adapter-postgres]
@@ -71,3 +78,4 @@ flowchart TD
 - Spec: `agent-os/specs/2026-02-10-postgres-one-liner-lazy-client/spec.md`
 - Architecture: `docs/Architecture Overview.md`
 - Subsystem: `docs/architecture docs/subsystems/4. Runtime & Plugin Framework.md`
+- Subsystem: `docs/architecture docs/subsystems/5. Adapters & Targets.md`

package/dist/runtime.d.mts

@@ -1,14 +1,26 @@
-import { PostgresBinding, PostgresBinding as PostgresBinding$1, PostgresDriverCreateOptions } from "@prisma-next/driver-postgres/runtime";
+import { KyselifyContract } from "@prisma-next/integration-kysely";
 import { SelectBuilder } from "@prisma-next/sql-lane";
+import { orm } from "@prisma-next/sql-orm-client";
 import { SchemaHandle } from "@prisma-next/sql-relational-core/schema";
 import { ExecutionContext, Plugin, Runtime, RuntimeVerifyOptions, SqlExecutionStackWithDriver, SqlRuntimeExtensionDescriptor } from "@prisma-next/sql-runtime";
+import { Kysely } from "kysely";
 import { Client, Pool } from "pg";
 import { ExtractCodecTypes, ExtractOperationTypes, SqlContract, SqlStorage } from "@prisma-next/sql-contract/types";
 import { OperationTypeSignature, OperationTypes } from "@prisma-next/sql-relational-core/types";
 
 //#region src/runtime/binding.d.ts
+type PostgresBinding = {
+  readonly kind: 'url';
+  readonly url: string;
+} | {
+  readonly kind: 'pgPool';
+  readonly pool: Pool;
+} | {
+  readonly kind: 'pgClient';
+  readonly client: Client;
+};
 type PostgresBindingInput = {
-  readonly binding: PostgresBinding$1;
+  readonly binding: PostgresBinding;
   readonly url?: never;
   readonly pg?: never;
 } | {
@@ -25,24 +37,36 @@ type PostgresBindingInput = {
 type NormalizeOperationTypes<T> = { [TypeId in keyof T]: { [Method in keyof T[TypeId]]: T[TypeId][Method] extends OperationTypeSignature ? T[TypeId][Method] : OperationTypeSignature } };
 type ToSchemaOperationTypes<T> = T extends OperationTypes ? T : NormalizeOperationTypes<T>;
 type PostgresTargetId = 'postgres';
+type OrmClient<TContract extends SqlContract<SqlStorage>> = ReturnType<typeof orm<TContract>>;
 interface PostgresClient<TContract extends SqlContract<SqlStorage>> {
   readonly sql: SelectBuilder<TContract, unknown, ExtractCodecTypes<TContract>, ExtractOperationTypes<TContract>>;
+  kysely(runtime: Runtime): Kysely<KyselifyContract<TContract>>;
   readonly schema: SchemaHandle<TContract, ExtractCodecTypes<TContract>, ToSchemaOperationTypes<ExtractOperationTypes<TContract>>>;
+  readonly orm: OrmClient<TContract>;
   readonly context: ExecutionContext<TContract>;
   readonly stack: SqlExecutionStackWithDriver<PostgresTargetId>;
-  runtime(): Promise<Runtime>;
+  connect(bindingInput?: PostgresBindingInput): Promise<Runtime>;
+  runtime(): Runtime;
 }
 interface PostgresOptionsBase<TContract extends SqlContract<SqlStorage>> {
   readonly extensions?: readonly SqlRuntimeExtensionDescriptor<PostgresTargetId>[];
   readonly plugins?: readonly Plugin<TContract>[];
   readonly verify?: RuntimeVerifyOptions;
-  readonly cursor?: PostgresDriverCreateOptions['cursor'];
+  readonly poolOptions?: {
+    readonly connectionTimeoutMillis?: number;
+    readonly idleTimeoutMillis?: number;
+  };
+}
+interface PostgresBindingOptions {
+  readonly binding?: PostgresBinding;
+  readonly url?: string;
+  readonly pg?: Pool | Client;
 }
-type PostgresOptionsWithContract<TContract extends SqlContract<SqlStorage>> = PostgresBindingInput & PostgresOptionsBase<TContract> & {
+type PostgresOptionsWithContract<TContract extends SqlContract<SqlStorage>> = PostgresBindingOptions & PostgresOptionsBase<TContract> & {
   readonly contract: TContract;
   readonly contractJson?: never;
 };
-type PostgresOptionsWithContractJson<TContract extends SqlContract<SqlStorage>> = PostgresBindingInput & PostgresOptionsBase<TContract> & {
+type PostgresOptionsWithContractJson<TContract extends SqlContract<SqlStorage>> = PostgresBindingOptions & PostgresOptionsBase<TContract> & {
   readonly contractJson: unknown;
   readonly contract?: never;
 };

package/dist/runtime.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/runtime/binding.ts","../src/runtime/postgres.ts"],"sourcesContent":[],"mappings":";;;;;;;;;KAIY,oBAAA;oBAEY;;;;;;EAFZ,SAAA,EAAA,CAAA,EAAA,KAAA;CAEY,GAAA;EAUL,SAAA,EAAA,EAAA,IAAA,GAAO,MAAP;EAAO,SAAA,OAAA,CAAA,EAAA,KAAA;EAAM,SAAA,GAAA,CAAA,EAAA,KAAA;;;;KCoB3B,gDACc,iBDjCP,MCkCS,CDlCT,CCkCW,MDlCS,CAAA,GCkCC,CDlCD,CCkCG,MDlCH,CAAA,CCkCW,MDlCX,CAAA,SCkC2B,sBDlC3B,GCmCxB,CDnCwB,CCmCtB,MDnCsB,CAAA,CCmCd,MDnCc,CAAA,GCoCxB,sBDpCwB,EAER,EAUL;KC4Bd,sBD5BqB,CAAA,CAAA,CAAA,GC4BO,CD5BP,SC4BiB,cD5BjB,GC4BkC,CD5BlC,GC4BsC,uBD5BtC,CC4B8D,CD5B9D,CAAA;AAAM,KC8BpB,gBAAA,GD9BoB,UAAA;UCgCf,iCAAiC,YAAY;gBAC9C,cACZ,oBAEA,kBAAkB,YAClB,sBAAsB;mBAEP,aACf,WACA,kBAAkB,YAClB,uBAAuB,sBAAsB;EAtB5C,SAAA,OAAA,EAwBe,gBAxBQ,CAwBS,SAxBT,CAAA;EACT,SAAA,KAAA,EAwBD,2BAxBC,CAwB2B,gBAxB3B,CAAA;EACE,OAAA,EAAA,EAwBR,OAxBQ,CAwBA,OAxBA,CAAA;;AAAY,UA2BhB,mBA3BgB,CAAA,kBA2BsB,WA3BtB,CA2BkC,UA3BlC,CAAA,CAAA,CAAA;EAAE,SAAA,UAAA,CAAA,EAAA,SA4BF,6BA5BE,CA4B4B,gBA5B5B,CAAA,EAAA;EAAQ,SAAA,OAAA,CAAA,EAAA,SA6Bb,MA7Ba,CA6BN,SA7BM,CAAA,EAAA;EAAgB,SAAA,MAAA,CAAA,EA8BvC,oBA9BuC;EACnD,SAAA,MAAA,CAAA,EA8BY,2BA9BZ,CAAA,QAAA,CAAA;;AAAU,KAiCN,2BAjCM,CAAA,kBAiCwC,WAjCxC,CAiCoD,UAjCpD,CAAA,CAAA,GAkChB,oBAlCgB,GAmCd,mBAnCc,CAmCM,SAnCN,CAAA,GAAA;EACV,SAAA,QAAA,EAmCiB,SAnCjB;EAAsB,SAAA,YAAA,CAAA,EAAA,KAAA;AAAA,CAAA;AAIG,KAmCrB,+BAnCqB,CAAA,kBAmC6B,WAnC7B,CAmCyC,UAnCzC,CAAA,CAAA,GAoC/B,oBApC+B,GAqC7B,mBArC6B,CAqCT,SArCS,CAAA,GAAA;EAAU,SAAA,YAAA,EAAA,OAAA;EAAiB,SAAA,QAAA,CAAA,EAAA,KAAA;CAA4B;AAAxB,KA0CpD,eA1CoD,CAAA,kBA0ClB,WA1CkB,CA0CN,UA1CM,CAAA,CAAA,GA2C5D,2BA3C4D,CA2ChC,SA3CgC,CAAA,GA4C5D,+BA5C4D,CA4C5B,SA5C4B,CAAA;;AAEhE;AAEA;;AAAkD,iBA2D1B,QA3D0B,CAAA,kBA2DC,WA3DD,CA2Da,UA3Db,CAAA,CAAA,CAAA,OAAA,EA4DvC,2BA5DuC,CA4DX,SA5DW,CAAA,CAAA,EA6D/C,cA7D+C,CA6DhC,SA7DgC,CAAA;AAE9C,iBA4DoB,QA5DpB,CAAA,kBA4D+C,WA5D/C,CA4D2D,UA5D3D,CAAA,CAAA,CAAA,OAAA,EA6DO,+BA7DP,CA6DuC,SA7DvC,CAAA,CAAA,EA8DD,cA9DC,CA8Dc,SA9Dd,CAAA"}
+{"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/runtime/binding.ts","../src/runtime/postgres.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/runtime.mjs

@@ -1,61 +1,38 @@
 import postgresAdapter from "@prisma-next/adapter-postgres/runtime";
 import { instantiateExecutionStack } from "@prisma-next/core-execution-plane/stack";
 import postgresDriver from "@prisma-next/driver-postgres/runtime";
+import { KyselyPrismaDialect } from "@prisma-next/integration-kysely";
 import { validateContract } from "@prisma-next/sql-contract/validate";
 import { sql } from "@prisma-next/sql-lane";
+import { orm } from "@prisma-next/sql-orm-client";
 import { schema } from "@prisma-next/sql-relational-core/schema";
 import { createExecutionContext, createRuntime, createSqlExecutionStack } from "@prisma-next/sql-runtime";
 import postgresTarget from "@prisma-next/target-postgres/runtime";
-import { ifDefined } from "@prisma-next/utils/defined";
+import { Kysely } from "kysely";
 import { Client, Pool } from "pg";
 
 //#region src/runtime/binding.ts
-function bindingError(message, details) {
-	const error = new Error(message);
-	Object.defineProperty(error, "name", {
-		value: "RuntimeError",
-		configurable: true
-	});
-	return Object.assign(error, {
-		code: "DRIVER.BINDING_INVALID",
-		category: "RUNTIME",
-		severity: "error",
-		message,
-		details
-	});
-}
 function validatePostgresUrl(url) {
 	const trimmed = url.trim();
-	if (trimmed.length === 0) throw bindingError("Postgres URL must be a non-empty string", {
-		field: "url",
-		reason: "empty"
-	});
+	if (trimmed.length === 0) throw new Error("Postgres URL must be a non-empty string");
 	let parsed;
 	try {
 		parsed = new URL(trimmed);
 	} catch {
-		throw bindingError("Postgres URL must be a valid URL", {
-			field: "url",
-			reason: "invalid-url"
-		});
+		throw new Error("Postgres URL must be a valid URL");
 	}
-	if (parsed.protocol !== "postgres:" && parsed.protocol !== "postgresql:") throw bindingError("Postgres URL must use postgres:// or postgresql://", {
-		field: "url",
-		reason: "invalid-protocol",
-		protocol: parsed.protocol
-	});
+	if (parsed.protocol !== "postgres:" && parsed.protocol !== "postgresql:") throw new Error("Postgres URL must use postgres:// or postgresql://");
 	return trimmed;
 }
 function resolvePostgresBinding(options) {
-	const providedCount = Number(options.binding !== void 0) + Number(options.url !== void 0) + Number(options.pg !== void 0);
-	if (providedCount !== 1) throw bindingError("Provide one binding input: binding, url, or pg", { providedCount });
+	if (Number(options.binding !== void 0) + Number(options.url !== void 0) + Number(options.pg !== void 0) !== 1) throw new Error("Provide one binding input: binding, url, or pg");
 	if (options.binding !== void 0) return options.binding;
 	if (options.url !== void 0) return {
 		kind: "url",
 		url: validatePostgresUrl(options.url)
 	};
 	const pgBinding = options.pg;
-	if (pgBinding === void 0) throw bindingError("Invariant violation: expected pg binding after validation", { reason: "missing-pg-binding" });
+	if (pgBinding === void 0) throw new Error("Invariant violation: expected pg binding after validation");
 	if (pgBinding instanceof Pool) return {
 		kind: "pgPool",
 		pool: pgBinding
@@ -64,7 +41,11 @@ function resolvePostgresBinding(options) {
 		kind: "pgClient",
 		client: pgBinding
 	};
-	throw bindingError("Unable to determine pg binding type from pg input; use binding with explicit kind", { reason: "unknown-pg-instance" });
+	throw new Error("Unable to determine pg binding type from pg input; use binding with explicit kind");
+}
+function resolveOptionalPostgresBinding(options) {
+	if (Number(options.binding !== void 0) + Number(options.url !== void 0) + Number(options.pg !== void 0) === 0) return;
+	return resolvePostgresBinding(options);
 }
 
 //#endregion
@@ -75,18 +56,24 @@ function hasContractJson(options) {
 function resolveContract(options) {
 	return validateContract(hasContractJson(options) ? options.contractJson : options.contract);
 }
+function toRuntimeBinding(binding, options) {
+	if (binding.kind !== "url") return binding;
+	return {
+		kind: "pgPool",
+		pool: new Pool({
+			connectionString: binding.url,
+			connectionTimeoutMillis: options.poolOptions?.connectionTimeoutMillis ?? 2e4,
+			idleTimeoutMillis: options.poolOptions?.idleTimeoutMillis ?? 3e4
+		})
+	};
+}
 function postgres(options) {
 	const contract = resolveContract(options);
-	const binding = resolvePostgresBinding(options);
+	let binding = resolveOptionalPostgresBinding(options);
 	const stack = createSqlExecutionStack({
 		target: postgresTarget,
 		adapter: postgresAdapter,
-		driver: options.cursor === void 0 ? postgresDriver : {
-			...postgresDriver,
-			create() {
-				return postgresDriver.create({ cursor: options.cursor });
-			}
-		},
+		driver: postgresDriver,
 		extensionPacks: options.extensions ?? []
 	});
 	const context = createExecutionContext({
@@ -95,39 +82,80 @@ function postgres(options) {
 	});
 	const schema$1 = schema(context);
 	const sql$1 = sql({ context });
-	let runtimePromise;
+	let runtimeInstance;
+	let runtimeDriver;
+	let driverConnected = false;
+	let connectPromise;
+	let backgroundConnectError;
+	const connectDriver = async (resolvedBinding) => {
+		if (driverConnected) return;
+		if (!runtimeDriver) throw new Error("Postgres runtime driver missing");
+		if (connectPromise) return connectPromise;
+		const runtimeBinding = toRuntimeBinding(resolvedBinding, options);
+		connectPromise = runtimeDriver.connect(runtimeBinding).then(() => {
+			driverConnected = true;
+		}).catch(async (err) => {
+			backgroundConnectError = err;
+			connectPromise = void 0;
+			if (resolvedBinding.kind === "url" && runtimeBinding.kind === "pgPool") await runtimeBinding.pool.end().catch(() => void 0);
+			throw err;
+		});
+		return connectPromise;
+	};
+	const getRuntime = () => {
+		if (backgroundConnectError !== void 0) throw backgroundConnectError;
+		if (runtimeInstance) return runtimeInstance;
+		const stackInstance = instantiateExecutionStack(stack);
+		const driverDescriptor = stack.driver;
+		if (!driverDescriptor) throw new Error("Driver descriptor missing from execution stack");
+		const driver = driverDescriptor.create({ cursor: { disabled: true } });
+		runtimeDriver = driver;
+		if (binding !== void 0) connectDriver(binding).catch(() => void 0);
+		runtimeInstance = createRuntime({
+			stackInstance,
+			context,
+			driver,
+			verify: options.verify ?? {
+				mode: "onFirstUse",
+				requireMarker: false
+			},
+			...options.plugins ? { plugins: options.plugins } : {}
+		});
+		return runtimeInstance;
+	};
 	return {
 		sql: sql$1,
+		kysely(runtime) {
+			return new Kysely({ dialect: new KyselyPrismaDialect({
+				runtime,
+				contract
+			}) });
+		},
 		schema: schema$1,
+		orm: orm({
+			contract,
+			runtime: {
+				execute(plan) {
+					return getRuntime().execute(plan);
+				},
+				connection() {
+					return getRuntime().connection();
+				}
+			}
+		}),
 		context,
 		stack,
-		async runtime() {
-			if (runtimePromise) return runtimePromise;
-			runtimePromise = (async () => {
-				const stackInstance = instantiateExecutionStack(stack);
-				const driver = stackInstance.driver;
-				if (driver === void 0) throw new Error("Relational runtime requires a driver descriptor on the execution stack");
-				try {
-					await driver.connect(binding);
-					return createRuntime({
-						stackInstance,
-						context,
-						driver,
-						verify: options.verify ?? {
-							mode: "onFirstUse",
-							requireMarker: false
-						},
-						...ifDefined("plugins", options.plugins)
-					});
-				} catch (error) {
-					await driver.close().catch(() => void 0);
-					throw error;
-				}
-			})();
-			runtimePromise.catch(() => {
-				runtimePromise = void 0;
-			});
-			return runtimePromise;
+		async connect(bindingInput) {
+			if (driverConnected || connectPromise) throw new Error("Postgres client already connected");
+			if (bindingInput !== void 0) binding = resolvePostgresBinding(bindingInput);
+			if (binding === void 0) throw new Error("Postgres binding not configured. Pass url/pg/binding to postgres(...) or call db.connect({ ... }).");
+			const runtime = getRuntime();
+			if (driverConnected) return runtime;
+			await connectDriver(binding);
+			return runtime;
+		},
+		runtime() {
+			return getRuntime();
 		}
 	};
 }

package/dist/runtime.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.mjs","names":["parsed: URL","PgPool","PgClient","schema: PostgresClient<TContract>['schema']","schemaBuilder","sql","sqlBuilder","runtimePromise: Promise<Runtime> | undefined"],"sources":["../src/runtime/binding.ts","../src/runtime/postgres.ts"],"sourcesContent":["import type { PostgresBinding } from '@prisma-next/driver-postgres/runtime';\nimport type { Client, Pool } from 'pg';\nimport { Client as PgClient, Pool as PgPool } from 'pg';\n\nexport type PostgresBindingInput =\n  | {\n      readonly binding: PostgresBinding;\n      readonly url?: never;\n      readonly pg?: never;\n    }\n  | {\n      readonly url: string;\n      readonly binding?: never;\n      readonly pg?: never;\n    }\n  | {\n      readonly pg: Pool | Client;\n      readonly binding?: never;\n      readonly url?: never;\n    };\n\ninterface PostgresBindingError extends Error {\n  readonly code: 'DRIVER.BINDING_INVALID';\n  readonly category: 'RUNTIME';\n  readonly severity: 'error';\n  readonly details?: Record<string, unknown>;\n}\n\nfunction bindingError(message: string, details?: Record<string, unknown>): PostgresBindingError {\n  const error = new Error(message) as PostgresBindingError;\n  Object.defineProperty(error, 'name', {\n    value: 'RuntimeError',\n    configurable: true,\n  });\n  return Object.assign(error, {\n    code: 'DRIVER.BINDING_INVALID' as const,\n    category: 'RUNTIME' as const,\n    severity: 'error' as const,\n    message,\n    details,\n  });\n}\n\nfunction validatePostgresUrl(url: string): string {\n  const trimmed = url.trim();\n  if (trimmed.length === 0) {\n    throw bindingError('Postgres URL must be a non-empty string', {\n      field: 'url',\n      reason: 'empty',\n    });\n  }\n\n  let parsed: URL;\n  try {\n    parsed = new URL(trimmed);\n  } catch {\n    throw bindingError('Postgres URL must be a valid URL', {\n      field: 'url',\n      reason: 'invalid-url',\n    });\n  }\n\n  if (parsed.protocol !== 'postgres:' && parsed.protocol !== 'postgresql:') {\n    throw bindingError('Postgres URL must use postgres:// or postgresql://', {\n      field: 'url',\n      reason: 'invalid-protocol',\n      protocol: parsed.protocol,\n    });\n  }\n\n  return trimmed;\n}\n\nexport function resolvePostgresBinding(options: PostgresBindingInput): PostgresBinding {\n  const providedCount =\n    Number(options.binding !== undefined) +\n    Number(options.url !== undefined) +\n    Number(options.pg !== undefined);\n\n  if (providedCount !== 1) {\n    throw bindingError('Provide one binding input: binding, url, or pg', {\n      providedCount,\n    });\n  }\n\n  if (options.binding !== undefined) {\n    return options.binding;\n  }\n\n  if (options.url !== undefined) {\n    return { kind: 'url', url: validatePostgresUrl(options.url) };\n  }\n\n  const pgBinding = options.pg;\n  if (pgBinding === undefined) {\n    throw bindingError('Invariant violation: expected pg binding after validation', {\n      reason: 'missing-pg-binding',\n    });\n  }\n\n  if (pgBinding instanceof PgPool) {\n    return { kind: 'pgPool', pool: pgBinding };\n  }\n\n  if (pgBinding instanceof PgClient) {\n    return { kind: 'pgClient', client: pgBinding };\n  }\n\n  throw bindingError(\n    'Unable to determine pg binding type from pg input; use binding with explicit kind',\n    {\n      reason: 'unknown-pg-instance',\n    },\n  );\n}\n","import postgresAdapter from '@prisma-next/adapter-postgres/runtime';\nimport { instantiateExecutionStack } from '@prisma-next/core-execution-plane/stack';\nimport type { PostgresDriverCreateOptions } from '@prisma-next/driver-postgres/runtime';\nimport postgresDriver from '@prisma-next/driver-postgres/runtime';\nimport type {\n  ExtractCodecTypes,\n  ExtractOperationTypes,\n  SqlContract,\n  SqlStorage,\n} from '@prisma-next/sql-contract/types';\nimport { validateContract } from '@prisma-next/sql-contract/validate';\nimport type { SelectBuilder } from '@prisma-next/sql-lane';\nimport { sql as sqlBuilder } from '@prisma-next/sql-lane';\nimport type { SchemaHandle } from '@prisma-next/sql-relational-core/schema';\nimport { schema as schemaBuilder } from '@prisma-next/sql-relational-core/schema';\nimport type {\n  OperationTypeSignature,\n  OperationTypes,\n} from '@prisma-next/sql-relational-core/types';\nimport type {\n  ExecutionContext,\n  Plugin,\n  Runtime,\n  RuntimeVerifyOptions,\n  SqlExecutionStackWithDriver,\n  SqlRuntimeExtensionDescriptor,\n} from '@prisma-next/sql-runtime';\nimport {\n  createExecutionContext,\n  createRuntime,\n  createSqlExecutionStack,\n} from '@prisma-next/sql-runtime';\nimport postgresTarget from '@prisma-next/target-postgres/runtime';\nimport { ifDefined } from '@prisma-next/utils/defined';\nimport { type PostgresBindingInput, resolvePostgresBinding } from './binding';\n\ntype NormalizeOperationTypes<T> = {\n  [TypeId in keyof T]: {\n    [Method in keyof T[TypeId]]: T[TypeId][Method] extends OperationTypeSignature\n      ? T[TypeId][Method]\n      : OperationTypeSignature;\n  };\n};\n\ntype ToSchemaOperationTypes<T> = T extends OperationTypes ? T : NormalizeOperationTypes<T>;\n\nexport type PostgresTargetId = 'postgres';\n\nexport interface PostgresClient<TContract extends SqlContract<SqlStorage>> {\n  readonly sql: SelectBuilder<\n    TContract,\n    unknown,\n    ExtractCodecTypes<TContract>,\n    ExtractOperationTypes<TContract>\n  >;\n  readonly schema: SchemaHandle<\n    TContract,\n    ExtractCodecTypes<TContract>,\n    ToSchemaOperationTypes<ExtractOperationTypes<TContract>>\n  >;\n  readonly context: ExecutionContext<TContract>;\n  readonly stack: SqlExecutionStackWithDriver<PostgresTargetId>;\n  runtime(): Promise<Runtime>;\n}\n\nexport interface PostgresOptionsBase<TContract extends SqlContract<SqlStorage>> {\n  readonly extensions?: readonly SqlRuntimeExtensionDescriptor<PostgresTargetId>[];\n  readonly plugins?: readonly Plugin<TContract>[];\n  readonly verify?: RuntimeVerifyOptions;\n  readonly cursor?: PostgresDriverCreateOptions['cursor'];\n}\n\nexport type PostgresOptionsWithContract<TContract extends SqlContract<SqlStorage>> =\n  PostgresBindingInput &\n    PostgresOptionsBase<TContract> & {\n      readonly contract: TContract;\n      readonly contractJson?: never;\n    };\n\nexport type PostgresOptionsWithContractJson<TContract extends SqlContract<SqlStorage>> =\n  PostgresBindingInput &\n    PostgresOptionsBase<TContract> & {\n      readonly contractJson: unknown;\n      readonly contract?: never;\n    };\n\nexport type PostgresOptions<TContract extends SqlContract<SqlStorage>> =\n  | PostgresOptionsWithContract<TContract>\n  | PostgresOptionsWithContractJson<TContract>;\n\nfunction hasContractJson<TContract extends SqlContract<SqlStorage>>(\n  options: PostgresOptions<TContract>,\n): options is PostgresOptionsWithContractJson<TContract> {\n  return 'contractJson' in options;\n}\n\nfunction resolveContract<TContract extends SqlContract<SqlStorage>>(\n  options: PostgresOptions<TContract>,\n): TContract {\n  const contractInput = hasContractJson(options) ? options.contractJson : options.contract;\n  return validateContract<TContract>(contractInput);\n}\n\n/**\n * Creates a lazy Postgres client from either `contractJson` or a TypeScript-authored `contract`.\n * Static query surfaces are available immediately, while `runtime()` instantiates the driver/pool on first call.\n */\nexport default function postgres<TContract extends SqlContract<SqlStorage>>(\n  options: PostgresOptionsWithContract<TContract>,\n): PostgresClient<TContract>;\nexport default function postgres<TContract extends SqlContract<SqlStorage>>(\n  options: PostgresOptionsWithContractJson<TContract>,\n): PostgresClient<TContract>;\nexport default function postgres<TContract extends SqlContract<SqlStorage>>(\n  options: PostgresOptions<TContract>,\n): PostgresClient<TContract> {\n  const contract = resolveContract(options);\n  const binding = resolvePostgresBinding(options);\n  const stack = createSqlExecutionStack({\n    target: postgresTarget,\n    adapter: postgresAdapter,\n    driver:\n      options.cursor === undefined\n        ? postgresDriver\n        : {\n            ...postgresDriver,\n            create() {\n              return postgresDriver.create({ cursor: options.cursor });\n            },\n          },\n    extensionPacks: options.extensions ?? [],\n  });\n\n  const context = createExecutionContext({\n    contract,\n    stack,\n  });\n\n  const schema: PostgresClient<TContract>['schema'] = schemaBuilder(context);\n  const sql = sqlBuilder({ context });\n\n  let runtimePromise: Promise<Runtime> | undefined;\n\n  return {\n    sql,\n    schema,\n    context,\n    stack,\n    async runtime() {\n      if (runtimePromise) {\n        return runtimePromise;\n      }\n\n      runtimePromise = (async () => {\n        const stackInstance = instantiateExecutionStack(stack);\n        const driver = stackInstance.driver;\n        if (driver === undefined) {\n          throw new Error('Relational runtime requires a driver descriptor on the execution stack');\n        }\n\n        try {\n          // `binding` is normalized by resolvePostgresBinding(), so this call site remains\n          // type-safe in practice while SqlRuntimeDriverInstance currently uses SqlDriver<unknown>.\n          await driver.connect(binding);\n\n          return createRuntime({\n            stackInstance,\n            context,\n            driver,\n            verify: options.verify ?? { mode: 'onFirstUse', requireMarker: false },\n            ...ifDefined('plugins', options.plugins),\n          });\n        } catch (error) {\n          await driver.close().catch(() => undefined);\n          throw error;\n        }\n      })();\n\n      runtimePromise.catch(() => {\n        runtimePromise = undefined;\n      });\n\n      return runtimePromise;\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"runtime.mjs","names":["parsed: URL","PgPool","PgClient","schema: PostgresClient<TContract>['schema']","schemaBuilder","sql","sqlBuilder","runtimeInstance: Runtime | undefined","runtimeDriver: { connect(binding: unknown): Promise<void> } | undefined","connectPromise: Promise<void> | undefined","backgroundConnectError: unknown","ormBuilder"],"sources":["../src/runtime/binding.ts","../src/runtime/postgres.ts"],"sourcesContent":["import type { Client, Pool } from 'pg';\nimport { Client as PgClient, Pool as PgPool } from 'pg';\n\nexport type PostgresBinding =\n  | { readonly kind: 'url'; readonly url: string }\n  | { readonly kind: 'pgPool'; readonly pool: Pool }\n  | { readonly kind: 'pgClient'; readonly client: Client };\n\nexport type PostgresBindingInput =\n  | {\n      readonly binding: PostgresBinding;\n      readonly url?: never;\n      readonly pg?: never;\n    }\n  | {\n      readonly url: string;\n      readonly binding?: never;\n      readonly pg?: never;\n    }\n  | {\n      readonly pg: Pool | Client;\n      readonly binding?: never;\n      readonly url?: never;\n    };\n\ntype PostgresBindingFields = {\n  readonly binding?: PostgresBinding;\n  readonly url?: string;\n  readonly pg?: Pool | Client;\n};\n\nfunction validatePostgresUrl(url: string): string {\n  const trimmed = url.trim();\n  if (trimmed.length === 0) {\n    throw new Error('Postgres URL must be a non-empty string');\n  }\n\n  let parsed: URL;\n  try {\n    parsed = new URL(trimmed);\n  } catch {\n    throw new Error('Postgres URL must be a valid URL');\n  }\n\n  if (parsed.protocol !== 'postgres:' && parsed.protocol !== 'postgresql:') {\n    throw new Error('Postgres URL must use postgres:// or postgresql://');\n  }\n\n  return trimmed;\n}\n\nexport function resolvePostgresBinding(options: PostgresBindingInput): PostgresBinding {\n  const providedCount =\n    Number(options.binding !== undefined) +\n    Number(options.url !== undefined) +\n    Number(options.pg !== undefined);\n\n  if (providedCount !== 1) {\n    throw new Error('Provide one binding input: binding, url, or pg');\n  }\n\n  if (options.binding !== undefined) {\n    return options.binding;\n  }\n\n  if (options.url !== undefined) {\n    return { kind: 'url', url: validatePostgresUrl(options.url) };\n  }\n\n  const pgBinding = options.pg;\n  if (pgBinding === undefined) {\n    throw new Error('Invariant violation: expected pg binding after validation');\n  }\n\n  if (pgBinding instanceof PgPool) {\n    return { kind: 'pgPool', pool: pgBinding };\n  }\n\n  if (pgBinding instanceof PgClient) {\n    return { kind: 'pgClient', client: pgBinding };\n  }\n\n  throw new Error(\n    'Unable to determine pg binding type from pg input; use binding with explicit kind',\n  );\n}\n\nexport function resolveOptionalPostgresBinding(\n  options: PostgresBindingFields,\n): PostgresBinding | undefined {\n  const providedCount =\n    Number(options.binding !== undefined) +\n    Number(options.url !== undefined) +\n    Number(options.pg !== undefined);\n\n  if (providedCount === 0) {\n    return undefined;\n  }\n\n  return resolvePostgresBinding(options as PostgresBindingInput);\n}\n","import postgresAdapter from '@prisma-next/adapter-postgres/runtime';\nimport { instantiateExecutionStack } from '@prisma-next/core-execution-plane/stack';\nimport postgresDriver from '@prisma-next/driver-postgres/runtime';\nimport { type KyselifyContract, KyselyPrismaDialect } from '@prisma-next/integration-kysely';\nimport type {\n  ExtractCodecTypes,\n  ExtractOperationTypes,\n  SqlContract,\n  SqlStorage,\n} from '@prisma-next/sql-contract/types';\nimport { validateContract } from '@prisma-next/sql-contract/validate';\nimport type { SelectBuilder } from '@prisma-next/sql-lane';\nimport { sql as sqlBuilder } from '@prisma-next/sql-lane';\nimport { orm as ormBuilder } from '@prisma-next/sql-orm-client';\nimport type { SchemaHandle } from '@prisma-next/sql-relational-core/schema';\nimport { schema as schemaBuilder } from '@prisma-next/sql-relational-core/schema';\nimport type {\n  OperationTypeSignature,\n  OperationTypes,\n} from '@prisma-next/sql-relational-core/types';\nimport type {\n  ExecutionContext,\n  Plugin,\n  Runtime,\n  RuntimeVerifyOptions,\n  SqlExecutionStackWithDriver,\n  SqlRuntimeExtensionDescriptor,\n} from '@prisma-next/sql-runtime';\nimport {\n  createExecutionContext,\n  createRuntime,\n  createSqlExecutionStack,\n} from '@prisma-next/sql-runtime';\nimport postgresTarget from '@prisma-next/target-postgres/runtime';\nimport { Kysely } from 'kysely';\nimport { type Client, Pool } from 'pg';\nimport {\n  type PostgresBinding,\n  type PostgresBindingInput,\n  resolveOptionalPostgresBinding,\n  resolvePostgresBinding,\n} from './binding';\n\ntype NormalizeOperationTypes<T> = {\n  [TypeId in keyof T]: {\n    [Method in keyof T[TypeId]]: T[TypeId][Method] extends OperationTypeSignature\n      ? T[TypeId][Method]\n      : OperationTypeSignature;\n  };\n};\n\ntype ToSchemaOperationTypes<T> = T extends OperationTypes ? T : NormalizeOperationTypes<T>;\n\nexport type PostgresTargetId = 'postgres';\ntype OrmClient<TContract extends SqlContract<SqlStorage>> = ReturnType<\n  typeof ormBuilder<TContract>\n>;\n\nexport interface PostgresClient<TContract extends SqlContract<SqlStorage>> {\n  readonly sql: SelectBuilder<\n    TContract,\n    unknown,\n    ExtractCodecTypes<TContract>,\n    ExtractOperationTypes<TContract>\n  >;\n  kysely(runtime: Runtime): Kysely<KyselifyContract<TContract>>;\n  readonly schema: SchemaHandle<\n    TContract,\n    ExtractCodecTypes<TContract>,\n    ToSchemaOperationTypes<ExtractOperationTypes<TContract>>\n  >;\n  readonly orm: OrmClient<TContract>;\n  readonly context: ExecutionContext<TContract>;\n  readonly stack: SqlExecutionStackWithDriver<PostgresTargetId>;\n  connect(bindingInput?: PostgresBindingInput): Promise<Runtime>;\n  runtime(): Runtime;\n}\n\nexport interface PostgresOptionsBase<TContract extends SqlContract<SqlStorage>> {\n  readonly extensions?: readonly SqlRuntimeExtensionDescriptor<PostgresTargetId>[];\n  readonly plugins?: readonly Plugin<TContract>[];\n  readonly verify?: RuntimeVerifyOptions;\n  readonly poolOptions?: {\n    readonly connectionTimeoutMillis?: number;\n    readonly idleTimeoutMillis?: number;\n  };\n}\n\nexport interface PostgresBindingOptions {\n  readonly binding?: PostgresBinding;\n  readonly url?: string;\n  readonly pg?: Pool | Client;\n}\n\nexport type PostgresOptionsWithContract<TContract extends SqlContract<SqlStorage>> =\n  PostgresBindingOptions &\n    PostgresOptionsBase<TContract> & {\n      readonly contract: TContract;\n      readonly contractJson?: never;\n    };\n\nexport type PostgresOptionsWithContractJson<TContract extends SqlContract<SqlStorage>> =\n  PostgresBindingOptions &\n    PostgresOptionsBase<TContract> & {\n      readonly contractJson: unknown;\n      readonly contract?: never;\n    };\n\nexport type PostgresOptions<TContract extends SqlContract<SqlStorage>> =\n  | PostgresOptionsWithContract<TContract>\n  | PostgresOptionsWithContractJson<TContract>;\n\nfunction hasContractJson<TContract extends SqlContract<SqlStorage>>(\n  options: PostgresOptions<TContract>,\n): options is PostgresOptionsWithContractJson<TContract> {\n  return 'contractJson' in options;\n}\n\nfunction resolveContract<TContract extends SqlContract<SqlStorage>>(\n  options: PostgresOptions<TContract>,\n): TContract {\n  const contractInput = hasContractJson(options) ? options.contractJson : options.contract;\n  return validateContract<TContract>(contractInput);\n}\n\nfunction toRuntimeBinding<TContract extends SqlContract<SqlStorage>>(\n  binding: PostgresBinding,\n  options: PostgresOptions<TContract>,\n) {\n  if (binding.kind !== 'url') {\n    return binding;\n  }\n\n  return {\n    kind: 'pgPool',\n    pool: new Pool({\n      connectionString: binding.url,\n      connectionTimeoutMillis: options.poolOptions?.connectionTimeoutMillis ?? 20_000,\n      idleTimeoutMillis: options.poolOptions?.idleTimeoutMillis ?? 30_000,\n    }),\n  } as const;\n}\n\n/**\n * Creates a lazy Postgres client from either `contractJson` or a TypeScript-authored `contract`.\n * Static query surfaces are available immediately, while `runtime()` instantiates the driver/pool on first call.\n */\nexport default function postgres<TContract extends SqlContract<SqlStorage>>(\n  options: PostgresOptionsWithContract<TContract>,\n): PostgresClient<TContract>;\nexport default function postgres<TContract extends SqlContract<SqlStorage>>(\n  options: PostgresOptionsWithContractJson<TContract>,\n): PostgresClient<TContract>;\nexport default function postgres<TContract extends SqlContract<SqlStorage>>(\n  options: PostgresOptions<TContract>,\n): PostgresClient<TContract> {\n  const contract = resolveContract(options);\n  let binding = resolveOptionalPostgresBinding(options);\n  const stack = createSqlExecutionStack({\n    target: postgresTarget,\n    adapter: postgresAdapter,\n    driver: postgresDriver,\n    extensionPacks: options.extensions ?? [],\n  });\n\n  const context = createExecutionContext({\n    contract,\n    stack,\n  });\n\n  const schema: PostgresClient<TContract>['schema'] = schemaBuilder(context);\n  const sql = sqlBuilder({ context });\n  let runtimeInstance: Runtime | undefined;\n  let runtimeDriver: { connect(binding: unknown): Promise<void> } | undefined;\n  let driverConnected = false;\n  let connectPromise: Promise<void> | undefined;\n  let backgroundConnectError: unknown;\n  const connectDriver = async (resolvedBinding: PostgresBinding): Promise<void> => {\n    if (driverConnected) return;\n    if (!runtimeDriver) throw new Error('Postgres runtime driver missing');\n    if (connectPromise) return connectPromise;\n    const runtimeBinding = toRuntimeBinding(resolvedBinding, options);\n    connectPromise = runtimeDriver\n      .connect(runtimeBinding)\n      .then(() => {\n        driverConnected = true;\n      })\n      .catch(async (err) => {\n        backgroundConnectError = err;\n        connectPromise = undefined;\n        if (resolvedBinding.kind === 'url' && runtimeBinding.kind === 'pgPool') {\n          await runtimeBinding.pool.end().catch(() => undefined);\n        }\n        throw err;\n      });\n    return connectPromise;\n  };\n  const getRuntime = (): Runtime => {\n    if (backgroundConnectError !== undefined) {\n      throw backgroundConnectError;\n    }\n\n    if (runtimeInstance) {\n      return runtimeInstance;\n    }\n\n    const stackInstance = instantiateExecutionStack(stack);\n    const driverDescriptor = stack.driver;\n    if (!driverDescriptor) {\n      throw new Error('Driver descriptor missing from execution stack');\n    }\n\n    const driver = driverDescriptor.create({\n      cursor: { disabled: true },\n    });\n    runtimeDriver = driver;\n    if (binding !== undefined) {\n      void connectDriver(binding).catch(() => undefined);\n    }\n\n    runtimeInstance = createRuntime({\n      stackInstance,\n      context,\n      driver,\n      verify: options.verify ?? { mode: 'onFirstUse', requireMarker: false },\n      ...(options.plugins ? { plugins: options.plugins } : {}),\n    });\n\n    return runtimeInstance;\n  };\n  const orm: OrmClient<TContract> = ormBuilder({\n    contract,\n    runtime: {\n      execute(plan) {\n        return getRuntime().execute(plan);\n      },\n      connection() {\n        return getRuntime().connection();\n      },\n    },\n  });\n\n  return {\n    sql,\n    kysely(runtime: Runtime) {\n      return new Kysely<KyselifyContract<TContract>>({\n        dialect: new KyselyPrismaDialect({ runtime, contract }),\n      });\n    },\n    schema,\n    orm,\n    context,\n    stack,\n    async connect(bindingInput) {\n      if (driverConnected || connectPromise) {\n        throw new Error('Postgres client already connected');\n      }\n\n      if (bindingInput !== undefined) {\n        binding = resolvePostgresBinding(bindingInput);\n      }\n\n      if (binding === undefined) {\n        throw new Error(\n          'Postgres binding not configured. Pass url/pg/binding to postgres(...) or call db.connect({ ... }).',\n        );\n      }\n\n      const runtime = getRuntime();\n      if (driverConnected) {\n        return runtime;\n      }\n\n      await connectDriver(binding);\n      return runtime;\n    },\n    runtime() {\n      return getRuntime();\n    },\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -1,20 +1,22 @@
 {
   "name": "@prisma-next/postgres",
-  "version": "0.3.0-dev.43",
+  "version": "0.3.0-dev.45",
   "type": "module",
   "sideEffects": false,
   "description": "One-liner lazy Postgres client composition for Prisma Next",
   "dependencies": {
+    "kysely": "0.28.10",
     "pg": "8.16.3",
-    "@prisma-next/adapter-postgres": "0.3.0-dev.43",
-    "@prisma-next/core-execution-plane": "0.3.0-dev.43",
-    "@prisma-next/driver-postgres": "0.3.0-dev.43",
-    "@prisma-next/sql-contract": "0.3.0-dev.43",
-    "@prisma-next/sql-lane": "0.3.0-dev.43",
-    "@prisma-next/sql-relational-core": "0.3.0-dev.43",
-    "@prisma-next/sql-runtime": "0.3.0-dev.43",
-    "@prisma-next/target-postgres": "0.3.0-dev.43",
-    "@prisma-next/utils": "0.3.0-dev.43"
+    "@prisma-next/adapter-postgres": "0.3.0-dev.45",
+    "@prisma-next/core-execution-plane": "0.3.0-dev.45",
+    "@prisma-next/driver-postgres": "0.3.0-dev.45",
+    "@prisma-next/integration-kysely": "0.3.0-dev.45",
+    "@prisma-next/sql-contract": "0.3.0-dev.45",
+    "@prisma-next/sql-lane": "0.3.0-dev.45",
+    "@prisma-next/sql-orm-client": "0.3.0-dev.45",
+    "@prisma-next/sql-relational-core": "0.3.0-dev.45",
+    "@prisma-next/sql-runtime": "0.3.0-dev.45",
+    "@prisma-next/target-postgres": "0.3.0-dev.45"
   },
   "devDependencies": {
     "@types/pg": "8.16.0",
@@ -33,20 +35,9 @@
     "node": ">=20"
   },
   "exports": {
-    ".": {
-      "types": "./dist/runtime.d.mts",
-      "import": "./dist/runtime.mjs"
-    },
+    "./runtime": "./dist/runtime.mjs",
     "./package.json": "./package.json"
   },
-  "main": "./dist/runtime.mjs",
-  "module": "./dist/runtime.mjs",
-  "types": "./dist/runtime.d.mts",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/prisma/prisma-next.git",
-    "directory": "packages/3-targets/8-clients/postgres"
-  },
   "scripts": {
     "build": "tsdown",
     "test": "vitest run",

package/src/exports/runtime.ts

@@ -1,4 +1,4 @@
-export type { PostgresBinding } from '@prisma-next/driver-postgres/runtime';
+export type { PostgresBinding } from '../runtime/binding';
 export type {
   PostgresClient,
   PostgresOptions,

package/src/runtime/binding.ts

@@ -1,7 +1,11 @@
-import type { PostgresBinding } from '@prisma-next/driver-postgres/runtime';
 import type { Client, Pool } from 'pg';
 import { Client as PgClient, Pool as PgPool } from 'pg';
 
+export type PostgresBinding =
+  | { readonly kind: 'url'; readonly url: string }
+  | { readonly kind: 'pgPool'; readonly pool: Pool }
+  | { readonly kind: 'pgClient'; readonly client: Client };
+
 export type PostgresBindingInput =
   | {
       readonly binding: PostgresBinding;
@@ -19,53 +23,27 @@ export type PostgresBindingInput =
       readonly url?: never;
     };
 
-interface PostgresBindingError extends Error {
-  readonly code: 'DRIVER.BINDING_INVALID';
-  readonly category: 'RUNTIME';
-  readonly severity: 'error';
-  readonly details?: Record<string, unknown>;
-}
-
-function bindingError(message: string, details?: Record<string, unknown>): PostgresBindingError {
-  const error = new Error(message) as PostgresBindingError;
-  Object.defineProperty(error, 'name', {
-    value: 'RuntimeError',
-    configurable: true,
-  });
-  return Object.assign(error, {
-    code: 'DRIVER.BINDING_INVALID' as const,
-    category: 'RUNTIME' as const,
-    severity: 'error' as const,
-    message,
-    details,
-  });
-}
+type PostgresBindingFields = {
+  readonly binding?: PostgresBinding;
+  readonly url?: string;
+  readonly pg?: Pool | Client;
+};
 
 function validatePostgresUrl(url: string): string {
   const trimmed = url.trim();
   if (trimmed.length === 0) {
-    throw bindingError('Postgres URL must be a non-empty string', {
-      field: 'url',
-      reason: 'empty',
-    });
+    throw new Error('Postgres URL must be a non-empty string');
   }
 
   let parsed: URL;
   try {
     parsed = new URL(trimmed);
   } catch {
-    throw bindingError('Postgres URL must be a valid URL', {
-      field: 'url',
-      reason: 'invalid-url',
-    });
+    throw new Error('Postgres URL must be a valid URL');
   }
 
   if (parsed.protocol !== 'postgres:' && parsed.protocol !== 'postgresql:') {
-    throw bindingError('Postgres URL must use postgres:// or postgresql://', {
-      field: 'url',
-      reason: 'invalid-protocol',
-      protocol: parsed.protocol,
-    });
+    throw new Error('Postgres URL must use postgres:// or postgresql://');
   }
 
   return trimmed;
@@ -78,9 +56,7 @@ export function resolvePostgresBinding(options: PostgresBindingInput): PostgresB
     Number(options.pg !== undefined);
 
   if (providedCount !== 1) {
-    throw bindingError('Provide one binding input: binding, url, or pg', {
-      providedCount,
-    });
+    throw new Error('Provide one binding input: binding, url, or pg');
   }
 
   if (options.binding !== undefined) {
@@ -93,9 +69,7 @@ export function resolvePostgresBinding(options: PostgresBindingInput): PostgresB
 
   const pgBinding = options.pg;
   if (pgBinding === undefined) {
-    throw bindingError('Invariant violation: expected pg binding after validation', {
-      reason: 'missing-pg-binding',
-    });
+    throw new Error('Invariant violation: expected pg binding after validation');
   }
 
   if (pgBinding instanceof PgPool) {
@@ -106,10 +80,22 @@ export function resolvePostgresBinding(options: PostgresBindingInput): PostgresB
     return { kind: 'pgClient', client: pgBinding };
   }
 
-  throw bindingError(
+  throw new Error(
     'Unable to determine pg binding type from pg input; use binding with explicit kind',
-    {
-      reason: 'unknown-pg-instance',
-    },
   );
 }
+
+export function resolveOptionalPostgresBinding(
+  options: PostgresBindingFields,
+): PostgresBinding | undefined {
+  const providedCount =
+    Number(options.binding !== undefined) +
+    Number(options.url !== undefined) +
+    Number(options.pg !== undefined);
+
+  if (providedCount === 0) {
+    return undefined;
+  }
+
+  return resolvePostgresBinding(options as PostgresBindingInput);
+}

package/src/runtime/postgres.ts

@@ -1,7 +1,7 @@
 import postgresAdapter from '@prisma-next/adapter-postgres/runtime';
 import { instantiateExecutionStack } from '@prisma-next/core-execution-plane/stack';
-import type { PostgresDriverCreateOptions } from '@prisma-next/driver-postgres/runtime';
 import postgresDriver from '@prisma-next/driver-postgres/runtime';
+import { type KyselifyContract, KyselyPrismaDialect } from '@prisma-next/integration-kysely';
 import type {
   ExtractCodecTypes,
   ExtractOperationTypes,
@@ -11,6 +11,7 @@ import type {
 import { validateContract } from '@prisma-next/sql-contract/validate';
 import type { SelectBuilder } from '@prisma-next/sql-lane';
 import { sql as sqlBuilder } from '@prisma-next/sql-lane';
+import { orm as ormBuilder } from '@prisma-next/sql-orm-client';
 import type { SchemaHandle } from '@prisma-next/sql-relational-core/schema';
 import { schema as schemaBuilder } from '@prisma-next/sql-relational-core/schema';
 import type {
@@ -31,8 +32,14 @@ import {
   createSqlExecutionStack,
 } from '@prisma-next/sql-runtime';
 import postgresTarget from '@prisma-next/target-postgres/runtime';
-import { ifDefined } from '@prisma-next/utils/defined';
-import { type PostgresBindingInput, resolvePostgresBinding } from './binding';
+import { Kysely } from 'kysely';
+import { type Client, Pool } from 'pg';
+import {
+  type PostgresBinding,
+  type PostgresBindingInput,
+  resolveOptionalPostgresBinding,
+  resolvePostgresBinding,
+} from './binding';
 
 type NormalizeOperationTypes<T> = {
   [TypeId in keyof T]: {
@@ -45,6 +52,9 @@ type NormalizeOperationTypes<T> = {
 type ToSchemaOperationTypes<T> = T extends OperationTypes ? T : NormalizeOperationTypes<T>;
 
 export type PostgresTargetId = 'postgres';
+type OrmClient<TContract extends SqlContract<SqlStorage>> = ReturnType<
+  typeof ormBuilder<TContract>
+>;
 
 export interface PostgresClient<TContract extends SqlContract<SqlStorage>> {
   readonly sql: SelectBuilder<
@@ -53,32 +63,44 @@ export interface PostgresClient<TContract extends SqlContract<SqlStorage>> {
     ExtractCodecTypes<TContract>,
     ExtractOperationTypes<TContract>
   >;
+  kysely(runtime: Runtime): Kysely<KyselifyContract<TContract>>;
   readonly schema: SchemaHandle<
     TContract,
     ExtractCodecTypes<TContract>,
     ToSchemaOperationTypes<ExtractOperationTypes<TContract>>
   >;
+  readonly orm: OrmClient<TContract>;
   readonly context: ExecutionContext<TContract>;
   readonly stack: SqlExecutionStackWithDriver<PostgresTargetId>;
-  runtime(): Promise<Runtime>;
+  connect(bindingInput?: PostgresBindingInput): Promise<Runtime>;
+  runtime(): Runtime;
 }
 
 export interface PostgresOptionsBase<TContract extends SqlContract<SqlStorage>> {
   readonly extensions?: readonly SqlRuntimeExtensionDescriptor<PostgresTargetId>[];
   readonly plugins?: readonly Plugin<TContract>[];
   readonly verify?: RuntimeVerifyOptions;
-  readonly cursor?: PostgresDriverCreateOptions['cursor'];
+  readonly poolOptions?: {
+    readonly connectionTimeoutMillis?: number;
+    readonly idleTimeoutMillis?: number;
+  };
+}
+
+export interface PostgresBindingOptions {
+  readonly binding?: PostgresBinding;
+  readonly url?: string;
+  readonly pg?: Pool | Client;
 }
 
 export type PostgresOptionsWithContract<TContract extends SqlContract<SqlStorage>> =
-  PostgresBindingInput &
+  PostgresBindingOptions &
     PostgresOptionsBase<TContract> & {
       readonly contract: TContract;
       readonly contractJson?: never;
     };
 
 export type PostgresOptionsWithContractJson<TContract extends SqlContract<SqlStorage>> =
-  PostgresBindingInput &
+  PostgresBindingOptions &
     PostgresOptionsBase<TContract> & {
       readonly contractJson: unknown;
       readonly contract?: never;
@@ -101,6 +123,24 @@ function resolveContract<TContract extends SqlContract<SqlStorage>>(
   return validateContract<TContract>(contractInput);
 }
 
+function toRuntimeBinding<TContract extends SqlContract<SqlStorage>>(
+  binding: PostgresBinding,
+  options: PostgresOptions<TContract>,
+) {
+  if (binding.kind !== 'url') {
+    return binding;
+  }
+
+  return {
+    kind: 'pgPool',
+    pool: new Pool({
+      connectionString: binding.url,
+      connectionTimeoutMillis: options.poolOptions?.connectionTimeoutMillis ?? 20_000,
+      idleTimeoutMillis: options.poolOptions?.idleTimeoutMillis ?? 30_000,
+    }),
+  } as const;
+}
+
 /**
  * Creates a lazy Postgres client from either `contractJson` or a TypeScript-authored `contract`.
  * Static query surfaces are available immediately, while `runtime()` instantiates the driver/pool on first call.
@@ -115,19 +155,11 @@ export default function postgres<TContract extends SqlContract<SqlStorage>>(
   options: PostgresOptions<TContract>,
 ): PostgresClient<TContract> {
   const contract = resolveContract(options);
-  const binding = resolvePostgresBinding(options);
+  let binding = resolveOptionalPostgresBinding(options);
   const stack = createSqlExecutionStack({
     target: postgresTarget,
     adapter: postgresAdapter,
-    driver:
-      options.cursor === undefined
-        ? postgresDriver
-        : {
-            ...postgresDriver,
-            create() {
-              return postgresDriver.create({ cursor: options.cursor });
-            },
-          },
+    driver: postgresDriver,
     extensionPacks: options.extensions ?? [],
   });
 
@@ -138,49 +170,112 @@ export default function postgres<TContract extends SqlContract<SqlStorage>>(
 
   const schema: PostgresClient<TContract>['schema'] = schemaBuilder(context);
   const sql = sqlBuilder({ context });
+  let runtimeInstance: Runtime | undefined;
+  let runtimeDriver: { connect(binding: unknown): Promise<void> } | undefined;
+  let driverConnected = false;
+  let connectPromise: Promise<void> | undefined;
+  let backgroundConnectError: unknown;
+  const connectDriver = async (resolvedBinding: PostgresBinding): Promise<void> => {
+    if (driverConnected) return;
+    if (!runtimeDriver) throw new Error('Postgres runtime driver missing');
+    if (connectPromise) return connectPromise;
+    const runtimeBinding = toRuntimeBinding(resolvedBinding, options);
+    connectPromise = runtimeDriver
+      .connect(runtimeBinding)
+      .then(() => {
+        driverConnected = true;
+      })
+      .catch(async (err) => {
+        backgroundConnectError = err;
+        connectPromise = undefined;
+        if (resolvedBinding.kind === 'url' && runtimeBinding.kind === 'pgPool') {
+          await runtimeBinding.pool.end().catch(() => undefined);
+        }
+        throw err;
+      });
+    return connectPromise;
+  };
+  const getRuntime = (): Runtime => {
+    if (backgroundConnectError !== undefined) {
+      throw backgroundConnectError;
+    }
+
+    if (runtimeInstance) {
+      return runtimeInstance;
+    }
+
+    const stackInstance = instantiateExecutionStack(stack);
+    const driverDescriptor = stack.driver;
+    if (!driverDescriptor) {
+      throw new Error('Driver descriptor missing from execution stack');
+    }
+
+    const driver = driverDescriptor.create({
+      cursor: { disabled: true },
+    });
+    runtimeDriver = driver;
+    if (binding !== undefined) {
+      void connectDriver(binding).catch(() => undefined);
+    }
 
-  let runtimePromise: Promise<Runtime> | undefined;
+    runtimeInstance = createRuntime({
+      stackInstance,
+      context,
+      driver,
+      verify: options.verify ?? { mode: 'onFirstUse', requireMarker: false },
+      ...(options.plugins ? { plugins: options.plugins } : {}),
+    });
+
+    return runtimeInstance;
+  };
+  const orm: OrmClient<TContract> = ormBuilder({
+    contract,
+    runtime: {
+      execute(plan) {
+        return getRuntime().execute(plan);
+      },
+      connection() {
+        return getRuntime().connection();
+      },
+    },
+  });
 
   return {
     sql,
+    kysely(runtime: Runtime) {
+      return new Kysely<KyselifyContract<TContract>>({
+        dialect: new KyselyPrismaDialect({ runtime, contract }),
+      });
+    },
     schema,
+    orm,
     context,
     stack,
-    async runtime() {
-      if (runtimePromise) {
-        return runtimePromise;
+    async connect(bindingInput) {
+      if (driverConnected || connectPromise) {
+        throw new Error('Postgres client already connected');
       }
 
-      runtimePromise = (async () => {
-        const stackInstance = instantiateExecutionStack(stack);
-        const driver = stackInstance.driver;
-        if (driver === undefined) {
-          throw new Error('Relational runtime requires a driver descriptor on the execution stack');
-        }
+      if (bindingInput !== undefined) {
+        binding = resolvePostgresBinding(bindingInput);
+      }
 
-        try {
-          // `binding` is normalized by resolvePostgresBinding(), so this call site remains
-          // type-safe in practice while SqlRuntimeDriverInstance currently uses SqlDriver<unknown>.
-          await driver.connect(binding);
-
-          return createRuntime({
-            stackInstance,
-            context,
-            driver,
-            verify: options.verify ?? { mode: 'onFirstUse', requireMarker: false },
-            ...ifDefined('plugins', options.plugins),
-          });
-        } catch (error) {
-          await driver.close().catch(() => undefined);
-          throw error;
-        }
-      })();
+      if (binding === undefined) {
+        throw new Error(
+          'Postgres binding not configured. Pass url/pg/binding to postgres(...) or call db.connect({ ... }).',
+        );
+      }
 
-      runtimePromise.catch(() => {
-        runtimePromise = undefined;
-      });
+      const runtime = getRuntime();
+      if (driverConnected) {
+        return runtime;
+      }
 
-      return runtimePromise;
+      await connectDriver(binding);
+      return runtime;
+    },
+    runtime() {
+      return getRuntime();
     },
   };
 }