@stacksjs/database 0.70.36 → 0.70.38

package/dist/auth-tables.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Create all authentication tables
+ */
+export declare function migrateAuthTables(options?: { verbose?: boolean }): Promise<{ success: boolean, error?: string }>;

package/dist/class-seeder.d.ts

@@ -0,0 +1,16 @@
+/*.ts`; an explicit `--class` filters to one.
+ */
+export declare function runClassSeeders(options?: RunOptions): Promise<{ ran: string[], skipped: string[] }>;
+declare interface RunOptions {
+  class?: string
+  dir?: string
+}
+/**
+ * Base class for class-based seeders. Subclass this and implement
+ * `async run()`. Seeders may call `this.call()` to invoke other
+ * seeders, mirroring Laravel's nested-seeder pattern.
+ */
+export declare abstract class Seeder {
+  abstract run(): Promise<void> | void;
+  protected call(other: new () => Seeder): Promise<void>;
+}

package/dist/custom/audits.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Create the `model_audits` table used by the `useAudit` ORM trait.
+ *
+ * The trait writes one row per create/update/delete on any model that
+ * declares `traits: { useAudit: true }`. The schema is intentionally
+ * polymorphic — `auditable_type` + `auditable_id` rather than per-table
+ * audit columns — so adding the trait to a new model never requires a
+ * follow-up migration.
+ *
+ * @example
+ * ```ts
+ * import { createModelAuditsTable } from '@stacksjs/database'
+ * await createModelAuditsTable() // idempotent — checks before writing
+ * ```
+ */
+export declare function createModelAuditsTable(): Promise<void>;

package/dist/custom/errors.d.ts

@@ -0,0 +1 @@
+export declare function createErrorsTable(): Promise<void>;

package/dist/custom/index.d.ts

@@ -0,0 +1,3 @@
+export * from './audits';
+export * from './errors';
+export * from './jobs';

package/dist/custom/jobs.d.ts

@@ -0,0 +1,3 @@
+import type { MigrationResult } from '../migrations';
+import type { Result } from '@stacksjs/error-handling';
+export declare function createJobsMigration(): Promise<Result<MigrationResult[] | string, Error>>;

package/dist/database.d.ts

@@ -0,0 +1,87 @@
+import type { QueryBuilder, QueryBuilderConfig, SupportedDialect } from 'bun-query-builder';
+/**
+ * Create a database connection with the given options
+ */
+export declare function createDatabase(options: DatabaseOptions): Database;
+/**
+ * Create a SQLite database connection
+ */
+export declare function createSqliteDatabase(database: string, options?: Partial<Omit<DatabaseOptions, 'driver' | 'connection'>>): Database;
+/**
+ * Create a PostgreSQL database connection
+ */
+export declare function createPostgresDatabase(connection: DatabaseConnectionConfig, options?: Partial<Omit<DatabaseOptions, 'driver' | 'connection'>>): Database;
+/**
+ * Create a MySQL database connection
+ */
+export declare function createMysqlDatabase(connection: DatabaseConnectionConfig, options?: Partial<Omit<DatabaseOptions, 'driver' | 'connection'>>): Database;
+export declare interface DatabaseConnectionConfig {
+  database: string
+  host?: string
+  port?: number
+  username?: string
+  password?: string
+  url?: string
+}
+export declare interface DatabaseOptions {
+  driver: SupportedDialect
+  connection: DatabaseConnectionConfig
+  verbose?: boolean
+  timestamps?: {
+    createdAt?: string
+    updatedAt?: string
+    defaultOrderColumn?: string
+  }
+  softDeletes?: {
+    enabled?: boolean
+    column?: string
+    defaultFilter?: boolean
+  }
+  hooks?: QueryBuilderConfig['hooks']
+}
+/**
+ * Database class for managing database connections
+ *
+ * @example
+ * ```ts
+ * // Initialize with SQLite
+ * const db = new Database({
+ *   driver: 'sqlite',
+ *   connection: { database: 'database/app.sqlite' }
+ * })
+ *
+ * // Initialize with PostgreSQL
+ * const db = new Database({
+ *   driver: 'postgres',
+ *   connection: {
+ *     database: 'myapp',
+ *     host: 'localhost',
+ *     port: 5432,
+ *     username: 'postgres',
+ *     password: 'secret'
+ *   }
+ * })
+ *
+ * // Use the query builder
+ * const users = await db.query.selectFrom('users').where('active', '=', true).get()
+ * ```
+ */
+export declare class Database {
+  constructor(options: DatabaseOptions);
+  get driver(): SupportedDialect;
+  get connection(): DatabaseConnectionConfig;
+  get isInitialized(): boolean;
+  get query(): QueryBuilder<any>;
+  initialize(): void;
+  switchDriver(driver: SupportedDialect, connection: DatabaseConnectionConfig): void;
+  close(): void;
+  static fromConfig(config: {
+    default: SupportedDialect
+    connections: {
+      sqlite?: { database: string }
+      mysql?: { name: string, host?: string, port?: number, username?: string, password?: string }
+      postgres?: { name: string, host?: string, port?: number, username?: string, password?: string }
+    }
+  }, env?: string): Database;
+  static fromEnv(): Database;
+}

package/dist/defaults.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Get default connection config for a given database driver.
+ * Reads from the typed env proxy so values are auto-coerced.
+ */
+export declare function getConnectionDefaults(driver: string, envProxy?: Record<string, any>): ConnectionDefaults;
+/**
+ * Database Defaults & Constants
+ *
+ * Centralizes all hardcoded default values for database connections
+ * so they are defined once and easily discoverable.
+ */
+// ============================================================================
+// HOST / PORT DEFAULTS
+// ============================================================================
+export declare const DB_HOST_DEFAULT: '127.0.0.1';
+export declare const DB_PORTS: {
+  mysql: 3306;
+  postgres: 5432;
+  sqlite: 0
+};
+export declare const DB_NAMES: {
+  default: 'stacks';
+  sqlitePath: 'database/stacks.sqlite';
+  sqliteTestingPath: 'database/stacks_testing.sqlite'
+};
+export declare const DB_USERS: {
+  mysql: 'root';
+  postgres: 'postgres';
+  sqlite: ''
+};
+export declare const REDIS_DEFAULTS: {
+  host: 'localhost';
+  port: 6379
+};
+export declare const AWS_DEFAULTS: {
+  region: 'us-east-1'
+};
+// ============================================================================
+// CONNECTION CONFIG BUILDERS
+// ============================================================================
+export declare interface ConnectionDefaults {
+  database: string
+  host?: string
+  port?: number
+  username?: string
+  password?: string
+  prefix?: string
+}

package/dist/driver-config.d.ts

@@ -0,0 +1,120 @@
+import type { SupportedDialect } from 'bun-query-builder';
+/**
+ * Get the connection string for a given driver and configuration
+ */
+export declare function getConnectionString(driver: SupportedDialect, config: DatabaseConnections[keyof DatabaseConnections]): string;
+/**
+ * Validate driver configuration
+ */
+export declare function validateDriverConfig(driver: SupportedDialect, config: DatabaseConnections[keyof DatabaseConnections]): { valid: boolean, errors: string[] };
+/**
+ * Merge user configuration with defaults
+ */
+export declare function mergeWithDefaults<T extends keyof DatabaseConnections>(driver: T, config: Partial<DatabaseConnections[T]>): DatabaseConnections[T];
+/**
+ * Get the appropriate configuration for a driver from environment variables
+ */
+export declare function getConfigFromEnv(driver: SupportedDialect): DatabaseConnections[keyof DatabaseConnections];
+/**
+ * Detect the best available driver based on environment
+ */
+export declare function detectDriver(): SupportedDialect;
+/**
+ * Default configuration values for each driver
+ */
+export declare const driverDefaults: {
+  sqlite: {
+  database: 'database/stacks.sqlite';
+  prefix: ''
+};
+  mysql: {
+  name: 'stacks';
+  host: '127.0.0.1';
+  port: 3306;
+  username: 'root';
+  password: '';
+  prefix: '';
+  charset: 'utf8mb4';
+  collation: 'utf8mb4_unicode_ci'
+};
+  postgres: {
+  name: 'stacks';
+  host: '127.0.0.1';
+  port: 5432;
+  username: 'postgres';
+  password: '';
+  prefix: '';
+  schema: 'public'
+};
+  browser: {}
+};
+/**
+ * SQLite specific configuration
+ */
+export declare interface SqliteConfig {
+  database: string
+  prefix?: string
+}
+/**
+ * MySQL specific configuration
+ */
+export declare interface MysqlConfig {
+  name: string
+  host?: string
+  port?: number
+  username?: string
+  password?: string
+  prefix?: string
+  charset?: string
+  collation?: string
+}
+/**
+ * PostgreSQL specific configuration
+ */
+export declare interface PostgresConfig {
+  name: string
+  host?: string
+  port?: number
+  username?: string
+  password?: string
+  prefix?: string
+  schema?: string
+  sslMode?: 'disable' | 'require' | 'verify-ca' | 'verify-full'
+}
+/**
+ * DynamoDB specific configuration
+ */
+export declare interface DynamoDbConfig {
+  key: string
+  secret: string
+  region?: string
+  prefix?: string
+  endpoint?: string
+  tableName?: string
+  singleTable?: {
+    enabled?: boolean
+    pkAttribute?: string
+    skAttribute?: string
+    entityTypeAttribute?: string
+    keyDelimiter?: string
+    gsiCount?: number
+  }
+}
+/**
+ * All database connections configuration
+ */
+export declare interface DatabaseConnections {
+  sqlite?: SqliteConfig
+  mysql?: MysqlConfig
+  postgres?: PostgresConfig
+  dynamodb?: DynamoDbConfig
+}
+/**
+ * Full database configuration
+ */
+export declare interface FullDatabaseConfig {
+  default: SupportedDialect
+  connections: DatabaseConnections
+  migrations?: string
+  migrationLocks?: string
+}

