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

package/dist/adapter-CSP-Ek-L.d.ts

@@ -0,0 +1,1166 @@
+import { a as DropTableOptions, c as TableDefinition, f as SqlParam, i as CreateTableOptions, m as TableResolver, n as AlterTableOptions, p as SupportedDialect, t as AlterTableOperation } from "./schema-Bkkr3JMC.js";
+import { A as UpdateOptions, C as TransactionContext, D as DeleteOptions, E as CountOptions, F as WhereClause, O as InsertOptions, S as PoolStats, T as TransactionOptions, c as DatabaseError, g as Migration, j as UpsertOptions, k as SelectOptions, l as DatabaseErrorKind, x as DatabaseCapabilities, y as MigrationResult } from "./index-BYb6cDli.js";
+import { AnyRelations, SQL } from "drizzle-orm";
+/**
+ * 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;
+}
+/**
+ * Interface representing an adapter that can execute CRUD operations with an optional executor.
+ */
+interface TransactionCrudDelegator {
+  select<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T[]>;
+  selectOne<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T | null>;
+  updateCount(table: string, data: Record<string, unknown>, where: WhereClause, executor?: unknown): Promise<number>;
+  delete(table: string, where: WhereClause, options?: DeleteOptions, executor?: unknown): Promise<number>;
+  upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions, executor?: unknown): Promise<T>;
+}
+/**
+ * Transaction context CRUD methods provided by the forwarder.
+ *
+ * `update` is not among them. The pooled `update` goes through the Drizzle
+ * query builder, which writes the columns the runtime model declares; a
+ * transaction's update must reach the columns the physical table has, and
+ * each adapter binds the base class's `transactionUpdate` beside its
+ * transactional `insert`.
+ */
+type TransactionCrudForwarders = Pick<TransactionContext, "select" | "selectOne" | "updateCount" | "delete" | "upsert" | "getDrizzle">;
+declare abstract class DrizzleAdapter {
+  /**
+   * Database dialect identifier.
+   *
+   * @remarks
+   * Must be set by subclass to identify the database type.
+   */
+  abstract readonly dialect: SupportedDialect;
+  /**
+   * Establish connection to the database.
+   *
+   * @remarks
+   * This method should be idempotent - calling it multiple times
+   * should not create multiple connections.
+   *
+   * @throws {DatabaseError} If connection fails
+   */
+  abstract connect(): Promise<void>;
+  /**
+   * Close database connection and release resources.
+   *
+   * @remarks
+   * This method should be idempotent - calling it multiple times
+   * should be safe.
+   */
+  abstract disconnect(): Promise<void>;
+  /**
+   * Execute a raw SQL query.
+   *
+   * @param sql - SQL query to execute
+   * @param params - Query parameters
+   * @returns Array of result rows
+   *
+   * @throws {DatabaseError} If query execution fails
+   */
+  abstract executeQuery<T = unknown>(sql: string, params?: SqlParam[]): Promise<T[]>;
+  /**
+   * Execute operations within a database transaction.
+   *
+   * @remarks
+   * The transaction is automatically committed on success or rolled back on error.
+   * Supports nested transactions via savepoints on databases that support them.
+   *
+   * Two kinds of error leave this method, and a caller has to be able to tell
+   * them apart. An error carrying the Nextly application brand — see
+   * `isApplicationError` — arrives exactly as it was thrown, because that is
+   * the application refusing the write rather than the database failing to
+   * perform it, and rewriting it would discard the code and payload the caller
+   * is meant to act on.
+   *
+   * Everything else arrives as a `DatabaseError` with its kind classified, and
+   * that deliberately includes an unbranded error the callback itself threw:
+   * the brand is the only thing distinguishing a deliberate refusal from a
+   * driver failure that surfaced through callback code, and guessing from the
+   * throw site would put raw driver text on the wire under a caller's own
+   * error shape.
+   *
+   * The rollback is the same either way.
+   *
+   * @param callback - Function to execute within transaction
+   * @param options - Transaction options
+   * @returns Result from the callback
+   *
+   * @throws {DatabaseError} If the transaction itself fails, or if the callback
+   * threw an error that does not carry the application brand
+   * @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;
+  /** Each pool's reporting views, by method list (`observedPool`). Gone with the pool. */
+  private readonly observedPools;
+  /**
+   * 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>;
+  /**
+   * Record that the calling flow's transaction now holds its own connection.
+   *
+   * A pooled dialect calls this right after checking out the connection a
+   * transaction runs on, so {@link notePoolAccess} can tell that checkout,
+   * which belongs to the transaction, from any later one, which escapes it.
+   */
+  protected markFlowTransactionConnected(): void;
+  /**
+   * Check out, through `checkout`, the connection the calling flow's
+   * transaction runs on. A transaction opened inside another's work takes a
+   * second connection, so the checkout is reported first
+   * ({@link notePoolAccess}); once it holds its own, the transaction is
+   * marked connected, so its later checkouts are told apart from it.
+   *
+   * @param checkout - Takes a connection from the dialect's pool
+   * @returns The connection
+   */
+  protected connectFlowTransaction<C>(checkout: () => Promise<C>): Promise<C>;
+  /**
+   * Called by a pooled dialect before it takes anything from its pool: a
+   * query, or a connection checkout.
+   *
+   * While the calling flow is inside a transaction that already holds its own
+   * connection, a pool access runs on another connection: outside the
+   * transaction, blind to its uncommitted writes, not undone by its rollback,
+   * and able to stall a small pool. Such an access is reported to the
+   * observer a test harness installs under
+   * `Symbol.for("nextly.transactionEscapeObserver")`, with the stack that
+   * names its call site. With no observer installed, which is every
+   * production process, this is one property read.
+   *
+   * @param statement - What the pool call was handed, its SQL passed on so
+   *   the harness can say which statement escaped; nothing for a checkout
+   */
+  protected notePoolAccess(statement?: unknown): void;
+  /**
+   * `pool`, with {@link notePoolAccess} called before each of `methods`, for
+   * handing to code that queries the pool directly, such as Drizzle's handle.
+   * Everything else, `instanceof` included, reaches the pool unchanged.
+   *
+   * One view per pool and method list, made once: every Drizzle handle on the pool is given the
+   * same one, so `getDrizzle()` and `getDrizzle(relations)` share a `$client`, as they did when
+   * each was handed the pool itself.
+   *
+   * @param pool - The driver's pool
+   * @param methods - The pool methods that take a connection
+   * @returns A view of `pool` that reports those calls
+   */
+  protected observedPool<P extends object>(pool: P, methods: readonly string[]): P;
+  /**
+   * 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.
+   *
+   * @remarks
+   * Returns static capability flags for this adapter's dialect.
+   * Used by services to conditionally enable features or implement fallbacks.
+   *
+   * @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.
+   *
+   * @remarks
+   * This method provides escape hatch access to the raw Drizzle instance.
+   * Use this when you need to run complex queries that the adapter API
+   * doesn't support, or for legacy code migration.
+   *
+   * **Note:** Prefer using adapter methods when possible as they provide:
+   * - Database-agnostic API
+   * - Consistent error handling
+   * - Proper connection pooling
+   *
+   * @param relations - Optional drizzle v1 relations config (defineRelations
+   *   output) that enables the typed relational query API on the instance
+   * @returns Raw Drizzle ORM database instance
+   *
+   * @example
+   * ```typescript
+   * // For legacy code that needs direct Drizzle access
+   * const db = adapter.getDrizzle(myRelations); // defineRelations output
+   * const result = await db.insert(users).values({ ... }).returning();
+   * ```
+   */
+  abstract getDrizzle<T = unknown>(relations?: AnyRelations): T;
+  /**
+   * Table resolver for looking up Drizzle table objects by name.
+   * When set, CRUD methods use Drizzle's query API instead of raw SQL.
+   * Set via setTableResolver() after boot-time schema loading.
+   */
+  protected tableResolver: TableResolver | null;
+  /**
+   * Set the table resolver for Drizzle query API support.
+   * When a resolver is set, CRUD methods (select, insert, update, delete, upsert)
+   * will use Drizzle's query API (db.select().from(), etc.) instead of raw SQL
+   * string building. Falls back to raw SQL if the resolver doesn't have the table.
+   *
+   * @param resolver - TableResolver implementation (e.g. SchemaRegistry)
+   */
+  setTableResolver(resolver: TableResolver): void;
+  /**
+   * Get a Drizzle table object by name from the resolver.
+   * Returns null if no resolver is set or table is not found.
+   */
+  protected getTableObject(tableName: string): unknown;
+  /**
+   * Run a Drizzle-built statement and return its rows.
+   *
+   * @remarks
+   * The CRUD methods resolve their table through the schema registry and reject
+   * any name it does not declare, which leaves no way to read from a table the
+   * ORM does not know — one mid-rename, above all — except by assembling SQL and
+   * quoting identifiers by hand. This takes Drizzle's `sql` template instead, so
+   * the dialect in use decides the quoting and the parameter binding.
+   *
+   * Concrete rather than abstract so existing adapters keep working unchanged.
+   * The three drivers disagree about both the call and the result: node-postgres
+   * returns `{ rows }`, mysql2 a `[rows, fields]` tuple, and better-sqlite3 has
+   * no `execute` at all and answers `all`. Keeping that here rather than at each
+   * call site is the point — a caller reasoning about it would be reasoning
+   * about a driver it cannot see.
+   *
+   * @param statement - Drizzle `sql` template to run
+   * @returns Rows the statement produced
+   */
+  queryStatement<T = Record<string, unknown>>(statement: SQL): Promise<T[]>;
+  /**
+   * Map data keys from SQL column names (snake_case) to Drizzle JS property names (camelCase).
+   * Drizzle schemas define columns as e.g. `createdAt: timestamp("created_at")` — the JS
+   * property is `createdAt` but the SQL column is `created_at`. Services pass snake_case keys
+   * because they match the DB column names. This method maps them to the JS names Drizzle expects.
+   */
+  protected mapDataToColumnNames(tableObj: unknown, data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Map data keys from Drizzle JS property names to SQL column names for the
+   * raw-SQL transaction insert path. The transaction context builds INSERT
+   * statements from Object.keys(data) used directly as column identifiers, so a
+   * table whose Drizzle property names differ from its SQL column names
+   * (camelCase core tables like nextly_versions) needs its keys translated
+   * first. For tables whose property names already equal their column names
+   * (the dynamic dc_/single_/comp_ tables) every lookup is identity, so
+   * existing callers are unaffected.
+   */
+  protected mapKeysToSqlColumns(tableObj: unknown, data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Map a list of column identifiers (Drizzle property names) to their SQL
+   * column names, for the raw-SQL transaction insert paths that build a
+   * RETURNING clause from `options.returning`. Same identity behavior as
+   * `mapKeysToSqlColumns`: names that are already SQL columns (the dynamic
+   * dc_/single_/comp_ tables) pass through unchanged.
+   */
+  protected mapColumnNamesToSql(tableObj: unknown, names: string[]): string[];
+  /**
+   * Remap a raw-SQL result row's KEYS from SQL column names to Drizzle property
+   * names, so the raw-SQL transaction insert paths return the same key casing
+   * as the non-transactional (Drizzle) insert. Keys only - values are left
+   * untouched, so this does not change how JSON/date columns are decoded. For
+   * tables whose property names already equal their SQL columns (the dynamic
+   * dc_/single_/comp_ tables) every lookup is identity, so existing callers see
+   * no change.
+   */
+  protected mapRowKeysToJs<T = unknown>(tableObj: unknown, row: T): T;
+  /**
+   * Decode a raw-SQL result row's DATE column values the way a Drizzle query
+   * would, so a write answers with the same representation a read of the same
+   * column gives.
+   *
+   * A Drizzle query path runs every value through its column definition; a
+   * raw-SQL path does not, so a dialect that stores a timestamp as a number
+   * answers a write with that number while every read answers a `Date`. Only
+   * date columns are touched, and a value that is already a `Date` is left
+   * alone, so a driver that decodes on its own is unaffected.
+   *
+   * Runs after {@link mapRowKeysToJs}: keys are Drizzle property names by then,
+   * which is what the table definition is keyed by.
+   */
+  protected mapDateValuesFromDriver<T = unknown>(tableObj: unknown, row: T): T;
+  /**
+   * Encode a row's DATE values the way a Drizzle query would before binding
+   * them, so what lands in the column does not depend on the server's timezone.
+   *
+   * A column declared without a time zone stores a wall clock and records
+   * nothing about which zone it belongs to, so both ends have to agree. Drizzle
+   * writes UTC and reads UTC. A driver handed a `Date` writes the LOCAL wall
+   * clock instead, and the same row then reads back shifted by the offset --
+   * on a UTC server the two agree and nothing is visibly wrong, which is why
+   * this survives CI.
+   *
+   * Only date columns are touched. A value that is not a `Date` is left as it
+   * is, so a caller that already encoded one is not encoded twice.
+   *
+   * Keys may be spelled either way at this point, so both the Drizzle property
+   * name and the SQL column name resolve.
+   */
+  protected mapDateValuesToDriver(tableObj: unknown, data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Bring a row about to be written through a raw-SQL statement into the shape
+   * a Drizzle query would have bound: SQL column names for keys, encoded values
+   * for date columns.
+   *
+   * The mirror of {@link mapRowFromRawSql}. The raw-SQL write paths exist
+   * because a dialect needs SQL a Drizzle query cannot express, not because
+   * their callers want different values in the table.
+   */
+  protected mapRowToRawSql(tableObj: unknown, data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Bring a raw-SQL result row into the shape a Drizzle query would have
+   * produced: Drizzle property names for keys, decoded values for date columns.
+   *
+   * The raw-SQL write paths exist because a dialect needs SQL a Drizzle query
+   * cannot express, not because their callers want a different row shape, so
+   * every one of them ends here.
+   */
+  protected mapRowFromRawSql<T = unknown>(tableObj: unknown, row: T, aliases?: ReadonlyArray<{
+    alias: string;
+    jsName: string;
+  }>): T;
+  /**
+   * The date columns a statement is about to return, and the alias each one's
+   * wall clock is spelled out under.
+   *
+   * A driver turns a timestamp into a `Date` using ITS zone before any of this
+   * code runs, and that conversion is lossy: a wall clock inside a
+   * daylight-saving gap is a local time that does not exist, so the driver
+   * normalizes it and the original is gone. Asking the database for the wall
+   * clock as text alongside the row is the only way to read it exactly.
+   *
+   * `"*"` covers every date column; a projection covers only the ones it asked
+   * for, so a caller still gets back what it requested and nothing more.
+   */
+  protected dateWallClockAliases(tableObj: unknown, returning: string[] | "*" | undefined): Array<{
+    sqlName: string;
+    alias: string;
+    jsName: string;
+  }>;
+  /**
+   * Replace each date in a row with the wall clock the database spelled out,
+   * read as UTC, and drop the aliases that carried it.
+   *
+   * The statement writes a UTC wall clock, so reading one back as UTC is what
+   * makes a write and a later read agree. Whatever the column actually stored
+   * is what arrives -- a column keeping only whole seconds reports whole
+   * seconds -- because this is the database's own text, not a value
+   * reconstructed from the one that was bound.
+   */
+  protected applyWallClockAliases<T>(row: T, aliases: ReadonlyArray<{
+    alias: string;
+    jsName: string;
+  }>): T;
+  /**
+   * Build a Drizzle column projection object (`{ propertyName: column }`) from a
+   * requested column list, used by `select` (columns) and `insert` (returning).
+   * A requested name resolves against either the Drizzle property name
+   * (camelCase) or the SQL column name (snake_case); the projection is keyed by
+   * the property name so the row shape matches a full select. Returns undefined
+   * for `"*"` or when nothing resolves, so callers fall back to all columns.
+   */
+  protected buildColumnProjection(tableObj: unknown, names: string[] | "*" | undefined): Record<string, unknown> | undefined;
+  /**
+   * The requested column names split into what this table has and what it does not.
+   *
+   * One resolution, reported both ways, because two callers need different halves
+   * of the same answer: a projection drops what it cannot find, while a distinct
+   * count has to REFUSE it. Resolving twice would let the two disagree about what
+   * "found" means — the SQL-name alias below is exactly the kind of detail a
+   * second implementation gets wrong — and the count would then reject a column
+   * the projection happily uses.
+   *
+   * Both spellings resolve: a caller may name the Drizzle property or the SQL
+   * column, and either maps to the same projection key.
+   */
+  protected resolveColumns(tableObj: unknown, names: readonly string[]): {
+    projection: Record<string, unknown>;
+    unresolved: string[];
+  };
+  /**
+   * Check if the adapter is currently connected.
+   *
+   * @remarks
+   * Default implementation returns false. Subclasses should override
+   * to provide accurate connection status.
+   *
+   * @returns True if connected, false otherwise
+   */
+  isConnected(): boolean;
+  /**
+   * Get connection pool statistics.
+   *
+   * @remarks
+   * Returns null by default. Subclasses with connection pooling
+   * should override to provide pool statistics.
+   *
+   * @returns Pool statistics or null if not applicable
+   */
+  getPoolStats(): PoolStats | null;
+  /**
+   * Default query timeout in milliseconds.
+   *
+   * @remarks
+   * This value is used by executeWithTimeout() when no explicit timeout
+   * is provided. Subclasses should set this from their config.
+   *
+   * @default 15000 (15 seconds)
+   *
+   * @protected
+   */
+  protected defaultQueryTimeoutMs: number;
+  /**
+   * Execute an async operation with a timeout.
+   *
+   * @remarks
+   * Wraps an async operation with a timeout that aborts if the operation
+   * exceeds the specified duration. Uses Promise.race for clean timeout
+   * handling without memory leaks.
+   *
+   * When the timeout is reached, a DatabaseError with kind 'timeout' is thrown.
+   * Note that this does NOT cancel the underlying database query - it only
+   * prevents the calling code from waiting indefinitely. For true query
+   * cancellation, use database-level statement timeouts (PostgreSQL) or
+   * similar mechanisms.
+   *
+   * @param operation - Async operation to execute
+   * @param timeoutMs - Timeout in milliseconds (defaults to defaultQueryTimeoutMs)
+   * @returns Result of the operation
+   *
+   * @throws {DatabaseError} With kind 'timeout' if operation exceeds timeout
+   *
+   * @example
+   * ```typescript
+   * // Use default timeout
+   * const result = await adapter.executeWithTimeout(
+   *   () => adapter.select('users', { limit: 1000 })
+   * );
+   *
+   * // Use custom timeout for specific operation
+   * const result = await adapter.executeWithTimeout(
+   *   () => adapter.select('large_table'),
+   *   60000 // 60 seconds for large queries
+   * );
+   * ```
+   *
+   * @public
+   */
+  executeWithTimeout<T>(operation: () => Promise<T>, timeoutMs?: number): Promise<T>;
+  /**
+   * Set the default query timeout.
+   *
+   * @remarks
+   * This method allows runtime configuration of the default timeout.
+   * Subclasses should call this in their constructor or connect() method
+   * based on their configuration.
+   *
+   * @param timeoutMs - Timeout in milliseconds (0 to disable)
+   *
+   * @protected
+   */
+  protected setDefaultQueryTimeout(timeoutMs: number): void;
+  /**
+   * Get the current default query timeout.
+   *
+   * @returns Current default timeout in milliseconds
+   *
+   * @public
+   */
+  getDefaultQueryTimeout(): number;
+  /**
+   * Select multiple records from a table.
+   *
+   * @remarks
+   * Default implementation builds a SELECT query and executes it.
+   * Subclasses can override for optimization or dialect-specific features.
+   *
+   * @param table - Table name
+   * @param options - Select options (filtering, sorting, pagination)
+   * @returns Array of matching records
+   *
+   * @throws {DatabaseError} If query fails
+   *
+   * @example
+   * ```typescript
+   * const users = await adapter.select('users', {
+   *   where: { and: [{ column: 'role', op: '=', value: 'admin' }] },
+   *   orderBy: [{ column: 'created_at', direction: 'desc' }],
+   *   limit: 10
+   * });
+   * ```
+   */
+  select<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T[]>;
+  /**
+   * Select a single record from a table.
+   *
+   * @remarks
+   * Default implementation uses `select()` with limit 1 and returns first result.
+   * Returns null if no matching record is found.
+   *
+   * @param table - Table name
+   * @param options - Select options
+   * @returns First matching record or null
+   *
+   * @throws {DatabaseError} If query fails
+   *
+   * @example
+   * ```typescript
+   * const user = await adapter.selectOne('users', {
+   *   where: { and: [{ column: 'email', op: '=', value: 'user@example.com' }] }
+   * });
+   * ```
+   */
+  /** The registered table object, or a refusal naming what is missing. */
+  private requireTableObject;
+  /**
+   * The columns a distinct count groups by, or `undefined` for a row count.
+   *
+   * 🔴 EVERY named column must resolve, not merely one of them. A `distinctOn`
+   * naming no column this table has would fall through to a row count, and one
+   * naming a valid column beside a misspelled or since-removed column would
+   * count distinct over a NARROWER key than the caller asked for. Both answer a
+   * different question than the one asked, silently; the second is the worse of
+   * the two, because a subset key groups more rows together and so UNDERCOUNTS,
+   * which reads as a plausible number rather than as a fault. Refused here,
+   * where the mistake was made, rather than surfacing as a wrong figure.
+   */
+  private countProjection;
+  /**
+   * `COUNT(*)` over a `SELECT DISTINCT` subquery.
+   *
+   * Its own function because it is a genuinely different query from the plain
+   * count rather than a variation on one, and because building both inline made
+   * the public method a chain of decisions the complexity gate objected to
+   * before a reader would have.
+   */
+  private countDistinctRows;
+  /** `COUNT(*)` over the table itself. */
+  private countAllRows;
+  /**
+   * How many rows match, or how many DISTINCT combinations of some columns do.
+   *
+   * The data layer had no count at all: collection totals go through
+   * `countEntries`, an access-controlled path built for collection tables, and
+   * nothing could count a system table. A caller wanting one selected the rows
+   * and measured the array, which transfers every row to learn a number and
+   * cannot be bounded without making the number wrong.
+   *
+   * 🔴 `distinctOn` compiles to `COUNT(*)` over a `SELECT DISTINCT` SUBQUERY,
+   * never to `COUNT(DISTINCT a, b)`. The inline form is not portable and fails
+   * in the direction that is hardest to notice -- MySQL accepts it, PostgreSQL
+   * needs a row constructor, and SQLite rejects it outright with "wrong number
+   * of arguments to function count()" -- so a query written against one engine
+   * is a syntax error on another. The subquery is the single form all three
+   * accept, and building it here rather than at each call site is what keeps
+   * the answer identical per dialect.
+   */
+  count(table: string, options?: CountOptions, executor?: unknown): Promise<number>;
+  selectOne<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T | null>;
+  /**
+   * Insert a single record into a table.
+   *
+   * @remarks
+   * Default implementation handles databases with and without RETURNING support.
+   * For databases without RETURNING (MySQL), performs INSERT followed by SELECT.
+   *
+   * @param table - Table name
+   * @param data - Record data to insert
+   * @param options - Insert options
+   * @returns Inserted record (with RETURNING columns if specified)
+   *
+   * @throws {DatabaseError} If insert fails
+   *
+   * @example
+   * ```typescript
+   * const user = await adapter.insert('users', {
+   *   email: 'user@example.com',
+   *   name: 'John Doe'
+   * }, { returning: ['id', 'email', 'created_at'] });
+   * ```
+   */
+  insert<T = unknown>(table: string, data: Record<string, unknown>, options?: InsertOptions): Promise<T>;
+  /**
+   * Insert multiple records into a table.
+   *
+   * @remarks
+   * Default implementation performs individual inserts in sequence.
+   * Subclasses can override for bulk insert optimization (e.g., COPY in PostgreSQL).
+   *
+   * @param table - Table name
+   * @param data - Array of records to insert
+   * @param options - Insert options
+   * @returns Inserted records (with RETURNING columns if specified)
+   *
+   * @throws {DatabaseError} If insert fails
+   *
+   * @example
+   * ```typescript
+   * const users = await adapter.insertMany('users', [
+   *   { email: 'user1@example.com', name: 'User 1' },
+   *   { email: 'user2@example.com', name: 'User 2' }
+   * ], { returning: ['id'] });
+   * ```
+   */
+  insertMany<T = unknown>(table: string, data: Record<string, unknown>[], options?: InsertOptions): Promise<T[]>;
+  /**
+   * Update records in a table.
+   *
+   * @remarks
+   * Default implementation builds an UPDATE query with WHERE clause.
+   * Returns updated records if RETURNING is supported and requested.
+   *
+   * @param table - Table name
+   * @param data - Data to update
+   * @param where - Conditions for records to update
+   * @param options - Update options
+   * @returns Updated records (with RETURNING columns if specified)
+   *
+   * @throws {DatabaseError} If update fails
+   *
+   * @example
+   * ```typescript
+   * const updated = await adapter.update('users',
+   *   { status: 'active' },
+   *   { and: [{ column: 'id', op: '=', value: userId }] },
+   *   { returning: ['id', 'status', 'updated_at'] }
+   * );
+   * ```
+   */
+  update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions, executor?: unknown): Promise<T[]>;
+  /**
+   * Update records in a table and report how many rows the statement affected.
+   *
+   * The count is the whole return value, mirroring `delete`. `update` cannot answer this: without
+   * `returning` it discards the driver's count, and WITH `returning` on a dialect that lacks
+   * RETURNING it re-SELECTs using the same WHERE — so a conditional update that just changed a
+   * column named in that WHERE reads back zero rows and a write that landed reports as unmatched.
+   * Reading the driver's own count has no second query to disagree with the first.
+   *
+   * 🔴 MySQL reports CHANGED rows, not matched rows: an UPDATE that matches a row but writes values
+   * identical to what it holds counts zero. A caller using this as a compare-and-set must therefore
+   * include a column the write always moves — a version bump, a timestamp with enough resolution —
+   * so that matched implies changed. Postgres (`rowCount`) and SQLite (`changes`) count matched
+   * rows and do not need the precaution, which is exactly why it cannot be dropped: the dialect
+   * where the distinction exists is the one with no RETURNING to fall back on.
+   */
+  updateCount(table: string, data: Record<string, unknown>, where: WhereClause, executor?: unknown): Promise<number>;
+  /**
+   * Delete records from a table.
+   *
+   * @remarks
+   * Default implementation builds a DELETE query with WHERE clause.
+   * Returns the number of deleted records.
+   *
+   * @param table - Table name
+   * @param where - Conditions for records to delete
+   * @param options - Delete options
+   * @returns Number of deleted records
+   *
+   * @throws {DatabaseError} If delete fails
+   *
+   * @example
+   * ```typescript
+   * const count = await adapter.delete('users', {
+   *   and: [{ column: 'status', op: '=', value: 'inactive' }]
+   * });
+   * console.log(`Deleted ${count} users`);
+   * ```
+   */
+  delete(table: string, where: WhereClause, _options?: DeleteOptions, executor?: unknown): Promise<number>;
+  /**
+   * Upsert (INSERT or UPDATE) a record.
+   *
+   * @remarks
+   * Default implementation uses dialect-specific ON CONFLICT syntax.
+   * PostgreSQL/SQLite: ON CONFLICT ... DO 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
+   * @param options - Upsert options (must specify conflict columns)
+   * @returns Upserted record (with RETURNING columns if specified)
+   *
+   * @throws {DatabaseError} If upsert fails
+   *
+   * @example
+   * ```typescript
+   * const user = await adapter.upsert('users', {
+   *   email: 'user@example.com',
+   *   name: 'Updated Name'
+   * }, {
+   *   conflictColumns: ['email'],
+   *   updateColumns: ['name'],
+   *   returning: ['id', 'email', 'name']
+   * });
+   * ```
+   */
+  upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions, executor?: unknown): Promise<T>;
+  /**
+   * Run pending migrations.
+   *
+   * @remarks
+   * Default implementation is a placeholder. Subclasses should implement
+   * migration tracking and execution logic.
+   *
+   * @param migrations - Array of migrations to run
+   * @returns Migration result with applied and pending migrations
+   *
+   * @throws {DatabaseError} If migration fails
+   */
+  migrate(_migrations: Migration[]): Promise<MigrationResult>;
+  /**
+   * Rollback the last migration.
+   *
+   * @remarks
+   * Default implementation is a placeholder. Subclasses should implement
+   * migration rollback logic.
+   *
+   * @returns Migration result after rollback
+   *
+   * @throws {DatabaseError} If rollback fails
+   */
+  rollback(): Promise<MigrationResult>;
+  /**
+   * Get migration status.
+   *
+   * @remarks
+   * Default implementation is a placeholder. Subclasses should implement
+   * migration status checking.
+   *
+   * @returns Current migration status
+   *
+   * @throws {DatabaseError} If status check fails
+   */
+  getMigrationStatus(): Promise<MigrationResult>;
+  /**
+   * Create a new table.
+   *
+   * @remarks
+   * Default implementation is a placeholder. Subclasses should implement
+   * table creation logic.
+   *
+   * @param definition - Table definition
+   * @param options - Creation options
+   *
+   * @throws {DatabaseError} If table creation fails
+   */
+  createTable(definition: TableDefinition, options?: CreateTableOptions): Promise<void>;
+  /**
+   * Drop a table.
+   *
+   * @remarks
+   * Default implementation is a placeholder. Subclasses should implement
+   * table dropping logic.
+   *
+   * @param tableName - Name of table to drop
+   * @param options - Drop options
+   *
+   * @throws {DatabaseError} If table drop fails
+   */
+  dropTable(tableName: string, options?: DropTableOptions): Promise<void>;
+  /**
+   * Alter an existing table.
+   *
+   * @remarks
+   * Default implementation is a placeholder. Subclasses should implement
+   * table alteration logic.
+   *
+   * @param tableName - Name of table to alter
+   * @param operations - Alteration operations
+   * @param options - Alter options
+   *
+   * @throws {DatabaseError} If table alteration fails
+   */
+  alterTable(tableName: string, operations: AlterTableOperation[], _options?: AlterTableOptions): Promise<void>;
+  /**
+   * Check if a table exists in the database.
+   *
+   * @remarks
+   * Uses dialect-specific information schema queries to check table existence.
+   * This is useful for development mode auto-sync to determine whether to
+   * CREATE or DROP/CREATE tables.
+   *
+   * @param tableName - Name of table to check
+   * @param schema - Optional schema name (defaults to 'public' for PostgreSQL)
+   * @returns True if table exists, false otherwise
+   *
+   * @throws {DatabaseError} If query fails
+   *
+   * @example
+   * ```typescript
+   * const exists = await adapter.tableExists('users');
+   * if (exists) {
+   *   await adapter.dropTable('users');
+   * }
+   * await adapter.createTable(userTableDef);
+   * ```
+   */
+  tableExists(tableName: string, schema?: string): Promise<boolean>;
+  /**
+   * Get list of all tables in the database.
+   *
+   * @remarks
+   * Uses dialect-specific information schema queries to list tables.
+   * Useful for detecting orphaned tables or validating schema state.
+   *
+   * @param schema - Optional schema name (defaults to 'public' for PostgreSQL)
+   * @returns Array of table names
+   *
+   * @throws {DatabaseError} If query fails
+   */
+  listTables(schema?: string): Promise<string[]>;
+  /**
+   * Escape a table or column identifier.
+   *
+   * @remarks
+   * Default uses double quotes (SQL standard).
+   * MySQL adapter should override to use backticks.
+   *
+   * @param identifier - Identifier to escape
+   * @returns Escaped identifier
+   *
+   * @protected
+   */
+  protected escapeIdentifier(identifier: string): string;
+  /**
+   * Create a DatabaseError with proper error kind classification.
+   *
+   * @remarks
+   * Protected helper for subclasses to create consistent errors.
+   * Subclasses can override to add dialect-specific error classification.
+   *
+   * @param kind - Error kind
+   * @param message - Error message
+   * @param cause - Original error
+   * @returns DatabaseError instance
+   *
+   * @protected
+   */
+  protected createDatabaseError(kind: DatabaseErrorKind, message: string, cause?: Error): DatabaseError;
+  /**
+   * Helper to create transaction context CRUD forwarding methods.
+   *
+   * @param txDb - Thunk returning the transaction-bound Drizzle executor
+   * @returns Object providing forwarded CRUD and getDrizzle methods
+   *
+   * @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.
+   *
+   * Not forwarded to the pooled `update` the way `select` and `delete` are:
+   * that one goes through the Drizzle query builder, which writes the columns
+   * the runtime MODEL declares, and a transaction's update must reach the
+   * columns the physical TABLE has — the localization transition window
+   * writes a column the model has already moved to a companion table that
+   * does not exist yet. The INSERT half of every transaction context already
+   * builds its own statement for that reason; `update-statement.ts` is the
+   * UPDATE half, spelled once for the three adapters, and this runs it: on
+   * the transaction executor, classified with the operation and table named
+   * as the pooled `update` classifies its failures, and read back through
+   * `select` on the same executor when the caller asked for rows.
+   *
+   * That read is by the rows' IDENTITY where the dialect can report it: on
+   * PostgreSQL and SQLite the statement carries `RETURNING <primary key>`, and
+   * the read-back asks for exactly those rows — so a row another transaction
+   * adds under the same predicate meanwhile is not among them, and an update
+   * whose own write falsifies its predicate still reads its rows back. MySQL
+   * has no RETURNING, so there the read re-runs the predicate, as the pooled
+   * `update` always has on that dialect; a table with no primary key in its
+   * model reads back the same way.
+   *
+   * @param txDb - thunk returning the transaction-bound Drizzle instance
+   * @param run - how this dialect runs a statement on that instance, and the
+   *   rows it returns when the statement carries RETURNING: better-sqlite3
+   *   answers synchronously, the pooled drivers do not
+   * @param bindUnmodeled - how a value binds when the model declares no
+   *   column for it; a declared column binds through its own encoder
+   * @returns the context's `update` method
+   */
+  protected transactionUpdate(txDb: () => unknown, run: (statement: SQL, returnsRows: boolean) => Promise<Record<string, unknown>[] | undefined> | Record<string, unknown>[] | undefined, bindUnmodeled: (value: unknown) => unknown): TransactionContext["update"];
+  /**
+   * The columns that identify a row of this table, under both spellings: the
+   * SQL name RETURNING reports and the Drizzle property name the query
+   * builder's WHERE is addressed by. Columns flagged primary first; failing
+   * that, the table-level primary key the dialect's table config carries
+   * (`primaryKey({ columns })` leaves each column's flag false), which each
+   * adapter reads through its own dialect. Empty when the model declares
+   * neither, and the read-back falls back to the caller's predicate.
+   */
+  protected identityColumns(tableObj: Record<string, unknown>): Array<{
+    jsName: string;
+    sqlName: string;
+  }>;
+  /**
+   * How a value binds to a column the model does not declare, on a driver
+   * that binds scalars, dates and binary natively: a structured value goes
+   * as JSON text, since what node-postgres and mysql2 make of a bare object
+   * 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
+   * naming a dialect, so each adapter answers for its own; a dialect that does
+   * not answer reports none.
+   */
+  protected compositePrimaryKey(_tableObj: Record<string, unknown>): object[];
+  /** The registered table object, or the error every CRUD method throws without one. */
+  private resolvedTableObject;
+  /**
+   * The statement `transactionUpdate` runs.
+   *
+   * @throws when nothing would be written — every key `undefined`, or none at
+   *   all. The query builder refused that too ("No values to set"), and a
+   *   patch that names nothing is a caller's mistake rather than a write of
+   *   nothing.
+   */
+  private buildTransactionUpdate;
+  /**
+   * Whether a transaction's `update` reads the rows it changed back: the
+   * caller named columns, or `*`. An empty list, like no option at all, asks
+   * for nothing and `update` answers `[]`, as it always has. The rows come
+   * from a read of the update's own WHERE on its own transaction, so they are
+   * the model's view of the row, decoded as every read is decoded — which is
+   * what the query-builder update returned for them, and why the named list
+   * 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.
+   *
+   * @remarks
+   * Subclasses can override this method to add dialect-specific error code classification.
+   *
+   * @param error - Original error
+   * @param sql - SQL statement that caused the error (optional)
+   * @returns DatabaseError instance
+   *
+   * @protected
+   */
+  protected classifyError(error: unknown, sql?: string): DatabaseError;
+  /**
+   * Handle query errors and convert to DatabaseError.
+   *
+   * @remarks
+   * Protected helper for consistent error handling across CRUD operations.
+   * Delegates to `classifyError` and attaches operation and table context if not present.
+   * Subclasses override `classifyError` to provide dialect-specific error code classification.
+   *
+   * @param error - Original error
+   * @param operation - Operation that failed
+   * @param table - Table name
+   * @returns DatabaseError instance
+   *
+   * @protected
+   */
+  protected handleQueryError(error: unknown, operation: string, table: string): DatabaseError;
+}
+export { TransactionCrudDelegator as n, TransactionCrudForwarders as r, DrizzleAdapter as t };
+//# sourceMappingURL=adapter-CSP-Ek-L.d.ts.map