@prisma-next/postgres 0.0.1

package/README.md

@@ -0,0 +1,73 @@
+# @prisma-next/postgres
+
+One-liner lazy Postgres client for Prisma Next runtime composition.
+
+## Package Classification
+
+- **Domain**: targets
+- **Layer**: clients
+- **Plane**: runtime
+
+## Overview
+
+`@prisma-next/postgres/runtime` exposes a single `postgres(...)` helper that composes the SQL execution stack for Postgres and returns static query roots immediately:
+
+- `db.sql`
+- `db.schema`
+- `db.context`
+- `db.stack`
+
+Runtime and connection resources are deferred until `await db.runtime()` is called. The getter returns `Promise<Runtime>`.
+
+When URL binding is used, pool timeouts are configurable via `poolOptions`:
+
+- `poolOptions.connectionTimeoutMillis` (default `20_000`)
+- `poolOptions.idleTimeoutMillis` (default `30_000`)
+
+## Responsibilities
+
+- Build a static Postgres execution stack from target, adapter, and driver descriptors
+- Build static query 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
+
+## Dependencies
+
+- `@prisma-next/sql-runtime` for stack/context/runtime primitives
+- `@prisma-next/core-execution-plane` for stack instantiation
+- `@prisma-next/target-postgres` for target descriptor
+- `@prisma-next/adapter-postgres` for adapter descriptor
+- `@prisma-next/driver-postgres` for driver descriptor
+- `@prisma-next/sql-lane` for `sql(...)`
+- `@prisma-next/sql-relational-core` for `schema(...)`
+- `@prisma-next/sql-contract` for `validateContract(...)` and contract types
+- `pg` for binding validation when using `pg` (Pool or Client) input
+
+## Architecture
+
+```mermaid
+flowchart TD
+    App[App Code] --> Client[postgres(...)]
+    Client --> Static[Static roots: sql schema 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]
+
+    Runtime --> Target[@prisma-next/target-postgres]
+    Runtime --> Adapter[@prisma-next/adapter-postgres]
+    Runtime --> Driver[@prisma-next/driver-postgres]
+    Runtime --> SqlRuntime[@prisma-next/sql-runtime]
+    Runtime --> ExecPlane[@prisma-next/core-execution-plane]
+```
+
+## Related Docs
+
+- 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`

package/dist/runtime.d.mts

@@ -0,0 +1,58 @@
+import { PostgresBinding, PostgresBinding as PostgresBinding$1, PostgresDriverCreateOptions } from "@prisma-next/driver-postgres/runtime";
+import { SelectBuilder } from "@prisma-next/sql-lane";
+import { SchemaHandle } from "@prisma-next/sql-relational-core/schema";
+import { ExecutionContext, Plugin, Runtime, RuntimeVerifyOptions, SqlExecutionStackWithDriver, SqlRuntimeExtensionDescriptor } from "@prisma-next/sql-runtime";
+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 PostgresBindingInput = {
+  readonly binding: PostgresBinding$1;
+  readonly url?: never;
+  readonly pg?: never;
+} | {
+  readonly url: string;
+  readonly binding?: never;
+  readonly pg?: never;
+} | {
+  readonly pg: Pool | Client;
+  readonly binding?: never;
+  readonly url?: never;
+};
+//#endregion
+//#region src/runtime/postgres.d.ts
+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';
+interface PostgresClient<TContract extends SqlContract<SqlStorage>> {
+  readonly sql: SelectBuilder<TContract, unknown, ExtractCodecTypes<TContract>, ExtractOperationTypes<TContract>>;
+  readonly schema: SchemaHandle<TContract, ExtractCodecTypes<TContract>, ToSchemaOperationTypes<ExtractOperationTypes<TContract>>>;
+  readonly context: ExecutionContext<TContract>;
+  readonly stack: SqlExecutionStackWithDriver<PostgresTargetId>;
+  runtime(): Promise<Runtime>;
+}
+interface PostgresOptionsBase<TContract extends SqlContract<SqlStorage>> {
+  readonly extensions?: readonly SqlRuntimeExtensionDescriptor<PostgresTargetId>[];
+  readonly plugins?: readonly Plugin<TContract>[];
+  readonly verify?: RuntimeVerifyOptions;
+  readonly cursor?: PostgresDriverCreateOptions['cursor'];
+}
+type PostgresOptionsWithContract<TContract extends SqlContract<SqlStorage>> = PostgresBindingInput & PostgresOptionsBase<TContract> & {
+  readonly contract: TContract;
+  readonly contractJson?: never;
+};
+type PostgresOptionsWithContractJson<TContract extends SqlContract<SqlStorage>> = PostgresBindingInput & PostgresOptionsBase<TContract> & {
+  readonly contractJson: unknown;
+  readonly contract?: never;
+};
+type PostgresOptions<TContract extends SqlContract<SqlStorage>> = PostgresOptionsWithContract<TContract> | PostgresOptionsWithContractJson<TContract>;
+/**
+ * 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.
+ */
+declare function postgres<TContract extends SqlContract<SqlStorage>>(options: PostgresOptionsWithContract<TContract>): PostgresClient<TContract>;
+declare function postgres<TContract extends SqlContract<SqlStorage>>(options: PostgresOptionsWithContractJson<TContract>): PostgresClient<TContract>;
+//#endregion
+export { type PostgresBinding, type PostgresClient, type PostgresOptions, type PostgresOptionsBase, type PostgresOptionsWithContract, type PostgresOptionsWithContractJson, postgres 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/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"}

package/dist/runtime.mjs

@@ -0,0 +1,137 @@
+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 { validateContract } from "@prisma-next/sql-contract/validate";
+import { sql } from "@prisma-next/sql-lane";
+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 { 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"
+	});
+	let parsed;
+	try {
+		parsed = new URL(trimmed);
+	} catch {
+		throw bindingError("Postgres URL must be a valid URL", {
+			field: "url",
+			reason: "invalid-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
+	});
+	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 (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 instanceof Pool) return {
+		kind: "pgPool",
+		pool: pgBinding
+	};
+	if (pgBinding instanceof Client) return {
+		kind: "pgClient",
+		client: pgBinding
+	};
+	throw bindingError("Unable to determine pg binding type from pg input; use binding with explicit kind", { reason: "unknown-pg-instance" });
+}
+
+//#endregion
+//#region src/runtime/postgres.ts
+function hasContractJson(options) {
+	return "contractJson" in options;
+}
+function resolveContract(options) {
+	return validateContract(hasContractJson(options) ? options.contractJson : options.contract);
+}
+function postgres(options) {
+	const contract = resolveContract(options);
+	const binding = resolvePostgresBinding(options);
+	const stack = createSqlExecutionStack({
+		target: postgresTarget,
+		adapter: postgresAdapter,
+		driver: options.cursor === void 0 ? postgresDriver : {
+			...postgresDriver,
+			create() {
+				return postgresDriver.create({ cursor: options.cursor });
+			}
+		},
+		extensionPacks: options.extensions ?? []
+	});
+	const context = createExecutionContext({
+		contract,
+		stack
+	});
+	const schema$1 = schema(context);
+	const sql$1 = sql({ context });
+	let runtimePromise;
+	return {
+		sql: sql$1,
+		schema: schema$1,
+		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;
+		}
+	};
+}
+
+//#endregion
+export { postgres as default };
+//# sourceMappingURL=runtime.mjs.map

package/dist/runtime.mjs.map

@@ -0,0 +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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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@prisma-next/postgres",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "One-liner lazy Postgres client composition for Prisma Next",
+  "dependencies": {
+    "pg": "8.16.3",
+    "@prisma-next/adapter-postgres": "0.0.1",
+    "@prisma-next/core-execution-plane": "0.0.1",
+    "@prisma-next/sql-contract": "0.0.1",
+    "@prisma-next/driver-postgres": "0.0.1",
+    "@prisma-next/sql-relational-core": "0.0.1",
+    "@prisma-next/target-postgres": "0.0.1",
+    "@prisma-next/sql-runtime": "0.0.1",
+    "@prisma-next/sql-lane": "0.0.1",
+    "@prisma-next/utils": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/pg": "8.16.0",
+    "tsdown": "0.18.4",
+    "typescript": "5.9.3",
+    "vitest": "4.0.17",
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/tsdown": "0.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/runtime.d.mts",
+      "import": "./dist/runtime.mjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.mts",
+      "import": "./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",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  }
+}

package/src/exports/runtime.ts

@@ -0,0 +1,9 @@
+export type { PostgresBinding } from '@prisma-next/driver-postgres/runtime';
+export type {
+  PostgresClient,
+  PostgresOptions,
+  PostgresOptionsBase,
+  PostgresOptionsWithContract,
+  PostgresOptionsWithContractJson,
+} from '../runtime/postgres';
+export { default } from '../runtime/postgres';

package/src/runtime/binding.ts

@@ -0,0 +1,115 @@
+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 PostgresBindingInput =
+  | {
+      readonly binding: PostgresBinding;
+      readonly url?: never;
+      readonly pg?: never;
+    }
+  | {
+      readonly url: string;
+      readonly binding?: never;
+      readonly pg?: never;
+    }
+  | {
+      readonly pg: Pool | Client;
+      readonly binding?: never;
+      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,
+  });
+}
+
+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',
+    });
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw bindingError('Postgres URL must be a valid URL', {
+      field: 'url',
+      reason: 'invalid-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,
+    });
+  }
+
+  return trimmed;
+}
+
+export function resolvePostgresBinding(options: PostgresBindingInput): PostgresBinding {
+  const providedCount =
+    Number(options.binding !== undefined) +
+    Number(options.url !== undefined) +
+    Number(options.pg !== undefined);
+
+  if (providedCount !== 1) {
+    throw bindingError('Provide one binding input: binding, url, or pg', {
+      providedCount,
+    });
+  }
+
+  if (options.binding !== undefined) {
+    return options.binding;
+  }
+
+  if (options.url !== undefined) {
+    return { kind: 'url', url: validatePostgresUrl(options.url) };
+  }
+
+  const pgBinding = options.pg;
+  if (pgBinding === undefined) {
+    throw bindingError('Invariant violation: expected pg binding after validation', {
+      reason: 'missing-pg-binding',
+    });
+  }
+
+  if (pgBinding instanceof PgPool) {
+    return { kind: 'pgPool', pool: pgBinding };
+  }
+
+  if (pgBinding instanceof PgClient) {
+    return { kind: 'pgClient', client: pgBinding };
+  }
+
+  throw bindingError(
+    'Unable to determine pg binding type from pg input; use binding with explicit kind',
+    {
+      reason: 'unknown-pg-instance',
+    },
+  );
+}

package/src/runtime/postgres.ts

@@ -0,0 +1,186 @@
+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 {
+  ExtractCodecTypes,
+  ExtractOperationTypes,
+  SqlContract,
+  SqlStorage,
+} from '@prisma-next/sql-contract/types';
+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 type { SchemaHandle } from '@prisma-next/sql-relational-core/schema';
+import { schema as schemaBuilder } from '@prisma-next/sql-relational-core/schema';
+import type {
+  OperationTypeSignature,
+  OperationTypes,
+} from '@prisma-next/sql-relational-core/types';
+import type {
+  ExecutionContext,
+  Plugin,
+  Runtime,
+  RuntimeVerifyOptions,
+  SqlExecutionStackWithDriver,
+  SqlRuntimeExtensionDescriptor,
+} from '@prisma-next/sql-runtime';
+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 { type PostgresBindingInput, resolvePostgresBinding } from './binding';
+
+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>;
+
+export type PostgresTargetId = 'postgres';
+
+export interface PostgresClient<TContract extends SqlContract<SqlStorage>> {
+  readonly sql: SelectBuilder<
+    TContract,
+    unknown,
+    ExtractCodecTypes<TContract>,
+    ExtractOperationTypes<TContract>
+  >;
+  readonly schema: SchemaHandle<
+    TContract,
+    ExtractCodecTypes<TContract>,
+    ToSchemaOperationTypes<ExtractOperationTypes<TContract>>
+  >;
+  readonly context: ExecutionContext<TContract>;
+  readonly stack: SqlExecutionStackWithDriver<PostgresTargetId>;
+  runtime(): Promise<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'];
+}
+
+export type PostgresOptionsWithContract<TContract extends SqlContract<SqlStorage>> =
+  PostgresBindingInput &
+    PostgresOptionsBase<TContract> & {
+      readonly contract: TContract;
+      readonly contractJson?: never;
+    };
+
+export type PostgresOptionsWithContractJson<TContract extends SqlContract<SqlStorage>> =
+  PostgresBindingInput &
+    PostgresOptionsBase<TContract> & {
+      readonly contractJson: unknown;
+      readonly contract?: never;
+    };
+
+export type PostgresOptions<TContract extends SqlContract<SqlStorage>> =
+  | PostgresOptionsWithContract<TContract>
+  | PostgresOptionsWithContractJson<TContract>;
+
+function hasContractJson<TContract extends SqlContract<SqlStorage>>(
+  options: PostgresOptions<TContract>,
+): options is PostgresOptionsWithContractJson<TContract> {
+  return 'contractJson' in options;
+}
+
+function resolveContract<TContract extends SqlContract<SqlStorage>>(
+  options: PostgresOptions<TContract>,
+): TContract {
+  const contractInput = hasContractJson(options) ? options.contractJson : options.contract;
+  return validateContract<TContract>(contractInput);
+}
+
+/**
+ * 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.
+ */
+export default function postgres<TContract extends SqlContract<SqlStorage>>(
+  options: PostgresOptionsWithContract<TContract>,
+): PostgresClient<TContract>;
+export default function postgres<TContract extends SqlContract<SqlStorage>>(
+  options: PostgresOptionsWithContractJson<TContract>,
+): PostgresClient<TContract>;
+export default function postgres<TContract extends SqlContract<SqlStorage>>(
+  options: PostgresOptions<TContract>,
+): PostgresClient<TContract> {
+  const contract = resolveContract(options);
+  const binding = resolvePostgresBinding(options);
+  const stack = createSqlExecutionStack({
+    target: postgresTarget,
+    adapter: postgresAdapter,
+    driver:
+      options.cursor === undefined
+        ? postgresDriver
+        : {
+            ...postgresDriver,
+            create() {
+              return postgresDriver.create({ cursor: options.cursor });
+            },
+          },
+    extensionPacks: options.extensions ?? [],
+  });
+
+  const context = createExecutionContext({
+    contract,
+    stack,
+  });
+
+  const schema: PostgresClient<TContract>['schema'] = schemaBuilder(context);
+  const sql = sqlBuilder({ context });
+
+  let runtimePromise: Promise<Runtime> | undefined;
+
+  return {
+    sql,
+    schema,
+    context,
+    stack,
+    async runtime() {
+      if (runtimePromise) {
+        return runtimePromise;
+      }
+
+      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');
+        }
+
+        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;
+        }
+      })();
+
+      runtimePromise.catch(() => {
+        runtimePromise = undefined;
+      });
+
+      return runtimePromise;
+    },
+  };
+}