@nextlyhq/adapter-drizzle 0.0.2-alpha.6 → 0.0.2-alpha.60

package/dist/{adapter-nvlxFkF-.d.cts → adapter-BG7MnOUw.d.cts}

@@ -1,7 +1,8 @@
+import { AnyRelations, SQL } from 'drizzle-orm';
 import { S as SupportedDialect, a as SqlParam, T as TableResolver } from './core-CVO7WYDj.cjs';
-import { T as TransactionContext, e as TransactionOptions, D as DatabaseCapabilities, P as PoolStats, S as SelectOptions, I as InsertOptions, W as WhereClause, U as UpdateOptions, f as DeleteOptions, g as UpsertOptions, a as Migration, d as MigrationResult } from './migration-BbO5meEV.cjs';
+import { T as TransactionContext, e as TransactionOptions, D as DatabaseCapabilities, P as PoolStats, S as SelectOptions, I as InsertOptions, W as WhereClause, U as UpdateOptions, f as DeleteOptions, g as UpsertOptions, a as Migration, d as MigrationResult } from './migration-BUc56kip.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-um1d_3Uo.cjs';
+import { D as DatabaseErrorKind, a as DatabaseError } from './error-BrdknH2s.cjs';
 
 /**
  * Base database adapter abstract class.
@@ -16,53 +17,6 @@ import { D as DatabaseErrorKind, a as DatabaseError } from './error-um1d_3Uo.cjs
  * @packageDocumentation
  */
 
