@dbsp/adapter-pgsql 3.4.0 → 3.5.0

package/dist/index.d.ts

@@ -960,6 +960,10 @@ declare class PgsqlTransactionTimeoutError extends Error {
 /**
  * Options for PgsqlAdapter.
  */
+interface PgsqlPreparedStatementsOptions {
+    /** Maximum distinct compiled statements admitted per executor (default: 500). */
+    readonly maxStatements?: number;
+}
 interface PgsqlAdapterOptions {
     /** Schema name for multi-tenant queries */
     readonly schemaName?: string;
@@ -978,6 +982,11 @@ interface PgsqlAdapterOptions {
     readonly defaultPkColumnName?: string;
     /** Convention for deriving FK column names: (tableName, pkName) => fkColumnName */
     readonly deriveFkColumnName?: FkColumnDerivation;
+    /**
+     * Opt in to node-postgres named prepared statements for compiled queries with
+     * parameters. `true` uses the default statement cap; an object overrides it.
+     */
+    readonly preparedStatements?: boolean | PgsqlPreparedStatementsOptions;
 }
 interface PgsqlPoolAdapterOptions extends PgsqlAdapterOptions {
     readonly borrowedClient?: false;
@@ -1042,6 +1051,8 @@ declare class PgsqlAdapter<DB = unknown> implements Adapter<DB> {
     private readonly naming;
     private readonly model;
     private readonly logger;
+    private readonly preparedStatements;
+    private readonly preparedStatementRegistry;
     private readonly _capabilities;
     private readonly defaultPk;
     private readonly deriveFk;
@@ -3585,4 +3596,4 @@ declare function escapeDiagnosticText(value: string): string;
  */
 declare function validateSqlExpression(sql: string, context: string): void;
 
-export { ADD_CHECK_RULE_ID, ALTER_AUTHORITY_OBSERVATION, ALTER_COLUMN_SET_NOT_NULL_OPERATION_KIND, ALTER_TYPE_ADD_VALUE_OPERATION_KIND, ATTACH_LOGICAL_IDENTITY_OPERATION_KIND, type AddedEnumValue, type AlterColumnSetNotNullPayload, type AlterTypeAddValuePayload, type AttachLogicalIdentityPayload, type BatchValuesJoinDecision, COLUMN_EXISTS_OBSERVATION, CamelCaseNamingPlugin, type CanonicalizeCheckConstraintsOptions, type ChangeKind, CheckConstraintCanonicalizationError, type CheckConstraintCanonicalizationWarning, CheckConstraintNewEnumValueError, ColumnDefaultCanonicalizationError, type ColumnDefaultCanonicalizationWarning, type ComparePgsqlDatabaseSchemaOptions, type CompareSchemataOptions, type CompiledResult, type CompilerContext, type CompilerOptions, type CompilerState, type ConflictAction, type ConflictTarget, type CursorHoldOption, type CursorOptions, type CursorScrollOption, DBSP_LOGICAL_IDENTITY_TABLE, DBSP_META_SCHEMA, DBSP_TRANSITION_JOURNAL_TABLE, DBSP_TRANSITION_RUN_PLAN_TABLE, DBSP_TRANSITION_RUN_TABLE, DEFAULT_PK_COLUMN, DEFAULT_REDACTION_PATTERNS, type Decision, type DeleteConfig, type DetectedHierarchy, type DiffSummary, ENGINE_VERSION_OBSERVATION, ENUM_ADD_VALUE_RULE_ID, ENUM_LABEL_VISIBLE_OBSERVATION, ENUM_TYPE_EXISTS_OBSERVATION, type EnumAddValueMatch, type EnumAddValueRuleOptions, type ExplainFormat, type ExplainOptions, type ExplainPlan, ExpressionCanonicalizationUnavailableError, type ExpressionCanonicalizationWarning, type ExpressionHandler, type FetchDirection, type FetchOptions, type FkColumnDerivation, type GenerateDDLOptions, type IdentityAdoptionAsserter, IdentityNamingPlugin, type IncludeHandler, type IncludeResult, type IndexCapabilityContext, IndexFeatureUnsupportedError, type IndexRenderSpec, type InsertConfig, type IntrospectedModelIR, type IntrospectionOptions, InvalidIdentifierError, type JoinDecision, LOGICAL_IDENTITY_ADOPTION_RULE_ID, LOGICAL_IDENTITY_CARRIER_OBSERVATION, type LeafCompileFn, type LogicalIdentityAdoptionMatch, type LogicalIdentityAdoptionRuleOptions, MANUAL_SQL_OPERATION_KIND, type ManualSqlPayload, type MigrationRecord, type MigrationSQLOptions, NO_NULLS_GUARD, type NamingPlugin, NonConvergentSchemaDiffError, type NonConvergentSchemaDiffSurface, PG_INTROSPECTION_ARTIFACT, PG_OPERATION_PACK_ARTIFACT, PG_RULE_PACK_ARTIFACT, type ParamRefValidationResult, type ParsedMigrationFile, type PgAdvisoryLockKey, type PgAdvisoryLockResult, PgExecutionContractDerivationError, type PgTransitionClientLease, type PgTransitionPackOptions, PgsqlAdapter, type PgsqlAdapterOptions, PgsqlAdvisoryLockOptionsError, type PgsqlBorrowedClientAdapterOptions, PgsqlPinnedConnectionAbortSignalError, type PgsqlPoolAdapterOptions, PgsqlRawSqlTransactionControlError, PgsqlTransactionAbortSignalError, PgsqlTransactionAbortedCommitError, PgsqlTransactionAbortedError, PgsqlTransactionOptionsError, PgsqlTransactionTimeoutError, PlanCompiler, type PlanDecision, type PrecompiledJoinDecision, type RedactionConfig, type RedactionPattern, type RollbackOnlyPgsqlScope, SET_NOT_NULL_RULE_ID, type SchemaChange, type SchemaDiff, type SchemaScopeOptions, type SetNotNullMatch, type SetNotNullRuleOptions, type SetOperationResult, type SimplifiedPlanReport, type StreamConfig, type UpdateConfig, type UpsertConfig, type WhereDispatcher, type WhereHandler, acquirePgTransitionClient, assertCreateIndexSupported, assertCreateIndexesSupported, assertNoRepeatedExpressionSurfaceDrift, bm25Search, booleanSearch, boost, buildCloseCursor, buildDeclareCursor, buildExplain, buildExplainAnalyzeJson, buildExplainPlan, buildExplainVerbose, buildFetch, buildFetchAll, buildFetchFirst, buildFetchForward, buildFetchNext, buildOnConflictClause, buildStreamingStatements, camelCaseNaming, canGenerateCreateIndex, canonicalizeCheckConstraints, collectAndValidateParamRefs, comparePgsqlDatabaseSchema, compareSchemata, compileDelete, compileInsert, compileMutation, compilePlan, compileSetOperation, compileUpdate, compileUpsert, conditionalUpdate, cosineDistance, createAlterColumnSetNotNullOperationRuntime, createAlterTypeAddValueOperationRuntime, createAnyExpr, createAttachLogicalIdentityOperationRuntime, createEnumAddValueRule, createEqualityExpr, createLeafCompileFn, createLogicalIdentityAdoptionRule, createManualSqlOperationRuntime, createParamRef, createPgExecutionContract, createPgObservationIssuer, createPgTransitionLessor, createPgTransitionPack, createPgTransitionRunPersister, createPgsqlAdapter, createPgsqlCompileOnlyAdapter, createSetNotNullRule, createTypeCastParamRef, defaultFkDerivation, derivePostgresqlCapabilitiesForVersion, ensureMigrationsTable, ensureTransitionJournal, escapeDiagnosticText, evaluatePgExecutionContract, excludedRef, executePgObservationFromLessor, generateCreateIndex, generateCursorName, generateDDL, generateDownSQL, generateMigrationFile, generateMigrationSQL, generateSeries, getAppliedMigrations, getNamingPluginForDbCasing, getNextSchemaVersion, getRowEstimates, getTotalExecutionTime, identityNaming, innerProduct, introspect, isBatchValuesJoinDecision, isDestructiveDown, isJoinDecision, isMigrationApplied, isPrecompiledJoinDecision, isReservedKeyword, l2Distance, mapColumnType, mapOnDeleteAction, nextval, normalizeManualSqlPayload, parse, parseExplainJson, parseMigrationFile, pgTargetIdentityMismatch, rawDistance, readPgExecutionTargetFromClient, readPgObservationContextFromLessor, readTransitionJournal, recordMigration, redactParams, removeMigrationRecord, renderAlterColumnSetNotNullSql, renderAlterTypeAddValueSql, renderAttachLogicalIdentityLockSql, renderCreateDbspMetaSchemaSql, renderCreateIndex, renderCreateLogicalIdentityIndexesSql, renderCreateLogicalIdentitySideTableSql, renderCreateTransitionJournalTableSql, renderCreateTransitionRunPlanTableSql, renderCreateTransitionRunTableSql, renderInsertLogicalIdentitySql, renderNoNullsCheckSql, renderSetNotNullLockSql, resolveLogicalName, sanitizeForDisplay, score, validateIdentifier, validateIdentifiers, validateParamRef, validateQualifiedIdentifier, validateSqlExpression, vectorDims, withMigrationLock };
+export { ADD_CHECK_RULE_ID, ALTER_AUTHORITY_OBSERVATION, ALTER_COLUMN_SET_NOT_NULL_OPERATION_KIND, ALTER_TYPE_ADD_VALUE_OPERATION_KIND, ATTACH_LOGICAL_IDENTITY_OPERATION_KIND, type AddedEnumValue, type AlterColumnSetNotNullPayload, type AlterTypeAddValuePayload, type AttachLogicalIdentityPayload, type BatchValuesJoinDecision, COLUMN_EXISTS_OBSERVATION, CamelCaseNamingPlugin, type CanonicalizeCheckConstraintsOptions, type ChangeKind, CheckConstraintCanonicalizationError, type CheckConstraintCanonicalizationWarning, CheckConstraintNewEnumValueError, ColumnDefaultCanonicalizationError, type ColumnDefaultCanonicalizationWarning, type ComparePgsqlDatabaseSchemaOptions, type CompareSchemataOptions, type CompiledResult, type CompilerContext, type CompilerOptions, type CompilerState, type ConflictAction, type ConflictTarget, type CursorHoldOption, type CursorOptions, type CursorScrollOption, DBSP_LOGICAL_IDENTITY_TABLE, DBSP_META_SCHEMA, DBSP_TRANSITION_JOURNAL_TABLE, DBSP_TRANSITION_RUN_PLAN_TABLE, DBSP_TRANSITION_RUN_TABLE, DEFAULT_PK_COLUMN, DEFAULT_REDACTION_PATTERNS, type Decision, type DeleteConfig, type DetectedHierarchy, type DiffSummary, ENGINE_VERSION_OBSERVATION, ENUM_ADD_VALUE_RULE_ID, ENUM_LABEL_VISIBLE_OBSERVATION, ENUM_TYPE_EXISTS_OBSERVATION, type EnumAddValueMatch, type EnumAddValueRuleOptions, type ExplainFormat, type ExplainOptions, type ExplainPlan, ExpressionCanonicalizationUnavailableError, type ExpressionCanonicalizationWarning, type ExpressionHandler, type FetchDirection, type FetchOptions, type FkColumnDerivation, type GenerateDDLOptions, type IdentityAdoptionAsserter, IdentityNamingPlugin, type IncludeHandler, type IncludeResult, type IndexCapabilityContext, IndexFeatureUnsupportedError, type IndexRenderSpec, type InsertConfig, type IntrospectedModelIR, type IntrospectionOptions, InvalidIdentifierError, type JoinDecision, LOGICAL_IDENTITY_ADOPTION_RULE_ID, LOGICAL_IDENTITY_CARRIER_OBSERVATION, type LeafCompileFn, type LogicalIdentityAdoptionMatch, type LogicalIdentityAdoptionRuleOptions, MANUAL_SQL_OPERATION_KIND, type ManualSqlPayload, type MigrationRecord, type MigrationSQLOptions, NO_NULLS_GUARD, type NamingPlugin, NonConvergentSchemaDiffError, type NonConvergentSchemaDiffSurface, PG_INTROSPECTION_ARTIFACT, PG_OPERATION_PACK_ARTIFACT, PG_RULE_PACK_ARTIFACT, type ParamRefValidationResult, type ParsedMigrationFile, type PgAdvisoryLockKey, type PgAdvisoryLockResult, PgExecutionContractDerivationError, type PgTransitionClientLease, type PgTransitionPackOptions, PgsqlAdapter, type PgsqlAdapterOptions, PgsqlAdvisoryLockOptionsError, type PgsqlBorrowedClientAdapterOptions, PgsqlPinnedConnectionAbortSignalError, type PgsqlPoolAdapterOptions, type PgsqlPreparedStatementsOptions, PgsqlRawSqlTransactionControlError, PgsqlTransactionAbortSignalError, PgsqlTransactionAbortedCommitError, PgsqlTransactionAbortedError, PgsqlTransactionOptionsError, PgsqlTransactionTimeoutError, PlanCompiler, type PlanDecision, type PrecompiledJoinDecision, type RedactionConfig, type RedactionPattern, type RollbackOnlyPgsqlScope, SET_NOT_NULL_RULE_ID, type SchemaChange, type SchemaDiff, type SchemaScopeOptions, type SetNotNullMatch, type SetNotNullRuleOptions, type SetOperationResult, type SimplifiedPlanReport, type StreamConfig, type UpdateConfig, type UpsertConfig, type WhereDispatcher, type WhereHandler, acquirePgTransitionClient, assertCreateIndexSupported, assertCreateIndexesSupported, assertNoRepeatedExpressionSurfaceDrift, bm25Search, booleanSearch, boost, buildCloseCursor, buildDeclareCursor, buildExplain, buildExplainAnalyzeJson, buildExplainPlan, buildExplainVerbose, buildFetch, buildFetchAll, buildFetchFirst, buildFetchForward, buildFetchNext, buildOnConflictClause, buildStreamingStatements, camelCaseNaming, canGenerateCreateIndex, canonicalizeCheckConstraints, collectAndValidateParamRefs, comparePgsqlDatabaseSchema, compareSchemata, compileDelete, compileInsert, compileMutation, compilePlan, compileSetOperation, compileUpdate, compileUpsert, conditionalUpdate, cosineDistance, createAlterColumnSetNotNullOperationRuntime, createAlterTypeAddValueOperationRuntime, createAnyExpr, createAttachLogicalIdentityOperationRuntime, createEnumAddValueRule, createEqualityExpr, createLeafCompileFn, createLogicalIdentityAdoptionRule, createManualSqlOperationRuntime, createParamRef, createPgExecutionContract, createPgObservationIssuer, createPgTransitionLessor, createPgTransitionPack, createPgTransitionRunPersister, createPgsqlAdapter, createPgsqlCompileOnlyAdapter, createSetNotNullRule, createTypeCastParamRef, defaultFkDerivation, derivePostgresqlCapabilitiesForVersion, ensureMigrationsTable, ensureTransitionJournal, escapeDiagnosticText, evaluatePgExecutionContract, excludedRef, executePgObservationFromLessor, generateCreateIndex, generateCursorName, generateDDL, generateDownSQL, generateMigrationFile, generateMigrationSQL, generateSeries, getAppliedMigrations, getNamingPluginForDbCasing, getNextSchemaVersion, getRowEstimates, getTotalExecutionTime, identityNaming, innerProduct, introspect, isBatchValuesJoinDecision, isDestructiveDown, isJoinDecision, isMigrationApplied, isPrecompiledJoinDecision, isReservedKeyword, l2Distance, mapColumnType, mapOnDeleteAction, nextval, normalizeManualSqlPayload, parse, parseExplainJson, parseMigrationFile, pgTargetIdentityMismatch, rawDistance, readPgExecutionTargetFromClient, readPgObservationContextFromLessor, readTransitionJournal, recordMigration, redactParams, removeMigrationRecord, renderAlterColumnSetNotNullSql, renderAlterTypeAddValueSql, renderAttachLogicalIdentityLockSql, renderCreateDbspMetaSchemaSql, renderCreateIndex, renderCreateLogicalIdentityIndexesSql, renderCreateLogicalIdentitySideTableSql, renderCreateTransitionJournalTableSql, renderCreateTransitionRunPlanTableSql, renderCreateTransitionRunTableSql, renderInsertLogicalIdentitySql, renderNoNullsCheckSql, renderSetNotNullLockSql, resolveLogicalName, sanitizeForDisplay, score, validateIdentifier, validateIdentifiers, validateParamRef, validateQualifiedIdentifier, validateSqlExpression, vectorDims, withMigrationLock };

package/dist/index.js

@@ -23010,6 +23010,123 @@ function matchGlob(pattern, value) {
 
 // src/pgsql-adapter.ts
 init_naming_plugin();
+
+// src/prepared-statements.ts
+import { createHash as createHash2 } from "crypto";
+var DEFAULT_MAX_PREPARED_STATEMENTS = 500;
+var PREPARED_STATEMENT_NAMESPACE = "dbsp_ps_";
+function derivePreparedStatementFingerprint(sql) {
+  return createHash2("sha256").update(sql).digest("hex");
+}
+function derivePreparedStatementName(sql) {
+  return `${PREPARED_STATEMENT_NAMESPACE}${derivePreparedStatementFingerprint(sql).slice(0, 32)}`;
+}
+var PreparedStatementRegistry = class {
+  constructor(maxStatements, hashName = derivePreparedStatementName) {
+    this.maxStatements = maxStatements;
+    this.hashName = hashName;
+  }
+  maxStatements;
+  hashName;
+  candidates = /* @__PURE__ */ new Set();
+  namesByFingerprint = /* @__PURE__ */ new Map();
+  fingerprintsByName = /* @__PURE__ */ new Map();
+  pendingByFingerprint = /* @__PURE__ */ new Map();
+  collisionRejectedFingerprints = /* @__PURE__ */ new Set();
+  nextGeneration = 0;
+  /**
+   * Reserves a name only from the second sighting onward. Call confirm after
+   * successful named execution, or abort when that execution fails.
+   */
+  admit(sql) {
+    const fingerprint = derivePreparedStatementFingerprint(sql);
+    if (this.collisionRejectedFingerprints.has(fingerprint)) return void 0;
+    const knownName = this.namesByFingerprint.get(fingerprint);
+    if (knownName !== void 0) return { name: knownName };
+    const pending = this.pendingByFingerprint.get(fingerprint);
+    if (pending !== void 0) {
+      return this.reserveAttempt(fingerprint, pending);
+    }
+    if (!this.candidates.delete(fingerprint)) {
+      if (this.atCapacity()) return void 0;
+      if (this.candidates.size >= this.maxStatements) {
+        const oldest = this.candidates.values().next().value;
+        if (oldest !== void 0) this.candidates.delete(oldest);
+      }
+      this.candidates.add(fingerprint);
+      return void 0;
+    }
+    if (this.atCapacity()) return void 0;
+    const name = this.hashName(sql);
+    const existingFingerprint = this.fingerprintsByName.get(name);
+    if (existingFingerprint !== void 0 && existingFingerprint !== fingerprint) {
+      this.rejectHashCollision(fingerprint);
+      return void 0;
+    }
+    this.fingerprintsByName.set(name, fingerprint);
+    const reservation = this.reserveAttempt(fingerprint, {
+      name,
+      generations: /* @__PURE__ */ new Set()
+    });
+    if (this.atCapacity()) this.candidates.clear();
+    return reservation;
+  }
+  /** Confirms a reservation only after PostgreSQL accepted its named execution. */
+  confirm(reservation) {
+    const pending = this.pendingByFingerprint.get(reservation.fingerprint);
+    if (pending === void 0 || pending.name !== reservation.name || !pending.generations.has(reservation.generation))
+      return;
+    this.pendingByFingerprint.delete(reservation.fingerprint);
+    this.namesByFingerprint.set(reservation.fingerprint, reservation.name);
+  }
+  /** Aborts only this still-pending attempt, never a later confirmation. */
+  abort(reservation) {
+    const pending = this.pendingByFingerprint.get(reservation.fingerprint);
+    if (pending === void 0 || pending.name !== reservation.name || !pending.generations.delete(reservation.generation))
+      return;
+    if (pending.generations.size !== 0) return;
+    this.pendingByFingerprint.delete(reservation.fingerprint);
+    if (this.fingerprintsByName.get(reservation.name) === reservation.fingerprint) {
+      this.fingerprintsByName.delete(reservation.name);
+    }
+  }
+  atCapacity() {
+    return this.namesByFingerprint.size + this.pendingByFingerprint.size >= this.maxStatements;
+  }
+  reserveAttempt(fingerprint, pending) {
+    this.pendingByFingerprint.set(fingerprint, pending);
+    const reservation = {
+      fingerprint,
+      name: pending.name,
+      generation: this.nextGeneration++
+    };
+    pending.generations.add(reservation.generation);
+    return { name: pending.name, reservation };
+  }
+  /** Keeps a colliding full fingerprint unnamed within a bounded registry. */
+  rejectHashCollision(fingerprint) {
+    if (this.collisionRejectedFingerprints.size >= this.maxStatements) {
+      const oldest = this.collisionRejectedFingerprints.values().next().value;
+      if (oldest !== void 0)
+        this.collisionRejectedFingerprints.delete(oldest);
+    }
+    this.collisionRejectedFingerprints.add(fingerprint);
+    this.candidates.delete(fingerprint);
+  }
+};
+function normalizeMaxPreparedStatements(maxStatements) {
+  const resolved = maxStatements === void 0 ? DEFAULT_MAX_PREPARED_STATEMENTS : maxStatements;
+  if (!Number.isSafeInteger(resolved))
+    throw new Error("preparedStatements.maxStatements must be a safe integer.");
+  const normalized = resolved;
+  if (normalized < 1)
+    throw new Error(
+      "preparedStatements.maxStatements must be greater than zero."
+    );
+  return normalized;
+}
+
+// src/pgsql-adapter.ts
 init_cte_compiler();
 
 // src/set-operation.ts
@@ -23264,6 +23381,8 @@ var pgsqlAdapterInternalOptionsKey = /* @__PURE__ */ Symbol(
   "dbsp-pgsql-adapter-internal-options"
 );
 var activeClientScopes = /* @__PURE__ */ new WeakMap();
+var preparedStatementRegistries = /* @__PURE__ */ new WeakMap();
+var preparedStatementQuarantines = /* @__PURE__ */ new WeakMap();
 var PgsqlRawSqlTransactionControlError = class extends Error {
   dbspRawSqlTransactionControl = true;
   constructor(cause) {
@@ -23334,6 +23453,57 @@ function poolClientTransactionOpen(client) {
 function isPgErrorWithCode(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
+function isDriverLocalPreparedStatementNameCollision(error, attemptedName) {
+  const message = `Prepared statements must be unique - '${attemptedName}' was used for a different statement`;
+  return error instanceof Error && !("code" in error) && error.message === message;
+}
+function isVerifiedPreparedStatementInfrastructureError(error) {
+  if (typeof error !== "object" || error === null) return false;
+  const { code, routine } = error;
+  return code === "0A000" && routine === "RevalidateCachedQuery" || code === "26000" && routine === "FetchPreparedStatement" || code === "42P05" && routine === "StorePreparedStatement";
+}
+function didNamedExecutionReachExecution(error) {
+  if (typeof error !== "object" || error === null) return false;
+  const { code, position } = error;
+  return typeof code === "string" && /^[0-9A-Z]{5}$/.test(code) && position === void 0 && !isVerifiedPreparedStatementInfrastructureError(error);
+}
+function shouldAbortPreparedStatementReservation(error, executor, attemptedName) {
+  if (typeof error === "object" && error !== null && "position" in error && error.position !== void 0)
+    return true;
+  if (isDriverLocalPreparedStatementNameCollision(error, attemptedName))
+    return true;
+  if (!isPoolClientLike(executor)) return false;
+  if (didNamedExecutionReachExecution(error)) return false;
+  return !(error instanceof Error && error.message.startsWith("Prepared statements must be unique - '"));
+}
+function isVerifiedClientWidePreparedStatementLoss(error) {
+  if (typeof error !== "object" || error === null) return false;
+  const { code, routine } = error;
+  return code === "26000" && routine === "FetchPreparedStatement";
+}
+function isPreparedStatementQuarantined(client, sql) {
+  const quarantine = preparedStatementQuarantines.get(client);
+  return quarantine?.allStatements === true || quarantine?.fingerprints.has(derivePreparedStatementFingerprint(sql)) === true;
+}
+function hasPreparedStatementQuarantine(client) {
+  return preparedStatementQuarantines.has(client);
+}
+function quarantinePreparedStatement(client, sql, clientWide) {
+  const quarantine = preparedStatementQuarantines.get(client);
+  if (quarantine !== void 0) {
+    if (clientWide) {
+      quarantine.allStatements = true;
+      quarantine.fingerprints.clear();
+    } else if (!quarantine.allStatements) {
+      quarantine.fingerprints.add(derivePreparedStatementFingerprint(sql));
+    }
+    return;
+  }
+  preparedStatementQuarantines.set(client, {
+    allStatements: clientWide,
+    fingerprints: clientWide ? /* @__PURE__ */ new Set() : /* @__PURE__ */ new Set([derivePreparedStatementFingerprint(sql)])
+  });
+}
 function describeTransactionOptionValue(value) {
   if (value === null) return "null";
   if (typeof value === "string") return `string ${JSON.stringify(value)}`;
@@ -24357,6 +24527,45 @@ function getDbspScopeTokenOption(options) {
 function getDbspScopeStateOption(options) {
   return isPgsqlAdapterInternalOptions(options) ? options.dbspScopeState : void 0;
 }
+function getPreparedStatementRegistryOption(options) {
+  return isPgsqlAdapterInternalOptions(options) ? options.preparedStatementRegistry : void 0;
+}
+function getOrCreatePreparedStatementRegistry(executor, maxStatements) {
+  const configured = preparedStatementRegistries.get(executor);
+  if (configured === void 0) {
+    const registry = new PreparedStatementRegistry(maxStatements);
+    preparedStatementRegistries.set(executor, { maxStatements, registry });
+    return registry;
+  }
+  if (configured.maxStatements !== maxStatements) {
+    const executorKind = isPoolClientLike(executor) ? "borrowed client" : "pool";
+    throw new Error(
+      `preparedStatements.maxStatements is configured ${executorKind}-wide: expected ${configured.maxStatements}, received ${maxStatements}.`
+    );
+  }
+  return configured.registry;
+}
+function normalizePreparedStatements(value) {
+  if (value === void 0 || value === false) return false;
+  if (value === true) {
+    return Object.freeze({
+      maxStatements: normalizeMaxPreparedStatements(void 0)
+    });
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      "preparedStatements must be true, false, or a non-null options object."
+    );
+  }
+  return Object.freeze({
+    maxStatements: normalizeMaxPreparedStatements(
+      value.maxStatements
+    )
+  });
+}
+function clonePreparedStatements(config) {
+  return config === false ? false : { maxStatements: config.maxStatements };
+}
 function createPgsqlAdapterFromConstructionOptions(connection, options) {
   return new PgsqlAdapter(
     connection,
@@ -24378,6 +24587,8 @@ var PgsqlAdapter = class {
   naming;
   model;
   logger;
+  preparedStatements;
+  preparedStatementRegistry;
   _capabilities;
   defaultPk;
   deriveFk;
@@ -24424,6 +24635,15 @@ var PgsqlAdapter = class {
     this.naming = getNamingPluginForDbCasing(this._dbCasing);
     this.model = options?.model;
     this.logger = options?.logger;
+    this.preparedStatements = normalizePreparedStatements(
+      options?.preparedStatements
+    );
+    if (this.preparedStatements !== false) {
+      const { maxStatements } = this.preparedStatements;
+      this.preparedStatementRegistry = getPreparedStatementRegistryOption(options) ?? (this.pool !== void 0 ? getOrCreatePreparedStatementRegistry(this.pool, maxStatements) : this.client !== void 0 ? getOrCreatePreparedStatementRegistry(this.client, maxStatements) : void 0);
+    } else {
+      this.preparedStatementRegistry = void 0;
+    }
     this.defaultPk = options?.defaultPkColumnName ?? DEFAULT_PK_COLUMN;
     this.deriveFk = options?.deriveFkColumnName ?? defaultFkDerivation;
     const supportsManagedTransactions = this.pool != null || this.client != null && this.managedTransactions;
@@ -24454,7 +24674,8 @@ var PgsqlAdapter = class {
     const scopeToken = overrides.dbspScopeToken ?? this.scopeToken;
     const scopeState = overrides.dbspScopeState ?? this.scopeState;
     const rollbackOnlyScope = overrides.rollbackOnlyScope ?? this.rollbackOnlyScope ? true : void 0;
-    const hasInternalOptions = adapterManagedTransaction === true || adapterManagedPinnedConnection === true || rollbackOnlyScope === true || scopeToken !== void 0 || scopeState !== void 0;
+    const preparedStatementRegistry = this.preparedStatementRegistry;
+    const hasInternalOptions = adapterManagedTransaction === true || adapterManagedPinnedConnection === true || rollbackOnlyScope === true || scopeToken !== void 0 || scopeState !== void 0 || preparedStatementRegistry !== void 0;
     return {
       ...hasInternalOptions && {
         [pgsqlAdapterInternalOptionsKey]: true
@@ -24463,6 +24684,9 @@ var PgsqlAdapter = class {
       ...this._dbCasing !== void 0 && { dbCasing: this._dbCasing },
       ...this.model !== void 0 && { model: this.model },
       ...this.logger !== void 0 && { logger: this.logger },
+      ...this.preparedStatements !== false && {
+        preparedStatements: clonePreparedStatements(this.preparedStatements)
+      },
       defaultPkColumnName: this.defaultPk,
       deriveFkColumnName: this.deriveFk,
       ...this.borrowedClient && { borrowedClient: true },
@@ -24474,6 +24698,9 @@ var PgsqlAdapter = class {
       ...rollbackOnlyScope === true && { rollbackOnlyScope },
       ...scopeToken !== void 0 && { dbspScopeToken: scopeToken },
       ...scopeState !== void 0 && { dbspScopeState: scopeState },
+      ...preparedStatementRegistry !== void 0 && {
+        preparedStatementRegistry
+      },
       ...overrides
     };
   }
@@ -25058,7 +25285,7 @@ var PgsqlAdapter = class {
   async executeWithMeta(query) {
     this.requireConnection("execute");
     const guardedQuery = guardCompiledQuery(query, "execute");
-    const result = await this.executeQueryProtectingOpenTransaction(guardedQuery.sql, guardedQuery.parameters);
+    const result = await this.executeQueryProtectingOpenTransaction(guardedQuery.sql, guardedQuery.parameters, { prepareEligible: true });
     const metadata = queryResultMetadata(result);
     const rows = this.transformResultRows(result.rows, guardedQuery);
     return {
@@ -26559,11 +26786,11 @@ var PgsqlAdapter = class {
     }
   }
   releaseClient(client, error) {
-    if (error === void 0) {
+    if (error === void 0 && !hasPreparedStatementQuarantine(client)) {
       client.release();
       return;
     }
-    client.release(error);
+    client.release(error ?? true);
   }
   async rollbackAndReleaseSavepoint(client, savepointName, allowedScopeToken, scopeState, options) {
     const rolledBack = await this.rollbackSavepoint(
@@ -27260,7 +27487,8 @@ var PgsqlAdapter = class {
       const rawResult = await this.issueConnectionQuery(
         executor,
         sql,
-        parameters
+        parameters,
+        options.prepareEligible ?? false
       );
       if (options.inspectTransactionControl !== false) {
         await this.assertNoTransactionControlCommand(
@@ -27401,7 +27629,44 @@ var PgsqlAdapter = class {
     }
     return result;
   }
-  async issueConnectionQuery(executor, sql, parameters) {
+  async issueConnectionQuery(executor, sql, parameters, prepareEligible) {
+    if (this.preparedStatementRegistry !== void 0 && prepareEligible && parameters !== void 0 && parameters.length > 0) {
+      if (isPoolClientLike(executor) && isPreparedStatementQuarantined(executor, sql)) {
+        return executor.query(sql, [...parameters]);
+      }
+      const admission = this.preparedStatementRegistry.admit(sql);
+      if (admission === void 0) {
+        return executor.query(sql, [...parameters]);
+      }
+      try {
+        const result = await executor.query({
+          name: admission.name,
+          text: sql,
+          values: [...parameters]
+        });
+        if (admission.reservation !== void 0)
+          this.preparedStatementRegistry.confirm(admission.reservation);
+        return result;
+      } catch (error) {
+        if (admission.reservation !== void 0) {
+          if (shouldAbortPreparedStatementReservation(
+            error,
+            executor,
+            admission.name
+          )) {
+            this.preparedStatementRegistry.abort(admission.reservation);
+          } else this.preparedStatementRegistry.confirm(admission.reservation);
+        }
+        if (isPoolClientLike(executor) && (isVerifiedPreparedStatementInfrastructureError(error) || isDriverLocalPreparedStatementNameCollision(error, admission.name))) {
+          quarantinePreparedStatement(
+            executor,
+            sql,
+            isVerifiedClientWidePreparedStatementLoss(error)
+          );
+        }
+        throw error;
+      }
+    }
     if (parameters === void 0) {
       return executor.query(sql);
     }
@@ -30596,7 +30861,7 @@ function createPgObservationIssuer() {
 }
 
 // src/transition/operations/alter-column-set-not-null.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { createEvidenceView } from "@dbsp/core";
 init_validate();
 
@@ -31869,7 +32134,7 @@ function operationPackSemanticsAssumption(payload, context) {
   };
 }
 function digest(value) {
-  return createHash2("sha256").update(stableJson(value)).digest("hex");
+  return createHash3("sha256").update(stableJson(value)).digest("hex");
 }
 function fact(key, value) {
   return {
@@ -32541,7 +32806,7 @@ function createAlterColumnSetNotNullOperationRuntime() {
 }
 
 // src/transition/operations/alter-table-add-check.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 init_validate();
 var GUARD_STATEMENT_TIMEOUT_MS2 = 5e3;
 var RENDERER_SESSION_REQUIREMENTS = [
@@ -32772,7 +33037,7 @@ function operationPackSemanticsAssumption2(payload, context) {
   };
 }
 function digest2(value) {
-  return createHash3("sha256").update(stableJson(value)).digest("hex");
+  return createHash4("sha256").update(stableJson(value)).digest("hex");
 }
 function fact2(key, value) {
   return {
@@ -33246,7 +33511,7 @@ function createAlterTableAddCheckOperationRuntime() {
 }
 
 // src/transition/operations/alter-type-add-value.ts
-import { createHash as createHash4 } from "crypto";
+import { createHash as createHash5 } from "crypto";
 init_validate();
 var MAX_PG_ENUM_LABEL_BYTES = 63;
 var RENDERER_SESSION_REQUIREMENTS2 = [
@@ -33414,7 +33679,7 @@ function operationPackSemanticsAssumption3(payload, context) {
   };
 }
 function digest3(value) {
-  return createHash4("sha256").update(stableJson(value)).digest("hex");
+  return createHash5("sha256").update(stableJson(value)).digest("hex");
 }
 function fact3(key, value) {
   return {
@@ -33814,7 +34079,7 @@ function createAlterTypeAddValueOperationRuntime() {
 }
 
 // src/transition/operations/attach-logical-identity.ts
-import { createHash as createHash5 } from "crypto";
+import { createHash as createHash6 } from "crypto";
 init_validate();
 function isRecord11(value) {
   return value != null && typeof value === "object" && !Array.isArray(value);
@@ -33957,7 +34222,7 @@ function renderInsertLogicalIdentitySql(_schema) {
   return `INSERT INTO ${qualifiedSideTable()} (logical_id, schema_name, table_name, column_name, carrier_kind) VALUES ($1, $2, $3, $4, $5)`;
 }
 function digest4(value) {
-  return createHash5("sha256").update(stableJson(value)).digest("hex");
+  return createHash6("sha256").update(stableJson(value)).digest("hex");
 }
 function fact4(key, value) {
   return {
@@ -34360,7 +34625,7 @@ function createAttachLogicalIdentityOperationRuntime() {
 }
 
 // src/transition/operations/create-unique-index-concurrently.ts
-import { createHash as createHash6 } from "crypto";
+import { createHash as createHash7 } from "crypto";
 init_validate();
 var DEFAULT_LOCK_TIMEOUT_MS = 5e3;
 function isRecord12(value) {
@@ -34472,7 +34737,7 @@ function operationPackSemanticsAssumption5(payload, context) {
   };
 }
 function digest5(value) {
-  return createHash6("sha256").update(stableJson(value)).digest("hex");
+  return createHash7("sha256").update(stableJson(value)).digest("hex");
 }
 function fact5(key, value) {
   return {
@@ -35151,7 +35416,7 @@ function createCreateUniqueIndexConcurrentlyOperationRuntime() {
 }
 
 // src/transition/operations/manual-sql.ts
-import { createHash as createHash7 } from "crypto";
+import { createHash as createHash8 } from "crypto";
 import { resourceScopeCovers } from "@dbsp/core";
 function isRecord13(value) {
   return value != null && typeof value === "object" && !Array.isArray(value);
@@ -35168,7 +35433,7 @@ function clientQuery6(client) {
   return queryable7(client.opaqueClient);
 }
 function digest6(value) {
-  return createHash7("sha256").update(stableJson(value)).digest("hex");
+  return createHash8("sha256").update(stableJson(value)).digest("hex");
 }
 function fact6(key, value) {
   return {