@spfn/core 0.2.0-beta.9 → 0.3.0-beta.10

package/dist/db/index.d.ts

@@ -1,12 +1,48 @@
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import postgres, { Sql } from 'postgres';
-import * as drizzle_orm from 'drizzle-orm';
-import { SQL } from 'drizzle-orm';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
-import { PgColumn, PgTable } from 'drizzle-orm/pg-core';
+import { PgAsyncDatabase, PgAsyncTransaction, PgColumn, PgTable } from 'drizzle-orm/pg-core';
+import * as drizzle_orm from 'drizzle-orm';
+import { SQL, InferSelectModel, InferInsertModel, AnyRelations, EmptyRelations } from 'drizzle-orm';
 import * as hono_types from 'hono/types';
 import { DatabaseError } from '@spfn/core/errors';
 
+/**
+ * Database Manager Types
+ */
+
+/**
+ * DB connection type
+ */
+type DbConnectionType = 'read' | 'write';
+/**
+ * Common base for PostgreSQL Drizzle drivers.
+ *
+ * Both the built-in postgres.js database and externally supplied drivers such
+ * as PGlite extend this class.
+ */
+type DrizzleDatabase = PgAsyncDatabase<any, any>;
+/** Default database type used by the environment-backed postgres.js path. */
+type DefaultDatabase = PostgresJsDatabase;
+/** Resolve the transaction type belonging to a PostgreSQL Drizzle database. */
+type DatabaseTransaction<TDatabase extends DrizzleDatabase> = TDatabase extends PgAsyncDatabase<infer TQueryResult, infer TRelations> ? PgAsyncTransaction<TQueryResult, TRelations> : never;
+/**
+ * An externally owned PostgreSQL Drizzle database.
+ *
+ * The provider owns connection creation. SPFN calls `close` at most once when
+ * `closeDatabase()` or server shutdown releases the registered provider.
+ */
+interface DatabaseProvider<TDatabase extends DrizzleDatabase = DrizzleDatabase> {
+    /** Primary database for writes (and reads when no replica is supplied). */
+    write: TDatabase;
+    /** Optional read replica. Falls back to `write`. */
+    read?: TDatabase;
+    /** Driver identifier used for diagnostics, for example `pglite`. */
+    kind: string;
+    /** Release provider-owned resources. */
+    close?: () => void | Promise<void>;
+}
+
 /**
  * Database Configuration
  *
@@ -23,11 +59,11 @@ import { DatabaseError } from '@spfn/core/errors';
  * - src/server/core/db/index.ts (main exports)
  */
 
