@dockstat/sqlite-wrapper 1.3.3 → 1.3.5

package/README.md

@@ -9,26 +9,31 @@ Schema-first table helpers, an expressive chainable QueryBuilder, safe defaults
 
 ---
 
-## 🆕 What's New in v1.3
-
-### Bug Fixes
-- **Fixed Boolean parsing** — Boolean columns now correctly convert SQLite's `0`/`1` to JavaScript `true`/`false`
-- **Fixed Wrong packing** — Before the `publish` script was added, workspace dependencies were not correctly propagated
+## 🆕 What's New in v1.3.5
 
 ### New Features
+
+- **Automatic Schema Migration** — Tables automatically migrate when schema changes are detected! Add/remove columns, change constraints, and preserve data without manual intervention
 - **Auto-detection of JSON & Boolean columns** — No more manual parser configuration! Columns using `column.json()` or `column.boolean()` are automatically detected from schema
 - **Automatic backups with retention** — Configure `autoBackup` to create periodic backups with automatic cleanup of old files
 - **Backup & Restore API** — New `backup()`, `restore()`, and `listBackups()` methods
 - **`getPath()` method** — Get the database file path
 
+### Bug Fixes
+
+- **Fixed Boolean parsing** — Boolean columns now correctly convert SQLite's `0`/`1` to JavaScript `true`/`false`
+- **Fixed Wrong packing** — Before the `publish` script was added, workspace dependencies were not correctly propagated
+
 ### Architecture Improvements
+
 - **New `utils/` module** — Reusable utilities for SQL building, logging, and row transformation
 - **Structured logging** — Cleaner, more consistent log output with dedicated loggers per component
 - **Reduced code duplication** — Extracted common patterns into shared utilities
 - **Better maintainability** — Clearer separation of concerns across modules
 
 ### Breaking Changes
-- None! v1.3 is fully backward compatible with v1.2.x
+
+- None! v1.4 is fully backward compatible with v1.3.x
 
 ---
 
@@ -96,6 +101,7 @@ const users = userTable
 - 🚀 Designed for production workflows: WAL, pragmatic PRAGMAs, bulk ops, transactions
 - 🔄 **Automatic JSON/Boolean detection** — no manual parser configuration needed
 - 💾 **Built-in backup & restore** — with automatic retention policies
+- 🔀 **Automatic Schema Migration** — seamlessly migrate tables when schemas change
 
 ---
 