-/**
- * Abstract base class for database adapters.
- *
- * @remarks
- * All dialect-specific adapters must extend this class and implement the abstract methods.
- * Default implementations are provided for CRUD operations, which can be overridden for
- * optimization or dialect-specific behavior.
- *
- * ## Required Implementations
- *
- * Subclasses must implement:
- * - `dialect` - Database dialect identifier
- * - `connect()` - Establish database connection
- * - `disconnect()` - Close database connection
- * - `executeQuery()` - Execute raw SQL query
- * - `transaction()` - Execute operations within a transaction
- * - `getCapabilities()` - Report database feature support
- *
- * ## Optional Overrides
- *
- * Subclasses can override default CRUD methods for optimization:
- * - `select()`, `selectOne()` - Custom query optimization
- * - `insert()`, `insertMany()` - Bulk insert optimization
- * - `update()`, `delete()` - Custom update/delete logic
- * - `upsert()` - Dialect-specific upsert syntax
- *
- * @example
- * ```typescript
- * export class PostgresAdapter extends DrizzleAdapter {
- *   readonly dialect = 'postgresql' as const;
- *
- *   async connect() {
- *     this.pool = new Pool({ connectionString: this.config.url });
- *     // ... connection logic
- *   }
- *
- *   async executeQuery<T>(sql: string, params?: SqlParam[]) {
- *     const result = await this.pool.query(sql, params);
- *     return result.rows as T[];
- *   }
- *
- *   // ... other required methods
- * }
- * ```
- *
- * @public
- */
 declare abstract class DrizzleAdapter {
     /**
      * Database dialect identifier.
@@ -106,11 +60,29 @@ declare abstract class DrizzleAdapter {
      * 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 transaction fails
+     * @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>;
     /**
@@ -136,17 +108,18 @@ declare abstract class DrizzleAdapter {
      * - Consistent error handling
      * - Proper connection pooling
      *
-     * @param schema - Optional schema object for typed queries
+     * @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(mySchemas);
+     * const db = adapter.getDrizzle(myRelations); // defineRelations output
      * const result = await db.insert(users).values({ ... }).returning();
      * ```
      */
-    abstract getDrizzle<T = unknown>(schema?: Record<string, unknown>): T;
+    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.
@@ -167,6 +140,27 @@ declare abstract class DrizzleAdapter {
      * 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
@@ -174,6 +168,131 @@ declare abstract class DrizzleAdapter {
      * 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;
     /**
      * Check if the adapter is currently connected.
      *
@@ -286,7 +405,7 @@ declare abstract class DrizzleAdapter {
      * });
      * ```
      */
-    select<T = unknown>(table: string, options?: SelectOptions): Promise<T[]>;
+    select<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T[]>;
     /**
      * Select a single record from a table.
      *
@@ -307,7 +426,7 @@ declare abstract class DrizzleAdapter {
      * });
      * ```
      */
-    selectOne<T = unknown>(table: string, options?: SelectOptions): Promise<T | null>;
+    selectOne<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T | null>;
     /**
      * Insert a single record into a table.
      *
@@ -378,7 +497,24 @@ declare abstract class DrizzleAdapter {
      * );
      * ```
      */
-    update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions): Promise<T[]>;
+    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.
      *
@@ -401,7 +537,7 @@ declare abstract class DrizzleAdapter {
      * console.log(`Deleted ${count} users`);
      * ```
      */
-    delete(table: string, where: WhereClause, _options?: DeleteOptions): Promise<number>;
+    delete(table: string, where: WhereClause, _options?: DeleteOptions, executor?: unknown): Promise<number>;
     /**
      * Upsert (INSERT or UPDATE) a record.
      *
@@ -429,7 +565,7 @@ declare abstract class DrizzleAdapter {
      * });
      * ```
      */
-    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions): Promise<T>;
+    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions, executor?: unknown): Promise<T>;
     /**
      * Run pending migrations.
      *

package/dist/{adapter-BxJVtttb.d.ts → adapter-DjPoLjBK.d.ts}

@@ -1,7 +1,8 @@
+import { AnyRelations, SQL } from 'drizzle-orm';
 import { S as SupportedDialect, a as SqlParam, T as TableResolver } from './core-CVO7WYDj.js';
-import { T as TransactionContext, e as TransactionOptions, D as DatabaseCapabilities, P as PoolStats, S as SelectOptions, I as InsertOptions, W as WhereClause, U as UpdateOptions, f as DeleteOptions, g as UpsertOptions, a as Migration, d as MigrationResult } from './migration-Qe70wDOC.js';
+import { T as TransactionContext, e as TransactionOptions, D as DatabaseCapabilities, P as PoolStats, S as SelectOptions, I as InsertOptions, W as WhereClause, U as UpdateOptions, f as DeleteOptions, g as UpsertOptions, a as Migration, d as MigrationResult } from './migration-Bj84e15B.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-um1d_3Uo.js';
+import { D as DatabaseErrorKind, a as DatabaseError } from './error-BrdknH2s.js';
 
 /**
  * Base database adapter abstract class.
@@ -16,53 +17,6 @@ import { D as DatabaseErrorKind, a as DatabaseError } from './error-um1d_3Uo.js'
  * @packageDocumentation
  */
 
-/**
- * Abstract base class for database adapters.
- *
- * @remarks
- * All dialect-specific adapters must extend this class and implement the abstract methods.
- * Default implementations are provided for CRUD operations, which can be overridden for
- * optimization or dialect-specific behavior.
- *
- * ## Required Implementations
- *
- * Subclasses must implement:
- * - `dialect` - Database dialect identifier
- * - `connect()` - Establish database connection
- * - `disconnect()` - Close database connection
- * - `executeQuery()` - Execute raw SQL query
- * - `transaction()` - Execute operations within a transaction
- * - `getCapabilities()` - Report database feature support
- *
- * ## Optional Overrides
- *
- * Subclasses can override default CRUD methods for optimization:
- * - `select()`, `selectOne()` - Custom query optimization
- * - `insert()`, `insertMany()` - Bulk insert optimization
- * - `update()`, `delete()` - Custom update/delete logic
- * - `upsert()` - Dialect-specific upsert syntax
- *
- * @example
- * ```typescript
- * export class PostgresAdapter extends DrizzleAdapter {
- *   readonly dialect = 'postgresql' as const;
- *
- *   async connect() {
- *     this.pool = new Pool({ connectionString: this.config.url });
- *     // ... connection logic
- *   }
- *
- *   async executeQuery<T>(sql: string, params?: SqlParam[]) {
- *     const result = await this.pool.query(sql, params);
- *     return result.rows as T[];
- *   }
- *
- *   // ... other required methods
- * }
- * ```
- *
- * @public
- */
 declare abstract class DrizzleAdapter {
     /**
      * Database dialect identifier.
@@ -106,11 +60,29 @@ declare abstract class DrizzleAdapter {
      * 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 transaction fails
+     * @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>;
     /**
@@ -136,17 +108,18 @@ declare abstract class DrizzleAdapter {
      * - Consistent error handling
      * - Proper connection pooling
      *
-     * @param schema - Optional schema object for typed queries
+     * @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(mySchemas);
+     * const db = adapter.getDrizzle(myRelations); // defineRelations output
      * const result = await db.insert(users).values({ ... }).returning();
      * ```
      */
-    abstract getDrizzle<T = unknown>(schema?: Record<string, unknown>): T;
+    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.
@@ -167,6 +140,27 @@ declare abstract class DrizzleAdapter {
      * 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
@@ -174,6 +168,131 @@ declare abstract class DrizzleAdapter {
      * 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;
     /**
      * Check if the adapter is currently connected.
      *
@@ -286,7 +405,7 @@ declare abstract class DrizzleAdapter {
      * });
      * ```
      */
-    select<T = unknown>(table: string, options?: SelectOptions): Promise<T[]>;
+    select<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T[]>;
     /**
      * Select a single record from a table.
      *
@@ -307,7 +426,7 @@ declare abstract class DrizzleAdapter {
      * });
      * ```
      */
-    selectOne<T = unknown>(table: string, options?: SelectOptions): Promise<T | null>;
+    selectOne<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T | null>;
     /**
      * Insert a single record into a table.
      *
@@ -378,7 +497,24 @@ declare abstract class DrizzleAdapter {
      * );
      * ```
      */
-    update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions): Promise<T[]>;
+    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.
      *
@@ -401,7 +537,7 @@ declare abstract class DrizzleAdapter {
      * console.log(`Deleted ${count} users`);
      * ```
      */
-    delete(table: string, where: WhereClause, _options?: DeleteOptions): Promise<number>;
+    delete(table: string, where: WhereClause, _options?: DeleteOptions, executor?: unknown): Promise<number>;
     /**
      * Upsert (INSERT or UPDATE) a record.
      *
@@ -429,7 +565,7 @@ declare abstract class DrizzleAdapter {
      * });
      * ```
      */
-    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions): Promise<T>;
+    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions, executor?: unknown): Promise<T>;
     /**
      * Run pending migrations.
      *