@nextlyhq/adapter-drizzle 0.0.2-alpha.66 → 0.0.2-alpha.67

package/dist/{adapter-Cs3Jl9Fb.d.cts → adapter-bUAaPzjV.d.cts}

@@ -1,9 +1,51 @@
 import { AnyRelations, SQL } from 'drizzle-orm';
-import { T as TransactionContext, S as SelectOptions, W as WhereClause, D as DeleteOptions, U as UpsertOptions, e as TransactionOptions, f as DatabaseCapabilities, P as PoolStats, C as CountOptions, I as InsertOptions, g as UpdateOptions, a as Migration, d as MigrationResult } from './migration-Ce0hkgr_.cjs';
+import { T as TransactionContext, S as SelectOptions, W as WhereClause, D as DeleteOptions, U as UpsertOptions, e as TransactionOptions, f as DatabaseCapabilities, P as PoolStats, C as CountOptions, I as InsertOptions, g as UpdateOptions, a as Migration, d as MigrationResult } from './migration-Bu0WLdX4.cjs';
 import { S as SupportedDialect, a as SqlParam, T as TableResolver } from './core-CVO7WYDj.cjs';
 import { T as TableDefinition, C as CreateTableOptions, D as DropTableOptions, A as AlterTableOperation, a as AlterTableOptions } from './schema-BDn8WfSL.cjs';
 import { D as DatabaseErrorKind, a as DatabaseError } from './error-BrdknH2s.cjs';
 