package/dist/drivers/defaults/index.d.ts

@@ -0,0 +1,2 @@
+export * from './passwords';
+export * from './traits';

package/dist/drivers/defaults/passwords.d.ts

@@ -0,0 +1,4 @@
+// SQLite/MySQL version
+export declare function createPasswordResetsTable(): Promise<void>;
+// PostgreSQL version
+export declare function createPostgresPasswordResetsTable(): Promise<void>;

package/dist/drivers/defaults/traits.d.ts

@@ -0,0 +1,33 @@
+// bun-query-builder utilities are used via db.unsafe() for raw SQL
+export declare function getTraitTables(): string[];
+// SQLite/MySQL version
+export declare function createPasskeyMigration(): Promise<void>;
+// PostgreSQL version
+export declare function createPostgresPasskeyMigration(): Promise<void>;
+export declare function createTaggableTable(): Promise<void>;
+export declare function createPostgresTagsTable(): Promise<void>;
+// SQLite/MySQL version
+export declare function createCategorizableTable(): Promise<void>;
+// PostgreSQL version
+export declare function createPostgresCategorizableTable(): Promise<void>;
+// SQLite/MySQL version
+export declare function createCommentablesTable(options?: {
+  requiresApproval?: boolean
+  reportable?: boolean
+  votable?: boolean
+  requiresAuth?: boolean
+}): Promise<void>;
+// PostgreSQL version
+export declare function createPostgresCommentsTable(): Promise<void>;
+export declare function dropCommonTables(): Promise<void>;
+export declare function truncateMigrationTables(): Promise<void>;
+export declare function dropMigrationTables(): Promise<void>;
+export declare function createCommentUpvoteMigration(): Promise<void>;
+export declare function createPostgresCommentUpvoteMigration(): Promise<void>;
+export declare function createCommentablesPivotTable(): Promise<void>;
+export declare function createPostgresCommentablesPivotTable(): Promise<void>;
+export declare function createTaggablesTable(): Promise<void>;
+export declare function createPostgresTaggablesTable(): Promise<void>;
+export declare function createQueryLogsTable(): Promise<void>;
+// PostgreSQL version
+export declare function createPostgresQueryLogsTable(): Promise<void>;

package/dist/drivers/dynamodb.d.ts

@@ -0,0 +1,148 @@
+import type { Model } from '@stacksjs/types';
+/**
+ * Marshall a JS object to DynamoDB format
+ */
+declare function marshall(obj: Record<string, any>): Record<string, any>;
+/**
+ * Unmarshall a DynamoDB object to JS format
+ */
+declare function unmarshall(obj: Record<string, any>): Record<string, any>;
+/**
+ * Generate key pattern for an entity
+ */
+export declare function generateKeyPattern(entityName: string, idField?: string): string;
+/**
+ * Parse a key pattern and extract values
+ */
+export declare function parseKeyPattern(pattern: string, key: string): Record<string, string>;
+/**
+ * Build a key from a pattern and values
+ */
+export declare function buildKey(pattern: string, values: Record<string, string>): string;
+/**
+ * Create a new DynamoDB client instance
+ */
+export declare function createDynamo(): DynamoClient;
+/**
+ * DynamoDB client singleton
+ */
+export declare const dynamo: DynamoClient;
+/**
+ * DynamoDB connection configuration
+ */
+export declare interface DynamoConnectionConfig {
+  region: string
+  table: string
+  endpoint?: string
+  credentials?: {
+    accessKeyId: string
+    secretAccessKey: string
+    sessionToken?: string
+  }
+  pkAttribute?: string
+  skAttribute?: string
+  entityTypeAttribute?: string
+  keyDelimiter?: string
+}
+/**
+ * Entity mapping for single-table design
+ */
+export declare interface SingleTableEntityMapping {
+  entityType: string
+  pkPattern: string
+  skPattern?: string
+  gsi1pk?: string
+  gsi1sk?: string
+  gsi2pk?: string
+  gsi2sk?: string
+}
+/**
+ * Sort key builder for fluent API
+ */
+export declare interface SortKeyBuilder {
+  equals(value: string): EntityQueryBuilder
+  beginsWith(prefix: string): EntityQueryBuilder
+  between(start: string, end: string): EntityQueryBuilder
+  lt(value: string): EntityQueryBuilder
+  lte(value: string): EntityQueryBuilder
+  gt(value: string): EntityQueryBuilder
+  gte(value: string): EntityQueryBuilder
+}
+/**
+ * Batch write operation
+ */
+export declare interface BatchWriteOperation {
+  put?: { entity: string, item: Record<string, any> }
+  delete?: { entity: string, pk: string, sk: string }
+}
+/**
+ * Transact write operation
+ */
+export declare interface TransactWriteOperation {
+  put?: { entity: string, item: Record<string, any>, condition?: string }
+  update?: { entity: string, pk: string, sk?: string, set?: Record<string, any>, add?: Record<string, number>, remove?: string[] }
+  delete?: { entity: string, pk: string, sk: string, condition?: string }
+  conditionCheck?: { entity: string, pk: string, sk: string, condition: string }
+}
+/**
+ * Query result
+ */
+export declare interface QueryResult<T = any> {
+  items: T[]
+  count: number
+  scannedCount?: number
+  lastKey?: Record<string, any>
+}
+/**
+ * Entity-centric query builder for DynamoDB
+ */
+export declare class EntityQueryBuilder<T = any> {
+  constructor(client: any, tableName: string, config: { pkAttribute: string, skAttribute: string, entityTypeAttribute: string, keyDelimiter: string });
+  entity(entityType: string): this;
+  pk(value: string): this;
+  get sk(): SortKeyBuilder;
+  index(indexName: string): this;
+  project(...attributes: string[]): this;
+  filter(attribute: string, operator: string, value?: any): this;
+  where(attribute: string, value: any): this;
+  whereIn(attribute: string, values: any[]): this;
+  limit(count: number): this;
+  asc(): this;
+  desc(): this;
+  consistent(): this;
+  startFrom(key: Record<string, any>): this;
+  toRequest(): Record<string, any>;
+  get(): Promise<T[]>;
+  first(): Promise<T | undefined>;
+  getAll(): Promise<T[]>;
+  count(): Promise<number>;
+}
+/**
+ * DynamoDB client with entity-centric API
+ */
+declare class DynamoClient {
+  connection(config: DynamoConnectionConfig): this;
+  isConfigured(): boolean;
+  setClient(client: any): this;
+  getClient(): any;
+  registerEntity(mapping: SingleTableEntityMapping): this;
+  registerModel(model: Model): this;
+  getEntityMapping(entityType: string): SingleTableEntityMapping | undefined;
+  entity<T = any>(entityType: string): EntityQueryBuilder<T>;
+  batchWrite(operations: BatchWriteOperation[]): Promise<void>;
+  transactWrite(operations: TransactWriteOperation[]): Promise<void>;
+  put(entity: string, item: Record<string, any>): Promise<void>;
+  get<T = any>(pk: string, sk?: string): Promise<T | undefined>;
+  delete(pk: string, sk?: string): Promise<void>;
+  update(pk: string, sk: string | undefined, updates: Record<string, any>): Promise<void>;
+  getTableName(): string;
+  getConfig(): {
+    tableName: string
+    pkAttribute: string
+    skAttribute: string
+    entityTypeAttribute: string
+    keyDelimiter: string
+  };
+}
+// Export marshall/unmarshall utilities
+export { marshall, unmarshall };

package/dist/drivers/helpers.d.ts