-interface DatabaseClients {
+interface DatabaseClients<TDatabase extends DrizzleDatabase = PostgresJsDatabase> {
     /** Primary database for writes (or both read/write if no replica) */
-    write?: PostgresJsDatabase;
+    write?: TDatabase;
     /** Replica database for reads (optional, falls back to write) */
-    read?: PostgresJsDatabase;
+    read?: TDatabase;
     /** Raw postgres client for write operations (for cleanup) */
     writeClient?: Sql;
     /** Raw postgres client for read operations (for cleanup) */
@@ -71,6 +107,17 @@ interface DatabaseOptions {
      */
     monitoring?: Partial<MonitoringConfig>;
 }
+/** Database initialization options, including an optional external provider. */
+interface DatabaseInitOptions<TDatabase extends DrizzleDatabase = PostgresJsDatabase> extends DatabaseOptions {
+    /**
+     * Externally owned PostgreSQL Drizzle provider.
+     *
+     * When set, environment-based postgres.js initialization, health checks,
+     * and automatic reconnect are skipped. The provider's `close` callback is
+     * used during shutdown.
+     */
+    provider?: DatabaseProvider<TDatabase>;
+}
 /**
  * Connection pool configuration
  *
@@ -81,6 +128,21 @@ interface PoolConfig {
     max: number;
     /** Idle connection timeout in seconds */
     idleTimeout: number;
+    /**
+     * Maximum connections for the read-replica pool. Defaults to `max`. Set
+     * separately (DB_POOL_READ_MAX) so a master-replica app can size the two
+     * pools independently and keep `write.max + read.max` under the server's
+     * `max_connections` (otherwise each process opens up to 2 × max).
+     */
+    readMax?: number;
+    /**
+     * Use server-side prepared statements (postgres-js `prepare`). When
+     * `undefined`, the connection layer auto-detects: it is disabled for
+     * transaction-mode poolers (PgBouncer/Supavisor, e.g. Supabase :6543),
+     * where cached statements break as the pooler rotates backends, and
+     * enabled otherwise. Set explicitly (or via `SPFN_DB_PREPARE`) to override.
+     */
+    prepare?: boolean;
 }
 /**
  * Retry configuration for exponential backoff algorithm
@@ -134,15 +196,6 @@ interface RetryConfig {
  */
 declare function createDatabaseFromEnv(options?: DatabaseOptions): Promise<DatabaseClients>;
 
-/**
- * Database Manager Types
- */
-
-/**
- * DB connection type
- */
-type DbConnectionType = 'read' | 'write';
-
 /**
  * Global Database instance manager
  * Provides singleton access to database across all modules
@@ -169,7 +222,7 @@ type DbConnectionType = 'read' | 'write';
  * const posts = await dbRead.select().from(postsTable);
  * ```
  */
-declare function getDatabase(type?: DbConnectionType): PostgresJsDatabase<Record<string, unknown>>;
+declare function getDatabase<TDatabase extends DrizzleDatabase = DefaultDatabase>(type?: DbConnectionType): TDatabase;
 /**
  * Set global database instances (for testing or manual configuration)
  *
@@ -193,15 +246,23 @@ declare function getDatabase(type?: DbConnectionType): PostgresJsDatabase<Record
  * // Set custom database instances (testing)
  * const writeClient = postgres('postgresql://primary:5432/mydb');
  * const readClient = postgres('postgresql://replica:5432/mydb');
- * setDatabase(drizzle(writeClient), drizzle(readClient));
+ * setDatabase(drizzle({ client: writeClient }), drizzle({ client: readClient }));
  *
  * // Clear instances (not recommended - use closeDatabase() instead)
  * setDatabase(undefined, undefined);
  * ```
  */
-declare function setDatabase(write: PostgresJsDatabase<Record<string, unknown>> | undefined, read?: PostgresJsDatabase<Record<string, unknown>> | undefined): void;
+declare function setDatabase<TDatabase extends DrizzleDatabase = DefaultDatabase>(write: TDatabase | undefined, read?: TDatabase | undefined): void;
 /**
- * Initialize database from environment variables
+ * Register an externally owned PostgreSQL Drizzle provider.
+ *
+ * This is the synchronous/manual counterpart to `initDatabase({ provider })`.
+ * It performs no connection test. Use `closeDatabase()` to invoke the
+ * provider's close callback and clear the global instances.
+ */
+declare function setDatabaseProvider<TDatabase extends DrizzleDatabase>(provider: DatabaseProvider<TDatabase>): DatabaseClients<TDatabase>;
+/**
+ * Initialize a database provider or create postgres.js clients from environment variables
  * Automatically called by server startup
  *
  * Supported environment variables:
@@ -246,14 +307,11 @@ declare function setDatabase(write: PostgresJsDatabase<Record<string, unknown>>
  * });
  * ```
  */
-declare function initDatabase(options?: DatabaseOptions): Promise<{
-    write?: PostgresJsDatabase<Record<string, unknown>>;
-    read?: PostgresJsDatabase<Record<string, unknown>>;
-}>;
+declare function initDatabase<TDatabase extends DrizzleDatabase = DefaultDatabase>(options?: DatabaseInitOptions<TDatabase>): Promise<DatabaseClients<TDatabase>>;
 /**
- * Close all database connections and cleanup
+ * Close the active database provider or postgres.js connections and clean up
  *
- * Properly closes postgres connection pools with timeout.
+ * Invokes an external provider's close callback, or closes postgres.js pools with timeout.
  * Should be called during graceful shutdown or after tests.
  *
  * @example
@@ -273,6 +331,36 @@ declare function initDatabase(options?: DatabaseOptions): Promise<{
  * ```
  */
 declare function closeDatabase(): Promise<void>;
+/**
+ * Force an immediate database pool rebuild
+ *
+ * Destroys the current postgres.js pool(s) and rebuilds them with the same
+ * configuration passed to the original `initDatabase()` call (or whatever
+ * was detected from environment variables). Uses the same atomic-swap
+ * strategy as the periodic health check: new connections are created and
+ * tested BEFORE the old ones are torn down, so `getDatabase()` callers never
+ * observe a missing instance.
+ *
+ * Use this when application code detects that the pool is stuck and does not
+ * want to wait for the next periodic health check tick. Concurrent calls are
+ * coalesced — if a reconnect is already in progress, this resolves to `false`
+ * without starting a second one.
+ *
+ * @param reason - Short label describing why the rebuild was requested (for logs)
+ * @returns `true` if a reconnection ran, `false` if one was already in-flight.
+ *          Resolves after the rebuild completes (success or max retries exhausted).
+ *
+ * @example
+ * ```typescript
+ * import { forceReconnectDatabase } from '@spfn/core/db';
+ *
+ * app.post('/admin/db/reconnect', async (c) => {
+ *     const ran = await forceReconnectDatabase('admin_request');
+ *     return c.json({ reconnected: ran });
+ * });
+ * ```
+ */
+declare function forceReconnectDatabase(reason?: string): Promise<boolean>;
 /**
  * Get database connection info (for debugging)
  *
@@ -306,8 +394,42 @@ declare function getDatabaseInfo(): {
     hasWrite: boolean;
     hasRead: boolean;
     isReplica: boolean;
+    providerKind?: string;
 };
 
+/**
+ * Determine whether an error looks like a pool/connection failure
+ *
+ * Returns true when any layer in the error chain exposes a connection-level
+ * code (postgres.js driver code, Node network errno, PG SQLSTATE class 08 etc.)
+ * or is an instance of our own ConnectionError wrapper.
+ *
+ * Returns false for query errors (syntax, constraint violations, etc.) — those
+ * should NOT trigger a pool rebuild.
+ */
+declare function isConnectionLevelError(error: unknown): boolean;
+/**
+ * Reset the internal error counter
+ *
+ * Exposed for tests that need a clean slate between cases. Does not clear
+ * the WeakSet (which is GC-backed and self-cleans with error lifetimes).
+ */
+declare function resetConnectionErrorCounter(): void;
+/**
+ * Report a database error to the reconnect trigger
+ *
+ * Call this from any site that catches a query error before rethrowing.
+ * It is a no-op for non-connection-level errors. When the threshold is
+ * crossed it calls triggerForceReconnect() in the background — callers
+ * should NOT await it.
+ *
+ * Safe to call from any context: catches its own errors so it cannot
+ * disrupt the calling catch block. Deduplicates across error-chain
+ * re-wrapping so one failure counts exactly once regardless of how many
+ * catch layers it passes through.
+ */
+declare function reportDatabaseError(error: unknown): void;
+
 /**
  * Create database connection with exponential backoff retry strategy
  *
@@ -362,7 +484,7 @@ declare function checkConnection(client: Sql): Promise<boolean>;
 interface DrizzleConfigOptions {
     /** Database connection URL (defaults to process.env.DATABASE_URL) */
     databaseUrl?: string;
-    /** Schema files glob pattern or array of patterns (defaults to './src/server/entities/\*\*\/*.ts') */
+    /** Schema entry file(s), directories or glob pattern(s). Default: './src/server/entities/\*\*\/*.ts', or the registry `DRIZZLE_SCHEMA_PATH` (./src/server/entities/config.ts) when that scan finds no entity file; `schemaRegistry` reports the registry when both exist */
     schema?: string | string[];
     /** Migration output directory (defaults to './src/server/drizzle') */
     out?: string;
@@ -378,8 +500,8 @@ interface DrizzleConfigOptions {
     expandGlobs?: boolean;
     /** PostgreSQL schema filter for push/introspect commands */
     schemaFilter?: string[];
-    /** Auto-detect PostgreSQL schemas from entity files (requires expandGlobs: true) */
-    autoDetectSchemas?: boolean;
+    /** Migration prefix strategy (default: 'timestamp') */
+    migrationPrefix?: 'index' | 'timestamp' | 'unix' | 'none';
 }
 /**
  * Detect database dialect from connection URL
@@ -406,26 +528,55 @@ declare function detectDialect(url: string): 'postgresql' | 'mysql' | 'sqlite';
  */
 declare function getDrizzleConfig(options?: DrizzleConfigOptions): {
     schema: string | string[];
+    schemaSource: string;
+    schemaRegistry: string | undefined;
     out: string;
     dialect: "postgresql" | "mysql" | "sqlite";
     dbCredentials: {
         url: string;
     };
+    migrations: {
+        prefix: "timestamp" | "none" | "index" | "unix";
+    };
     schemaFilter?: undefined;
 } | {
     schema: string | string[];
+    schemaSource: string;
+    schemaRegistry: string | undefined;
     out: string;
     dialect: "postgresql" | "mysql" | "sqlite";
     dbCredentials: {
         url: string;
     };
     schemaFilter: string[] | undefined;
+    migrations: {
+        prefix: "timestamp" | "none" | "index" | "unix";
+    };
 };
 /**
- * Generate drizzle.config.ts file content
+ * The schema fields a rendered drizzle.config.ts needs
+ */
+interface RenderableDrizzleConfig {
+    schema: string | string[];
+    out: string;
+    dialect: string;
+    dbCredentials: Record<string, unknown>;
+    schemaFilter?: string[];
+    migrations?: Record<string, unknown>;
+}
+/**
+ * Render an already-resolved config as drizzle.config.ts source, schema
+ * paths made absolute for Drizzle Studio
  *
- * @param options - Configuration options
- * @returns File content as string
+ * @param config - Result of getDrizzleConfig, possibly with the schema replaced
+ * @param cwd - Base for relative schema paths (default: process.cwd())
+ */
+declare function renderDrizzleConfig(config: RenderableDrizzleConfig, cwd?: string): string;
+/**
+ * Generate drizzle.config.ts source from options: resolve the config, then render it
+ *
+ * @param options - Configuration options (see getDrizzleConfig)
+ * @returns drizzle.config.ts source
  */
 declare function generateDrizzleConfigFile(options?: DrizzleConfigOptions): string;
 
@@ -442,12 +593,23 @@ declare function generateDrizzleConfigFile(options?: DrizzleConfigOptions): stri
  * });
  * ```
  */
-declare function id(): drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_orm_pg_core.PgBigSerial53BuilderInitial<"id">>>;
+declare function id(): drizzle_orm_pg_core.SetIsPrimaryKey<drizzle_orm_pg_core.PgBigSerial53Builder>;
 /**
  * Standard timestamp fields (createdAt, updatedAt)
  *
- * Both fields are timezone-aware, auto-set to current time on creation.
- * updatedAt must be manually updated in your application code.
+ * Both fields are timezone-aware and come from the database clock, never from the
+ * application process. On insert both take `now()` through their column default, so a
+ * new row's two timestamps are equal. On update Drizzle sets `updated_at = now()` for
+ * you — do not pass `new Date()` yourself.
+ *
+ * Stamping `updated_at` from the application would read a second clock: the app host
+ * and the database host are the same machine in development and different machines in
+ * production, so a row could record an update earlier than its own creation, and
+ * ordering rows by `updated_at` would order by whichever host's clock ran ahead.
+ *
+ * `now()` is the transaction's start time, matching what `.defaultNow()` writes. It is
+ * not a commit-order sequence — anything that needs a true sequence needs a sequence
+ * column, not a timestamp.
  *
  * @returns Object with createdAt and updatedAt columns
  *
@@ -459,23 +621,20 @@ declare function id(): drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_orm_
  *     ...timestamps(),
  * });
  *
- * // Manual update
+ * // updated_at is stamped by the database — it is not named here
  * await db.update(users)
- *     .set({
- *         email: 'new@example.com',
- *         updatedAt: new Date()
- *     })
+ *     .set({ email: 'new@example.com' })
  *     .where(eq(users.id, userId));
  * ```
  */
 declare function timestamps(): {
-    createdAt: drizzle_orm.NotNull<drizzle_orm.HasDefault<drizzle_orm_pg_core.PgTimestampBuilderInitial<"created_at">>>;
-    updatedAt: drizzle_orm.NotNull<drizzle_orm.HasDefault<drizzle_orm_pg_core.PgTimestampBuilderInitial<"updated_at">>>;
+    createdAt: drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgTimestampBuilder>>;
+    updatedAt: drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgTimestampBuilder>>>;
 };
 /**
  * Foreign key reference to another table
  *
- * Creates a bigserial column with cascade delete.
+ * Creates a bigint column with cascade delete.
  * Type-safe: ensures the reference points to a valid PostgreSQL column.
  *
  * @param name - Column name (e.g., 'author' creates 'author_id')
@@ -495,7 +654,7 @@ declare function timestamps(): {
  */
 declare function foreignKey<T extends PgColumn>(name: string, reference: () => T, options?: {
     onDelete?: 'cascade' | 'set null' | 'restrict' | 'no action';
-}): drizzle_orm.NotNull<drizzle_orm_pg_core.PgBigSerial53BuilderInitial<`${string}_id`>>;
+}): drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgBigInt53Builder>;
 /**
  * Optional foreign key reference (nullable)
  *
@@ -515,7 +674,7 @@ declare function foreignKey<T extends PgColumn>(name: string, reference: () => T
  */
 declare function optionalForeignKey<T extends PgColumn>(name: string, reference: () => T, options?: {
     onDelete?: 'cascade' | 'set null' | 'restrict' | 'no action';
-}): drizzle_orm_pg_core.PgBigSerial53BuilderInitial<`${string}_id`>;
+}): drizzle_orm_pg_core.PgBigInt53Builder;
 /**
  * UUID primary key
  *
@@ -533,7 +692,7 @@ declare function optionalForeignKey<T extends PgColumn>(name: string, reference:
  * });
  * ```
  */