+/**
+ * A pooled adapter's Drizzle transactions, each on a connection the adapter
+ * checks out and returns itself.
+ *
+ * Drizzle's own `transaction()` on a pool checks a connection out, but does
+ * not return it as carefully as the adapter's `transaction()` does: it sends
+ * BEGIN outside its `try`, so a failed BEGIN never gives the connection back;
+ * and when its ROLLBACK fails it hands the connection to the pool as if
+ * nothing had happened, possibly still inside the transaction, and throws the
+ * ROLLBACK's error in place of the work's. Core services open their
+ * transactions through that handle, so it gets the same care here: Drizzle
+ * runs the transaction on a connection this module owns, and this module
+ * decides how the connection goes back.
+ *
+ * @module pinned-transaction
+ */
+/**
+ * Drizzle's database handle, as far as running a transaction goes.
+ *
+ * The callback takes `unknown` and the options `never`, so every dialect's
+ * handle fits, whose callback receives its own transaction type and whose
+ * options are its own.
+ */
+interface DrizzleTransactor {
+    transaction<T>(work: (tx: unknown) => Promise<T>, config?: never): Promise<T>;
+}
+/** One connection a pooled adapter checked out for one transaction. */
+interface PinnedConnection {
+    /** Drizzle bound to this connection alone, with the handle's relations. */
+    drizzle: DrizzleTransactor;
+    /**
+     * Sends ROLLBACK on this connection. Harmless when no transaction is open
+     * on it: PostgreSQL answers with a warning, MySQL does nothing.
+     */
+    rollback(): Promise<unknown>;
+    /**
+     * Gives the connection back: to the pool, or, when `dirty`, closed and
+     * removed from it, because it may still be inside the transaction.
+     */
+    release(dirty: boolean): void;
+}
+
 /**
  * Transaction CRUD forwarder helper for database adapters.
  *
@@ -117,6 +159,122 @@ declare abstract class DrizzleAdapter {
      * @throws The callback's own error, unchanged, when it carries that brand
      */
     abstract transaction<T>(callback: (ctx: TransactionContext) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Whether a `transaction()` call made from the current async context would
+     * join a transaction already open on this adapter, as a savepoint, rather
+     * than open one of its own.
+     *
+     * A caller about to do something no rollback can undo — removing a stored
+     * file, say — asks this first: work that joins an enclosing transaction is
+     * undone with it, while the effect it performs after its own savepoint
+     * releases is not.
+     *
+     * False here. Concrete rather than abstract so existing adapters keep
+     * working unchanged, and false is right for a pooled adapter: a call made
+     * inside another transaction's work opens its own transaction on its own
+     * connection, which commits independently.
+     *
+     * @returns True when the call would nest in an open transaction
+     */
+    inTransaction(): boolean;
+    /**
+     * The transaction each async flow is inside, kept per flow rather than per
+     * connection: on SQLite every request shares the one connection, and
+     * another request's open transaction says nothing about this one.
+     */
+    private readonly flowTransactions;
+    /**
+     * Whether the calling async flow is inside a transaction on this adapter
+     * that has not finished: its own, or one it was started from inside.
+     *
+     * A write that must outlive any rollback — a count of a failed attempt, the
+     * spend of a single-use secret — asks this before running in a transaction
+     * of its own. Made inside an open transaction on SQLite, it joins that
+     * transaction as a savepoint and is undone with it. On PostgreSQL and MySQL
+     * it would commit on a connection of its own, so refusing it there too
+     * keeps code that passes on one dialect from failing on another. Unlike
+     * {@link inTransaction}, which asks whether a call would nest and is always
+     * false on a pooled adapter, this answers alike on every dialect, and
+     * another flow's open transaction never answers true.
+     *
+     * Covers transactions opened through {@link transaction} and through the
+     * Drizzle handle's own `transaction` on the dialects whose handle takes
+     * async work. A dialect that keeps scopes of its own judges from those
+     * instead; an adapter that does neither answers false.
+     *
+     * @experimental
+     * @returns True while a transaction the calling flow is inside is open
+     */
+    transactionOpenInFlow(): boolean;
+    /**
+     * Run a whole transaction, from its BEGIN until its COMMIT or ROLLBACK has
+     * run, as the calling flow's open transaction, for
+     * {@link transactionOpenInFlow}. A dialect's `transaction` runs through
+     * this unless it judges the flow from scopes of its own.
+     *
+     * The transaction counts as open for its work and for anything the work
+     * starts, awaited or not, until it has finished. Something the work starts
+     * that outlives it then sees it closed, or the one enclosing it still open.
+     *
+     * @param run - The transaction, BEGIN to COMMIT or ROLLBACK
+     * @returns What `run` resolves to
+     */
+    protected runInFlowTransaction<T>(run: () => Promise<T>): Promise<T>;
+    /**
+     * Run each of a pool-bound Drizzle handle's transactions on a connection
+     * `checkout` hands it, and return that connection as the adapter's own
+     * `transaction()` does: closed rather than pooled when no ROLLBACK can be
+     * confirmed on it, and never leaked by a failed BEGIN (`pinTransactions`).
+     *
+     * For PostgreSQL's and MySQL's handles. Apply it before
+     * {@link trackFlowTransactions}, which wraps whatever `transaction` the
+     * handle has at that point.
+     *
+     * @param db - A Drizzle handle on this adapter's pool
+     * @param checkout - Checks out a connection for one transaction
+     * @returns The same handle, its `transaction` replaced
+     */
+    protected pinDrizzleTransactions<D extends DrizzleTransactor>(db: D, checkout: () => Promise<PinnedConnection>): D;
+    /**
+     * Make a Drizzle handle's own `transaction` count for
+     * {@link transactionOpenInFlow}, as the adapter's does.
+     *
+     * Core's services run their transactions through the handle on PostgreSQL
+     * and MySQL; without this, a call made inside one would be refused on
+     * SQLite, where they go through the adapter, and let through on the
+     * others. Not for SQLite's handle: its `transaction` takes only
+     * synchronous work, which no async flow can be inside.
+     *
+     * @param db - A Drizzle handle this adapter created
+     * @returns The same handle, its `transaction` tracked
+     */
+    protected trackFlowTransactions<D extends DrizzleTransactor>(db: D): D;
+    /**
+     * Run `effect` once the write made from the current async context has
+     * committed: an event, a hook, a cache flush, anything outside the database
+     * that must not happen for a change that is rolled back.
+     *
+     * A caller invokes this after its own transaction has resolved. Where that
+     * transaction was nested in an enclosing one, as a savepoint, the change is
+     * not durable yet, and an adapter that nests (see {@link inTransaction})
+     * holds `effect` until the outermost transaction commits, and drops it when
+     * that transaction, or the savepoint it was registered in, rolls back. A
+     * held effect runs after the commit, before the outermost `transaction()`
+     * call resolves, in registration order; one that then throws or rejects is
+     * handed to `onDeferredFailure` rather than failing a transaction that has
+     * committed.
+     *
+     * Here `effect` runs now and the returned promise settles with it, its
+     * failure included. Concrete rather than abstract, as `inTransaction` is,
+     * and right for a pooled adapter: each transaction has its own connection
+     * and has committed by the time its caller continues.
+     *
+     * @experimental
+     * @param effect - What to run once the change is durable
+     * @param onDeferredFailure - Receives the error of a held effect that fails
+     * @returns Settles once `effect` has run, or once it has been held
+     */
+    afterCommit(effect: () => unknown, _onDeferredFailure?: (error: unknown) => void): Promise<void>;
     /**
      * Get database capabilities.
      *
@@ -127,6 +285,23 @@ declare abstract class DrizzleAdapter {
      * @returns Database capability flags
      */
     abstract getCapabilities(): DatabaseCapabilities;
+    /**
+     * The schema this adapter's connections resolve unqualified names in.
+     *
+     * @remarks
+     * Read-only, and optional because only PostgreSQL has a schema namespace:
+     * MySQL's "schema" is its database and SQLite has one file. An adapter that
+     * sets no `search_path` of its own answers `undefined`, meaning the server's
+     * default applies.
+     *
+     * Exposed so the caller that built its own adapter can be held to the same
+     * schema the rest of the application assumes. The value lives in the
+     * adapter's config, and a mismatch is not an error anywhere below: every
+     * query succeeds, in a namespace nothing else is looking at.
+     *
+     * @returns The configured schema name, or `undefined` when none is set
+     */
+    getConfiguredSchema?(): string | undefined;
     /**
      * Get the raw Drizzle ORM instance for direct queries.
      *
@@ -638,7 +813,8 @@ declare abstract class DrizzleAdapter {
      * @remarks
      * Default implementation uses dialect-specific ON CONFLICT syntax.
      * PostgreSQL/SQLite: ON CONFLICT ... DO UPDATE
-     * MySQL: ON DUPLICATE KEY UPDATE
+     * MySQL: the MySQL adapter overrides this, resolving the conflict by the
+     * conflict columns (see its `upsert`)
      *
      * @param table - Table name
      * @param data - Record data
@@ -811,6 +987,17 @@ declare abstract class DrizzleAdapter {
      * @protected
      */
     protected createTransactionForwarders(txDb: () => unknown): TransactionCrudForwarders;
+    /**
+     * The Drizzle handles one transaction hands out; see
+     * `transactionDrizzleHandles`. `build` makes an instance on the
+     * transaction's own connection, with the relations config when given one.
+     *
+     * @protected
+     */
+    protected transactionDrizzleHandles<TBare>(build: (relations?: AnyRelations) => TBare): {
+        bare: () => TBare;
+        withRelations: <T = unknown>(relations: AnyRelations) => T;
+    };
     /**
      * A transaction context's `update`, for each adapter to bind.
      *
@@ -864,6 +1051,15 @@ declare abstract class DrizzleAdapter {
      * or array is not JSON. For the adapters to hand `transactionUpdate`.
      */
     protected bindUnmodeledStructuredAsJson(value: unknown): unknown;
+    /**
+     * Refuse an upsert target every dialect would not answer alike: a conflict
+     * column named twice, which SQLite rejects as no constraint's target and
+     * MySQL would accept; and, when nothing is to be updated, a conflict column
+     * left for the database to fill, since the row that stands is then read
+     * back by a value the caller never gave. Shared with the dialects that
+     * override `upsert`, so the refusals are one rule.
+     */
+    protected assertUpsertTarget(table: string, data: Record<string, unknown>, options: UpsertOptions, keepExisting: boolean): void;
     /**
      * The columns of a table-level `primaryKey({ columns })`, as the dialect's
      * table config reports them. The base class cannot read that config without
@@ -892,6 +1088,27 @@ declare abstract class DrizzleAdapter {
      * selects nothing narrower.
      */
     private updateReturnsRows;
+    /**
+     * The driver's own error inside `error`: the first in its `cause` chain that
+     * `isDriverError` recognises, or `error` itself when none does.
+     *
+     * A query that runs through Drizzle fails with Drizzle's `DrizzleQueryError`,
+     * whose message is the SQL statement and which carries no driver code; the
+     * driver's error, the only object that knows what actually went wrong, is
+     * its `cause`. A dialect's {@link classifyError} classifies from what this
+     * returns, so a failure reads the same whether or not Drizzle wrapped it.
+     *
+     * The walk is bounded, because an error chain can be made cyclic and a
+     * classifier that can hang is worse than one that gives up. Falling back to
+     * `error` keeps an error that carries no code anywhere classified as before.
+     *
+     * @param error - The error as it was caught
+     * @param isDriverError - Whether a link in the chain is the driver's error
+     * @returns The driver's error, or `error` when no link is
+     */
+    protected driverErrorIn<T extends {
+        cause?: unknown;
+    }>(error: unknown, isDriverError: (candidate: T) => boolean): T;
     /**
      * Classify an error into a DatabaseError.
      *

package/dist/{adapter-CHlx_Taa.d.ts → adapter-iJ5hbUvL.d.ts}

@@ -1,9 +1,51 @@
 import { AnyRelations, SQL } from 'drizzle-orm';
-import { T as TransactionContext, S as SelectOptions, W as WhereClause, D as DeleteOptions, U as UpsertOptions, e as TransactionOptions, f as DatabaseCapabilities, P as PoolStats, C as CountOptions, I as InsertOptions, g as UpdateOptions, a as Migration, d as MigrationResult } from './migration-CgoxgWOL.js';
+import { T as TransactionContext, S as SelectOptions, W as WhereClause, D as DeleteOptions, U as UpsertOptions, e as TransactionOptions, f as DatabaseCapabilities, P as PoolStats, C as CountOptions, I as InsertOptions, g as UpdateOptions, a as Migration, d as MigrationResult } from './migration-BqHebSwM.js';
 import { S as SupportedDialect, a as SqlParam, T as TableResolver } from './core-CVO7WYDj.js';
 import { T as TableDefinition, C as CreateTableOptions, D as DropTableOptions, A as AlterTableOperation, a as AlterTableOptions } from './schema-BIQ0YQZ_.js';
 import { D as DatabaseErrorKind, a as DatabaseError } from './error-BrdknH2s.js';
 
+/**
+ * A pooled adapter's Drizzle transactions, each on a connection the adapter
+ * checks out and returns itself.
+ *
+ * Drizzle's own `transaction()` on a pool checks a connection out, but does
+ * not return it as carefully as the adapter's `transaction()` does: it sends
+ * BEGIN outside its `try`, so a failed BEGIN never gives the connection back;
+ * and when its ROLLBACK fails it hands the connection to the pool as if
+ * nothing had happened, possibly still inside the transaction, and throws the
+ * ROLLBACK's error in place of the work's. Core services open their
+ * transactions through that handle, so it gets the same care here: Drizzle
+ * runs the transaction on a connection this module owns, and this module
+ * decides how the connection goes back.
+ *
+ * @module pinned-transaction
+ */
+/**
+ * Drizzle's database handle, as far as running a transaction goes.
+ *
+ * The callback takes `unknown` and the options `never`, so every dialect's
+ * handle fits, whose callback receives its own transaction type and whose
+ * options are its own.
+ */
+interface DrizzleTransactor {
+    transaction<T>(work: (tx: unknown) => Promise<T>, config?: never): Promise<T>;
+}
+/** One connection a pooled adapter checked out for one transaction. */
+interface PinnedConnection {
+    /** Drizzle bound to this connection alone, with the handle's relations. */
+    drizzle: DrizzleTransactor;
+    /**
+     * Sends ROLLBACK on this connection. Harmless when no transaction is open
+     * on it: PostgreSQL answers with a warning, MySQL does nothing.
+     */
+    rollback(): Promise<unknown>;
+    /**
+     * Gives the connection back: to the pool, or, when `dirty`, closed and
+     * removed from it, because it may still be inside the transaction.
+     */
+    release(dirty: boolean): void;
+}
+
 /**
  * Transaction CRUD forwarder helper for database adapters.
  *
@@ -117,6 +159,122 @@ declare abstract class DrizzleAdapter {
      * @throws The callback's own error, unchanged, when it carries that brand
      */
     abstract transaction<T>(callback: (ctx: TransactionContext) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Whether a `transaction()` call made from the current async context would
+     * join a transaction already open on this adapter, as a savepoint, rather
+     * than open one of its own.
+     *
+     * A caller about to do something no rollback can undo — removing a stored
+     * file, say — asks this first: work that joins an enclosing transaction is
+     * undone with it, while the effect it performs after its own savepoint
+     * releases is not.
+     *
+     * False here. Concrete rather than abstract so existing adapters keep
+     * working unchanged, and false is right for a pooled adapter: a call made
+     * inside another transaction's work opens its own transaction on its own
+     * connection, which commits independently.
+     *
+     * @returns True when the call would nest in an open transaction
+     */
+    inTransaction(): boolean;
+    /**
+     * The transaction each async flow is inside, kept per flow rather than per
+     * connection: on SQLite every request shares the one connection, and
+     * another request's open transaction says nothing about this one.
+     */
+    private readonly flowTransactions;
+    /**
+     * Whether the calling async flow is inside a transaction on this adapter
+     * that has not finished: its own, or one it was started from inside.
+     *
+     * A write that must outlive any rollback — a count of a failed attempt, the
+     * spend of a single-use secret — asks this before running in a transaction
+     * of its own. Made inside an open transaction on SQLite, it joins that
+     * transaction as a savepoint and is undone with it. On PostgreSQL and MySQL
+     * it would commit on a connection of its own, so refusing it there too
+     * keeps code that passes on one dialect from failing on another. Unlike
+     * {@link inTransaction}, which asks whether a call would nest and is always
+     * false on a pooled adapter, this answers alike on every dialect, and
+     * another flow's open transaction never answers true.
+     *
+     * Covers transactions opened through {@link transaction} and through the
+     * Drizzle handle's own `transaction` on the dialects whose handle takes
+     * async work. A dialect that keeps scopes of its own judges from those
+     * instead; an adapter that does neither answers false.
+     *
+     * @experimental
+     * @returns True while a transaction the calling flow is inside is open
+     */
+    transactionOpenInFlow(): boolean;
+    /**
+     * Run a whole transaction, from its BEGIN until its COMMIT or ROLLBACK has
+     * run, as the calling flow's open transaction, for
+     * {@link transactionOpenInFlow}. A dialect's `transaction` runs through
+     * this unless it judges the flow from scopes of its own.
+     *
+     * The transaction counts as open for its work and for anything the work
+     * starts, awaited or not, until it has finished. Something the work starts
+     * that outlives it then sees it closed, or the one enclosing it still open.
+     *
+     * @param run - The transaction, BEGIN to COMMIT or ROLLBACK
+     * @returns What `run` resolves to
+     */
+    protected runInFlowTransaction<T>(run: () => Promise<T>): Promise<T>;
+    /**
+     * Run each of a pool-bound Drizzle handle's transactions on a connection
+     * `checkout` hands it, and return that connection as the adapter's own
+     * `transaction()` does: closed rather than pooled when no ROLLBACK can be
+     * confirmed on it, and never leaked by a failed BEGIN (`pinTransactions`).
+     *
+     * For PostgreSQL's and MySQL's handles. Apply it before
+     * {@link trackFlowTransactions}, which wraps whatever `transaction` the
+     * handle has at that point.
+     *
+     * @param db - A Drizzle handle on this adapter's pool
+     * @param checkout - Checks out a connection for one transaction
+     * @returns The same handle, its `transaction` replaced
+     */
+    protected pinDrizzleTransactions<D extends DrizzleTransactor>(db: D, checkout: () => Promise<PinnedConnection>): D;
+    /**
+     * Make a Drizzle handle's own `transaction` count for
+     * {@link transactionOpenInFlow}, as the adapter's does.
+     *
+     * Core's services run their transactions through the handle on PostgreSQL
+     * and MySQL; without this, a call made inside one would be refused on
+     * SQLite, where they go through the adapter, and let through on the
+     * others. Not for SQLite's handle: its `transaction` takes only
+     * synchronous work, which no async flow can be inside.
+     *
+     * @param db - A Drizzle handle this adapter created
+     * @returns The same handle, its `transaction` tracked
+     */
+    protected trackFlowTransactions<D extends DrizzleTransactor>(db: D): D;
+    /**
+     * Run `effect` once the write made from the current async context has
+     * committed: an event, a hook, a cache flush, anything outside the database
+     * that must not happen for a change that is rolled back.
+     *
+     * A caller invokes this after its own transaction has resolved. Where that
+     * transaction was nested in an enclosing one, as a savepoint, the change is
+     * not durable yet, and an adapter that nests (see {@link inTransaction})
+     * holds `effect` until the outermost transaction commits, and drops it when
+     * that transaction, or the savepoint it was registered in, rolls back. A
+     * held effect runs after the commit, before the outermost `transaction()`
+     * call resolves, in registration order; one that then throws or rejects is
+     * handed to `onDeferredFailure` rather than failing a transaction that has
+     * committed.
+     *
+     * Here `effect` runs now and the returned promise settles with it, its
+     * failure included. Concrete rather than abstract, as `inTransaction` is,
+     * and right for a pooled adapter: each transaction has its own connection
+     * and has committed by the time its caller continues.
+     *
+     * @experimental
+     * @param effect - What to run once the change is durable
+     * @param onDeferredFailure - Receives the error of a held effect that fails
+     * @returns Settles once `effect` has run, or once it has been held
+     */
+    afterCommit(effect: () => unknown, _onDeferredFailure?: (error: unknown) => void): Promise<void>;
     /**
      * Get database capabilities.
      *
@@ -127,6 +285,23 @@ declare abstract class DrizzleAdapter {
      * @returns Database capability flags
      */
     abstract getCapabilities(): DatabaseCapabilities;
+    /**
+     * The schema this adapter's connections resolve unqualified names in.
+     *
+     * @remarks
+     * Read-only, and optional because only PostgreSQL has a schema namespace:
+     * MySQL's "schema" is its database and SQLite has one file. An adapter that
+     * sets no `search_path` of its own answers `undefined`, meaning the server's
+     * default applies.
+     *
+     * Exposed so the caller that built its own adapter can be held to the same
+     * schema the rest of the application assumes. The value lives in the
+     * adapter's config, and a mismatch is not an error anywhere below: every
+     * query succeeds, in a namespace nothing else is looking at.
+     *
+     * @returns The configured schema name, or `undefined` when none is set
+     */
+    getConfiguredSchema?(): string | undefined;
     /**
      * Get the raw Drizzle ORM instance for direct queries.
      *
@@ -638,7 +813,8 @@ declare abstract class DrizzleAdapter {
      * @remarks
      * Default implementation uses dialect-specific ON CONFLICT syntax.
      * PostgreSQL/SQLite: ON CONFLICT ... DO UPDATE
-     * MySQL: ON DUPLICATE KEY UPDATE
+     * MySQL: the MySQL adapter overrides this, resolving the conflict by the
+     * conflict columns (see its `upsert`)
      *
      * @param table - Table name
      * @param data - Record data
@@ -811,6 +987,17 @@ declare abstract class DrizzleAdapter {
      * @protected
      */
     protected createTransactionForwarders(txDb: () => unknown): TransactionCrudForwarders;
+    /**
+     * The Drizzle handles one transaction hands out; see
+     * `transactionDrizzleHandles`. `build` makes an instance on the
+     * transaction's own connection, with the relations config when given one.
+     *
+     * @protected
+     */
+    protected transactionDrizzleHandles<TBare>(build: (relations?: AnyRelations) => TBare): {
+        bare: () => TBare;
+        withRelations: <T = unknown>(relations: AnyRelations) => T;
+    };
     /**
      * A transaction context's `update`, for each adapter to bind.
      *
@@ -864,6 +1051,15 @@ declare abstract class DrizzleAdapter {
      * or array is not JSON. For the adapters to hand `transactionUpdate`.
      */
     protected bindUnmodeledStructuredAsJson(value: unknown): unknown;
+    /**
+     * Refuse an upsert target every dialect would not answer alike: a conflict
+     * column named twice, which SQLite rejects as no constraint's target and
+     * MySQL would accept; and, when nothing is to be updated, a conflict column
+     * left for the database to fill, since the row that stands is then read
+     * back by a value the caller never gave. Shared with the dialects that
+     * override `upsert`, so the refusals are one rule.
+     */
+    protected assertUpsertTarget(table: string, data: Record<string, unknown>, options: UpsertOptions, keepExisting: boolean): void;
     /**
      * The columns of a table-level `primaryKey({ columns })`, as the dialect's
      * table config reports them. The base class cannot read that config without
@@ -892,6 +1088,27 @@ declare abstract class DrizzleAdapter {
      * selects nothing narrower.
      */
     private updateReturnsRows;
+    /**
+     * The driver's own error inside `error`: the first in its `cause` chain that
+     * `isDriverError` recognises, or `error` itself when none does.
+     *
+     * A query that runs through Drizzle fails with Drizzle's `DrizzleQueryError`,
+     * whose message is the SQL statement and which carries no driver code; the
+     * driver's error, the only object that knows what actually went wrong, is
+     * its `cause`. A dialect's {@link classifyError} classifies from what this
+     * returns, so a failure reads the same whether or not Drizzle wrapped it.
+     *
+     * The walk is bounded, because an error chain can be made cyclic and a
+     * classifier that can hang is worse than one that gives up. Falling back to
+     * `error` keeps an error that carries no code anywhere classified as before.
+     *
+     * @param error - The error as it was caught
+     * @param isDriverError - Whether a link in the chain is the driver's error
+     * @returns The driver's error, or `error` when no link is
+     */
+    protected driverErrorIn<T extends {
+        cause?: unknown;
+    }>(error: unknown, isDriverError: (candidate: T) => boolean): T;
     /**
      * Classify an error into a DatabaseError.
      *