@@ -0,0 +1,29 @@
+import type { Attribute, AttributesElements, Model } from '@stacksjs/types';
+import type { DateValidatorType, EnumValidatorType, NumberValidatorType, StringValidatorType, ValidationType } from '@stacksjs/ts-validation';
+export declare function deleteMigrationFiles(): Promise<void>;
+export declare function deleteFrameworkModels(): Promise<void>;
+export declare function getLastMigrationFields(modelName: string): Promise<AttributesElements>;
+export declare function modelTableName(model: Model | string): Promise<string>;
+export declare function hasTableBeenMigrated(tableName: string): Promise<boolean>;
+export declare function hasMigrationBeenCreated(tableName: string): Promise<boolean>;
+export declare function getExecutedMigrations(): Promise<{ name: string }[]>;
+export declare function prepareTextColumnType(validator: StringValidatorType, driver?: string): string;
+// Add new function for date/time column types
+export declare function prepareDateTimeColumnType(validator: DateValidatorType, driver?: string): string;
+export declare function compareRanges(range1: Range, range2: Range): boolean;
+export declare function checkPivotMigration(dynamicPart: string): Promise<boolean>;
+export declare function pluckChanges(array1: string[], array2: string[]): { added: string[], removed: string[] } | null;
+export declare function arrangeColumns(attributes: AttributesElements | undefined): Array<[string, Attribute]>;
+export declare function isArrayEqual(arr1: (number | undefined)[], arr2: (number | undefined)[]): boolean;
+export declare function findDifferingKeys(obj1: any, obj2: any): { key: string, max: number, min: number }[];
+export declare function fetchTables(): Promise<string[]>;
+export declare function getUpvoteTableName(model: Model, tableName: string): string | undefined;
+export declare function prepareNumberColumnType(validator: NumberValidatorType, driver?: string): string;
+// Add new function for enum column types
+export declare function prepareEnumColumnType(validator: EnumValidatorType, driver?: string): string;
+export declare function mapFieldTypeToColumnType(validator: ValidationType, driver?: string): string;
+export declare function checkIsRequired(rule: string): boolean;
+declare interface Range {
+  min: number
+  max: number
+}

package/dist/drivers/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Drivers — barrel export.
+ *
+ * Helpers shared across driver implementations live in `./helpers.ts` (NOT
+ * inline here) so driver modules can import them without re-importing this
+ * barrel and triggering a self-cycle. See `./helpers.ts` for the rationale.
+ */
+export * from './helpers';
+export * from './mysql';
+export * from './postgres';
+export * from './sqlite';
+export * from './defaults/index';
+export * from './dynamodb';

package/dist/drivers/mysql.d.ts

@@ -0,0 +1,7 @@
+import type { Ok } from '@stacksjs/error-handling';
+export declare function resetMysqlDatabase(): Promise<Ok<string, never>>;
+export declare function dropMysqlTables(): Promise<void>;
+export declare function generateMysqlMigration(modelPath: string): Promise<void>;
+export declare function generateMysqlTraitMigrations(): Promise<void>;
+export declare function createMysqlForeignKeyMigrations(modelPath: string): Promise<void>;
+export declare function createAlterTableMigration(modelPath: string): Promise<void>;

package/dist/drivers/postgres.d.ts

@@ -0,0 +1,7 @@
+import type { Ok } from '@stacksjs/error-handling';
+export declare function dropPostgresTables(): Promise<void>;
+export declare function generatePostgresTraitMigrations(): Promise<void>;
+export declare function resetPostgresDatabase(): Promise<Ok<string, never>>;
+export declare function generatePostgresMigration(modelPath: string): Promise<void>;
+export declare function createPostgresForeignKeyMigrations(modelPath: string): Promise<void>;
+export declare function fetchPostgresTables(): Promise<string[]>;

package/dist/drivers/sqlite.d.ts

@@ -0,0 +1,23 @@
+import type { Ok } from '@stacksjs/error-handling';
+export declare function resetSqliteDatabase(): Promise<Ok<string, never>>;
+/**
+ * Configure SQLite for the Stacks workload. Idempotent — the pragmas are
+ * cheap to re-apply, but each one is a no-op once set so repeated calls
+ * during dev hot-reload don't accumulate state.
+ *
+ * - WAL journaling: lets readers and a single writer proceed in parallel
+ *   instead of serializing every transaction. Critical for dev where the
+ *   API server, queue worker, and dashboard all hit the same file.
+ * - foreign_keys=ON: SQLite ships with FK enforcement OFF by default.
+ *   Without this, FK constraint violations are silently ignored — broken
+ *   relations land in the DB and fail later, far from the original write.
+ * - busy_timeout: backs off when the file is locked by another writer
+ *   instead of failing the whole query immediately.
+ */
+export declare function configureSqlitePragmas(): Promise<void>;
+export declare function dropSqliteTables(): Promise<void>;
+export declare function fetchSqliteFile(): string;
+export declare function fetchTestSqliteFile(): string;
+export declare function generateSqliteMigration(modelPath: string): Promise<void>;
+export declare function createSqliteForeignKeyMigrations(_modelPath: string): Promise<void>;
+export declare function copyModelFiles(modelPath: string): Promise<void>;

package/dist/index.d.ts

@@ -0,0 +1,112 @@
+export type {
+  DatabaseConnectionConfig,
+  DatabaseOptions,
+} from './database';
+export type {
+  DatabaseConnections,
+  DynamoDbConfig,
+  FullDatabaseConfig,
+  MysqlConfig,
+  PostgresConfig,
+  SqliteConfig,
+} from './driver-config';
+export type {
+  QueryBuilder,
+  QueryBuilderConfig,
+  Seeder as QueryBuilderSeeder,
+  SupportedDialect,
+} from 'bun-query-builder';
+export type {
+  DynamoConnectionConfig,
+  SingleTableEntityMapping,
+  SortKeyBuilder,
+  BatchWriteOperation,
+  TransactWriteOperation,
+  QueryResult,
+} from './drivers/dynamodb';
+/**
+ * @stacksjs/database
+ *
+ * Database module powered by bun-query-builder.
+ * Provides database initialization, driver configuration, migrations,
+ * seeding, and a fluent query builder interface.
+ *
+ * @example
+ * ```ts
+ * import { Database, db, createSqliteDatabase } from '@stacksjs/database'
+ *
+ * // Use the default db instance (configured from environment)
+ * const users = await db.selectFrom('users').where('active', '=', true).get()
+ *
+ * // Or create a custom database instance
+ * const customDb = new Database({
+ *   driver: 'postgres',
+ *   connection: {
+ *     database: 'myapp',
+ *     host: 'localhost',
+ *     port: 5432,
+ *     username: 'postgres',
+ *     password: 'secret'
+ *   }
+ * })
+ *
+ * // Helper functions for quick setup
+ * const sqliteDb = createSqliteDatabase('database/app.sqlite')
+ * ```
+ */
+// Database initialization and management
+export {
+  Database,
+  createDatabase,
+  createMysqlDatabase,
+  createPostgresDatabase,
+  createSqliteDatabase,
+} from './database';
+// Driver configuration
+export {
+  detectDriver,
+  driverDefaults,
+  getConfigFromEnv,
+  getConnectionString,
+  mergeWithDefaults,
+  validateDriverConfig,
+} from './driver-config';
+// Core database utilities and default instance
+export * from './utils';
+// Types (compatibility layer for Kysely types)
+export * from './types';
+// Migrations
+export * from './migrations';
+// Query logger DI hook (router calls setQueryTracker on init)
+export { setQueryTracker, logQuery } from './query-logger';
+// Class-based seeders (supplements the model-attribute auto-seeder)
+export { Seeder, runClassSeeders } from './class-seeder';
+// Zero-downtime migration helpers
+export { addColumnSafely, backfillInBatches, renameColumnSafely } from './safe-migrations';
+// Seeding
+export * from './seeder';
+// Driver utilities
+export * from './drivers/index';
+// Custom migrations (jobs, errors, etc.)
+export * from './custom/index';
+// Auth tables migration
+export * from './auth-tables';
+// SQL dialect helpers & connection defaults
+export * from './sql-helpers';
+export * from './defaults';
+// Re-export bun-query-builder functions and types
+export {
+  createQueryBuilder,
+  setConfig,
+} from 'bun-query-builder';
+// DynamoDB entity-centric API
+export {
+  createDynamo,
+  dynamo,
+  EntityQueryBuilder,
+  generateKeyPattern,
+  parseKeyPattern,
+  buildKey,
+  marshall,
+  unmarshall,
+} from './drivers/dynamodb';

package/dist/index.js

