@nextlyhq/adapter-drizzle 0.0.2-alpha.7 → 0.0.2-alpha.70

package/dist/index-BYb6cDli.d.ts

@@ -0,0 +1,1168 @@
+import { f as SqlParam, p as SupportedDialect } from "./schema-Bkkr3JMC.js";
+import { AnyRelations, SQL } from "drizzle-orm";
+/**
+ * Every WHERE clause operator this package DECLARES, as a value.
+ *
+ * @remarks
+ * Declared, not guaranteed executable. Membership here means a `WhereCondition`
+ * carrying the operator type-checks — it does NOT mean the adapter can run it.
+ * `OVERLAPS` is declared and unimplemented, and throws at build time, so a
+ * validator written against this list will admit input the query layer then
+ * rejects. Validate against it to catch a misspelled operator; do not read
+ * acceptance here as a capability.
+ *
+ * - Standard comparison: =, !=, <, >, <=, >=
+ * - Set operations: IN, NOT IN
+ * - Pattern matching: LIKE, ILIKE (case-insensitive, PostgreSQL/emulated)
+ * - NULL checks: IS NULL, IS NOT NULL
+ * - Range: BETWEEN, NOT BETWEEN
+ * - Substring: CONTAINS — a LITERAL match on a TEXT column; see below
+ * - Declared but NOT implemented: OVERLAPS, which throws
+ *
+ * This list is the source of truth and {@link WhereOperator} is derived from it,
+ * rather than the two being written out separately. A guard that has to enumerate
+ * the operators — a validator over caller input, or a test asserting the builder
+ * handles or refuses each one — can only do that from a runtime value, and a
+ * hand-kept copy of the union would agree with it on the day it was written and
+ * silently stop agreeing the next time a member is added.
+ *
+ * @public
+ */
+declare const WHERE_OPERATORS: readonly ["=", "!=", "<", ">", "<=", ">=", "IN", "NOT IN", "LIKE", "ILIKE", "IS NULL", "IS NOT NULL", "BETWEEN", "NOT BETWEEN", "CONTAINS", "ICONTAINS", "OVERLAPS"];
+/**
+ * Every WHERE clause operator this package declares. Derived from
+ * {@link WHERE_OPERATORS}, and carrying the same caveat: a value of this type
+ * type-checks, which is not the same as the adapter being able to execute it.
+ *
+ * @public
+ */
+type WhereOperator = (typeof WHERE_OPERATORS)[number];
+/**
+ * Individual WHERE condition.
+ *
+ * @remarks
+ * Represents a single condition in a WHERE clause. For IS NULL and IS NOT NULL
+ * operators, the value field is optional.
+ *
+ * @public
+ */
+interface WhereCondition {
+  /** Column name to filter on */
+  column: string;
+  /** Comparison operator */
+  op: WhereOperator;
+  /** Value(s) to compare against (optional for IS NULL/IS NOT NULL) */
+  value?: SqlParam | SqlParam[];
+  /** Second value for BETWEEN operator */
+  valueTo?: SqlParam;
+}
+/**
+ * Complex WHERE clause with logical operators.
+ *
+ * @remarks
+ * Supports nested conditions with AND, OR, and NOT logical operators.
+ * Can be recursively nested for complex queries.
+ *
+ * @example
+ * ```typescript
+ * const where: WhereClause = {
+ *   and: [
+ *     { column: "status", op: "=", value: "published" },
+ *     {
+ *       or: [
+ *         { column: "author", op: "=", value: "john" },
+ *         { column: "author", op: "=", value: "jane" }
+ *       ]
+ *     }
+ *   ]
+ * };
+ * ```
+ *
+ * @public
+ */
+interface WhereClause {
+  /** All conditions must be true (AND) */
+  and?: (WhereCondition | WhereClause)[];
+  /** At least one condition must be true (OR) */
+  or?: (WhereCondition | WhereClause)[];
+  /** Negate a condition (NOT) */
+  not?: WhereCondition | WhereClause;
+}
+/**
+ * ORDER BY specification for query results.
+ *
+ * @remarks
+ * Controls the sorting of query results. NULL handling varies by database
+ * but can be explicitly controlled with the nulls field.
+ *
+ * @public
+ */
+interface OrderBySpec {
+  /** Column name to sort by */
+  column: string;
+  /** Sort direction (default: asc) */
+  direction?: "asc" | "desc";
+  /** NULL value ordering (database-specific defaults vary) */
+  nulls?: "first" | "last";
+}
+/**
+ * JOIN specification for table joins.
+ *
+ * @remarks
+ * Supports different types of JOINs. Note that complex joins may require
+ * dialect-specific handling.
+ *
+ * @public
+ */
+interface JoinSpec {
+  /** Type of join */
+  type: "inner" | "left" | "right" | "full";
+  /** Table name to join */
+  table: string;
+  /** Join condition */
+  on: {
+    /** Column from the left table */
+    leftColumn: string;
+    /** Column from the right table */
+    rightColumn: string;
+  };
+  /** Optional alias for the joined table */
+  alias?: string;
+}
+/**
+ * Options for SELECT queries.
+ *
+ * @remarks
+ * Provides a database-agnostic way to build SELECT queries with filtering,
+ * sorting, pagination, and joins.
+ *
+ * @public
+ */
+/**
+ * What a COUNT asks for.
+ *
+ * 🔴 `distinctOn` is a column LIST rather than a boolean, and the difference is
+ * the whole reason this option exists: counting rows and counting the things
+ * those rows are about are different questions whenever a thing can own more
+ * than one row. A document holding a pending edit in three languages is one
+ * document and three version rows.
+ */
+interface CountOptions {
+  /** Filter conditions, the same vocabulary `select` takes. */
+  where?: WhereClause;
+  /**
+   * Count DISTINCT combinations of these columns instead of rows.
+   *
+   * Compiled as `COUNT(*)` over a `SELECT DISTINCT` subquery rather than as
+   * `COUNT(DISTINCT a, b)`, because the latter is not portable: MySQL accepts
+   * it, PostgreSQL requires a row constructor, and SQLite rejects it outright
+   * with "wrong number of arguments to function count()". The subquery is the
+   * one form all three engines agree on, and it is what this compiles to on
+   * every dialect so the number cannot differ by engine.
+   */
+  distinctOn?: string[];
+}
+interface SelectOptions {
+  /** Specific columns to select (default: all columns) */
+  columns?: string[];
+  /** Filter conditions */
+  where?: WhereClause;
+  /** Sort order */
+  orderBy?: OrderBySpec[];
+  /** Maximum number of rows to return */
+  limit?: number;
+  /** Number of rows to skip */
+  offset?: number;
+  /** Table joins */
+  joins?: JoinSpec[];
+  /** GROUP BY columns */
+  groupBy?: string[];
+  /** HAVING clause (for aggregated results) */
+  having?: WhereClause;
+  /** Return distinct rows only */
+  distinct?: boolean;
+  /**
+   * Take a `FOR UPDATE` row lock on the selected rows for the rest of the
+   * transaction, and read the latest committed values rather than the
+   * transaction's snapshot. Use for read-modify-write sequences that must not
+   * interleave (e.g. re-reading a status under the lock the write will take).
+   *
+   * Requires a transaction executor. No-ops on SQLite, which has no `FOR UPDATE`
+   * and needs none — its transactions open with `BEGIN IMMEDIATE`, already
+   * serializing writers.
+   */
+  forUpdate?: boolean;
+}
+/**
+ * Options for INSERT operations.
+ *
+ * @remarks
+ * Controls the behavior of INSERT operations including conflict handling
+ * and returning inserted data.
+ *
+ * @public
+ */
+interface InsertOptions {
+  /** Columns to return after insert (use "*" for all columns) */
+  returning?: string[] | "*";
+  /** Handle conflicts (unique constraint violations) */
+  onConflict?: {
+    /** Columns that define the conflict (unique constraint) */
+    columns: string[];
+    /** Action to take on conflict */
+    action: "ignore" | "update";
+    /** Columns to update on conflict (required if action is "update") */
+    updateColumns?: string[];
+  };
+}
+/**
+ * Options for UPDATE operations.
+ *
+ * @remarks
+ * Controls what data is returned after an update operation.
+ *
+ * @public
+ */
+interface UpdateOptions {
+  /** Columns to return after update (use "*" for all columns) */
+  returning?: string[] | "*";
+}
+/**
+ * Options for DELETE operations.
+ *
+ * @remarks
+ * Controls what data is returned after a delete operation.
+ *
+ * @public
+ */
+interface DeleteOptions {
+  /** Columns to return after delete (use "*" for all columns) */
+  returning?: string[] | "*";
+}
+/**
+ * Options for UPSERT operations (INSERT or UPDATE).
+ *
+ * @remarks
+ * Combines INSERT and UPDATE behavior. If a row with the specified
+ * conflict columns exists, it will be updated; otherwise, a new row
+ * will be inserted.
+ *
+ * @public
+ */
+interface UpsertOptions {
+  /** Columns that define uniqueness for conflict detection */
+  conflictColumns: string[];
+  /**
+   * Columns to update if conflict occurs (default: all provided columns).
+   *
+   * Empty means "insert, or keep the row that stands". The kept row is read
+   * back after the statement, so on PostgreSQL and SQLite a row another
+   * writer deletes between the two cannot be returned, and the call resolves
+   * to `null`. Whether THIS call created the row is told by the id it
+   * returns: send a fresh id, and only a call whose own insert ran gets it
+   * back — a read-back can only return another writer's row.
+   */
+  updateColumns?: string[];
+  /** Columns to return after upsert (use "*" for all columns) */
+  returning?: string[] | "*";
+}
+/**
+ * Transaction isolation levels.
+ *
+ * @remarks
+ * Controls the visibility of changes between concurrent transactions.
+ * Not all levels are supported by all databases:
+ * - PostgreSQL: All levels supported
+ * - MySQL: All levels supported
+ * - SQLite: Serializable only (default)
+ *
+ * @public
+ */
+type TransactionIsolationLevel = "read uncommitted" | "read committed" | "repeatable read" | "serializable";
+/**
+ * Options for transaction execution.
+ *
+ * @remarks
+ * Configures transaction behavior including isolation level, read-only mode,
+ * timeouts, and retry logic.
+ *
+ * @public
+ */
+interface TransactionOptions {
+  /** Transaction isolation level */
+  isolationLevel?: TransactionIsolationLevel;
+  /** Read-only transaction (optimization hint) */
+  readOnly?: boolean;
+  /** Per-transaction statement timeout in milliseconds */
+  timeoutMs?: number;
+  /** Number of retry attempts on serialization failures (default: 0) */
+  retryCount?: number;
+  /** Delay between retry attempts in milliseconds (default: 100) */
+  retryDelayMs?: number;
+  /**
+   * MySQL only: run the transaction in strict mode, so a statement that would
+   * cut a string to its column's length or clamp a number to its range fails
+   * rather than applying with a warning. The session's own mode is restored
+   * before the connection returns to the pool. PostgreSQL and SQLite ignore
+   * it: PostgreSQL refuses such values already, and SQLite enforces no
+   * declared length.
+   */
+  strictSqlMode?: boolean;
+}
+/**
+ * Transaction context for executing operations within a transaction.
+ *
+ * @remarks
+ * All operations executed through this context are part of the same
+ * database transaction. The transaction is automatically committed on
+ * success or rolled back on error.
+ *
+ * Savepoint methods are optional and only available on databases that
+ * support them (PostgreSQL, SQLite).
+ *
+ * @public
+ */
+interface TransactionContext {
+  /**
+   * Execute raw SQL within the transaction.
+   *
+   * @param sql - SQL statement to execute
+   * @param params - Optional parameters for the statement
+   * @returns Array of result rows
+   */
+  execute<T = unknown>(sql: string, params?: SqlParam[]): Promise<T[]>;
+  /**
+   * An instance bound to the SAME transaction client with the relational
+   * query API (`db.query.*`) enabled — the transaction's counterpart of
+   * `getDrizzle(relations)`.
+   *
+   * The `getDrizzle()` instance has an empty `query` namespace, so a
+   * relational read inside the transaction needs this one; the pooled
+   * `getDrizzle(relations)` would read on a different connection and miss the
+   * transaction's uncommitted writes. Memoized per relations object, as
+   * `getDrizzle` is, so repeated calls with an unchanged config share one
+   * instance.
+   *
+   * @param relations - drizzle v1 relations config (defineRelations output)
+   */
+  drizzleWithRelations<T = unknown>(relations: AnyRelations): T;
+  /**
+   * Run a Drizzle-built statement within the transaction, for its effect.
+   *
+   * @remarks
+   * The typed CRUD methods below resolve their table through the schema
+   * registry and reject any name it does not declare. That leaves no way to
+   * write to a table addressed under a name the ORM does not know — a table
+   * mid-rename, most of all — other than assembling SQL by hand, which also
+   * means hand-picking each driver's placeholder syntax.
+   *
+   * This accepts Drizzle's `sql` template instead, so identifier quoting and
+   * parameter binding are generated for the dialect in use. Implemented per
+   * adapter because the underlying call is not uniform: node-postgres and
+   * mysql2 expose `execute`, while better-sqlite3 needs `run` and throws on a
+   * statement that returns no rows.
+   *
+   * Returns nothing: this is for statements run to change data, not to read it.
+   *
+   * @param statement - Drizzle `sql` template to run
+   */
+  runStatement(statement: SQL): Promise<void>;
+  /**
+   * Run a Drizzle-built statement within the transaction and return its rows.
+   *
+   * @remarks
+   * The reading half of `runStatement`, for the same reason: a table the schema
+   * registry does not declare cannot be reached through the typed CRUD methods,
+   * which reject the name outright. Implemented per adapter because the drivers
+   * disagree about both the call and the result — node-postgres answers
+   * `{ rows }`, mysql2 a `[rows, fields]` tuple, and better-sqlite3 needs `all`.
+   *
+   * @param statement - Drizzle `sql` template to run
+   * @returns Rows the statement produced
+   */
+  queryStatement<T = Record<string, unknown>>(statement: SQL): Promise<T[]>;
+  /**
+   * Take an exclusive lock on a single row for the rest of this transaction.
+   *
+   * @remarks
+   * For read-modify-write sequences that must not interleave: without a lock
+   * another transaction can commit between the read and the write, leaving the
+   * caller's view of the prior state inconsistent with what its own write
+   * applied on top of.
+   *
+   * No-ops on dialects without row-level locking. SQLite is the case that
+   * matters and needs nothing — its transactions open with `BEGIN IMMEDIATE`,
+   * which already serializes writers.
+   *
+   * @param table - Table name
+   * @param id - Primary-key value of the row to lock
+   */
+  lockRow(table: string, id: SqlParam): Promise<void>;
+  /**
+   * Insert a single record.
+   *
+   * @param table - Table name
+   * @param data - Record data to insert
+   * @param options - Insert options
+   * @returns Inserted record (with RETURNING columns if specified)
+   */
+  insert<T = unknown>(table: string, data: Record<string, unknown>, options?: InsertOptions): Promise<T>;
+  /**
+   * Insert multiple records.
+   *
+   * @param table - Table name
+   * @param data - Array of records to insert
+   * @param options - Insert options
+   * @returns Inserted records (with RETURNING columns if specified)
+   */
+  insertMany<T = unknown>(table: string, data: Record<string, unknown>[], options?: InsertOptions): Promise<T[]>;
+  /**
+   * Select multiple records.
+   *
+   * @param table - Table name
+   * @param options - Select options (filtering, sorting, etc.)
+   * @returns Array of matching records
+   */
+  select<T = unknown>(table: string, options?: SelectOptions): Promise<T[]>;
+  /**
+   * Select a single record.
+   *
+   * @param table - Table name
+   * @param options - Select options (filtering, sorting, etc.)
+   * @returns First matching record or null
+   */
+  selectOne<T = unknown>(table: string, options?: SelectOptions): Promise<T | null>;
+  /**
+   * Update records.
+   *
+   * @remarks
+   * Built by the adapter rather than by the Drizzle query builder, as `insert`
+   * is: the statement writes the columns the PHYSICAL table has, where the
+   * pooled `update` writes the ones the runtime model declares. A column the
+   * model declares binds through its own encoder, exactly as the query builder
+   * binds it; one it does not declare binds the way this adapter's
+   * transactional insert binds every value; a key naming no column on the
+   * table is a database error rather than a silent drop. A key whose value is
+   * `undefined` is not written, `null` is, and an update naming nothing to
+   * write is refused.
+   *
+   * When `options.returning` asks for rows, they come from a read on this
+   * transaction, decoded as every read is — the model's view of the row,
+   * whatever columns were named. On PostgreSQL and SQLite that read is by the
+   * identities the statement reported through RETURNING, so it is exactly the
+   * rows this update changed. MySQL has no RETURNING, so there the read
+   * re-runs `where`, as it always has on that dialect: an update whose own
+   * write falsifies its `where` reads back nothing, and a row another
+   * transaction adds under the predicate meanwhile is included. A fenced
+   * compare-and-set wants `updateCount` on every dialect.
+   *
+   * @param table - Table name
+   * @param data - Data to update, keyed by SQL column name; Drizzle property
+   *   names are accepted as well
+   * @param where - Conditions for records to update
+   * @param options - Update options
+   * @returns The updated rows when `returning` asked for them, else `[]`
+   */
+  update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions): Promise<T[]>;
+  /**
+   * Update records and report how many rows the statement affected.
+   *
+   * @remarks
+   * The transactional half of the adapter's `updateCount`, and the only way to
+   * perform a fenced compare-and-set inside a transaction. `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 whose own write falsifies its predicate
+   * reads back zero rows, and a write that landed reports as unmatched.
+   *
+   * 🔴 Inherits the adapter's MySQL caveat: MySQL counts CHANGED rows rather
+   * than matched ones, so a caller using this as a compare-and-set must write
+   * at least one column the update always moves — a state transition, a version
+   * bump, a timestamp of sufficient resolution. 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.
+   *
+   * @param table - Table name
+   * @param data - Column values to write
+   * @param where - Conditions the update must match
+   * @returns Number of rows the statement affected
+   */
+  updateCount(table: string, data: Record<string, unknown>, where: WhereClause): Promise<number>;
+  /**
+   * Delete records.
+   *
+   * @param table - Table name
+   * @param where - Conditions for records to delete
+   * @param options - Delete options
+   * @returns Number of deleted records
+   */
+  delete(table: string, where: WhereClause, options?: DeleteOptions): Promise<number>;
+  /**
+   * Upsert a record (INSERT or UPDATE).
+   *
+   * @param table - Table name
+   * @param data - Record data
+   * @param options - Upsert options (must specify conflict columns)
+   * @returns Upserted record (with RETURNING columns if specified)
+   */
+  upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions): Promise<T>;
+  /**
+   * Create a savepoint (PostgreSQL, SQLite only).
+   *
+   * @remarks
+   * Savepoints allow partial rollback within a transaction.
+   * Not supported on MySQL.
+   *
+   * @param name - Savepoint name
+   */
+  savepoint?(name: string): Promise<void>;
+  /**
+   * Rollback to a savepoint (PostgreSQL, SQLite only).
+   *
+   * @remarks
+   * Discards all changes made after the savepoint was created.
+   *
+   * @param name - Savepoint name
+   */
+  rollbackToSavepoint?(name: string): Promise<void>;
+  /**
+   * Release a savepoint (PostgreSQL, SQLite only).
+   *
+   * @remarks
+   * Commits the savepoint, making its changes permanent within the transaction.
+   *
+   * @param name - Savepoint name
+   */
+  releaseSavepoint?(name: string): Promise<void>;
+  /**
+   * Return the Drizzle ORM instance bound to THIS transaction's connection.
+   *
+   * @remarks
+   * Runs Drizzle `sql` templates / fluent queries inside the caller's
+   * transaction (same client the delegated CRUD methods use), so services
+   * that drop to Drizzle raw SQL (e.g. junction-table writes) can participate
+   * in the transaction instead of running on the pooled connection. Required
+   * so callers never silently fall back to the pooled connection (which would
+   * run a write outside the transaction); every adapter must implement it.
+   * Generic return so callers narrow to the dialect Drizzle type they need
+   * without an `any` cast.
+   */
+  getDrizzle<T = unknown>(): T;
+}
+/**
+ * Database feature capabilities.
+ *
+ * @remarks
+ * Describes what features are supported by a specific database adapter.
+ * Services can check these capabilities to conditionally enable features
+ * or implement fallback behavior.
+ *
+ * @example
+ * ```typescript
+ * const capabilities = adapter.getCapabilities();
+ * if (capabilities.supportsJsonb) {
+ *   // Use JSONB-specific features
+ * } else if (capabilities.supportsJson) {
+ *   // Fallback to JSON
+ * }
+ * ```
+ *
+ * @public
+ */
+interface DatabaseCapabilities {
+  /** Database dialect */
+  dialect: SupportedDialect;
+  /**
+   * Native JSONB support (PostgreSQL only).
+   *
+   * @remarks
+   * JSONB provides better performance and indexing than JSON.
+   * Other databases will use JSON or emulated JSON.
+   */
+  supportsJsonb: boolean;
+  /**
+   * JSON column type support.
+   *
+   * @remarks
+   * All supported databases have some form of JSON support:
+   * - PostgreSQL: Native JSON and JSONB
+   * - MySQL: Native JSON column type
+   * - SQLite: JSON functions (json_extract, json_array, etc.)
+   */
+  supportsJson: boolean;
+  /**
+   * Array column type support (PostgreSQL only).
+   *
+   * @remarks
+   * PostgreSQL has native array types. Other databases must use
+   * JSON arrays or separate tables.
+   */
+  supportsArrays: boolean;
+  /**
+   * Generated/computed columns support.
+   *
+   * @remarks
+   * Support for columns whose values are automatically computed from
+   * other columns:
+   * - PostgreSQL: GENERATED ALWAYS AS ... STORED
+   * - MySQL: Generated columns
+   * - SQLite: Generated columns (3.31.0+)
+   */
+  supportsGeneratedColumns: boolean;
+  /**
+   * Full-text search support.
+   *
+   * @remarks
+   * Native full-text search capabilities:
+   * - PostgreSQL: tsvector/tsquery
+   * - MySQL: FULLTEXT indexes (limited)
+   * - SQLite: FTS5 extension (not enabled by default)
+   */
+  supportsFts: boolean;
+  /**
+   * Case-insensitive ILIKE operator support (PostgreSQL only).
+   *
+   * @remarks
+   * Other databases must emulate with LOWER(column) LIKE LOWER(value).
+   */
+  supportsIlike: boolean;
+  /**
+   * RETURNING clause support.
+   *
+   * @remarks
+   * Support for returning data from INSERT/UPDATE/DELETE:
+   * - PostgreSQL: Yes
+   * - MySQL: No (requires separate SELECT)
+   * - SQLite: Yes
+   */
+  supportsReturning: boolean;
+  /**
+   * Savepoint support for nested transactions.
+   *
+   * @remarks
+   * - PostgreSQL: Yes
+   * - MySQL: No (limited support, not recommended)
+   * - SQLite: Yes
+   */
+  supportsSavepoints: boolean;
+  /**
+   * ON CONFLICT clause support for upserts.
+   *
+   * @remarks
+   * - PostgreSQL: ON CONFLICT DO NOTHING/UPDATE
+   * - MySQL: ON DUPLICATE KEY UPDATE (different syntax)
+   * - SQLite: ON CONFLICT (similar to PostgreSQL)
+   */
+  supportsOnConflict: boolean;
+  /**
+   * Maximum number of parameters per query.
+   *
+   * @remarks
+   * Database-specific limits:
+   * - PostgreSQL: 65,535
+   * - MySQL: 65,535
+   * - SQLite: 999 (can be increased with SQLITE_MAX_VARIABLE_NUMBER)
+   */
+  maxParamsPerQuery: number;
+  /**
+   * Maximum length for table/column identifiers.
+   *
+   * @remarks
+   * - PostgreSQL: 63 bytes
+   * - MySQL: 64 characters
+   * - SQLite: No limit (practically unlimited)
+   */
+  maxIdentifierLength: number;
+  /**
+   * Whether the server accepts `SELECT ... FOR SHARE`.
+   *
+   * @remarks
+   * Reported by the MySQL adapter once it has connected and read the server's
+   * version: MySQL 8, Aurora MySQL and Vitess/PlanetScale accept it, MariaDB
+   * and TiDB reject it as a syntax error. PostgreSQL always accepts it and
+   * SQLite has no row locks, so their adapters leave it unset. Unset means
+   * not known; a caller then takes a lock every server accepts.
+   *
+   * @experimental
+   */
+  sharedRowLock?: boolean;
+}
+/**
+ * Connection pool statistics.
+ *
+ * @remarks
+ * Provides visibility into connection pool health. Not all adapters
+ * provide pool statistics (e.g., SQLite is single-connection).
+ *
+ * @public
+ */
+interface PoolStats {
+  /** Total number of connections in the pool */
+  total: number;
+  /** Number of idle (available) connections */
+  idle: number;
+  /** Number of clients waiting for a connection */
+  waiting: number;
+  /** Number of connections currently in use */
+  active: number;
+}
+/**
+ * Migration definition.
+ *
+ * @remarks
+ * Represents a single database migration with up and optional down functions.
+ * Migrations can be defined as raw SQL strings or as functions that use the
+ * transaction context for more complex operations.
+ *
+ * @public
+ */
+interface Migration {
+  /** Unique migration identifier (e.g., "20250104_001_create_users") */
+  id: string;
+  /** Human-readable migration name */
+  name: string;
+  /** Unix timestamp when migration was created */
+  timestamp: number;
+  /** Forward migration (apply changes) */
+  up: string | ((tx: TransactionContext) => Promise<void>);
+  /** Reverse migration (undo changes) - optional */
+  down?: string | ((tx: TransactionContext) => Promise<void>);
+}
+/**
+ * Migration record stored in the database.
+ *
+ * @remarks
+ * Tracks which migrations have been applied to the database.
+ * The migrations table is automatically created by the adapter.
+ *
+ * @public
+ */
+interface MigrationRecord {
+  /** Migration identifier */
+  id: string;
+  /** Migration name */
+  name: string;
+  /** When the migration was applied */
+  appliedAt: Date;
+  /** Optional checksum to detect migration changes */
+  checksum?: string;
+}
+/**
+ * Migration execution result.
+ *
+ * @remarks
+ * Provides information about migration status including applied and
+ * pending migrations.
+ *
+ * @public
+ */
+interface MigrationResult {
+  /** Migrations that were applied in this execution */
+  applied: MigrationRecord[];
+  /** Migrations that are pending (not yet applied) */
+  pending: Migration[];
+  /** ID of the current (most recent) migration, or null if none applied */
+  current: string | null;
+}
+/**
+ * Options for migration execution.
+ *
+ * @public
+ */
+interface MigrationOptions {
+  /** Target migration to migrate to (default: latest) */
+  target?: string;
+  /** Dry run mode - don't actually apply migrations */
+  dryRun?: boolean;
+  /** Run migrations in a single transaction (default: true) */
+  useTransaction?: boolean;
+  /**
+   * Strict checksum validation (default: true).
+   * If true, modified migrations will cause an error.
+   * If false, modified migrations will generate a warning.
+   */
+  strictChecksums?: boolean;
+}
+/**
+ * Migration status information.
+ *
+ * @public
+ */
+interface MigrationStatus {
+  /** Current migration ID (most recently applied) */
+  current: string | null;
+  /** Total number of applied migrations */
+  appliedCount: number;
+  /** Total number of pending migrations */
+  pendingCount: number;
+  /** Applied migration records */
+  applied: MigrationRecord[];
+  /** Pending migrations */
+  pending: Migration[];
+}
+/**
+ * Database error type definitions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Database error classification.
+ *
+ * @remarks
+ * Categorizes database errors for consistent error handling across adapters.
+ * Each adapter translates database-specific error codes to these kinds.
+ *
+ * @public
+ */
+type DatabaseErrorKind = "connection" | "query" | "constraint" | "unique_violation" | "foreign_key_violation" | "check_violation" | "not_null_violation" | "deadlock" | "timeout" | "serialization_failure" | "unsupported_version" | "unknown";
+/**
+ * Enhanced database error interface.
+ *
+ * @remarks
+ * Extends the standard Error interface with database-specific context.
+ * Adapters should throw errors implementing this interface for consistent
+ * error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await adapter.insert('users', { email: 'duplicate@example.com' });
+ * } catch (error) {
+ *   if (isDatabaseError(error) && error.kind === 'unique_violation') {
+ *     console.log(`Duplicate ${error.column} in ${error.table}`);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+interface DatabaseError extends Error {
+  /** Error classification */
+  kind: DatabaseErrorKind;
+  /** Database-specific error code (e.g., "23505" for PostgreSQL unique violation) */
+  code?: string;
+  /** Constraint name that was violated (if applicable) */
+  constraint?: string;
+  /** Table name involved in the error */
+  table?: string;
+  /** Column name involved in the error */
+  column?: string;
+  /** Detailed error description from the database */
+  detail?: string;
+  /** Hint for resolving the error */
+  hint?: string;
+  /** Original error from the database driver */
+  cause?: Error;
+}
+/**
+ * Type guard for DatabaseError.
+ *
+ * @remarks
+ * Checks if an error is a DatabaseError with proper typing.
+ *
+ * @param error - Error to check
+ * @returns True if error is a DatabaseError
+ *
+ * @public
+ */
+declare function isDatabaseError(error: unknown): error is DatabaseError;
+/**
+ * Whether an error is the application's verdict rather than the database's
+ * failure.
+ *
+ * Work running inside a transaction may throw to roll the write back — a
+ * refused value, a permission denial — and such an error is not something the
+ * driver produced. Classifying it as a database error replaces its code and its
+ * payload with a generic one, so a caller that asked for a refusal is handed an
+ * unexplained failure instead, and per-field validation detail is lost on the
+ * way out.
+ *
+ * @param error - Error to check
+ * @returns True if the error was raised by application code
+ *
+ * @public
+ */
+declare function isApplicationError(error: unknown): boolean;
+/**
+ * Database error constructor options.
+ *
+ * @public
+ */
+interface DatabaseErrorOptions {
+  /** Error classification */
+  kind: DatabaseErrorKind;
+  /** Error message */
+  message: string;
+  /** Database-specific error code */
+  code?: string;
+  /** Constraint name */
+  constraint?: string;
+  /** Table name */
+  table?: string;
+  /** Column name */
+  column?: string;
+  /** Detailed description */
+  detail?: string;
+  /** Resolution hint */
+  hint?: string;
+  /** Original error */
+  cause?: Error;
+}
+/**
+ * Create a DatabaseError instance.
+ *
+ * @remarks
+ * Helper function to create properly structured DatabaseError objects.
+ *
+ * @param options - Error options
+ * @returns DatabaseError instance
+ *
+ * @public
+ */
+declare function createDatabaseError(options: DatabaseErrorOptions): DatabaseError;
+/**
+ * The code an adapter gives the error it raises when a request has waited
+ * longer than `pool.connectionTimeoutMs` for a database connection.
+ *
+ * A code of the adapters' own rather than the driver's wording, because the
+ * drivers disagree: pg-pool raises a plain `Error` with no code, mysql2 has no
+ * such wait to time out, and better-sqlite3 has no pool. Core reads this one
+ * code to answer with its retryable "database busy" error.
+ *
+ * @public
+ */
+declare const POOL_WAIT_TIMEOUT_CODE = "NEXTLY_POOL_WAIT_TIMEOUT";
+/**
+ * The error for a request that waited `boundMs` for a database connection and
+ * was given none.
+ *
+ * @param boundMs - The bound it waited, `pool.connectionTimeoutMs`
+ * @param cause - The driver's own error, when the driver raised one
+ *
+ * @public
+ */
+declare function poolWaitTimeoutError(boundMs: number, cause?: Error): DatabaseError;
+/**
+ * Logger interface for adapter operations.
+ *
+ * @remarks
+ * Adapters use this interface to log queries, errors, and performance metrics.
+ *
+ * @public
+ */
+interface AdapterLogger {
+  /**
+   * Log a query execution.
+   *
+   * @param sql - SQL statement
+   * @param params - Query parameters
+   * @param durationMs - Query execution time in milliseconds
+   */
+  query?: (sql: string, params?: SqlParam[], durationMs?: number) => void;
+  /**
+   * Log an error.
+   *
+   * @param error - Error object
+   * @param context - Additional context about the error
+   */
+  error?: (error: Error, context?: Record<string, unknown>) => void;
+  /**
+   * Log a debug message.
+   *
+   * @param message - Debug message
+   * @param context - Additional context
+   */
+  debug?: (message: string, context?: Record<string, unknown>) => void;
+  /**
+   * Log a warning.
+   *
+   * @param message - Warning message
+   * @param context - Additional context
+   */
+  warn?: (message: string, context?: Record<string, unknown>) => void;
+  /**
+   * Log an info message.
+   *
+   * @param message - Info message
+   * @param context - Additional context
+   */
+  info?: (message: string, context?: Record<string, unknown>) => void;
+}
+/**
+ * Connection pool configuration.
+ *
+ * @remarks
+ * Controls connection pooling behavior. SQLite adapters ignore these
+ * settings as SQLite uses a single connection, except
+ * `connectionTimeoutMs`, which bounds the wait for that one connection.
+ *
+ * @public
+ */
+interface PoolConfig {
+  /** Minimum number of connections in the pool */
+  min?: number;
+  /** Maximum number of connections in the pool */
+  max?: number;
+  /** Time (ms) before an idle connection is closed */
+  idleTimeoutMs?: number;
+  /**
+   * Time (ms) a request waits for a connection before it fails as
+   * "database busy" (code `NEXTLY_POOL_WAIT_TIMEOUT` from the adapter,
+   * `DATABASE_BUSY` from Nextly), the same on every dialect. On PostgreSQL
+   * and MySQL it is the wait for a connection already in the pool; it is also
+   * the time a new one gets to open, and one that cannot open in time is a
+   * connection error rather than busy. On SQLite, the wait for the one
+   * connection behind the transactions ahead. `0` waits without limit.
+   *
+   * @default 15000 (a PostgreSQL provider may set its own: Neon's is 20000)
+   */
+  connectionTimeoutMs?: number;
+  /** Time (ms) before considering an unused connection stale */
+  maxLifetimeMs?: number;
+}
+/**
+ * SSL/TLS configuration for database connections.
+ *
+ * @remarks
+ * Relevant for PostgreSQL and MySQL. SQLite doesn't use network connections.
+ *
+ * @public
+ */
+interface SslConfig {
+  /** Reject unauthorized certificates (default: true for production) */
+  rejectUnauthorized?: boolean;
+  /** Path to CA certificate file */
+  ca?: string;
+  /** Path to client certificate file */
+  cert?: string;
+  /** Path to client private key file */
+  key?: string;
+}
+/**
+ * Base adapter configuration.
+ *
+ * @remarks
+ * Common configuration options for all database adapters. Dialect-specific
+ * adapters may extend this interface with additional options.
+ *
+ * @public
+ */
+interface BaseAdapterConfig {
+  /**
+   * Database connection URL.
+   *
+   * @remarks
+   * Examples:
+   * - PostgreSQL: `postgres://user:pass@localhost:5432/dbname`
+   * - MySQL: `mysql://user:pass@localhost:3306/dbname`
+   * - SQLite: `file:./data/app.db` or `file::memory:`
+   */
+  url?: string;
+  /** Database host (alternative to URL) */
+  host?: string;
+  /** Database port (alternative to URL) */
+  port?: number;
+  /** Database name (alternative to URL) */
+  database?: string;
+  /** Database user (alternative to URL) */
+  user?: string;
+  /** Database password (alternative to URL) */
+  password?: string;
+  /** Connection pool configuration */
+  pool?: PoolConfig;
+  /** Logger instance for queries and errors */
+  logger?: AdapterLogger;
+  /**
+   * Schema name (PostgreSQL only).
+   *
+   * Applied as `search_path` in the pool's startup options, which is the
+   * pooled-safe way to set it: a `SET search_path` issued as a query belongs
+   * to whichever pooled connection happened to run it, so the next checkout
+   * would see the default again.
+   *
+   * The adapter creates the schema if it is missing, because `search_path`
+   * naming a schema that does not exist does not fail — it falls through, and
+   * the tables land somewhere else.
+   *
+   * Declared here since the first release and read by nothing until now, which
+   * is why setting it appeared to work and changed nothing.
+   */
+  schema?: string;
+  /** SSL/TLS configuration */
+  ssl?: SslConfig | boolean;
+  /**
+   * Default query timeout in milliseconds.
+   *
+   * @remarks
+   * Queries exceeding this limit will be aborted and throw a DatabaseError
+   * with kind 'timeout'. This prevents runaway queries from blocking the
+   * system indefinitely.
+   *
+   * Can be overridden per-transaction via TransactionOptions.timeoutMs.
+   *
+   * Set to 0 or undefined to disable timeout (not recommended for production).
+   *
+   * @default 15000 (15 seconds)
+   *
+   * @example
+   * ```typescript
+   * const adapter = createPostgresAdapter({
+   *   url: 'postgres://localhost/mydb',
+   *   queryTimeoutMs: 30000, // 30 seconds
+   * });
+   * ```
+   */
+  queryTimeoutMs?: number;
+  /** Additional connection options (driver-specific) */
+  options?: Record<string, unknown>;
+}
+/**
+ * PostgreSQL-specific adapter configuration.
+ *
+ * @public
+ */
+interface PostgresAdapterConfig extends BaseAdapterConfig {
+  /** Application name for connection tracking */
+  applicationName?: string;
+  /** Statement timeout in milliseconds */
+  statementTimeout?: number;
+  /** Query timeout in milliseconds */
+  queryTimeout?: number;
+  /** Enable prepared statements (default: true) */
+  preparedStatements?: boolean;
+}
+/**
+ * MySQL-specific adapter configuration.
+ *
+ * @public
+ */
+interface MySqlAdapterConfig extends BaseAdapterConfig {
+  /** Character set (default: utf8mb4) */
+  charset?: string;
+  /** Timezone (default: 'local') */
+  timezone?: string;
+  /** Enable multiple statements per query (default: false, security risk) */
+  multipleStatements?: boolean;
+  /** Date strings instead of Date objects (default: false) */
+  dateStrings?: boolean;
+}
+/**
+ * SQLite-specific adapter configuration.
+ *
+ * @public
+ */
+interface SqliteAdapterConfig extends BaseAdapterConfig {
+  /** Enable WAL mode (default: true) */
+  wal?: boolean;
+  /** Busy timeout in milliseconds (default: 5000) */
+  busyTimeout?: number;
+  /** Enable foreign keys (default: true) */
+  foreignKeys?: boolean;
+  /** Memory-only database (overrides url) */
+  memory?: boolean;
+  /** Read-only mode (default: false) */
+  readonly?: boolean;
+}
+export { UpdateOptions as A, TransactionContext as C, DeleteOptions as D, CountOptions as E, WhereClause as F, WhereCondition as I, WhereOperator as L, JoinSpec as M, OrderBySpec as N, InsertOptions as O, WHERE_OPERATORS as P, PoolStats as S, TransactionOptions as T, MigrationOptions as _, PostgresAdapterConfig as a, MigrationStatus as b, DatabaseError as c, POOL_WAIT_TIMEOUT_CODE as d, createDatabaseError as f, Migration as g, poolWaitTimeoutError as h, PoolConfig as i, UpsertOptions as j, SelectOptions as k, DatabaseErrorKind as l, isDatabaseError as m, BaseAdapterConfig as n, SqliteAdapterConfig as o, isApplicationError as p, MySqlAdapterConfig as r, SslConfig as s, AdapterLogger as t, DatabaseErrorOptions as u, MigrationRecord as v, TransactionIsolationLevel as w, DatabaseCapabilities as x, MigrationResult as y };
+//# sourceMappingURL=index-BYb6cDli.d.ts.map