-declare function uuid(): drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_orm.HasDefault<drizzle_orm_pg_core.PgUUIDBuilderInitial<"id">>>>;
+declare function uuid(): drizzle_orm_pg_core.SetIsPrimaryKey<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgUUIDBuilder>>;
 /**
  * Audit fields for tracking record creators and updaters
  *
@@ -559,8 +718,8 @@ declare function uuid(): drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_or
  * ```
  */
 declare function auditFields(): {
-    createdBy: drizzle_orm_pg_core.PgTextBuilderInitial<"created_by", [string, ...string[]]>;
-    updatedBy: drizzle_orm_pg_core.PgTextBuilderInitial<"updated_by", [string, ...string[]]>;
+    createdBy: drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>;
+    updatedBy: drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>;
 };
 /**
  * Publishing fields for content management
@@ -591,8 +750,8 @@ declare function auditFields(): {
  * ```
  */
 declare function publishingFields(): {
-    publishedAt: drizzle_orm_pg_core.PgTimestampBuilderInitial<"published_at">;
-    publishedBy: drizzle_orm_pg_core.PgTextBuilderInitial<"published_by", [string, ...string[]]>;
+    publishedAt: drizzle_orm_pg_core.PgTimestampBuilder;
+    publishedBy: drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>;
 };
 /**
  * Custom verification timestamp field
@@ -621,7 +780,7 @@ declare function publishingFields(): {
  * ```
  */
 declare function verificationTimestamp(fieldName: string): {
-    [x: string]: drizzle_orm_pg_core.PgTimestampBuilderInitial<string>;
+    [x: string]: drizzle_orm_pg_core.PgTimestampBuilder;
 };
 /**
  * Soft delete fields
@@ -655,8 +814,8 @@ declare function verificationTimestamp(fieldName: string): {
  * ```
  */
 declare function softDelete(): {
-    deletedAt: drizzle_orm_pg_core.PgTimestampBuilderInitial<"deleted_at">;
-    deletedBy: drizzle_orm_pg_core.PgTextBuilderInitial<"deleted_by", [string, ...string[]]>;
+    deletedAt: drizzle_orm_pg_core.PgTimestampBuilder;
+    deletedBy: drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>;
 };
 /**
  * UTC timestamp field
@@ -688,7 +847,7 @@ declare function softDelete(): {
  * });
  * ```
  */