@@ -133,7 +133,7 @@ Or enable auto-install in your mock.config.ts: { autoInstallLocales: true }`)}th
           )`);let K=O.prepare("INSERT OR IGNORE INTO migrations (migration) VALUES (?)");for(let W of X)K.run(W)}finally{O.close()}}}catch(G){$0.debug(`[migration] Could not record dropped migrations as executed: ${G}`)}}async function uE(){let $=d8();if($==="sqlite")return;let Z=l1.connections[$],X=(Z?.name||"stacks").replace(/['"]/g,""),_=Z?.host||"localhost",Y=Z?.port||($==="postgres"?5432:3306),L=Z?.username||($==="postgres"?process.env.USER||"postgres":"root"),z=Z?.password||"",j=$==="postgres"?"postgres":"mysql";try{d9({dialect:$,database:{database:j,host:_,port:Y,username:L,password:z}}),b1();let U=F9();if($==="postgres")try{await U.unsafe(`CREATE DATABASE "${X}"`),$0.info(`Created database "${X}"`)}catch(Q){if(Q?.message?.includes("already exists")||Q?.errno==="42P04")$0.info(`Database "${X}" already exists`);else throw Q}else if($==="mysql")try{await U.unsafe(`CREATE DATABASE IF NOT EXISTS \`${X}\``),$0.info(`Ensured database "${X}" exists`)}catch(Q){if(Q?.message?.includes("database exists"))$0.info(`Database "${X}" already exists`);else throw Q}b1()}catch(U){$0.warn(`Could not auto-create database "${X}": ${U?.message||U}`),$0.info("If the database already exists, this warning can be ignored."),b1()}}async function oV(){let $=Date.now();try{if($0.info("Migrating database..."),await uE(),c5(),d8()==="sqlite")dE();let Z=v6.userModelsPath();return $0.debug(`[migration] Running migrations from: ${Z}`),await S6(Z),$0.success(`Database migration completed in ${Date.now()-$}ms.`),c8("Database migration completed.")}catch(Z){let X=Z instanceof Error?Z.message:String(Z);return $0.error(`[migration] Failed after ${Date.now()-$}ms: ${X}`),$0.info("[migration] Run `./buddy migrate:fresh` to drop and recreate the schema if state is partial."),f5(g5("Migration failed",Z))}}var mE=["oauth_refresh_tokens","oauth_access_tokens","oauth_clients","passkeys","failed_jobs","jobs","notifications","password_reset_tokens"];async function aV(){try{c5();let $=v6.userModelsPath(),Z=d8();return await sE(Z),await M6($,{dialect:Z}),c8("All tables dropped successfully!")}catch($){return f5(g5("Database reset failed",$))}}async function sE($){if($==="mysql")try{await v.unsafe("SET FOREIGN_KEY_CHECKS = 0").execute()}catch(Z){$0.warn(`Could not disable foreign key checks: ${Z instanceof Error?Z.message:String(Z)}`)}if($==="sqlite")try{await v.unsafe("PRAGMA foreign_keys = OFF").execute()}catch(Z){$0.warn(`Could not disable foreign key checks: ${Z instanceof Error?Z.message:String(Z)}`)}for(let Z of mE)try{let X;if($==="postgres")X=`DROP TABLE IF EXISTS "${Z}" CASCADE`;else if($==="mysql")X=`DROP TABLE IF EXISTS \`${Z}\``;else X=`DROP TABLE IF EXISTS "${Z}"`;$0.info(`Dropping framework table: ${Z}`),await v.unsafe(X).execute(),$0.info(`Dropped framework table: ${Z}`)}catch(X){$0.warn(`Could not drop table ${Z}: ${X instanceof Error?X.message:String(X)}`)}if($==="mysql")try{await v.unsafe("SET FOREIGN_KEY_CHECKS = 1").execute()}catch(Z){$0.warn(`Could not re-enable foreign key checks: ${Z instanceof Error?Z.message:String(Z)}`)}if($==="sqlite")try{await v.unsafe("PRAGMA foreign_keys = ON").execute()}catch(Z){$0.warn(`Could not re-enable foreign key checks: ${Z instanceof Error?Z.message:String(Z)}`)}}async function tV(){try{$0.info("Generating migrations..."),c5();let $=d8(),{modelsDir:Z,skip:X}=p4();if(X)return $0.info("No app/Models directory found; using committed framework migrations"),c8("Migrations generated");$0.debug(`[migration] Generating migrations for dialect: ${$}, models: ${Z}`);let _=await A5(Z,{dialect:$});if(_.hasChanges){let Y=lE(_.sqlStatements??[]);if(Y>0)$0.success(`Migrations generated (${Y} file${Y===1?"":"s"})`);else $0.success("Migrations generated")}else $0.info("No changes detected");return c8("Migrations generated")}catch($){return f5(g5("Migration generation failed",$))}}function lE($){if(!$?.length)return 0;let Z=Q8(process.cwd(),"database","migrations");try{H0("fs").mkdirSync(Z,{recursive:!0})}catch{}let X="";try{for(let U of h6(Z).filter((Q)=>Q.endsWith(".sql")))X+=`
 ${f4(Q8(Z,U),"utf8")}`}catch{}let _=(U)=>U.replace(/\s+/g," ").trim(),Y=_(X),L=nE($),z=0,j=iE(Z);for(let U of L){let Q=U.statements.filter((O)=>!Y.includes(_(O)));if(Q.length===0)continue;let E=`${String(j).padStart(10,"0")}-${U.label}.sql`,G=Q8(Z,E),F=`${Q.map((O)=>O.trim().replace(/;\s*$/,"")).join(`;
 `)};
-`;g4(G,F),$0.debug(`[migration] Wrote ${E} (${Q.length} stmt${Q.length===1?"":"s"})`),z+=1,j+=1}return z}function nE($){let Z=new Map,X=(_,Y)=>{let L=Z.get(_)??[];L.push(Y),Z.set(_,L)};for(let _ of $){let Y=_.trim();if(!Y)continue;let L=Y.match(/^\s*CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(\w+)["`]?/i);if(L){X(`create-${L[1]}-table`,Y);continue}let z=Y.match(/^\s*ALTER\s+TABLE\s+["`]?(\w+)["`]?\s+(?:ADD\s+COLUMN\s+["`]?(\w+)["`]?|DROP\s+COLUMN\s+["`]?(\w+)["`]?|ADD\s+CONSTRAINT)/i);if(z){X(`alter-${z[1]}-${z[2]||z[3]||"constraint"}`,Y);continue}let j=Y.match(/^\s*CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(\w+)["`]?\s+ON\s+["`]?(\w+)["`]?/i);if(j){X(`create-${j[1]}-index-in-${j[2]}`,Y);continue}let U=Y.match(/^\s*DROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?["`]?(\w+)["`]?/i);if(U){X(`drop-${U[1]}-table`,Y);continue}X("auto-misc",Y)}return[...Z.entries()].map(([_,Y])=>({label:_,statements:Y}))}function iE($){let Z=0;try{for(let X of h6($)){let _=X.match(/^(\d+)-/);if(_)Z=Math.max(Z,Number.parseInt(_[1],10))}}catch{}return Z+1}async function eV(){try{$0.info("Generating fresh migrations..."),c5();let $=d8(),{modelsDir:Z,skip:X}=p4();if(X)return $0.info("No app/Models directory found; using committed framework migrations"),c8("Migrations generated");return await A5(Z,{dialect:$,full:!0}),$0.success("Migrations generated"),c8("Migrations generated")}catch($){return f5(g5("Fresh migration generation failed",$))}}import{memoryUsage as aE}from"process";import{config as Z8}from"@stacksjs/config";import{log as n1}from"@stacksjs/logging";function b6($){let Z={normalized:"",type:"OTHER",tables:[]};if(!$)return Z;try{let X=$.trim().toUpperCase();if(X.startsWith("SELECT"))Z.type="SELECT";else if(X.startsWith("INSERT"))Z.type="INSERT";else if(X.startsWith("UPDATE"))Z.type="UPDATE";else if(X.startsWith("DELETE"))Z.type="DELETE";return Z.tables=rE($,Z.type),Z.normalized=oE($),Z}catch{return{normalized:$,type:"OTHER",tables:[]}}}function rE($,Z){let X=[],_=$.toLowerCase();try{let Y=null,L=null,z=null,j=null,U=null,Q=/join\s+([\w.]+)/gi;switch(Z){case"SELECT":if(Y=_.match(/from\s+([\w.]+)/i),Y&&Y[1])X.push(Y[1].replace(/`/g,"").split(".").pop());L=Q.exec(_);while(L!==null){if(L[1])X.push(L[1].replace(/`/g,"").split(".").pop());L=Q.exec(_)}break;case"INSERT":if(z=_.match(/into\s+([\w.]+)/i),z&&z[1])X.push(z[1].replace(/`/g,"").split(".").pop());break;case"UPDATE":if(j=_.match(/update\s+([\w.]+)/i),j&&j[1])X.push(j[1].replace(/`/g,"").split(".").pop());break;case"DELETE":if(U=_.match(/from\s+([\w.]+)/i),U&&U[1])X.push(U[1].replace(/`/g,"").split(".").pop());break}}catch{}return[...new Set(X)].filter(Boolean)}function oE($){try{let Z=$;return Z=Z.replace(/(?<![a-zA-Z_])\b\d+\b(?![a-zA-Z_])/g,"?"),Z=Z.replace(/'([^']|'')*'/g,"?"),Z=Z.replace(/"([^"]|"")*"/g,"?"),Z=Z.replace(/\btrue\b/gi,"?"),Z=Z.replace(/\bfalse\b/gi,"?"),Z=Z.replace(/\bnull\b/gi,"?"),Z=Z.replace(/\s+/g," ").trim(),Z}catch{return $}}await p0();var c4=()=>{};function tE($){c4=$}var f6=!1;async function eE($){if(f6)return;try{let{query:Z,durationMs:X,error:_,bindings:Y}=$O($);try{c4(Z,X,Z8.database?.default||"unknown")}catch{}if(!Z8.database?.queryLogging?.enabled)return;let L=ZO(X,_),z=await XO(Z,X,L,_,Y);if(Z8.database?.queryLogging?.analysis?.enabled&&(L==="slow"||Z8.database.queryLogging.analysis.analyzeAll))await zO(z);f6=!0;try{await OO(z)}finally{f6=!1}if(L!=="completed")n1[L==="failed"?"error":"warn"](`Query ${L}:`,{query:z.query,duration:z.duration,connection:z.connection,..._&&{error:_}})}catch(Z){n1.error("Failed to log query:",Z)}}function $O($){let Z=$.query?.sql||"",X=$.queryDurationMillis||0,_=$.error,Y;if($.query?.parameters)try{Y=JSON.stringify($.query.parameters)}catch{Y="[]"}return{query:Z,durationMs:X,error:_,bindings:Y}}function ZO($,Z){let X=Z8.database?.queryLogging?.slowThreshold||100;if(Z)return"failed";if($>X)return"slow";return"completed"}async function XO($,Z,X,_,Y){let L=Z8.database.default||"unknown",z=b6($).normalized||$,{trace:j,caller:U}=LO();return{query:$,normalized_query:z,duration:Z,connection:L,status:X,error:_?String(_):void 0,executed_at:new Date().toISOString(),bindings:Y,trace:j,...U,memory_usage:aE().heapUsed/1024/1024}}var _O=[/\b(?:sk|pk|rk|api|secret|token|bearer|password|pwd|key)[_-]?[A-Za-z0-9]{12,}/gi,/\bsk_(?:live|test)_[A-Za-z0-9]{20,}/g,/\bAKIA[0-9A-Z]{16}/g,/\b[A-Za-z0-9_-]{40,}\b(?=\s|$|['"])/g];function YO($){let Z=$;for(let X of _O)Z=Z.replace(X,"<redacted>");return Z}function LO(){try{let $=Error("Stack trace capture").stack||"",X=$.split(`
+`;g4(G,F),$0.debug(`[migration] Wrote ${E} (${Q.length} stmt${Q.length===1?"":"s"})`),z+=1,j+=1}return z}function nE($){let Z=new Map,X=(_,Y)=>{let L=Z.get(_)??[];L.push(Y),Z.set(_,L)};for(let _ of $){let Y=_.trim();if(!Y)continue;let L=Y.match(/^\s*CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(\w+)["`]?/i);if(L){X(`create-${L[1]}-table`,Y);continue}let z=Y.match(/^\s*ALTER\s+TABLE\s+["`]?(\w+)["`]?\s+(?:ADD\s+COLUMN\s+["`]?(\w+)["`]?|DROP\s+COLUMN\s+["`]?(\w+)["`]?|ADD\s+CONSTRAINT)/i);if(z){X(`alter-${z[1]}-${z[2]||z[3]||"constraint"}`,Y);continue}let j=Y.match(/^\s*CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(\w+)["`]?\s+ON\s+["`]?(\w+)["`]?/i);if(j){X(`create-${j[1]}-index-in-${j[2]}`,Y);continue}let U=Y.match(/^\s*DROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?["`]?(\w+)["`]?/i);if(U){X(`drop-${U[1]}-table`,Y);continue}X("auto-misc",Y)}return[...Z.entries()].map(([_,Y])=>({label:_,statements:Y}))}function iE($){let Z=0;try{for(let X of h6($)){let _=X.match(/^(\d+)-/);if(_?.[1])Z=Math.max(Z,Number.parseInt(_[1],10))}}catch{}return Z+1}async function eV(){try{$0.info("Generating fresh migrations..."),c5();let $=d8(),{modelsDir:Z,skip:X}=p4();if(X)return $0.info("No app/Models directory found; using committed framework migrations"),c8("Migrations generated");return await A5(Z,{dialect:$,full:!0}),$0.success("Migrations generated"),c8("Migrations generated")}catch($){return f5(g5("Fresh migration generation failed",$))}}import{memoryUsage as aE}from"process";import{config as Z8}from"@stacksjs/config";import{log as n1}from"@stacksjs/logging";function b6($){let Z={normalized:"",type:"OTHER",tables:[]};if(!$)return Z;try{let X=$.trim().toUpperCase();if(X.startsWith("SELECT"))Z.type="SELECT";else if(X.startsWith("INSERT"))Z.type="INSERT";else if(X.startsWith("UPDATE"))Z.type="UPDATE";else if(X.startsWith("DELETE"))Z.type="DELETE";return Z.tables=rE($,Z.type),Z.normalized=oE($),Z}catch{return{normalized:$,type:"OTHER",tables:[]}}}function rE($,Z){let X=[],_=$.toLowerCase();try{let Y=null,L=null,z=null,j=null,U=null,Q=/join\s+([\w.]+)/gi;switch(Z){case"SELECT":if(Y=_.match(/from\s+([\w.]+)/i),Y&&Y[1])X.push(Y[1].replace(/`/g,"").split(".").pop());L=Q.exec(_);while(L!==null){if(L[1])X.push(L[1].replace(/`/g,"").split(".").pop());L=Q.exec(_)}break;case"INSERT":if(z=_.match(/into\s+([\w.]+)/i),z&&z[1])X.push(z[1].replace(/`/g,"").split(".").pop());break;case"UPDATE":if(j=_.match(/update\s+([\w.]+)/i),j&&j[1])X.push(j[1].replace(/`/g,"").split(".").pop());break;case"DELETE":if(U=_.match(/from\s+([\w.]+)/i),U&&U[1])X.push(U[1].replace(/`/g,"").split(".").pop());break}}catch{}return[...new Set(X)].filter(Boolean)}function oE($){try{let Z=$;return Z=Z.replace(/(?<![a-zA-Z_])\b\d+\b(?![a-zA-Z_])/g,"?"),Z=Z.replace(/'([^']|'')*'/g,"?"),Z=Z.replace(/"([^"]|"")*"/g,"?"),Z=Z.replace(/\btrue\b/gi,"?"),Z=Z.replace(/\bfalse\b/gi,"?"),Z=Z.replace(/\bnull\b/gi,"?"),Z=Z.replace(/\s+/g," ").trim(),Z}catch{return $}}await p0();var c4=()=>{};function tE($){c4=$}var f6=!1;async function eE($){if(f6)return;try{let{query:Z,durationMs:X,error:_,bindings:Y}=$O($);try{c4(Z,X,Z8.database?.default||"unknown")}catch{}if(!Z8.database?.queryLogging?.enabled)return;let L=ZO(X,_),z=await XO(Z,X,L,_,Y);if(Z8.database?.queryLogging?.analysis?.enabled&&(L==="slow"||Z8.database.queryLogging.analysis.analyzeAll))await zO(z);f6=!0;try{await OO(z)}finally{f6=!1}if(L!=="completed")n1[L==="failed"?"error":"warn"](`Query ${L}:`,{query:z.query,duration:z.duration,connection:z.connection,..._&&{error:_}})}catch(Z){n1.error("Failed to log query:",Z)}}function $O($){let Z=$.query?.sql||"",X=$.queryDurationMillis||0,_=$.error,Y;if($.query?.parameters)try{Y=JSON.stringify($.query.parameters)}catch{Y="[]"}return{query:Z,durationMs:X,error:_,bindings:Y}}function ZO($,Z){let X=Z8.database?.queryLogging?.slowThreshold||100;if(Z)return"failed";if($>X)return"slow";return"completed"}async function XO($,Z,X,_,Y){let L=Z8.database.default||"unknown",z=b6($).normalized||$,{trace:j,caller:U}=LO();return{query:$,normalized_query:z,duration:Z,connection:L,status:X,error:_?String(_):void 0,executed_at:new Date().toISOString(),bindings:Y,trace:j,...U,memory_usage:aE().heapUsed/1024/1024}}var _O=[/\b(?:sk|pk|rk|api|secret|token|bearer|password|pwd|key)[_-]?[A-Za-z0-9]{12,}/gi,/\bsk_(?:live|test)_[A-Za-z0-9]{20,}/g,/\bAKIA[0-9A-Z]{16}/g,/\b[A-Za-z0-9_-]{40,}\b(?=\s|$|['"])/g];function YO($){let Z=$;for(let X of _O)Z=Z.replace(X,"<redacted>");return Z}function LO(){try{let $=Error("Stack trace capture").stack||"",X=$.split(`
 `).slice(1).find((Y)=>!Y.includes("query-logger.ts")),_={};if(X){let Y=X.match(/at (.+?) \(/),L=X.match(/\((.+?):(\d+):(\d+)\)/);if(Y&&Y[1]){let z=Y[1].split(".");_={model:z.length>1?z[0]:void 0,method:z.length>1?z[1]:z[0]}}if(L&&L[1]&&L[2])_={..._,file:L[1],line:Number.parseInt(L[2],10)}}return{trace:YO($),caller:_}}catch{return{trace:"",caller:{}}}}async function zO($){try{let{tables:Z,type:X}=b6($.query);if($.affected_tables=JSON.stringify(Z||[]),X==="SELECT"&&Z8.database?.queryLogging?.analysis?.explainPlan){let Y=await jO($.query);if(Y){if($.explain_plan=Y.plan,$.indexes_used=JSON.stringify(Y.indexesUsed||[]),$.missing_indexes=JSON.stringify(Y.missingIndexes||[]),Z8.database?.queryLogging?.analysis?.suggestions)$.optimization_suggestions=JSON.stringify(EO(Y,$))}}let _=[X];if(Z&&Z.length>0)_.push(...Z.map((Y)=>`table:${Y}`));$.tags=JSON.stringify(_)}catch(Z){n1.debug("Error during query analysis:",Z)}}var UO=new Set(["sqlite","mysql","postgres"]);async function jO($){try{let Z=(await import("@stacksjs/config")).config?.database?.default,X=typeof Z==="string"?Z:"sqlite";if(!UO.has(X))return null;let _;if(X==="mysql")_=`EXPLAIN FORMAT=JSON ${$}`;else if(X==="postgres")_=`EXPLAIN (FORMAT JSON) ${$}`;else _=`EXPLAIN QUERY PLAN ${$}`;let Y=await v.unsafe?.(_);if(!Y)return null;let L=Array.isArray(Y)?Y:Y.rows??[],z=JSON.stringify(L),j=[],U=[];if(X==="sqlite")for(let Q of L){let E=Q?.detail||"",G=E.match(/USING (?:COVERING )?INDEX (\w+)/i);if(G&&G[1])j.push(G[1]);else{let F=E.match(/^SCAN\s+(\w+)/i);if(F&&F[1])U.push(F[1])}}else if(X==="mysql"){let Q=z;for(let E of Q.matchAll(/"key"\s*:\s*"([^"]+)"/g))if(E[1])j.push(E[1]);for(let E of Q.matchAll(/"table_name"\s*:\s*"([^"]+)"[^}]*"access_type"\s*:\s*"ALL"/g))if(E[1])U.push(E[1])}else if(X==="postgres"){let Q=z;for(let E of Q.matchAll(/"Index Name"\s*:\s*"([^"]+)"/g))if(E[1])j.push(E[1]);for(let E of Q.matchAll(/"Node Type"\s*:\s*"Seq Scan"[^}]*"Relation Name"\s*:\s*"([^"]+)"/g))if(E[1])U.push(E[1])}return{plan:z.length>4000?`${z.slice(0,4000)}\u2026`:z,indexesUsed:Array.from(new Set(j)),missingIndexes:Array.from(new Set(U))}}catch(Z){return n1.debug("[query-logger] EXPLAIN failed (non-fatal):",Z),null}}function EO($,Z){let X=[];if($.missingIndexes&&$.missingIndexes.length>0)X.push(`Consider adding index on ${$.missingIndexes.join(", ")}`);if(Z.status==="slow"){if(X.push("Consider optimizing this query to reduce execution time"),Z.query.toLowerCase().includes("select *"))X.push("Specify only needed columns instead of using SELECT *");if(!Z.query.toLowerCase().includes("limit"))X.push("Consider adding LIMIT clause to reduce result set size")}return X}async function OO($){try{await v.insertInto("query_logs").values($).execute()}catch(Z){n1.error("Failed to store query log:",Z)}}import{log as i1}from"@stacksjs/logging";import{path as QO}from"@stacksjs/path";import{fs as d4}from"@stacksjs/storage";class u4{async call($){await new $().run()}}async function GO($={}){let Z=$.dir??QO.projectPath("database/seeders"),X=[],_=[];if(!d4.existsSync(Z))return i1.info(`[seeder] No class seeders directory at ${Z}`),{ran:X,skipped:_};let Y=d4.readdirSync(Z).filter((L)=>L.endsWith(".ts")&&!L.startsWith("_"));for(let L of Y){let z=L.replace(/\.ts$/,"");if($.class&&z!==$.class){_.push(z);continue}try{let j=await import(`${Z}/${L}`),U=j.default??j[z];if(!U){i1.warn(`[seeder] ${L} has no default export`),_.push(z);continue}let Q=new U;if(typeof Q.run!=="function"){i1.warn(`[seeder] ${z} does not implement run()`),_.push(z);continue}i1.info(`[seeder] Running ${z}\u2026`),await Q.run(),X.push(z)}catch(j){i1.error(`[seeder] ${z} failed:`,j),_.push(z)}}return{ran:X,skipped:_}}async function FO($,Z,X,_){let{type:Y,defaultValue:L,notNull:z=!1,batchSize:j=1000}=_,U=$,Q=L===void 0?"":` DEFAULT ${l4(L)}`;if(await u8(U,`ALTER TABLE ${c0(Z)} ADD COLUMN ${c0(X)} ${Y}${Q}`),L!==void 0)await s4($,Z,X,L,j);if(z)await u8(U,`ALTER TABLE ${c0(Z)} ALTER COLUMN ${c0(X)} SET NOT NULL`)}async function u8($,Z){if(typeof $.unsafe==="function")return await $.unsafe(Z)??{};return await u1`${u1.raw(Z)}`.execute($),{}}async function s4($,Z,X,_,Y=1000){let L=$,z=0,j=0;do{let U=`
       UPDATE ${c0(Z)} SET ${c0(X)} = ${l4(_)}
       WHERE ${c0(X)} IS NULL

package/dist/migrations.d.ts

@@ -0,0 +1,35 @@
+import type { Result } from '@stacksjs/error-handling';
+export type { MigrationResult as MigrationResultType };
+/**
+ * Run database migrations
+ */
+export declare function runDatabaseMigration(): Promise<Result<string, Error>>;
+/**
+ * Reset the database (drop all tables)
+ */
+export declare function resetDatabase(): Promise<Result<string, Error>>;
+/*` definitions to the stored snapshot
+ * (`.qb/model-snapshot.<dialect>.json`) via bun-query-builder, then — if
+ * there are changes — writes the resulting ALTER/CREATE/DROP statements
+ * out to a fresh file in `database/migrations/`. Each statement is
+ * grouped by table + DDL verb and lands in its own file using the
+ * runner's existing naming convention so it picks them up the same way
+ * as a hand-written migration.
+ *
+ * Without this write step the qb generator stages the diff in memory but
+ * the runner never sees it, so model edits silently no-op'd — defeating
+ * the "models are the source of truth" promise.
+ */
+export declare function generateMigrations(): Promise<Result<string, Error>>;
+/**
+ * Generate fresh migrations (full regeneration, ignoring previous state)
+ */
+export declare function generateMigrations2(): Promise<Result<string, Error>>;
+/**
+ * Migration result type for compatibility
+ */
+export declare interface MigrationResult {
+  migrationName: string
+  direction: 'Up' | 'Down'
+  status: 'Success' | 'Error' | 'NotExecuted'
+}

package/dist/query-logger.d.ts

@@ -0,0 +1,26 @@
+export declare function setQueryTracker(fn: QueryTracker): void;
+/**
+ * Process an executed query and store it in the database
+ */
+export declare function logQuery(event: LogEvent): Promise<void>;
+/**
+ * Query log event type - compatible with bun-query-builder hooks
+ */
+declare interface LogEvent {
+  query?: {
+    sql?: string
+    parameters?: unknown[]
+  }
+  queryDurationMillis?: number
+  error?: Error | unknown
+}
+/**
+ * Soft dependency on the router's query tracker. Importing it directly
+ * creates the cycle `database → router → database` (router uses db
+ * helpers transitively via middleware). The DI shape below lets the
+ * router register its tracker at module-init time and lets the database
+ * package stay leaf-node — runs that don't load the router (CLI tools,
+ * cron tasks) silently no-op the tracker call.
+ */
+// eslint-disable-next-line pickier/no-unused-vars
+declare type QueryTracker = (query: string, durationMs?: number, connection?: string) => void;

package/dist/query-parser.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Parse and normalize a SQL query
+ */
+export declare function parseQuery(sql: string): { normalized: string, type: string, tables: string[] };

package/dist/safe-migrations.d.ts

@@ -0,0 +1,72 @@
+import { db } from './utils';
+/**
+ * Add a column to `tableName` without taking a table-level lock long
+ * enough to disrupt traffic. The column is created nullable, backfilled
+ * in batches, and (if `notNull: true`) the constraint is added at the
+ * end.
+ *
+ * Pre-conditions:
+ *   - `tableName` exists
+ *   - `columnName` does NOT already exist (this helper doesn't gracefully
+ *     handle the rerun case — wrap in `if (!columnExists)` if you need that)
+ *
+ * Caveats:
+ *   - SQLite doesn't support adding NOT NULL columns to existing tables
+ *     without a default; we work around it by always supplying one
+ *   - Postgres < 11 rewrites the entire table when a default is added;
+ *     this helper assumes ≥ 11
+ *
+ * @example
+ * ```ts
+ * await addColumnSafely(db, 'users', 'email_verified', {
+ *   type: 'boolean',
+ *   defaultValue: false,
+ *   notNull: true,
+ * })
+ * ```
+ */
+export declare function addColumnSafely(db: Database, tableName: string, columnName: string, options: AddColumnSafelyOptions): Promise<void>;
+/**
+ * Back-fill `columnName` with `value` for any row where it's currently
+ * NULL. Runs in batches so the UPDATE doesn't lock the entire table.
+ *
+ * Useful as a standalone helper when you want to backfill an *existing*
+ * column (e.g. populating a denormalized count) — `addColumnSafely`
+ * uses it internally.
+ */
+export declare function backfillInBatches(db: Database, tableName: string, columnName: string, value: string | number | boolean | null, batchSize?: number): Promise<void>;
+/**
+ * Rename a column safely on a table that's actively serving traffic.
+ *
+ * Most database engines DO support `RENAME COLUMN` as a metadata-only
+ * operation (no rewrite, no long lock), which means the headline
+ * concern is *application-side*: app code reads the old column name,
+ * the migration renames it, and the next request 500s.
+ *
+ * This helper wraps the rename in a multi-step sequence the framework
+ * docs can teach as the canonical pattern:
+ *
+ *   1. Add the new column
+ *   2. Backfill from old → new
+ *   3. Update writes to dual-write old AND new (app-level, deploy step)
+ *   4. Update reads to read from new (app-level, deploy step)
+ *   5. Drop the old column (separate migration)
+ *
+ * For the rare case where the rename *can* happen atomically (small
+ * table, no live traffic), pass `{ atomic: true }` and we'll just emit
+ * the RENAME COLUMN.
+ *
+ * @example
+ * ```ts
+ * // Step 1 of the rename sequence — the rest is app-side coordination.
+ * await renameColumnSafely(db, 'users', 'name', 'full_name', { type: 'varchar(255)' })
+ * ```
+ */
+export declare function renameColumnSafely(db: Database, tableName: string, oldName: string, newName: string, options: { type: string, atomic?: boolean }): Promise<void>;
+declare interface AddColumnSafelyOptions {
+  type: string
+  defaultValue?: string | number | boolean | null
+  notNull?: boolean
+  batchSize?: number
+}
+declare type Database = typeof db;

package/dist/seeder.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Main seeding function
+ * Seeds the database using model factory functions
+ * Loads models from both framework defaults and user-defined models,
+ * with user models taking precedence.
+ */
+export declare function seed(config?: SeederConfig): Promise<SeedSummary>;
+/**
+ * Seed a specific model by name
+ * Searches both default and user models
+ */
+export declare function seedModel$(modelName: string, options?: { count?: number, fresh?: boolean, verbose?: boolean }): Promise<SeedResult>;
+/**
+ * Fresh seed - truncate all tables and reseed
+ */
+export declare function freshSeed(config?: SeederConfig): Promise<SeedSummary>;
+/**
+ * Get list of seedable models without seeding
+ * Returns models from both default and user directories
+ */
+export declare function listSeedableModels(): Promise<Array<{ name: string, table: string, count: number, source: 'default' | 'user' }>>;
+/**
+ * Seeder configuration options
+ */
+export declare interface SeederConfig {
+  modelsDir?: string
+  defaultCount?: number
+  verbose?: boolean
+  fresh?: boolean
+  only?: string[]
+  except?: string[]
+  includeDefaults?: boolean
+}
+/**
+ * Result of a single model seeding operation
+ */
+export declare interface SeedResult {
+  model: string
+  table: string
+  count: number
+  success: boolean
+  error?: string
+  duration: number
+}
+/**
+ * Result of the entire seeding operation
+ */
+export declare interface SeedSummary {
+  total: number
+  successful: number
+  failed: number
+  results: SeedResult[]
+  duration: number
+}
+// Legacy exports for backwards compatibility
+export { seed as runSeeders };
+export { freshSeed as freshWithSeed };

package/dist/sql-helpers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Create SQL dialect helpers for a given driver.
+ *
+ * @example
+ * ```ts
+ * import { sqlHelpers } from '@stacksjs/database'
+ * const sql = sqlHelpers('postgres')
+ * await db.unsafe(`SELECT * FROM users WHERE id = ${sql.param(1)}`, [userId])
+ * ```
+ */
+export declare function sqlHelpers(driver: string): SqlDialectHelpers;
+/**
+ * SQL Dialect Helpers
+ *
+ * Cross-database compatibility utilities for PostgreSQL, MySQL, and SQLite.
+ * Centralizes the isPostgres/isMysql/now/boolTrue/boolFalse/param helpers
+ * that were previously duplicated across tokens.ts, auth-tables.ts, and setup.ts.
+ */
+export declare interface SqlDialectHelpers {
+  driver: string
+  isPostgres: boolean
+  isMysql: boolean
+  isSqlite: boolean
+  now: string
+  boolTrue: string
+  boolFalse: string
+  autoIncrement: string
+  primaryKey: string
+  param: (index: number) => string
+  params: (...values: unknown[]) => { sql: string, values: unknown[] }
+}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * SQL template tag function.
+ * Creates parameterized SQL queries from template literals.
+ *
+ * @example
+ * ```ts
+ * const query = sql`SELECT * FROM users WHERE id = ${userId}`
+ * ```
+ */
+export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): Sql;
+/**
+ * Type for raw SQL expressions.
+ * Used when building dynamic SQL queries.
+ */
+export declare interface RawBuilder<T = unknown> {
+  readonly sql: string
+  readonly parameters?: unknown[]
+  readonly __result?: T
+}
+/**
+ * SQL template tag type.
+ * Used for tagged template literals that produce SQL.
+ */
+export declare interface Sql {
+  readonly sql: string
+  readonly parameters: unknown[]
+}
+/**
+ * Database types - Compatibility layer
+ *
+ * These types provide backwards compatibility with code that
+ * previously used Kysely types. They work with bun-query-builder's
+ * native type system.
+ */
+/**
+ * Marks a column as auto-generated (e.g., auto-increment primary keys).
+ * When inserting, this field is optional. When selecting, it's required.
+ */
+export type Generated<T> = T;
+/**
+ * Marks a column as always generated (computed columns).
+ * This field cannot be inserted or updated directly.
+ */
+export type GeneratedAlways<T> = T;
+/**
+ * Utility type for insert operations.
+ * Makes Generated fields optional, keeps required fields required.
+ */
+export type Insertable<T> = {
+  [K in keyof T]?: T[K]
+}
+/**
+ * Utility type for select operations.
+ * All fields are as defined in the table type.
+ */
+export type Selectable<T> = T;
+/**
+ * Utility type for update operations.
+ * All fields are optional since you may update only some fields.
+ */
+export type Updateable<T> = Partial<T>;
+/**
+ * Database type alias for backwards compatibility.
+ * Use the query builder from bun-query-builder instead.
+ */
+export type Database = any;