@@ -217,6 +223,100 @@ const db = new DB("app.db", {
 
 ---
 
+## Automatic Schema Migration
+
+When you call `createTable()` with a schema that differs from an existing table, the wrapper automatically:
+
+1. **Detects schema changes** — Compares existing columns with your new definition
+2. **Migrates the table** — Creates a temporary table, copies data, and swaps tables
+3. **Preserves data** — Maps columns by name, uses defaults for new columns
+4. **Maintains indexes & triggers** — Recreates them after migration
+
+### Basic Migration Example
+
+```typescript
+// Initial table creation
+const users = db.createTable("users", {
+  id: column.id(),
+  name: column.text({ notNull: true }),
+});
+
+users.insert({ name: "Alice" });
+
+// Later: Add email column (automatic migration!)
+const updatedUsers = db.createTable("users", {
+  id: column.id(),
+  name: column.text({ notNull: true }),
+  email: column.text({ unique: true }), // New column
+});
+
+// Data is preserved, new column uses NULL or default
+const user = updatedUsers.where({ name: "Alice" }).first();
+console.log(user); // { id: 1, name: "Alice", email: null }
+```
+
+### Migration Options
+
+Control migration behavior with the `migrate` option:
+
+```typescript
+db.createTable("users", schema, {
+  migrate: true, // Default: enable migration
+  // OR provide detailed options:
+  migrate: {
+    preserveData: true, // Copy existing data (default: true)
+    dropMissingColumns: true, // Remove columns not in new schema (default: true)
+    onConflict: "fail", // How to handle constraint violations: "fail" | "ignore" | "replace"
+    tempTableSuffix: "_temp", // Suffix for temporary table during migration
+  },
+});
+```
+
+### Disable Migration
+
+For cases where you want to ensure a table matches an exact schema without migration:
+
+```typescript
+db.createTable("users", schema, {
+  migrate: false, // Disable migration
+  ifNotExists: true, // Avoid errors if table exists
+});
+```
+
+### Migration Features
+
+- **Automatic column mapping** — Columns with matching names are preserved
+- **Type conversions** — Best-effort conversion between compatible types
+- **Constraint handling** — Adds/removes constraints as needed
+- **Index preservation** — Indexes are recreated after migration
+- **Trigger preservation** — Triggers are recreated after migration
+- **Foreign key support** — Handles foreign key constraints properly
+- **Transaction safety** — Migration runs in a transaction, rolls back on error
+
+### When Migration Occurs
+
+Migration is triggered when `createTable()` detects:
+
+- **Column additions** — New columns in schema
+- **Column removals** — Missing columns from schema
+- **Constraint changes** — Different NOT NULL, UNIQUE, etc.
+- **Type changes** — Different column types
+
+### Migration Limitations
+
+- **Data loss possible** — Removing columns or adding NOT NULL without defaults
+- **Type incompatibility** — Some type conversions may fail
+- **Performance** — Large tables take time to migrate
+- **Downtime** — Table is briefly locked during migration
+
+For production systems with large tables, consider:
+
+- Running migrations during maintenance windows
+- Testing migrations on a copy first
+- Using `migrate: false` and handling manually for critical tables
+
+---
+
 ## Manual Backup & Restore
 
 ### Creating Backups
@@ -284,7 +384,10 @@ const activeAdmins = userTable
   .all();
 
 // Get first match
-const user = userTable.select(["*"]).where({ email: "alice@example.com" }).first();
+const user = userTable
+  .select(["*"])
+  .where({ email: "alice@example.com" })
+  .first();
 
 // Count records
 const count = userTable.where({ active: true }).count();
@@ -321,7 +424,10 @@ userTable.insertOrIgnore({ email: "existing@example.com", name: "Name" });
 userTable.insertOrReplace({ email: "existing@example.com", name: "New Name" });
 
 // Insert and get the row back
-const newUser = userTable.insertAndGet({ name: "Charlie", email: "charlie@example.com" });
+const newUser = userTable.insertAndGet({
+  name: "Charlie",
+  email: "charlie@example.com",
+});
 ```
 
 ### UPDATE Operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dockstat/sqlite-wrapper",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "A TypeScript wrapper around bun:sqlite with type-safe query building",
   "type": "module",
   "main": "./src/index.ts",

package/src/index.ts

@@ -1,9 +1,9 @@
 import { Database, type SQLQueryBindings } from "bun:sqlite"
 import { Logger } from "@dockstat/logger"
-import type { ColumnDefinition, IndexColumn, IndexMethod, Parser, TableOptions } from "./types"
 import { backup as helperBackup } from "./lib/backup/backup"
+import { listBackups as helperListBackups } from "./lib/backup/listBackups"
+import { restore as helperRestore } from "./lib/backup/restore"
 import { setupAutoBackup as helperSetupAutoBackup } from "./lib/backup/setupAutoBackup"
-
 // helpers
 import { createIndex as helperCreateIndex } from "./lib/index/createIndex"
 import { dropIndex as helperDropIndex } from "./lib/index/dropIndex"
@@ -12,10 +12,17 @@ import { buildTableConstraints } from "./lib/table/buildTableConstraint"
 import { getTableComment as helperGetTableComment } from "./lib/table/getTableComment"
 import { isTableSchema } from "./lib/table/isTableSchema"
 import { setTableComment as helperSetTableComment } from "./lib/table/setTableComment"
+import { checkAndMigrate, tableExists } from "./migration"
 import { QueryBuilder } from "./query-builder/index"
+import type {
+  ColumnDefinition,
+  IndexColumn,
+  IndexMethod,
+  Parser,
+  TableOptions,
+  MigrationOptions,
+} from "./types"
 import { createLogger, type SqliteLogger } from "./utils"
-import { listBackups as helperListBackups } from "./lib/backup/listBackups"
-import { restore as helperRestore } from "./lib/backup/restore"
 
 // Re-export all types and utilities
 export { QueryBuilder }
@@ -29,6 +36,7 @@ export type {
   ForeignKeyAction,
   InsertOptions,
   InsertResult,
+  MigrationOptions,
   RegexCondition,
   SQLiteType,
   TableConstraints,
@@ -87,6 +95,7 @@ class DB {
   private dbLog: SqliteLogger
   private backupLog: SqliteLogger
   private tableLog: SqliteLogger
+  private migrationLog: SqliteLogger
 
   /**
    * Open or create a SQLite database at `path`.
@@ -105,6 +114,7 @@ class DB {
     this.dbLog = createLogger("DB", this.baseLogger)
     this.backupLog = createLogger("Backup", this.baseLogger)
     this.tableLog = createLogger("Table", this.baseLogger)
+    this.migrationLog = createLogger("Migration", this.baseLogger)
 
     this.dbLog.connection(path, "open")
 
@@ -224,6 +234,49 @@ class DB {
     columns: Record<keyof _T, ColumnDefinition>,
     options?: TableOptions<_T>
   ): QueryBuilder<_T> {
+    // Handle migration if enabled (default: true)
+    const migrateOption = options?.migrate !== undefined ? options.migrate : true
+
+    // Check if table already exists
+    const tableAlreadyExists =
+      !options?.temporary && tableName !== ":memory:" && tableExists(this.db, tableName)
+
+    if (tableAlreadyExists) {
+      if (migrateOption !== false) {
+        // Migration is enabled, check if we need to migrate
+        const migrationOptions: MigrationOptions =
+          typeof migrateOption === "object" ? migrateOption : {}
+
+        // Build table constraints to pass to migration
+        let tableConstraints: string[] = []
+        if (isTableSchema(columns) && options?.constraints) {
+          tableConstraints = buildTableConstraints(options.constraints)
+        }
+
+        const migrated = checkAndMigrate(
+          this.db,
+          tableName,
+          columns as Record<string, ColumnDefinition>,
+          this.migrationLog,
+          migrationOptions,
+          tableConstraints
+        )
+
+        if (migrated) {
+          // Table was migrated, skip creation and go directly to parser setup
+          return this._setupTableParser(tableName, columns, options)
+        }
+      }
+
+      // Table exists and either:
+      // 1. Migration is disabled, or
+      // 2. Migration is enabled but no changes were needed
+      // In both cases, return the existing table without trying to create it
+      if (!options?.ifNotExists) {
+        return this._setupTableParser(tableName, columns, options)
+      }
+    }
+
     const temp = options?.temporary ? "TEMPORARY " : tableName === ":memory" ? "TEMPORARY " : ""
     const ifNot = options?.ifNotExists ? "IF NOT EXISTS " : ""
     const withoutRowId = options?.withoutRowId ? " WITHOUT ROWID" : ""
@@ -288,6 +341,17 @@ class DB {
       helperSetTableComment(this.db, this.tableLog, tableName, options.comment)
     }
 
+    return this._setupTableParser(tableName, columns, options)
+  }
+
+  /**
+   * Setup parser for table (extracted for reuse after migration)
+   */
+  private _setupTableParser<_T extends Record<string, unknown> = Record<string, unknown>>(
+    tableName: string,
+    columns: Record<keyof _T, ColumnDefinition>,
+    options?: TableOptions<_T>
+  ): QueryBuilder<_T> {
     // Auto-detect JSON and BOOLEAN columns from schema
     const autoDetectedJson: Array<keyof _T> = []
     const autoDetectedBoolean: Array<keyof _T> = []

package/src/migration.ts

@@ -0,0 +1,375 @@
+import type { Database } from "bun:sqlite"
+import type { ColumnDefinition, MigrationOptions } from "./types"
+import { buildColumnSQL } from "./lib/table/buildColumnSQL"
+import { SqliteLogger } from "./utils/logger"
+
+export interface TableColumn {
+  cid: number
+  name: string
+  type: string
+  notnull: number
+  dflt_value: string | number | null
+  pk: number
+}
+
+export interface IndexInfo {
+  name: string
+  sql: string | null
+  unique: boolean
+  origin: string
+  partial: number
+}
+
+export interface ForeignKeyInfo {
+  id: number
+  seq: number
+  table: string
+  from: string
+  to: string
+  on_update: string
+  on_delete: string
+  match: string
+}
+
+/**
+ * Get the current schema of a table
+ */
+export function getTableColumns(db: Database, tableName: string): TableColumn[] {
+  const stmt = db.prepare(`PRAGMA table_info("${tableName}")`)
+  return stmt.all() as TableColumn[]
+}
+
+/**
+ * Get indexes for a table
+ */
+export function getTableIndexes(db: Database, tableName: string): IndexInfo[] {
+  interface PragmaIndex {
+    seq: number
+    name: string
+    unique: number
+    origin: string
+    partial: number
+  }
+
+  interface SqliteMasterRow {
+    sql: string | null
+  }
+
+  const stmt = db.prepare(`PRAGMA index_list("${tableName}")`)
+  const indexes = stmt.all() as PragmaIndex[]
+
+  return indexes.map((idx) => {
+    const infoStmt = db.prepare(`PRAGMA index_info("${idx.name}")`)
+    infoStmt.all() // Execute but don't need the result for this use case
+
+    // Get the CREATE INDEX statement if available
+    const sqlStmt = db.prepare(`SELECT sql FROM sqlite_master WHERE type = 'index' AND name = ?`)
+    const sqlResult = sqlStmt.get(idx.name) as SqliteMasterRow | null
+
+    return {
+      name: idx.name,
+      sql: sqlResult?.sql || null,
+      unique: idx.unique === 1,
+      origin: idx.origin,
+      partial: idx.partial,
+    }
+  })
+}
+
+/**
+ * Get foreign keys for a table
+ */
+export function getTableForeignKeys(db: Database, tableName: string): ForeignKeyInfo[] {
+  const stmt = db.prepare(`PRAGMA foreign_key_list("${tableName}")`)
+  return stmt.all() as ForeignKeyInfo[]
+}
+
+/**
+ * Get triggers for a table
+ */
+export function getTableTriggers(
+  db: Database,
+  tableName: string
+): Array<{ name: string; sql: string }> {
+  const stmt = db.prepare(
+    `SELECT name, sql FROM sqlite_master WHERE type = 'trigger' AND tbl_name = ?`
+  )
+  return stmt.all(tableName) as Array<{ name: string; sql: string }>
+}
+
+/**
+ * Check if a table exists
+ */
+export function tableExists(db: Database, tableName: string): boolean {
+  const stmt = db.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+  const result = stmt.get(tableName)
+  return result !== null
+}
+
+/**
+ * Compare two schemas to determine if migration is needed
+ */
+export function schemasAreDifferent(
+  currentSchema: TableColumn[],
+  newColumns: Record<string, ColumnDefinition>,
+  logger: SqliteLogger
+): boolean {
+  logger.info("Comparing schemas")
+  const currentColumnNames = new Set(currentSchema.map((col) => col.name))
+  const newColumnNames = new Set(Object.keys(newColumns))
+
+  // Check if column count differs
+  if (currentColumnNames.size !== newColumnNames.size) {
+    logger.info("Column count differs")
+    return true
+  }
+
+  // Check if all column names match
+  for (const name of newColumnNames) {
+    if (!currentColumnNames.has(name)) {
+      logger.info(`Column ${name} does not exist`)
+      return true
+    }
+    logger.debug(`Column ${name} exists`)
+  }
+
+  // Check column definitions
+  for (const currentCol of currentSchema) {
+    const newCol = newColumns[currentCol.name]
+    if (!newCol) {
+      logger.info(`Column ${currentCol.name} does not exist`)
+      return true
+    }
+
+    // For primary key columns, SQLite auto-adds AUTOINCREMENT which we need to account for
+    const isCurrentPK = currentCol.pk === 1
+    const isNewPK = newCol.primaryKey === true || newCol.autoincrement === true
+
+    // If both are primary keys, consider them the same (don't check other constraints)
+    if (isCurrentPK && isNewPK) {
+      logger.info(`Column ${currentCol.name} is a primary key`)
+      continue
+    }
+
+    if (isCurrentPK !== isNewPK) {
+      logger.info(
+        `Column ${currentCol.name} primary key status differs (current: ${isCurrentPK}, new: ${isNewPK})`
+      )
+      return true
+    }
+
+    // Check if NOT NULL constraint differs (ignore for primary keys as they're always NOT NULL)
+    if (!isCurrentPK) {
+      const isCurrentNotNull = currentCol.notnull === 1
+      const isNewNotNull = newCol.notNull === true
+      if (isCurrentNotNull !== isNewNotNull) {
+        logger.info(
+          `Column ${currentCol.name} NOT NULL constraint differs (current: ${isCurrentNotNull}, new: ${isNewNotNull})`
+        )
+        return true
+      }
+    }
+
+    // Basic type comparison (normalize types)
+    const normalizeType = (type: string) => type.toUpperCase().split("(")[0].trim()
+    const currentType = normalizeType(currentCol.type)
+    const newType = normalizeType(newCol.type)
+
+    // Handle type aliases
+    const typeAliases: Record<string, string> = {
+      INT: "INTEGER",
+      BOOL: "INTEGER",
+      BOOLEAN: "INTEGER",
+      JSON: "TEXT",
+      VARCHAR: "TEXT",
+      CHAR: "TEXT",
+      DATETIME: "TEXT",
+      DATE: "TEXT",
+      TIMESTAMP: "TEXT",
+    }
+
+    const normalizedCurrentType = typeAliases[currentType] || currentType
+    const normalizedNewType = typeAliases[newType] || newType
+
+    if (normalizedCurrentType !== normalizedNewType) {
+      logger.info(`Column ${currentCol.name} type differs`)
+      return true
+    }
+  }
+
+  logger.info("No schema changes detected")
+  return false
+}
+
+/**
+ * Generate column mapping for data migration
+ */
+export function generateColumnMapping(
+  currentSchema: TableColumn[],
+  newColumns: Record<string, ColumnDefinition>
+): { selectColumns: string[]; insertColumns: string[] } {
+  const currentColumnNames = new Set(currentSchema.map((col) => col.name))
+  const newColumnNames = Object.keys(newColumns)
+
+  // Find common columns
+  const commonColumns = newColumnNames.filter((name) => currentColumnNames.has(name))
+
+  return {
+    selectColumns: commonColumns,
+    insertColumns: commonColumns,
+  }
+}
+
+/**
+ * Migrate a table to a new schema
+ */
+export function migrateTable(
+  db: Database,
+  tableName: string,
+  newColumns: Record<string, ColumnDefinition>,
+  options: MigrationOptions = {},
+  tableConstraints: string[] = [],
+  migrationLog: SqliteLogger
+): void {
+  const { preserveData = true, onConflict = "fail", tempTableSuffix = "_migration_temp" } = options
+
+  migrationLog.info(`Starting migration for table: ${tableName}`)
+
+  // Get current table info
+  const currentSchema = getTableColumns(db, tableName)
+  const indexes = getTableIndexes(db, tableName)
+  const triggers = getTableTriggers(db, tableName)
+
+  // Check if migration is needed
+  if (!schemasAreDifferent(currentSchema, newColumns, migrationLog)) {
+    migrationLog.info(`No migration needed for table: ${tableName}`)
+    return
+  }
+
+  const tempTableName = `${tableName}${tempTableSuffix}`
+
+  // Start transaction for atomic migration
+  db.transaction(() => {
+    try {
+      // Step 1: Create temporary table with new schema
+      migrationLog.debug(`Creating temporary table: ${tempTableName}`)
+      const columnDefs: string[] = []
+
+      for (const [colName, colDef] of Object.entries(newColumns)) {
+        const sqlDef = buildColumnSQL(colName, colDef)
+        columnDefs.push(`"${colName}" ${sqlDef}`)
+      }
+
+      // Include table constraints if provided
+      const allDefinitions =
+        tableConstraints.length > 0
+          ? [...columnDefs, ...tableConstraints].join(", ")
+          : columnDefs.join(", ")
+
+      const createTempTableSql = `CREATE TABLE "${tempTableName}" (${allDefinitions})`
+      db.run(createTempTableSql)
+
+      // Step 2: Copy data if requested
+      if (preserveData && currentSchema.length > 0) {
+        const { selectColumns, insertColumns } = generateColumnMapping(currentSchema, newColumns)
+
+        if (selectColumns.length > 0) {
+          migrationLog.debug(`Copying data from ${tableName} to ${tempTableName}`)
+
+          const quotedSelectCols = selectColumns.map((col) => `"${col}"`).join(", ")
+          const quotedInsertCols = insertColumns.map((col) => `"${col}"`).join(", ")
+
+          let copySql = `INSERT INTO "${tempTableName}" (${quotedInsertCols})
+                         SELECT ${quotedSelectCols} FROM "${tableName}"`
+
+          if (onConflict === "ignore") {
+            copySql = `INSERT OR IGNORE INTO "${tempTableName}" (${quotedInsertCols})
+                       SELECT ${quotedSelectCols} FROM "${tableName}"`
+          } else if (onConflict === "replace") {
+            copySql = `INSERT OR REPLACE INTO "${tempTableName}" (${quotedInsertCols})
+                       SELECT ${quotedSelectCols} FROM "${tableName}"`
+          }
+
+          db.run(copySql)
+        }
+      }
+
+      // Step 3: Drop the original table
+      migrationLog.debug(`Dropping original table: ${tableName}`)
+
+      // Temporarily disable foreign key constraints
+      interface ForeignKeyStatus {
+        foreign_keys: number
+      }
+      const fkStatus = db.prepare("PRAGMA foreign_keys").get() as ForeignKeyStatus | null
+      if (fkStatus && fkStatus.foreign_keys === 1) {
+        db.run("PRAGMA foreign_keys = OFF")
+      }
+
+      db.run(`DROP TABLE "${tableName}"`)
+
+      // Step 4: Rename temporary table to original name
+      migrationLog.debug(`Renaming ${tempTableName} to ${tableName}`)
+      db.run(`ALTER TABLE "${tempTableName}" RENAME TO "${tableName}"`)
+
+      // Step 5: Recreate indexes
+      for (const index of indexes) {
+        if (index.sql && !index.sql.includes("sqlite_autoindex")) {
+          migrationLog.debug(`Recreating index: ${index.name}`)
+          try {
+            db.run(index.sql)
+          } catch (err) {
+            migrationLog.warn(`Failed to recreate index ${index.name}: ${err}`)
+          }
+        }
+      }
+
+      // Step 6: Recreate triggers
+      for (const trigger of triggers) {
+        migrationLog.debug(`Recreating trigger: ${trigger.name}`)
+        try {
+          db.run(trigger.sql)
+        } catch (err) {
+          migrationLog.warn(`Failed to recreate trigger ${trigger.name}: ${err}`)
+        }
+      }
+
+      // Re-enable foreign key constraints if they were enabled
+      if (fkStatus && fkStatus.foreign_keys === 1) {
+        db.run("PRAGMA foreign_keys = ON")
+      }
+
+      migrationLog.info(`Successfully migrated table: ${tableName}`)
+    } catch (error) {
+      migrationLog.error(`Migration failed for table ${tableName}: ${error}`)
+      throw error
+    }
+  })()
+}
+
+/**
+ * Check if migration is needed and perform if necessary
+ */
+export function checkAndMigrate(
+  db: Database,
+  tableName: string,
+  newColumns: Record<string, ColumnDefinition>,
+  migrationLog: SqliteLogger,
+  options?: MigrationOptions,
+  tableConstraints: string[] = []
+): boolean {
+  const logger = new SqliteLogger(tableName, migrationLog.getBaseLogger())
+
+  if (!tableExists(db, tableName)) {
+    return false // No existing table, no migration needed
+  }
+
+  const currentSchema = getTableColumns(db, tableName)
+
+  if (schemasAreDifferent(currentSchema, newColumns, logger)) {
+    migrateTable(db, tableName, newColumns, options, tableConstraints, migrationLog)
+    return true
+  }
+
+  return false
+}

package/src/query-builder/select.ts

@@ -175,8 +175,36 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
     return result
   }
 
+  private logSelectStart(
+    method: string,
+    details: { query?: string; optimizedQuery?: string; params?: unknown }
+  ): void {
+    const { query, optimizedQuery, params } = details
+    const q = query ?? optimizedQuery ?? ""
+    this.selectLog.info(
+      `${method} | ${query ? "query" : "optimizedQuery"}=${q} params=${WhereQueryBuilder.safeStringify(params)}`
+    )
+  }
+
+  private logSelectReturn(
+    method: string,
+    details: { returned?: unknown; length?: number; sample?: unknown }
+  ): void {
+    const { returned, length, sample } = details
+    if (length !== undefined && sample !== undefined) {
+      this.selectLog.info(
+        `${method} | returned=${length} sample=${WhereQueryBuilder.safeStringify(sample)}`
+      )
+    } else {
+      this.selectLog.info(`${method} | returned=${WhereQueryBuilder.safeStringify(returned)}`)
+    }
+  }
+
   // ===== Execution Methods =====
 
+  // Use the protected static helper inherited from WhereQueryBuilder: `safeStringify`
+  // (Removed duplicate implementation to avoid static-side conflicts with the base class.)
+
   /**
    * Execute the query and return all matching rows
    *
@@ -187,20 +215,22 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
     const hasRegex = this.hasRegexConditions()
     const [query, params] = this.buildSelectQuery(!hasRegex)
 
+    this.logSelectStart("all", { query, params })
     this.selectLog.query("SELECT", query, params)
 
     const rows = this.getDb()
       .prepare(query)
       .all(...params) as T[]
-
     this.selectLog.result("SELECT", rows.length)
 
-    // Transform rows (JSON/Boolean parsing)
     const transformed = this.transformRowsFromDb(rows)
-
-    // Apply client-side operations if needed
     const result = hasRegex ? this.applyClientSideOperations(transformed) : transformed
 
+    this.logSelectReturn("all", {
+      length: result.length,
+      sample: result[0] ?? null,
+    })
+
     this.reset()
     return result
   }
@@ -211,42 +241,43 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
    * Respects LIMIT if set, otherwise adds LIMIT 1 for efficiency
    */
   get(): T | null {
-    // If no regex and no explicit limit, optimize with LIMIT 1
     if (!this.hasRegexConditions() && this.limitValue === undefined) {
       const [query, params] = this.buildSelectQuery(true)
       const optimizedQuery = `${query} LIMIT 1`
 
+      this.logSelectStart("get", { optimizedQuery, params })
       this.selectLog.query("SELECT (get)", optimizedQuery, params)
 
       const row = this.getDb()
         .prepare(optimizedQuery)
         .get(...params) as T | null
-
       this.selectLog.result("SELECT (get)", row ? 1 : 0)
 
       const result = row ? this.transformRowFromDb(row) : null
+      this.logSelectReturn("get", { returned: result })
+
       this.reset()
       return result
     }
 
-    // If limit is set or regex conditions exist, use standard flow
     if (!this.hasRegexConditions()) {
       const [query, params] = this.buildSelectQuery(true)
 
+      this.logSelectStart("get", { query, params })
       this.selectLog.query("SELECT (get)", query, params)
 
       const row = this.getDb()
         .prepare(query)
         .get(...params) as T | null
-
       this.selectLog.result("SELECT (get)", row ? 1 : 0)
 
       const result = row ? this.transformRowFromDb(row) : null
+      this.logSelectReturn("get", { returned: result })
+
       this.reset()
       return result
     }
 
-    // Has regex conditions - fall back to all() and take first
     const results = this.all()
     return results[0] ?? null
   }
@@ -268,21 +299,23 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
    */
   count(): number {
     if (!this.hasRegexConditions()) {
-      // Use SQL COUNT for efficiency
       const [whereClause, whereParams] = this.buildWhereClause()
       const query = `SELECT COUNT(*) AS __count FROM ${quoteIdentifier(this.getTableName())}${whereClause}`
 
+      this.logSelectStart("count", { query, params: whereParams })
       this.selectLog.query("COUNT", query, whereParams)
 
       const result = this.getDb()
         .prepare(query)
         .get(...whereParams) as { __count: number } | null
 
+      const count = result?.__count ?? 0
       this.reset()
-      return result?.__count ?? 0
+
+      this.logSelectReturn("count", { returned: count })
+      return count
     }
 
-    // Has regex conditions - count client-side
     const results = this.all()
     return results.length
   }
@@ -292,44 +325,58 @@ export class SelectQueryBuilder<T extends Record<string, unknown>> extends Where
    */
   exists(): boolean {
     if (!this.hasRegexConditions()) {
-      // Use EXISTS for efficiency
       const [whereClause, whereParams] = this.buildWhereClause()
       const subquery = `SELECT 1 FROM ${quoteIdentifier(this.getTableName())}${whereClause} LIMIT 1`
       const query = `SELECT EXISTS(${subquery}) AS __exists`
 
+      this.logSelectStart("exists", { query, params: whereParams })
       this.selectLog.query("EXISTS", query, whereParams)
 
       const result = this.getDb()
         .prepare(query)
         .get(...whereParams) as { __exists: number } | null
 
+      const exists = Boolean(result?.__exists)
       this.reset()
-      return Boolean(result?.__exists)
+
+      this.logSelectReturn("exists", { returned: exists })
+      return exists
     }
 
-    // Has regex conditions - check client-side
     return this.count() > 0
   }
 
+  private logColumnReturn(method: "value" | "pluck", column: string, returned: unknown): void {
+    this.selectLog.info(
+      `${method} | column=${column} returned=${WhereQueryBuilder.safeStringify(returned)}`
+    )
+  }
+
   /**
-   * Get a single column value from the first matching row
+   * Get an array of values from a single column
    *
    * @example
-   * const name = table.where({ id: 1 }).value("name")
+   * const emails = table.where({ active: true }).pluck("email")
    */
-  value<K extends keyof T>(column: K): T[K] | null {
-    const row = this.first()
-    return row ? row[column] : null
+  pluck<K extends keyof T>(column: K): T[K][] {
+    const rows = this.all() || []
+    const values = rows.map((row) => row[column])
+
+    this.logColumnReturn("pluck", String(column), values)
+    return values
   }
 
   /**
-   * Get an array of values from a single column
+   * Get a single column value from the first matching row
    *
    * @example
-   * const emails = table.where({ active: true }).pluck("email")
+   * const name = table.where({ id: 1 }).value("name")
    */
-  pluck<K extends keyof T>(column: K): T[K][] {
-    const rows = this.all()
-    return rows.map((row) => row[column])
+  value<K extends keyof T>(column: K): T[K] | null {
+    const row = this.first()
+    const value = row ? row[column] : null
+
+    this.logColumnReturn("value", String(column), value)
+    return value
   }
 }

package/src/query-builder/where.ts

@@ -1,6 +1,12 @@
 import type { SQLQueryBindings } from "bun:sqlite"
 import type { RegexCondition, WhereCondition } from "../types"
-import { buildBetweenClause, buildInClause, normalizeOperator, quoteIdentifier } from "../utils"
+import {
+  buildBetweenClause,
+  buildInClause,
+  normalizeOperator,
+  quoteIdentifier,
+  truncate,
+} from "../utils"
 import { BaseQueryBuilder } from "./base"
 
 /**
@@ -17,6 +23,20 @@ import { BaseQueryBuilder } from "./base"
  */
 export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQueryBuilder<T> {
   // ===== Private Helpers =====
+  protected logWhere(method: string, data: Record<string, unknown>): void {
+    const parts = Object.entries(data).map(
+      ([key, value]) => `${key}=${WhereQueryBuilder.safeStringify(value)}`
+    )
+    this.log.info(`${method} | ${parts.join(" ")}`)
+  }
+
+  protected logWhereState(method: string, extra: Record<string, unknown> = {}): void {
+    this.logWhere(method, {
+      whereConditions: this.state.whereConditions,
+      whereParams: this.state.whereParams,
+      ...extra,
+    })
+  }
 
   /**
    * Remove an existing condition for a column to prevent duplicates
@@ -54,6 +74,16 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
 
   // ===== Public WHERE Methods =====
 
+  // Helper to stringify values safely (converts RegExp to string and falls back)
+  protected static safeStringify(obj: unknown): string {
+    try {
+      const dat = JSON.stringify(obj, (_k, v) => (v instanceof RegExp ? v.toString() : v))
+      return truncate(dat, 100)
+    } catch {
+      return truncate(String(obj), 100)
+    }
+  }
+
   /**
    * Add simple equality conditions to the WHERE clause
    *
@@ -66,6 +96,8 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "deleted_at" IS NULL
    */
   where(conditions: WhereCondition<T>): this {
+    this.logWhere("where", { conditions })
+
     for (const [column, value] of Object.entries(conditions)) {
       this.removeExistingCondition(column)
 
@@ -76,6 +108,8 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
         this.state.whereParams.push(this.toSqliteValue(value))
       }
     }
+
+    this.logWhereState("where")
     return this
   }
 
@@ -86,6 +120,9 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * .whereRgx({ email: /@gmail\.com$/ })
    */
   whereRgx(conditions: RegexCondition<T>): this {
+    // Log invocation with a safe serializer for regex values
+    this.log.info(`whereRgx | conditions=${WhereQueryBuilder.safeStringify(conditions)}`)
+
     for (const [column, value] of Object.entries(conditions)) {
       this.removeExistingCondition(column)
 
@@ -105,6 +142,10 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
         this.state.whereParams.push(value as SQLQueryBindings)
       }
     }
+
+    // Log resulting WHERE/regex state
+    this.logWhereState("whereRgx", { regexConditions: this.state.regexConditions })
+
     return this
   }
 
@@ -116,6 +157,9 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * .whereExpr("created_at > datetime('now', '-1 day')")
    */
   whereExpr(expr: string, params: SQLQueryBindings[] = []): this {
+    // Log invocation
+    this.log.info(`whereExpr | expr=${expr} params=${WhereQueryBuilder.safeStringify(params)}`)
+
     if (!expr || typeof expr !== "string") {
       throw new Error("whereExpr: expression must be a non-empty string")
     }
@@ -127,6 +171,13 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
       this.state.whereParams.push(...params)
     }
 
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereExpr | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -134,6 +185,8 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * Alias for whereExpr
    */
   whereRaw(expr: string, params: SQLQueryBindings[] = []): this {
+    // Log alias invocation
+    this.log.info(`whereRaw | expr=${expr} params=${WhereQueryBuilder.safeStringify(params)}`)
     return this.whereExpr(expr, params)
   }
 
@@ -145,6 +198,11 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "status" IN (?, ?)
    */
   whereIn(column: keyof T, values: SQLQueryBindings[]): this {
+    // Log invocation
+    this.log.info(
+      `whereIn | column=${String(column)} values=${WhereQueryBuilder.safeStringify(values)}`
+    )
+
     if (!Array.isArray(values) || values.length === 0) {
       throw new Error("whereIn: values must be a non-empty array")
     }
@@ -155,6 +213,13 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
     this.state.whereConditions.push(sql)
     this.state.whereParams.push(...params)
 
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereIn | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -166,6 +231,11 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "role" NOT IN (?, ?)
    */
   whereNotIn(column: keyof T, values: SQLQueryBindings[]): this {
+    // Log invocation
+    this.log.info(
+      `whereNotIn | column=${String(column)} values=${WhereQueryBuilder.safeStringify(values)}`
+    )
+
     if (!Array.isArray(values) || values.length === 0) {
       throw new Error("whereNotIn: values must be a non-empty array")
     }
@@ -176,6 +246,13 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
     this.state.whereConditions.push(sql)
     this.state.whereParams.push(...params)
 
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereNotIn | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -189,17 +266,20 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * .whereOp("name", "LIKE", "%smith%")
    */
   whereOp(column: keyof T, op: string, value: SQLQueryBindings): this {
-    const normalizedOp = normalizeOperator(op)
     const columnStr = String(column)
+    this.logWhere("whereOp", { column: columnStr, op, value })
+
+    const normalizedOp = normalizeOperator(op)
 
-    // Handle NULL special cases
     if (value === null || value === undefined) {
       if (normalizedOp === "=" || normalizedOp === "IS") {
         this.state.whereConditions.push(`${quoteIdentifier(columnStr)} IS NULL`)
+        this.logWhere("whereOp", { column: columnStr, added: "IS NULL" })
         return this
       }
       if (normalizedOp === "!=" || normalizedOp === "<>" || normalizedOp === "IS NOT") {
         this.state.whereConditions.push(`${quoteIdentifier(columnStr)} IS NOT NULL`)
+        this.logWhere("whereOp", { column: columnStr, added: "IS NOT NULL" })
         return this
       }
     }
@@ -207,6 +287,7 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
     this.state.whereConditions.push(`${quoteIdentifier(columnStr)} ${normalizedOp} ?`)
     this.state.whereParams.push(value)
 
+    this.logWhereState("whereOp")
     return this
   }
 
@@ -218,12 +299,26 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "age" BETWEEN ? AND ?
    */
   whereBetween(column: keyof T, min: SQLQueryBindings, max: SQLQueryBindings): this {
+    // Log invocation
+    this.log.info(
+      `whereBetween | column=${String(column)} min=${WhereQueryBuilder.safeStringify(min)} max=${WhereQueryBuilder.safeStringify(
+        max
+      )}`
+    )
+
     this.removeExistingCondition(String(column), "BETWEEN")
 
     const { sql, params } = buildBetweenClause(String(column), min, max, false)
     this.state.whereConditions.push(sql)
     this.state.whereParams.push(...params)
 
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereBetween | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -235,12 +330,26 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "score" NOT BETWEEN ? AND ?
    */
   whereNotBetween(column: keyof T, min: SQLQueryBindings, max: SQLQueryBindings): this {
+    // Log invocation
+    this.log.info(
+      `whereNotBetween | column=${String(column)} min=${WhereQueryBuilder.safeStringify(min)} max=${WhereQueryBuilder.safeStringify(
+        max
+      )}`
+    )
+
     this.removeExistingCondition(String(column), "NOT BETWEEN")
 
     const { sql, params } = buildBetweenClause(String(column), min, max, true)
     this.state.whereConditions.push(sql)
     this.state.whereParams.push(...params)
 
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereNotBetween | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -252,8 +361,19 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "deleted_at" IS NULL
    */
   whereNull(column: keyof T): this {
+    // Log invocation
+    this.log.info(`whereNull | column=${String(column)}`)
+
     this.removeExistingCondition(String(column))
     this.state.whereConditions.push(`${quoteIdentifier(String(column))} IS NULL`)
+
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereNull | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 
@@ -265,8 +385,19 @@ export class WhereQueryBuilder<T extends Record<string, unknown>> extends BaseQu
    * // WHERE "email" IS NOT NULL
    */
   whereNotNull(column: keyof T): this {
+    // Log invocation
+    this.log.info(`whereNotNull | column=${String(column)}`)
+
     this.removeExistingCondition(String(column))
     this.state.whereConditions.push(`${quoteIdentifier(String(column))} IS NOT NULL`)
+
+    // Log resulting WHERE clause state
+    this.log.info(
+      `whereNotNull | whereConditions=${WhereQueryBuilder.safeStringify(this.state.whereConditions)} params=${WhereQueryBuilder.safeStringify(
+        this.state.whereParams
+      )}`
+    )
+
     return this
   }
 }

package/src/types.ts

@@ -237,6 +237,17 @@ export interface TableConstraints<T> {
 /**
  * Enhanced table options
  */
+export interface MigrationOptions {
+  /** Whether to preserve data during migration (default: true) */
+  preserveData?: boolean
+  /** Whether to drop columns not in new schema (default: true) */
+  dropMissingColumns?: boolean
+  /** How to handle constraint violations during data copy */
+  onConflict?: "fail" | "ignore" | "replace"
+  /** Suffix for temporary table during migration (default: '_migration_temp') */
+  tempTableSuffix?: string
+}
+
 export interface TableOptions<T> {
   /** Add IF NOT EXISTS clause */
   ifNotExists?: boolean
@@ -248,6 +259,8 @@ export interface TableOptions<T> {
   temporary?: boolean
   /** Table comment */
   comment?: string
+  /** Enable automatic schema migration (default: true) */
+  migrate?: boolean | MigrationOptions
 
   parser?: Partial<Parser<T>>
 }
@@ -461,9 +474,9 @@ export const column = {
   /**
    * Create a foreign key reference column
    */
-  foreignKey: (
+  foreignKey: <_T extends Record<string, unknown>>(
     refTable: string,
-    refColumn = "id",
+    refColumn: keyof _T = "id",
     constraints?: ColumnConstraints & {
       onDelete?: ForeignKeyAction
       onUpdate?: ForeignKeyAction
@@ -473,7 +486,7 @@ export const column = {
     type: constraints?.type || SQLiteTypes.INTEGER,
     references: {
       table: refTable,
-      column: refColumn,
+      column: String(refColumn),
       onDelete: constraints?.onDelete,
       onUpdate: constraints?.onUpdate,
     },

package/src/utils/index.ts

@@ -44,3 +44,5 @@ export {
   transformRowsToDb,
   transformToDb,
 } from "./transformer"
+
+export * from "./truncate"

package/src/utils/truncate.ts

@@ -0,0 +1,6 @@
+export function truncate(str: string, maxLength: number, suffix = "..."): string {
+  if (str.length <= maxLength) {
+    return str
+  }
+  return str.slice(0, maxLength) + suffix
+}