-declare function utcTimestamp(fieldName: string, mode?: 'date' | 'string'): drizzle_orm_pg_core.PgTimestampBuilderInitial<string>;
+declare function utcTimestamp(fieldName: string, mode?: 'date' | 'string'): drizzle_orm_pg_core.PgTimestampBuilder;
 /**
  * Type-safe enum text field
  *
@@ -722,7 +881,7 @@ declare function utcTimestamp(fieldName: string, mode?: 'date' | 'string'): driz
  * });
  * ```
  */
-declare function enumText<T extends readonly [string, ...string[]]>(fieldName: string, values: T): drizzle_orm_pg_core.PgTextBuilderInitial<string, drizzle_orm.Writable<T & [string, ...string[]]>>;
+declare function enumText<T extends readonly [string, ...string[]]>(fieldName: string, values: T): drizzle_orm_pg_core.PgTextBuilder<drizzle_orm.Writable<T & [string, ...string[]]>>;
 /**
  * Type-safe JSONB field
  *
@@ -765,7 +924,7 @@ declare function enumText<T extends readonly [string, ...string[]]>(fieldName: s
  * tags: typedJsonb<string[]>('tags').notNull(),
  * ```
  */
-declare function typedJsonb<T>(fieldName: string): drizzle_orm.$Type<drizzle_orm_pg_core.PgJsonbBuilderInitial<string>, T>;
+declare function typedJsonb<T>(fieldName: string): drizzle_orm_pg_core.Set$Type<drizzle_orm_pg_core.PgJsonbBuilder, T>;
 
 /**
  * Database Schema Helper
@@ -828,6 +987,137 @@ declare function getSchemaInfo(packageName: string): {
     scope: string | null;
 };
 
+/**
+ * Function Package Migration Discovery
+ *
+ * Finds the migrations shipped by installed SPFN function packages (e.g.
+ * `@spfn/auth`) and reads their entries. Both drizzle-kit layouts are
+ * supported — `NNNN_name.sql` + `meta/_journal.json` (≤0.31) and
+ * `<YYYYMMDDHHMMSS>_name/migration.sql` (1.0) — so an installed package keeps
+ * working regardless of which drizzle-kit generated it.
+ *
+ * This module only reads the filesystem. Applying migrations is the CLI's job
+ * (`spfn db migrate`); the server and `spfn db status` share the reading half.
+ */
+type FunctionMigrationInfo = {
+    packageName: string;
+    migrationsDir: string;
+    packagePath: string;
+};
+type FunctionMigrationEntry = {
+    name: string;
+    statements: string[];
+    hash: string;
+    millis: number;
+};
+/**
+ * Per-package migrations table name — must match the CLI's migration runner.
+ */
+declare function functionMigrationsTable(packageName: string): string;
+/**
+ * Discover all installed SPFN function packages that ship migrations.
+ *
+ * A package opts in with a `spfn.migrations.dir` field in its package.json.
+ * Returns an empty list when the project has no `node_modules/@spfn` at all,
+ * which is also the "nothing to check" answer for apps without function packages.
+ */
+declare function discoverFunctionMigrations(cwd?: string): FunctionMigrationInfo[];
+/**
+ * Read a package's migration entries, auto-detecting the folder layout.
+ *
+ * A `meta/_journal.json` marks the drizzle-kit ≤0.31 layout; without it the
+ * directory is read as the drizzle-kit 1.0 layout.
+ */
+declare function readMigrationEntries(migrationsDir: string, packageName: string): FunctionMigrationEntry[];
+
+/**
+ * Migration Status Inspection
+ *
+ * Compares what each migration folder ships (function packages, plus the
+ * project's own `src/server/drizzle`) against what the database records as
+ * applied. `spfn db status`, the server's boot gate and the detailed health
+ * endpoint all read this one implementation.
+ */
+
+/**
+ * Project migrations use drizzle's default table, in the `drizzle` schema.
+ */
+declare const PROJECT_MIGRATIONS_TABLE = "__drizzle_migrations";
+/**
+ * The name `spfn db status` and health use for the project's own migrations.
+ */
+declare const PROJECT_TARGET_NAME = "project (src/server/drizzle)";
+type MigrationTargetStatus = {
+    name: string;
+    total: number;
+    applied: number;
+    pending: number;
+    pendingTags: string[];
+};
+type MigrationStatus = {
+    packages: MigrationTargetStatus[];
+    project: MigrationTargetStatus | null;
+};
+/**
+ * The minimum surface needed to read migration bookkeeping: anything that can
+ * run a drizzle `sql` fragment. The server passes its own pool, the CLI passes
+ * a short-lived connection.
+ */
+interface MigrationStatusDb {
+    execute(query: SQL): Promise<unknown>;
+}
+/**
+ * An entry counts as applied when its name is recorded (drizzle-orm 1.0
+ * projects) or its timestamp is not newer than the last applied record —
+ * the rule the CLI's function-migration runner and drizzle-orm ≤0.45 share.
+ */
+declare function filterPendingEntries(entries: FunctionMigrationEntry[], lastAppliedMillis: number, appliedNames: Set<string>): FunctionMigrationEntry[];
+/**
+ * Every target the status covers, packages first, in the order `spfn db status`
+ * prints them.
+ */
+declare function migrationTargets(status: MigrationStatus): MigrationTargetStatus[];
+/**
+ * The targets that still have migrations waiting.
+ */
+declare function pendingMigrationTargets(status: MigrationStatus): MigrationTargetStatus[];
+/**
+ * Total number of migrations waiting across every target.
+ */
+declare function countPendingMigrations(status: MigrationStatus): number;
+/**
+ * True when the project has nothing whose migration state could be inspected —
+ * no function package ships migrations and there is no project migrations
+ * folder. Callers use this to skip the database round-trip entirely.
+ */
+declare function hasMigrationTargets(cwd?: string): boolean;
+declare function projectMigrationsDir(cwd?: string): string;
+/**
+ * Read applied/pending counts for every function package and for the project.
+ *
+ * The project's own migrations are included when `src/server/drizzle` exists.
+ * A built server image usually does not ship that folder, so the project target
+ * is simply absent there — never reported as drift.
+ */
+declare function collectMigrationStatus(db: MigrationStatusDb, cwd?: string): Promise<MigrationStatus>;
+
+/**
+ * One wording for pending migrations, shared by the server's boot gate and the
+ * CLI's pre-flight check — an operator should read the same lines wherever the
+ * refusal comes from.
+ */
+
+declare const RUN_MIGRATIONS_HINT = "Run: pnpm spfn db migrate";
+/**
+ * Plain (uncoloured) lines listing every target with pending migrations and the
+ * name of each migration still waiting.
+ */
+declare function formatPendingMigrations(targets: MigrationTargetStatus[]): string[];
+/**
+ * The single-sentence reason a boot was refused.
+ */
+declare function pendingMigrationsSummary(targets: MigrationTargetStatus[]): string;
+
 /**
  * AsyncLocalStorage-based Transaction Context
  *
@@ -842,26 +1132,60 @@ declare function getSchemaInfo(packageName: string): {
  */
 
 /**
- * Transaction database type
- * Uses Record<string, unknown> to accept any schema shape
+ * Transaction type belonging to a PostgreSQL Drizzle database.
+ */
+type TransactionDB<TDatabase extends DrizzleDatabase = DefaultDatabase> = DatabaseTransaction<TDatabase>;
+/**
+ * afterCommit callback type
+ */
+type AfterCommitCallback = () => void | Promise<void>;
+/**
+ * beforeCommit callback type
+ */
+type BeforeCommitCallback = () => void | Promise<void>;
+/**
+ * afterRollback callback type
+ */
+type AfterRollbackCallback = () => void | Promise<void>;
+/**
+ * Serializes the savepoint frames opened directly off one transaction context
+ *
+ * @see createNestedFrameGate
  */