package/dist/utils.d.ts

@@ -0,0 +1,139 @@
+import { createQueryBuilder, setConfig } from 'bun-query-builder';
+import type { DatabaseSchema } from 'bun-query-builder';
+// Function to initialize the config when it's available
+export declare function initializeDbConfig(config: any): void;
+export declare function ensureDatabaseConfigLoaded(): Promise<void>;
+/**
+ * Lazy proxy for the query builder - connection is only made when first used.
+ * This is the main entry point for database operations.
+ */
+export declare const db: Proxy;
+/**
+ * Fluent chain returned by entry-point methods like `selectFrom`/`updateTable`.
+ *
+ * bun-query-builder marks legacy chain methods (e.g. `selectAll`, `whereILike`,
+ * `selectAllRelations`) as optional in its declarations even though they're
+ * always present at runtime. Re-typing them here avoids forcing every call
+ * site to use `?.()` or `!` on the chain.
+ *
+ * Returns are typed as `any` deliberately — typing each variant precisely
+ * would re-introduce the optional methods, and we already lose strict column
+ * typing one step into a chain (the underlying query builder is constructed
+ * with no schema). Tests cover the runtime semantics.
+ */
+export declare interface FluentChain {
+  where: (...args: any[]) => FluentChain
+  whereNull: (...args: any[]) => FluentChain
+  whereNotNull: (...args: any[]) => FluentChain
+  whereIn: (...args: any[]) => FluentChain
+  whereNotIn: (...args: any[]) => FluentChain
+  whereLike: (...args: any[]) => FluentChain
+  whereNotLike: (...args: any[]) => FluentChain
+  whereILike: (...args: any[]) => FluentChain
+  whereNotILike: (...args: any[]) => FluentChain
+  whereBetween: (...args: any[]) => FluentChain
+  whereNotBetween: (...args: any[]) => FluentChain
+  whereRaw: (...args: any[]) => FluentChain
+  whereColumn: (...args: any[]) => FluentChain
+  orWhere: (...args: any[]) => FluentChain
+  orWhereNull: (...args: any[]) => FluentChain
+  orWhereNotNull: (...args: any[]) => FluentChain
+  orWhereIn: (...args: any[]) => FluentChain
+  orWhereNotIn: (...args: any[]) => FluentChain
+  orWhereLike: (...args: any[]) => FluentChain
+  orWhereNotLike: (...args: any[]) => FluentChain
+  orWhereILike: (...args: any[]) => FluentChain
+  orWhereColumn: (...args: any[]) => FluentChain
+  andWhere: (...args: any[]) => FluentChain
+  having: (...args: any[]) => FluentChain
+  groupBy: (...args: any[]) => FluentChain
+  orderBy: (...args: any[]) => FluentChain
+  limit: (...args: any[]) => FluentChain
+  offset: (...args: any[]) => FluentChain
+  select: (...args: any[]) => FluentChain
+  selectAll: () => FluentChain
+  selectAllRelations: () => FluentChain
+  selectRaw: (...args: any[]) => FluentChain
+  distinct: () => FluentChain
+  distinctOn: (...args: any[]) => FluentChain
+  innerJoin: (...args: any[]) => FluentChain
+  leftJoin: (...args: any[]) => FluentChain
+  rightJoin: (...args: any[]) => FluentChain
+  fullJoin: (...args: any[]) => FluentChain
+  crossJoin: (...args: any[]) => FluentChain
+  with: (...args: any[]) => FluentChain
+  union: (...args: any[]) => FluentChain
+  unionAll: (...args: any[]) => FluentChain
+  values: (...args: any[]) => FluentChain
+  set: (...args: any[]) => FluentChain
+  returning: (...args: any[]) => FluentChain
+  returningAll: () => FluentChain
+  onConflict: (...args: any[]) => FluentChain
+  onDuplicateKeyUpdate: (...args: any[]) => FluentChain
+  onConflictDoNothing: (...args: any[]) => FluentChain
+  onDuplicateKeyIgnore: () => FluentChain
+  forUpdate: () => FluentChain
+  forShare: () => FluentChain
+  toSQL: () => string
+  execute: () => Promise<any>
+  executeTakeFirst: () => Promise<any>
+  executeTakeFirstOrThrow: () => Promise<any>
+  pluck: (...args: any[]) => Promise<any>
+  count: (...args: any[]) => Promise<number>
+  sum: (...args: any[]) => Promise<number>
+  avg: (...args: any[]) => Promise<number>
+  min: (...args: any[]) => Promise<any>
+  max: (...args: any[]) => Promise<any>
+  exists: () => Promise<boolean>
+  doesntExist: () => Promise<boolean>
+  [key: string]: any
+}
+// Permissive schema type that accepts any table name with any columns
+// This allows the query builder to work before model types are generated
+declare type AnySchema = DatabaseSchema<any> & Record<string, { columns: Record<string, any>, primaryKey: string }>;
+// The bun-query-builder types `unsafe()` as returning `Promise<any>`, but at
+// runtime it returns a Bun SQL Statement that has `.execute()`. This interface
+// corrects the return type so callers can chain `.execute()` without type errors.
+declare type UnsafeReturn = Promise<any> & { execute: () => Promise<any> }
+/**
+ * Top-level surface of the lazy `db` proxy. Methods that return a chainable
+ * builder are typed as `FluentChain` to flatten the optional-method noise
+ * inherent in bun-query-builder's declarations. Methods that introduce their
+ * own generics (`transaction<T>`, etc.) are kept as their original signatures
+ * via the underlying QueryBuilder type so call-site inference still works.
+ */
+declare type RawQueryBuilder = ReturnType<typeof createQueryBuilder>;
+declare type GenericPassthroughKeys = | 'transaction'
+  | 'savepoint'
+  | 'beginDistributed'
+  | 'transactional'
+  | 'configure'
+  | 'reserve'
+  | 'commitDistributed'
+  | 'rollbackDistributed'
+  | 'setTransactionDefaults'
+  | 'close'
+  | 'listen'
+  | 'unlisten'
+  | 'notify'
+  | 'copyTo'
+  | 'copyFrom'
+  | 'ping'
+  | 'waitForReady'
+  | 'count'
+  | 'sum'
+  | 'avg'
+  | 'min'
+  | 'max'
+  | 'insertOrIgnore'
+  | 'insertGetId'
+  | 'updateOrInsert'
+  | 'upsert'
+  | 'create'
+  | 'createMany'
+  | 'sql'
+  | 'raw'
+  | 'simple'
+  | 'file';
+// Export setConfig if available
+export { setConfig };

package/dist/validators.d.ts

@@ -0,0 +1,26 @@
+import type { BigintValidatorType, BinaryValidatorType, BlobValidatorType, BooleanValidatorType, DatetimeValidatorType, DateValidatorType, DecimalValidatorType, EnumValidatorType, FloatValidatorType, IntegerValidatorType, JsonValidatorType, NumberValidatorType, SmallintValidatorType, StringValidatorType, TimestampTzValidatorType, TimestampValidatorType, UnixValidatorType, ValidationType } from '@stacksjs/ts-validation';
+export declare function isStringValidator(v: ValidationType): v is StringValidatorType;
+export declare function isNumberValidator(v: ValidationType): v is NumberValidatorType;
+export declare function enumValidator(v: ValidationType): v is EnumValidatorType;
+export declare function isBooleanValidator(v: ValidationType): v is BooleanValidatorType;
+export declare function isDateValidator(v: ValidationType): v is DateValidatorType;
+export declare function isUnixValidator(v: ValidationType): v is UnixValidatorType;
+export declare function isFloatValidator(v: ValidationType): v is FloatValidatorType;
+export declare function isDatetimeValidator(v: ValidationType): v is DatetimeValidatorType;
+export declare function isTimestampValidator(v: ValidationType): v is TimestampValidatorType;
+export declare function isTimestampTzValidator(v: ValidationType): v is TimestampTzValidatorType;
+export declare function isDecimalValidator(v: ValidationType): v is DecimalValidatorType;
+export declare function isSmallintValidator(v: ValidationType): v is SmallintValidatorType;
+export declare function isIntegerValidator(v: ValidationType): v is IntegerValidatorType;
+export declare function isBigintValidator(v: ValidationType): v is BigintValidatorType;
+export declare function isBinaryValidator(v: ValidationType): v is BinaryValidatorType;
+export declare function isBlobValidator(v: ValidationType): v is BlobValidatorType;
+export declare function isJsonValidator(v: ValidationType): v is JsonValidatorType;
+export declare function checkValidator(validator: ValidationType, driver: string): string;
+export declare function prepareNumberColumnType(validator: NumberValidatorType, driver?: string): string;
+// Add new function for enum column types
+export declare function prepareEnumColumnType(validator: EnumValidatorType, driver?: string): string;
+export declare function prepareTextColumnType(validator: StringValidatorType, driver?: string): string;
+// Add new function for date/time column types
+export declare function prepareDateTimeColumnType(validator: DateValidatorType, driver?: string): string;
+export declare function findCharacterLength(validator: ValidationType): number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/database",
   "type": "module",
-  "version": "0.70.36",
+  "version": "0.70.38",
   "description": "The Stacks database integration.",
   "author": "Chris Breuer",
   "contributors": [
@@ -53,15 +53,15 @@
     "bun-query-builder": "^0.1.21"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.70.30",
-    "@stacksjs/config": "0.70.30",
-    "@stacksjs/logging": "0.70.30",
-    "@stacksjs/router": "0.70.30",
+    "@stacksjs/cli": "0.70.37",
+    "@stacksjs/config": "0.70.37",
+    "@stacksjs/logging": "0.70.37",
+    "@stacksjs/router": "0.70.37",
     "better-dx": "^0.2.12",
-    "@stacksjs/path": "0.70.30",
-    "@stacksjs/query-builder": "0.70.30",
-    "@stacksjs/storage": "0.70.30",
-    "@stacksjs/strings": "0.70.30",
-    "@stacksjs/utils": "0.70.30"
+    "@stacksjs/path": "0.70.37",
+    "@stacksjs/query-builder": "0.70.37",
+    "@stacksjs/storage": "0.70.37",
+    "@stacksjs/strings": "0.70.37",
+    "@stacksjs/utils": "0.70.37"
   }
 }