-type TransactionDB = PostgresJsDatabase<Record<string, unknown>>;
+type NestedFrameGate = {
+    /** Run `frame` once every frame queued before it on this context has finished */
+    run<T>(frame: () => Promise<T>): Promise<T>;
+};
 /**
  * Transaction context stored in AsyncLocalStorage
  */
-type TransactionContext = {
+type TransactionContext<TDatabase extends DrizzleDatabase = DrizzleDatabase> = {
     /** The actual Drizzle transaction object */
-    tx: TransactionDB;
+    tx: TransactionDB<TDatabase>;
     /** Unique transaction ID for logging and tracing */
     txId: string;
     level: number;
+    /** Callbacks to execute before the root transaction commits (still inside it) */
+    beforeCommitCallbacks: BeforeCommitCallback[];
+    /** Callbacks to execute after root transaction commits */
+    afterCommitCallbacks: AfterCommitCallback[];
+    /** Callbacks to execute after the root transaction rolled back */
+    afterRollbackCallbacks: AfterRollbackCallback[];
+    /** Serializes the savepoint frames opened directly off THIS context */
+    nestedFrames: NestedFrameGate;
 };
+/**
+ * Get current transaction object and metadata from AsyncLocalStorage
+ *
+ * @returns TransactionContext if available, null otherwise
+ */
+declare function getTransactionContext<TDatabase extends DrizzleDatabase = DefaultDatabase>(): TransactionContext<TDatabase> | null;
 /**
  * Get current transaction from AsyncLocalStorage
  *
  * @returns Transaction if available, null otherwise
  */
-declare function getTransaction(): TransactionDB | null;
+declare function getTransaction<TDatabase extends DrizzleDatabase = DefaultDatabase>(): TransactionDB<TDatabase> | null;
 /**
  * Run a function within a transaction context
  *
@@ -873,8 +1197,104 @@ declare function getTransaction(): TransactionDB | null;
  * @param callback - Function to run within transaction context
  * @returns Result of the callback
  */
-declare function runWithTransaction<T>(tx: TransactionDB, txId: string, // Add txId parameter
+declare function runWithTransaction<T, TDatabase extends DrizzleDatabase = DefaultDatabase>(tx: TransactionDB<TDatabase>, txId: string, // Add txId parameter
 callback: () => Promise<T>): Promise<T>;
+/**
+ * Register a callback to run after the current transaction commits
+ *
+ * - Inside a transaction: queued and executed after root transaction commits
+ * - Outside a transaction: executed immediately (already "committed")
+ * - Nested transactions: callbacks bubble up to root transaction
+ * - Callbacks run outside transaction context (new connection for DB access)
+ * - Errors are logged but never thrown (commit already succeeded)
+ *
+ * @example
+ * ```typescript
+ * import { onAfterCommit } from '@spfn/core/db';
+ *
+ * async function submit(spaceId: string, chatId: string)
+ * {
+ *     const publication = await publicationRepo.create({...});
+ *     await requestRepo.updateStatusAtomically(...);
+ *
+ *     onAfterCommit(() => generateArticle(spaceId, chatId, publication.id));
+ *
+ *     return publication;
+ * }
+ * ```
+ */
+declare function onAfterCommit(callback: AfterCommitCallback): void;
+/**
+ * Register a callback to run just before the current transaction commits
+ *
+ * - Inside a transaction: queued and executed after the root callback resolves,
+ *   while the transaction is still open — the callback MAY run statements and
+ *   they are part of the same commit
+ * - Outside a transaction: executed immediately with a WARNING (same rationale as
+ *   onAfterCommit — there is nothing left to commit), and the abort semantics
+ *   below do not apply: there is no transaction for a throw to roll back
+ * - Nested transactions: callbacks bubble up to root transaction
+ * - Callbacks run in registration order, inside the transaction context
+ *   (getTransaction() returns the live tx)
+ * - The queue is snapshot before the pass, so a callback registered BY a
+ *   beforeCommit callback does not run for this commit — it would otherwise
+ *   grow the queue mid-iteration and loop forever inside the open transaction
+ * - A throw ABORTS: later callbacks are skipped, the transaction rolls back,
+ *   the error propagates to the caller, and afterRollback callbacks fire
+ *
+ * @example
+ * ```typescript
+ * import { runInTransaction, onBeforeCommit } from '@spfn/core/db';
+ *
+ * async function transfer(fromId: string, toId: string, amount: number)
+ * {
+ *     // The transaction is what gives the check teeth — registered outside one,
+ *     // the callback runs immediately and its throw aborts nothing.
+ *     await runInTransaction(async () =>
+ *     {
+ *         await accountRepo.debit(fromId, amount);
+ *         await accountRepo.credit(toId, amount);
+ *
+ *         // Last-moment invariant check: a throw here rolls the whole transfer back.
+ *         onBeforeCommit(() => assertNoNegativeBalance(fromId));
+ *     });
+ * }
+ * ```
+ */
+declare function onBeforeCommit(callback: BeforeCommitCallback): void;
+/**
+ * Register a callback to run after the current transaction rolled back
+ *
+ * - Inside a transaction: queued and executed after the ROOT transaction rolled
+ *   back, before the causing error leaves runInTransaction / the middleware
+ * - Outside a transaction: no-op with a warning — there is no rollback to wait for
+ * - Nested transactions: callbacks bubble up to root transaction. A nested
+ *   rollback that the root survives does NOT fire them; these hooks are about
+ *   the root transaction's fate, not a savepoint's
+ * - Callbacks run outside the transaction context (new connection for DB access)
+ * - Errors are logged but never thrown: the original error keeps propagating
+ *   unchanged, never replaced by a callback failure
+ *
+ * @example
+ * ```typescript
+ * import { runInTransaction, onAfterRollback } from '@spfn/core/db';
+ *
+ * async function importAvatar(userId: string, file: Blob)
+ * {
+ *     // Upload first: external I/O never belongs inside the transaction.
+ *     const key = await objectStore.put(file);
+ *
+ *     await runInTransaction(async () =>
+ *     {
+ *         await userRepo.updateAvatar(userId, key);
+ *
+ *         // The upload cannot roll back on its own — undo it if the write never lands.
+ *         onAfterRollback(() => objectStore.delete(key));
+ *     });
+ * }
+ * ```
+ */
+declare function onAfterRollback(callback: AfterRollbackCallback): void;
 
 /**
  * Transaction middleware options
@@ -910,6 +1330,30 @@ interface TransactionalOptions {
      * ```
      */
     timeout?: number;
+    /**
+     * Idle-in-transaction timeout in milliseconds — Postgres reclaims the pooled
+     * connection if the transaction sits idle (e.g. the handler awaits external
+     * I/O) longer than this. A backstop against pool starvation, not a license
+     * to do non-DB work inside a transaction. `0` disables it.
+     *
+     * @default 30000 (30s) or TRANSACTION_IDLE_TIMEOUT environment variable
+     */
+    idleTimeout?: number;
+    /**
+     * Run in an independent transaction instead of joining an ambient one.
+     *
+     * Only bites when the middleware itself runs nested — a sub-app mounted
+     * under a route that already applied `Transactional()`, or a handler invoked
+     * from inside `runInTransaction`. By default that inner run takes a SAVEPOINT
+     * on the outer transaction; `requiresNew: true` gives it a real `BEGIN` on a
+     * second pooled connection, with its own timeouts and its own hook queues.
+     *
+     * See `RunInTransactionOptions.requiresNew` for the pool and self-deadlock
+     * costs — they apply here unchanged.
+     *
+     * @default false
+     */
+    requiresNew?: boolean;
 }
 /**
  * Transaction middleware for Hono routes
@@ -947,6 +1391,9 @@ interface TransactionalOptions {
  * - Success: Auto-commit
  * - Error: Auto-rollback
  * - Detects context.error to trigger rollback
+ * - Hooks: this delegates to runInTransaction, so onBeforeCommit, onAfterCommit
+ *   and onAfterRollback behave exactly as they do there. afterRollback callbacks
+ *   have already run by the time the error reaches the conversion below.
  *
  * 📊 Transaction logging:
  * - Auto-logs transaction start/commit/rollback
@@ -955,6 +1402,148 @@ interface TransactionalOptions {
  */
 declare function Transactional(options?: TransactionalOptions): hono_types.MiddlewareHandler<any, string, {}, Response>;
 
+/**
+ * Transaction runner options
+ */
+interface RunInTransactionOptions {
+    /**
+     * Slow transaction warning threshold in milliseconds
+     * @default 1000 (1 second)
+     */
+    slowThreshold?: number;
+    /**
+     * Enable transaction logging
+     * @default true
+     */
+    enableLogging?: boolean;
+    /**
+     * Transaction timeout in milliseconds
+     *
+     * Sets PostgreSQL `statement_timeout` to enforce database-level timeout.
+     * If transaction exceeds this duration, PostgreSQL will automatically cancel
+     * the query and rollback the transaction, ensuring data consistency.
+     *
+     * Behavior:
+     * - `timeout: 0` - Disables timeout (unlimited execution time)
+     * - `timeout: null` - Uses default (30s or TRANSACTION_TIMEOUT env var)
+     * - `timeout: undefined` - Uses default (30s or TRANSACTION_TIMEOUT env var)
+     * - `timeout: N` - Sets timeout to N milliseconds (1 to 2147483647)
+     *
+     * Note: Timeout is only applied to root transactions. A nested call takes a
+     * SAVEPOINT on the outer transaction's connection, where the outer
+     * transaction's `SET LOCAL statement_timeout` is already in force — so the
+     * nested call genuinely inherits it, and its own `timeout` is ignored (a
+     * warning is logged when the caller passed one explicitly). A
+     * `requiresNew: true` call is a root and gets its own.
+     *
+     * @default 30000 (30 seconds) or TRANSACTION_TIMEOUT environment variable
+     *
+     * @example
+     * ```typescript
+     * // Use default timeout (30s)
+     * await runInTransaction(callback);
+     *
+     * // Disable timeout for long-running operations
+     * await runInTransaction(callback, { timeout: 0 });
+     *
+     * // Set custom timeout (60s)
+     * await runInTransaction(callback, { timeout: 60000 });
+     * ```
+     */
+    timeout?: number;
+    /**
+     * Idle-in-transaction timeout in milliseconds (root transactions only).
+     *
+     * Sets PostgreSQL `idle_in_transaction_session_timeout`: if the transaction
+     * sits open without running a query for longer than this — e.g. while the
+     * handler awaits external I/O inside the transaction — Postgres terminates
+     * the session and rolls back, reclaiming the pooled connection instead of
+     * letting one stuck request hold it (and its row locks) indefinitely.
+     *
+     * Do not put external I/O inside a transaction; this is a backstop, not a
+     * license. `0` disables it.
+     *
+     * @default 30000 (30s) or TRANSACTION_IDLE_TIMEOUT environment variable
+     */
+    idleTimeout?: number;
+    /**
+     * Context string for logging (e.g., 'migration:add-user', 'script:cleanup')
+     * @default 'transaction'
+     */
+    context?: string;
+    /**
+     * Run in an independent transaction instead of joining an ambient one.
+     *
+     * By default a call made while another transaction is open takes a SAVEPOINT
+     * on that transaction's connection: its writes commit or roll back with the
+     * outer transaction. `requiresNew: true` opens a real `BEGIN` on a SECOND
+     * pooled connection instead, so the work commits on its own and survives an
+     * outer rollback — an audit trail or a failed-attempt record, for example.
+     *
+     * Being a root transaction, it gets its own `statement_timeout`,
+     * `idle_in_transaction_session_timeout`, and its OWN hook queues:
+     * `onBeforeCommit` / `onAfterCommit` / `onAfterRollback` registered inside it
+     * fire on ITS outcome, not the outer transaction's.
+     *
+     * Two costs, both consequences of the second connection:
+     * - It holds a second connection for its whole duration, so it counts twice
+     *   against the pool. Keep it short and don't fan it out.
+     * - It cannot see the outer transaction's uncommitted writes, and it BLOCKS
+     *   on any row the outer transaction has locked. Since the outer transaction
+     *   is waiting for this call to return, that block is a self-deadlock that
+     *   only `statement_timeout` breaks. Never touch rows the outer transaction
+     *   wrote.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * await runInTransaction(async () =>
+     * {
+     *     await orderRepo.create(order);
+     *
+     *     // Lands even if the order below rolls the outer transaction back.
+     *     await runInTransaction(
+     *         () => auditRepo.record('order.attempted', order.id),
+     *         { requiresNew: true },
+     *     );
+     *
+     *     await inventoryRepo.reserve(order.items);   // may throw
+     * });
+     * ```
+     */
+    requiresNew?: boolean;
+}
+/**
+ * Run a callback function within a database transaction
+ *
+ * Automatically manages transaction lifecycle:
+ * - Commits on success
+ * - Rolls back on error
+ * - Tracks execution time
+ * - Warns about slow transactions
+ * - Enforces timeout if configured
+ *
+ * Called with a transaction already open on the async call chain, it takes a
+ * SAVEPOINT on that transaction rather than opening an independent one: the work
+ * runs on the same connection, sees the outer transaction's uncommitted writes,
+ * and commits with it. A throw that the caller catches unwinds to the SAVEPOINT
+ * and leaves the outer transaction healthy; a throw that propagates rolls the
+ * whole thing back. Nested calls off one transaction are serialized — see
+ * `openTransaction` — so `Promise.all` over them runs them one at a time. Pass
+ * `requiresNew: true` for an independent transaction on its own connection.
+ *
+ * Errors are propagated to the caller without modification.
+ * Caller is responsible for error handling and conversion.
+ *
+ * @param callback - Function to execute within transaction
+ * @param options - Transaction options
+ * @returns Result of callback function
+ * @throws TransactionError if database not initialized or timeout exceeded
+ * @throws Any error thrown by callback function
+ */
+declare function runInTransaction<T, TDatabase extends DrizzleDatabase = DefaultDatabase>(callback: (tx: TransactionDB<TDatabase>) => Promise<T>, options?: RunInTransactionOptions): Promise<T>;
+
 /**
  * PostgreSQL Error Conversion Utilities
  *
@@ -1007,14 +1596,6 @@ declare function fromPostgresError(error: any): DatabaseError;
  * ```
  */
 
-/**
- * Infer SELECT model from PgTable
- */
-type InferSelectModel<T extends PgTable> = T['$inferSelect'];
-/**
- * Infer INSERT model from PgTable
- */
-type InferInsertModel<T extends PgTable> = T['$inferInsert'];
 /**
  * Object-based where condition (AND only, equality only)
  */
@@ -1126,8 +1707,8 @@ declare function createMany<T extends PgTable>(table: T, data: InferInsertModel<
  * }, {
  *     target: [cmsPublishedCache.section, cmsPublishedCache.locale],
  *     set: {
- *         content: data.content,
- *         updatedAt: new Date()
+ *         content: data.content
+ *         // updatedAt is stamped by the database — do not name it here
  *     }
  * });
  *
@@ -1266,11 +1847,11 @@ declare function count<T extends PgTable>(table: T, where?: WhereObject<InferSel
  *
  * @example With Transactions
  * ```typescript
- * import { runWithTransaction } from '@spfn/core/db';
+ * import { runInTransaction } from '@spfn/core/db';
  *
  * const userRepo = new UserRepository();
  *
- * await runWithTransaction(async () => {
+ * await runInTransaction(async () => {
  *     // Both db and readDb automatically use the transaction context
  *     const user = await userRepo.create({ name: 'John' });
  *     await userRepo.findById(user.id); // Uses same transaction
@@ -1279,10 +1860,10 @@ declare function count<T extends PgTable>(table: T, where?: WhereObject<InferSel
  *
  * @example With Custom Schema Type
  * ```typescript
- * import type { AppSchema } from './schema';
+ * import type { AppRelations } from './relations';
  *
- * export class UserRepository extends BaseRepository<AppSchema> {
- *     // Now this.db and this.readDb are typed with AppSchema
+ * export class UserRepository extends BaseRepository<AppRelations> {
+ *     // Now this.db and this.readDb preserve the app's Drizzle relations
  * }
  * ```
  *
@@ -1302,6 +1883,8 @@ declare function count<T extends PgTable>(table: T, where?: WhereObject<InferSel
  * ```
  */
 
+/** Database surface available to repositories inside and outside transactions. */
+type RepositoryDatabase<TDatabase extends DrizzleDatabase> = TDatabase extends PgAsyncDatabase<infer TQueryResult, infer TRelations> ? PgAsyncDatabase<TQueryResult, TRelations> : never;
 /**
  * Enhanced error class that includes repository context
  */
@@ -1323,9 +1906,10 @@ declare class RepositoryError extends Error {
  * - Inside transaction: Uses transaction DB
  * - Outside transaction: Uses global DB instance (with read/write separation)
  *
- * @template TSchema - Database schema type (defaults to Record<string, unknown>)
+ * @template TRelations - Drizzle relations type (defaults to no relations)
+ * @template TDatabase - PostgreSQL Drizzle driver type (defaults to postgres.js)
  */
-declare abstract class BaseRepository<TSchema extends Record<string, unknown> = Record<string, unknown>> {
+declare abstract class BaseRepository<TRelations extends AnyRelations = EmptyRelations, TDatabase extends DrizzleDatabase = PostgresJsDatabase<TRelations>> {
     /**
      * Write database instance
      *
@@ -1342,7 +1926,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * }
      * ```
      */
-    protected get db(): PostgresJsDatabase<TSchema>;
+    protected get db(): RepositoryDatabase<TDatabase>;
     /**
      * Read database instance
      *
@@ -1363,7 +1947,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * }
      * ```
      */
-    protected get readDb(): PostgresJsDatabase<TSchema>;
+    protected get readDb(): RepositoryDatabase<TDatabase>;
     /**
      * Wrap query execution with repository context
      *
@@ -1409,7 +1993,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * const user = await this._findOne(users, eq(users.id, 1));
      * ```
      */
-    protected _findOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<T['$inferSelect'] | null>;
+    protected _findOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<InferSelectModel<T> | null>;
     /**
      * Find multiple records
      *
@@ -1431,7 +2015,33 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
         orderBy?: SQL | SQL[];
         limit?: number;
         offset?: number;
-    }): Promise<T['$inferSelect'][]>;
+    }): Promise<InferSelectModel<T>[]>;
+    /**
+     * Keyset (cursor) pagination — O(limit) instead of OFFSET's O(offset).
+     *
+     * Pages by a strictly-ordered, unique column instead of a numeric offset, so a
+     * deep page doesn't scan and discard everything before it. Pass the cursor
+     * column's value from the last row of the previous page as `after`; omit it for
+     * the first page. The column must be unique and the sole sort key (e.g. an
+     * auto-increment id or a ULID).
+     *
+     * @example
+     * ```typescript
+     * const page1 = await this._findManyKeyset(users, { cursorColumn: users.id, limit: 20 });
+     * const page2 = await this._findManyKeyset(users, {
+     *     cursorColumn: users.id,
+     *     after: page1.at(-1)?.id,
+     *     limit: 20,
+     * });
+     * ```
+     */
+    protected _findManyKeyset<T extends PgTable>(table: T, options: {
+        cursorColumn: PgColumn;
+        limit: number;
+        after?: string | number | bigint | Date;
+        order?: 'asc' | 'desc';
+        where?: Record<string, any> | SQL | undefined;
+    }): Promise<InferSelectModel<T>[]>;
     /**
      * Create a new record
      *
@@ -1447,7 +2057,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * });
      * ```
      */
-    protected _create<T extends PgTable>(table: T, data: T['$inferInsert']): Promise<T['$inferSelect']>;
+    protected _create<T extends PgTable>(table: T, data: InferInsertModel<T>): Promise<InferSelectModel<T>>;
     /**
      * Create multiple records
      *
@@ -1463,7 +2073,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * ]);
      * ```
      */
-    protected _createMany<T extends PgTable>(table: T, data: T['$inferInsert'][]): Promise<T['$inferSelect'][]>;
+    protected _createMany<T extends PgTable>(table: T, data: InferInsertModel<T>[]): Promise<InferSelectModel<T>[]>;
     /**
      * Upsert a record (INSERT or UPDATE on conflict)
      *
@@ -1479,14 +2089,14 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      *     value: {...}
      * }, {
      *     target: [cache.key],
-     *     set: { value: data.value, updatedAt: new Date() }
+     *     set: { value: data.value } // updatedAt is stamped by the database
      * });
      * ```
      */
-    protected _upsert<T extends PgTable>(table: T, data: T['$inferInsert'], options: {
+    protected _upsert<T extends PgTable>(table: T, data: InferInsertModel<T>, options: {
         target: PgColumn[];
-        set?: Partial<T['$inferInsert']> | Record<string, SQL | any>;
-    }): Promise<T['$inferSelect']>;
+        set?: Partial<InferInsertModel<T>> | Record<string, SQL | any>;
+    }): Promise<InferSelectModel<T>>;
     /**
      * Update a single record
      *
@@ -1503,7 +2113,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * );
      * ```
      */
-    protected _updateOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined, data: Partial<T['$inferInsert']>): Promise<T['$inferSelect'] | null>;
+    protected _updateOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined, data: Partial<InferInsertModel<T>>): Promise<InferSelectModel<T> | null>;
     /**
      * Update multiple records
      *
@@ -1520,7 +2130,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * );
      * ```
      */
-    protected _updateMany<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined, data: Partial<T['$inferInsert']>): Promise<T['$inferSelect'][]>;
+    protected _updateMany<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined, data: Partial<InferInsertModel<T>>): Promise<InferSelectModel<T>[]>;
     /**
      * Delete a single record
      *
@@ -1533,7 +2143,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * const user = await this._deleteOne(users, { id: 1 });
      * ```
      */
-    protected _deleteOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<T['$inferSelect'] | null>;
+    protected _deleteOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<InferSelectModel<T> | null>;
     /**
      * Delete multiple records
      *
@@ -1546,7 +2156,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * const users = await this._deleteMany(users, { verified: false });
      * ```
      */
-    protected _deleteMany<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<T['$inferSelect'][]>;
+    protected _deleteMany<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<InferSelectModel<T>[]>;
     /**
      * Count records
      *
@@ -1563,4 +2173,4 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
     protected _count<T extends PgTable>(table: T, where?: Record<string, any> | SQL | undefined): Promise<number>;
 }
 
-export { BaseRepository, type DatabaseClients, type DrizzleConfigOptions, type PoolConfig, RepositoryError, type RetryConfig, type TransactionContext, type TransactionDB, Transactional, type TransactionalOptions, auditFields, checkConnection, closeDatabase, count, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, enumText, findMany, findOne, foreignKey, fromPostgresError, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, id, initDatabase, optionalForeignKey, packageNameToSchema, publishingFields, runWithTransaction, setDatabase, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
+export { type AfterCommitCallback, type AfterRollbackCallback, BaseRepository, type BeforeCommitCallback, type DatabaseClients, type DatabaseInitOptions, type DatabaseOptions, type DatabaseProvider, type DatabaseTransaction, type DefaultDatabase, type DrizzleConfigOptions, type DrizzleDatabase, type FunctionMigrationEntry, type FunctionMigrationInfo, type MigrationStatus, type MigrationStatusDb, type MigrationTargetStatus, type NestedFrameGate, PROJECT_MIGRATIONS_TABLE, PROJECT_TARGET_NAME, type PoolConfig, RUN_MIGRATIONS_HINT, type RenderableDrizzleConfig, type RepositoryDatabase, RepositoryError, type RetryConfig, type RunInTransactionOptions, type TransactionContext, type TransactionDB, Transactional, type TransactionalOptions, auditFields, checkConnection, closeDatabase, collectMigrationStatus, count, countPendingMigrations, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, discoverFunctionMigrations, enumText, filterPendingEntries, findMany, findOne, forceReconnectDatabase, foreignKey, formatPendingMigrations, fromPostgresError, functionMigrationsTable, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, getTransactionContext, hasMigrationTargets, id, initDatabase, isConnectionLevelError, migrationTargets, onAfterCommit, onAfterRollback, onBeforeCommit, optionalForeignKey, packageNameToSchema, pendingMigrationTargets, pendingMigrationsSummary, projectMigrationsDir, publishingFields, readMigrationEntries, renderDrizzleConfig, reportDatabaseError, resetConnectionErrorCounter, runInTransaction, runWithTransaction, setDatabase, setDatabaseProvider, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };