@mantiq/database 0.1.3 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Query builder, Eloquent-style ORM, schema migrations, seeders, and factories for MantiqJS. Supports SQLite, Postgres, MySQL, and MongoDB.
 
-Part of [MantiqJS](https://github.com/abdullahkhan/mantiq) — a batteries-included TypeScript web framework for Bun.
+Part of [MantiqJS](https://github.com/mantiqjs/mantiq) — a batteries-included TypeScript web framework for Bun.
 
 ## Installation
 
@@ -12,7 +12,7 @@ bun add @mantiq/database
 
 ## Documentation
 
-See the [MantiqJS repository](https://github.com/abdullahkhan/mantiq) for full documentation.
+See the [MantiqJS repository](https://github.com/mantiqjs/mantiq) for full documentation.
 
 ## License
 

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@mantiq/database",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Query builder, ORM, migrations, seeders, factories — with SQLite, Postgres, MySQL and MongoDB support",
   "type": "module",
   "license": "MIT",
   "author": "Abdullah Khan",
-  "homepage": "https://github.com/abdullahkhan/mantiq/tree/main/packages/database",
+  "homepage": "https://github.com/mantiqjs/mantiq/tree/main/packages/database",
   "repository": {
     "type": "git",
-    "url": "https://github.com/abdullahkhan/mantiq.git",
+    "url": "https://github.com/mantiqjs/mantiq.git",
     "directory": "packages/database"
   },
   "bugs": {
-    "url": "https://github.com/abdullahkhan/mantiq/issues"
+    "url": "https://github.com/mantiqjs/mantiq/issues"
   },
   "keywords": [
     "mantiq",
@@ -40,7 +40,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --packages=external",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"

package/src/contracts/Connection.ts

@@ -1,10 +1,23 @@
-import type { QueryBuilder } from '../query/Builder.ts'
+import type { QueryBuilder, QueryState } from '../query/Builder.ts'
 import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
 
 export interface DatabaseConnection {
+  // ── Universal execution (works on ALL drivers) ──────────────────────────
+  executeSelect(state: QueryState): Promise<Record<string, any>[]>
+  executeInsert(table: string, data: Record<string, any>): Promise<number>
+  executeInsertGetId(table: string, data: Record<string, any>): Promise<number | string>
+  executeUpdate(table: string, state: QueryState, data: Record<string, any>): Promise<number>
+  executeDelete(table: string, state: QueryState): Promise<number>
+  executeTruncate(table: string): Promise<void>
+  executeAggregate(state: QueryState, fn: 'count' | 'sum' | 'avg' | 'min' | 'max', column: string): Promise<number>
+  executeExists(state: QueryState): Promise<boolean>
+
+  // ── Raw SQL escape hatch (throws DriverNotSupportedError on non-SQL) ───
   select(sql: string, bindings?: any[]): Promise<Record<string, any>[]>
   statement(sql: string, bindings?: any[]): Promise<number>
-  insertGetId(sql: string, bindings?: any[]): Promise<number | bigint>
+  insertGetId(sql: string, bindings?: any[]): Promise<number | bigint | string>
+
+  // ── Shared ──────────────────────────────────────────────────────────────
   transaction<T>(callback: (connection: DatabaseConnection) => Promise<T>): Promise<T>
   table(name: string): QueryBuilder
   schema(): SchemaBuilder

package/src/drivers/BaseSQLConnection.ts

@@ -0,0 +1,111 @@
+import type { DatabaseConnection } from '../contracts/Connection.ts'
+import type { Grammar } from '../contracts/Grammar.ts'
+import type { QueryState } from '../query/Builder.ts'
+import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
+import { QueryBuilder } from '../query/Builder.ts'
+import { Expression } from '../query/Expression.ts'
+
+/**
+ * Abstract base for all SQL connections. Provides `executeXxx()` methods
+ * by compiling QueryState via Grammar and delegating to the raw SQL methods
+ * that each driver must implement.
+ */
+export abstract class BaseSQLConnection implements DatabaseConnection {
+  abstract readonly _grammar: Grammar
+
+  // ── Subclasses implement these (raw SQL execution) ──────────────────────
+  abstract select(sql: string, bindings?: any[]): Promise<Record<string, any>[]>
+  abstract statement(sql: string, bindings?: any[]): Promise<number>
+  abstract insertGetId(sql: string, bindings?: any[]): Promise<number | bigint | string>
+  abstract transaction<T>(callback: (connection: DatabaseConnection) => Promise<T>): Promise<T>
+  abstract schema(): SchemaBuilder
+  abstract getDriverName(): string
+
+  getTablePrefix(): string {
+    return ''
+  }
+
+  table(name: string): QueryBuilder {
+    return new QueryBuilder(this, name)
+  }
+
+  // ── Universal executeXxx (compile via Grammar → run via raw methods) ────
+
+  async executeSelect(state: QueryState): Promise<Record<string, any>[]> {
+    const { sql, bindings } = this._grammar.compileSelect(state)
+    return this.select(sql, bindings)
+  }
+
+  async executeInsert(table: string, data: Record<string, any>): Promise<number> {
+    const { sql, bindings } = this._grammar.compileInsert(table, data)
+    return this.statement(sql, bindings)
+  }
+
+  async executeInsertGetId(table: string, data: Record<string, any>): Promise<number | string> {
+    const { sql, bindings } = this._grammar.compileInsertGetId(table, data)
+    const id = await this.insertGetId(sql, bindings)
+    // SQL drivers always return numeric IDs (bigint from SQLite, string from pg for BIGSERIAL)
+    return Number(id)
+  }
+
+  async executeUpdate(table: string, state: QueryState, data: Record<string, any>): Promise<number> {
+    const { sql, bindings } = this._grammar.compileUpdate(table, state, data)
+    return this.statement(sql, bindings)
+  }
+
+  async executeDelete(table: string, state: QueryState): Promise<number> {
+    const { sql, bindings } = this._grammar.compileDelete(table, state)
+    return this.statement(sql, bindings)
+  }
+
+  async executeTruncate(table: string): Promise<void> {
+    const sql = this._grammar.compileTruncate(table)
+    await this.statement(sql, [])
+  }
+
+  async executeAggregate(state: QueryState, fn: 'count' | 'sum' | 'avg' | 'min' | 'max', column: string): Promise<number> {
+    const aggState: QueryState = {
+      ...state,
+      columns: [new Expression(`${fn.toUpperCase()}(${column}) as aggregate`)],
+      orders: [],  // aggregates don't need ORDER BY
+    }
+    const { sql, bindings } = this._grammar.compileSelect(aggState)
+    const rows = await this.select(sql, bindings)
+    return Number(rows[0]?.['aggregate'] ?? 0)
+  }
+
+  async executeExists(state: QueryState): Promise<boolean> {
+    const existsState: QueryState = {
+      ...state,
+      columns: [new Expression('1 as exists_check')],
+      limitValue: 1,
+      orders: [],
+    }
+    const { sql, bindings } = this._grammar.compileSelect(existsState)
+    const rows = await this.select(sql, bindings)
+    return rows.length > 0
+  }
+
+  /**
+   * Creates executeXxx methods for a transactional connection wrapper.
+   * Call this in transaction() to give the txConn the universal methods.
+   */
+  protected applyExecuteMethods(txConn: any): void {
+    txConn.executeSelect = (state: QueryState) =>
+      BaseSQLConnection.prototype.executeSelect.call({ ...txConn, _grammar: this._grammar }, state)
+    txConn.executeInsert = (table: string, data: Record<string, any>) =>
+      BaseSQLConnection.prototype.executeInsert.call({ ...txConn, _grammar: this._grammar }, table, data)
+    txConn.executeInsertGetId = (table: string, data: Record<string, any>) =>
+      BaseSQLConnection.prototype.executeInsertGetId.call({ ...txConn, _grammar: this._grammar }, table, data)
+    txConn.executeUpdate = (table: string, state: QueryState, data: Record<string, any>) =>
+      BaseSQLConnection.prototype.executeUpdate.call({ ...txConn, _grammar: this._grammar }, table, state, data)
+    txConn.executeDelete = (table: string, state: QueryState) =>
+      BaseSQLConnection.prototype.executeDelete.call({ ...txConn, _grammar: this._grammar }, table, state)
+    txConn.executeTruncate = (table: string) =>
+      BaseSQLConnection.prototype.executeTruncate.call({ ...txConn, _grammar: this._grammar }, table)
+    txConn.executeAggregate = (state: QueryState, fn: string, column: string) =>
+      BaseSQLConnection.prototype.executeAggregate.call({ ...txConn, _grammar: this._grammar }, state, fn, column)
+    txConn.executeExists = (state: QueryState) =>
+      BaseSQLConnection.prototype.executeExists.call({ ...txConn, _grammar: this._grammar }, state)
+  }
+}

package/src/drivers/MSSQLConnection.ts

@@ -1,5 +1,6 @@
 import type { DatabaseConnection } from '../contracts/Connection.ts'
 import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
+import { BaseSQLConnection } from './BaseSQLConnection.ts'
 import { QueryBuilder } from '../query/Builder.ts'
 import { MSSQLGrammar } from './MSSQLGrammar.ts'
 import { SchemaBuilderImpl } from '../schema/SchemaBuilder.ts'
@@ -17,12 +18,13 @@ export interface MSSQLConfig {
   pool?: { min?: number; max?: number }
 }
 
-export class MSSQLConnection implements DatabaseConnection {
+export class MSSQLConnection extends BaseSQLConnection {
   readonly _grammar = new MSSQLGrammar()
   private pool: any = null
   private config: MSSQLConfig
 
   constructor(config: MSSQLConfig) {
+    super()
     this.config = config
   }
 
@@ -100,33 +102,33 @@ export class MSSQLConnection implements DatabaseConnection {
     const transaction = new sql.Transaction(pool)
     await transaction.begin()
     try {
-      const txConn: DatabaseConnection = {
-        select: async (s, b = []) => {
+      const txConn: any = {
+        _grammar: this._grammar,
+        select: async (s: string, b: any[] = []) => {
           const req = transaction.request()
           b.forEach((val: any, i: number) => req.input(`p${i + 1}`, val))
           const r = await req.query(s)
           return r.recordset ?? []
         },
-        statement: async (s, b = []) => {
+        statement: async (s: string, b: any[] = []) => {
           const req = transaction.request()
           b.forEach((val: any, i: number) => req.input(`p${i + 1}`, val))
           const r = await req.query(s)
           return r.rowsAffected?.[0] ?? 0
         },
-        insertGetId: async (s, b = []) => {
+        insertGetId: async (s: string, b: any[] = []) => {
           const req = transaction.request()
           b.forEach((val: any, i: number) => req.input(`p${i + 1}`, val))
           const r = await req.query(s)
           return r.recordset?.[0]?.id ?? 0
         },
-        transaction: (cb) => cb(txConn),
-        table: (name) => new QueryBuilder(txConn, name),
+        transaction: (cb: any) => cb(txConn),
+        table: (name: string) => new QueryBuilder(txConn, name),
         schema: () => new SchemaBuilderImpl(txConn),
         getDriverName: () => 'mssql',
         getTablePrefix: () => '',
       }
-      // @ts-ignore — attach grammar
-      txConn._grammar = this._grammar
+      this.applyExecuteMethods(txConn)
       const result = await callback(txConn)
       await transaction.commit()
       return result
@@ -136,10 +138,6 @@ export class MSSQLConnection implements DatabaseConnection {
     }
   }
 
-  table(name: string): QueryBuilder {
-    return new QueryBuilder(this, name)
-  }
-
   schema(): SchemaBuilder {
     return new SchemaBuilderImpl(this)
   }
@@ -147,8 +145,4 @@ export class MSSQLConnection implements DatabaseConnection {
   getDriverName(): string {
     return 'mssql'
   }
-
-  getTablePrefix(): string {
-    return ''
-  }
 }

package/src/drivers/MongoConnection.ts

@@ -1,5 +1,6 @@
+import type { DatabaseConnection } from '../contracts/Connection.ts'
+import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
 import type {
-  MongoDatabaseConnection,
   MongoCollectionContract,
   MongoFilter,
   MongoUpdateDoc,
@@ -10,9 +11,12 @@ import type {
   MongoDeleteResult,
   MongoQueryBuilder,
 } from '../contracts/MongoConnection.ts'
+import type { QueryState, WhereClause } from '../query/Builder.ts'
+import { QueryBuilder } from '../query/Builder.ts'
+import { Expression } from '../query/Expression.ts'
 import { MongoQueryBuilderImpl } from './MongoQueryBuilderImpl.ts'
 import { ConnectionError } from '../errors/ConnectionError.ts'
-import { QueryError } from '../errors/QueryError.ts'
+import { DriverNotSupportedError } from '../errors/DriverNotSupportedError.ts'
 
 export interface MongoConfig {
   uri: string
@@ -20,149 +24,146 @@ export interface MongoConfig {
   options?: Record<string, any>
 }
 
-class MongoCollectionImpl implements MongoCollectionContract {
-  constructor(
-    private readonly col: any,
-    private readonly name: string,
-  ) {}
+// ── Operator translation map ──────────────────────────────────────────────────
 
-  find(filter: MongoFilter = {}): MongoQueryBuilder {
-    return new MongoQueryBuilderImpl(
-      this.name,
-      async (opts) => {
-        let cursor = this.col.find(opts.filter ?? {})
-        if (opts.projection) cursor = cursor.project(opts.projection)
-        if (opts.sort) cursor = cursor.sort(opts.sort)
-        if (opts.skip) cursor = cursor.skip(opts.skip)
-        if (opts.limit) cursor = cursor.limit(opts.limit)
-        return cursor.toArray()
-      },
-      async (f) => this.col.countDocuments(f),
-    )
-  }
+const OPERATOR_MAP: Record<string, string> = {
+  '=': '$eq',
+  '!=': '$ne',
+  '<>': '$ne',
+  '>': '$gt',
+  '>=': '$gte',
+  '<': '$lt',
+  '<=': '$lte',
+}
 
-  async findOne(filter: MongoFilter = {}): Promise<Record<string, any> | null> {
-    return this.col.findOne(filter)
-  }
+// ── MongoConnection — implements the universal DatabaseConnection interface ──
 
-  async findById(id: any): Promise<Record<string, any> | null> {
-    const { ObjectId } = await import('mongodb')
-    return this.col.findOne({ _id: typeof id === 'string' ? new ObjectId(id) : id })
-  }
+export class MongoConnection implements DatabaseConnection {
+  private client: any = null
+  private db: any = null
+  private config: MongoConfig
 
-  async insertOne(doc: Record<string, any>): Promise<MongoInsertResult> {
-    const result = await this.col.insertOne(doc)
-    return { insertedId: result.insertedId, acknowledged: result.acknowledged }
+  constructor(config: MongoConfig) {
+    this.config = config
   }
 
-  async insertMany(docs: Record<string, any>[]): Promise<MongoInsertManyResult> {
-    const result = await this.col.insertMany(docs)
-    return {
-      insertedIds: Object.values(result.insertedIds),
-      acknowledged: result.acknowledged,
-      insertedCount: result.insertedCount,
+  private async getDb(): Promise<any> {
+    if (!this.db) {
+      try {
+        const { MongoClient } = await import('mongodb')
+        this.client = new MongoClient(this.config.uri, this.config.options ?? {})
+        await this.client.connect()
+        this.db = this.client.db(this.config.database)
+      } catch (e: any) {
+        throw new ConnectionError(`MongoDB connection failed: ${e.message}`, 'mongodb', e)
+      }
     }
+    return this.db
   }
 
-  async updateOne(filter: MongoFilter, update: MongoUpdateDoc): Promise<MongoUpdateResult> {
-    const result = await this.col.updateOne(filter, update)
-    return { matchedCount: result.matchedCount, modifiedCount: result.modifiedCount, acknowledged: result.acknowledged }
-  }
+  // ── Universal executeXxx methods ──────────────────────────────────────────
 
-  async updateMany(filter: MongoFilter, update: MongoUpdateDoc): Promise<MongoUpdateResult> {
-    const result = await this.col.updateMany(filter, update)
-    return { matchedCount: result.matchedCount, modifiedCount: result.modifiedCount, acknowledged: result.acknowledged }
-  }
+  async executeSelect(state: QueryState): Promise<Record<string, any>[]> {
+    this.guardNoJoins(state)
+    this.guardNoHavings(state)
 
-  async replaceOne(filter: MongoFilter, replacement: Record<string, any>): Promise<MongoUpdateResult> {
-    const result = await this.col.replaceOne(filter, replacement)
-    return { matchedCount: result.matchedCount, modifiedCount: result.modifiedCount, acknowledged: result.acknowledged }
+    const db = await this.getDb()
+    const col = db.collection(state.table)
+    const filter = this.translateWheres(state.wheres)
+    const projection = this.translateColumns(state.columns)
+    const sort = this.translateOrders(state.orders)
+
+    let cursor = col.find(filter)
+    if (projection) cursor = cursor.project(projection)
+    if (sort) cursor = cursor.sort(sort)
+    if (state.offsetValue !== null) cursor = cursor.skip(state.offsetValue)
+    if (state.limitValue !== null) cursor = cursor.limit(state.limitValue)
+
+    return cursor.toArray()
   }
 
-  async upsert(filter: MongoFilter, update: MongoUpdateDoc): Promise<MongoUpdateResult> {
-    const result = await this.col.updateOne(filter, update, { upsert: true })
-    return { matchedCount: result.matchedCount, modifiedCount: result.modifiedCount, acknowledged: result.acknowledged }
+  async executeInsert(table: string, data: Record<string, any>): Promise<number> {
+    const db = await this.getDb()
+    const result = await db.collection(table).insertOne(data)
+    return result.acknowledged ? 1 : 0
   }
 
-  async deleteOne(filter: MongoFilter): Promise<MongoDeleteResult> {
-    const result = await this.col.deleteOne(filter)
-    return { deletedCount: result.deletedCount, acknowledged: result.acknowledged }
+  async executeInsertGetId(table: string, data: Record<string, any>): Promise<number | string> {
+    const db = await this.getDb()
+    const result = await db.collection(table).insertOne(data)
+    const id = result.insertedId
+    return typeof id === 'object' ? id.toString() : id
   }
 
-  async deleteMany(filter: MongoFilter): Promise<MongoDeleteResult> {
-    const result = await this.col.deleteMany(filter)
-    return { deletedCount: result.deletedCount, acknowledged: result.acknowledged }
+  async executeUpdate(table: string, state: QueryState, data: Record<string, any>): Promise<number> {
+    const db = await this.getDb()
+    const filter = this.translateWheres(state.wheres)
+    const result = await db.collection(table).updateMany(filter, { $set: data })
+    return result.modifiedCount
   }
 
-  async aggregate(pipeline: MongoPipelineStage[]): Promise<Record<string, any>[]> {
-    return this.col.aggregate(pipeline).toArray()
+  async executeDelete(table: string, state: QueryState): Promise<number> {
+    const db = await this.getDb()
+    const filter = this.translateWheres(state.wheres)
+    const result = await db.collection(table).deleteMany(filter)
+    return result.deletedCount
   }
 
-  async count(filter: MongoFilter = {}): Promise<number> {
-    return this.col.countDocuments(filter)
+  async executeTruncate(table: string): Promise<void> {
+    const db = await this.getDb()
+    await db.collection(table).deleteMany({})
   }
 
-  async createIndex(spec: Record<string, any>, options?: Record<string, any>): Promise<string> {
-    return this.col.createIndex(spec, options)
+  async executeAggregate(state: QueryState, fn: 'count' | 'sum' | 'avg' | 'min' | 'max', column: string): Promise<number> {
+    const db = await this.getDb()
+    const filter = this.translateWheres(state.wheres)
+
+    if (fn === 'count') {
+      return db.collection(state.table).countDocuments(filter)
+    }
+
+    const aggOp = `$${fn}`
+    const aggField = column === '*' ? 1 : `$${column}`
+    const pipeline: any[] = [
+      { $match: filter },
+      { $group: { _id: null, result: { [aggOp]: aggField } } },
+    ]
+    const [row] = await db.collection(state.table).aggregate(pipeline).toArray()
+    return Number(row?.result ?? 0)
   }
 
-  async drop(): Promise<boolean> {
-    return this.col.drop()
+  async executeExists(state: QueryState): Promise<boolean> {
+    const db = await this.getDb()
+    const filter = this.translateWheres(state.wheres)
+    const count = await db.collection(state.table).countDocuments(filter, { limit: 1 })
+    return count > 0
   }
-}
 
-export class MongoConnection implements MongoDatabaseConnection {
-  private client: any = null
-  private db: any = null
-  private config: MongoConfig
+  // ── Raw SQL methods — throw on MongoDB ────────────────────────────────────
 
-  constructor(config: MongoConfig) {
-    this.config = config
+  async select(sql: string, bindings?: any[]): Promise<Record<string, any>[]> {
+    throw new DriverNotSupportedError('mongodb', 'raw SQL queries')
   }
 
-  private async getDb(): Promise<any> {
-    if (!this.db) {
-      try {
-        const { MongoClient } = await import('mongodb')
-        this.client = new MongoClient(this.config.uri, this.config.options ?? {})
-        await this.client.connect()
-        this.db = this.client.db(this.config.database)
-      } catch (e: any) {
-        throw new ConnectionError(`MongoDB connection failed: ${e.message}`, 'mongodb', e)
-      }
-    }
-    return this.db
+  async statement(sql: string, bindings?: any[]): Promise<number> {
+    throw new DriverNotSupportedError('mongodb', 'raw SQL queries')
   }
 
-  collection(name: string): MongoCollectionContract {
-    // Lazily get collection — actual DB ops will connect
-    const self = this
-    const col = {
-      async getCol() {
-        const db = await self.getDb()
-        return db.collection(name)
-      },
-    }
-
-    // We need to return a proxy that defers the actual collection resolution
-    return new LazyMongoCollection(name, async () => {
-      const db = await self.getDb()
-      return db.collection(name)
-    })
+  async insertGetId(sql: string, bindings?: any[]): Promise<number | bigint | string> {
+    throw new DriverNotSupportedError('mongodb', 'raw SQL queries')
   }
 
-  async command(command: Record<string, any>): Promise<any> {
-    const db = await this.getDb()
-    return db.command(command)
+  // ── Shared interface ──────────────────────────────────────────────────────
+
+  table(name: string): QueryBuilder {
+    return new QueryBuilder(this, name)
   }
 
-  async listCollections(): Promise<string[]> {
-    const db = await this.getDb()
-    const collections = await db.listCollections().toArray()
-    return collections.map((c: any) => c.name)
+  schema(): SchemaBuilder {
+    throw new DriverNotSupportedError('mongodb', 'schema builder (MongoDB is schemaless — use native() for indexes)')
   }
 
-  async transaction<T>(callback: (conn: MongoDatabaseConnection) => Promise<T>): Promise<T> {
+  async transaction<T>(callback: (conn: DatabaseConnection) => Promise<T>): Promise<T> {
     const client = await this.getClient()
     const session = client.startSession()
     try {
@@ -179,22 +180,194 @@ export class MongoConnection implements MongoDatabaseConnection {
     }
   }
 
-  private async getClient(): Promise<any> {
-    await this.getDb()
-    return this.client
-  }
-
   getDriverName(): string {
     return 'mongodb'
   }
 
+  getTablePrefix(): string {
+    return ''
+  }
+
+  // ── Native escape hatch — direct MongoDB access ───────────────────────────
+
+  /** Returns the native MongoDB collection for advanced operations. */
+  collection(name: string): MongoCollectionContract {
+    return new LazyMongoCollection(name, async () => {
+      const db = await this.getDb()
+      return db.collection(name)
+    })
+  }
+
+  /** Returns the underlying MongoDB Db instance. */
+  async native(): Promise<any> {
+    return this.getDb()
+  }
+
+  async command(command: Record<string, any>): Promise<any> {
+    const db = await this.getDb()
+    return db.command(command)
+  }
+
+  async listCollections(): Promise<string[]> {
+    const db = await this.getDb()
+    const collections = await db.listCollections().toArray()
+    return collections.map((c: any) => c.name)
+  }
+
   async disconnect(): Promise<void> {
     await this.client?.close()
     this.client = null
     this.db = null
   }
+
+  private async getClient(): Promise<any> {
+    await this.getDb()
+    return this.client
+  }
+
+  // ── QueryState → MongoDB translation ──────────────────────────────────────
+
+  private translateWheres(wheres: WhereClause[]): Record<string, any> {
+    if (wheres.length === 0) return {}
+
+    const andClauses: Record<string, any>[] = []
+    const orGroups: Record<string, any>[][] = []
+    let currentAnd: Record<string, any>[] = []
+
+    for (const w of wheres) {
+      const clause = this.translateSingleWhere(w)
+
+      if (w.boolean === 'or' && currentAnd.length > 0) {
+        // Push accumulated AND clauses as one OR branch
+        orGroups.push(currentAnd)
+        currentAnd = [clause]
+      } else {
+        currentAnd.push(clause)
+      }
+    }
+
+    // Final group
+    if (orGroups.length > 0) {
+      orGroups.push(currentAnd)
+      return { $or: orGroups.map((group) => group.length === 1 ? group[0] : { $and: group }) }
+    }
+
+    if (currentAnd.length === 1) return currentAnd[0]
+    return { $and: currentAnd }
+  }
+
+  private translateSingleWhere(w: WhereClause): Record<string, any> {
+    switch (w.type) {
+      case 'basic': {
+        const col = w.column!
+        const op = w.operator ?? '='
+        const val = w.value
+
+        if (op === '=' || op === '$eq') {
+          return { [col]: val }
+        }
+
+        if (op === 'like' || op === 'LIKE') {
+          return { [col]: { $regex: this.likeToRegex(val), $options: 'i' } }
+        }
+
+        if (op === 'not like' || op === 'NOT LIKE') {
+          return { [col]: { $not: { $regex: this.likeToRegex(val), $options: 'i' } } }
+        }
+
+        const mongoOp = OPERATOR_MAP[op]
+        if (mongoOp) {
+          return { [col]: { [mongoOp]: val } }
+        }
+
+        throw new DriverNotSupportedError('mongodb', `operator "${op}"`)
+      }
+
+      case 'in':
+        return { [w.column!]: { $in: w.values! } }
+
+      case 'notIn':
+        return { [w.column!]: { $nin: w.values! } }
+
+      case 'null':
+        return { [w.column!]: null }
+
+      case 'notNull':
+        return { [w.column!]: { $ne: null } }
+
+      case 'between':
+        return { [w.column!]: { $gte: w.range![0], $lte: w.range![1] } }
+
+      case 'nested':
+        return this.translateWheres(w.nested ?? [])
+
+      case 'raw':
+        throw new DriverNotSupportedError('mongodb', 'whereRaw (use standard where methods instead)')
+
+      case 'column':
+        throw new DriverNotSupportedError('mongodb', 'whereColumn (use $expr in native queries instead)')
+
+      default:
+        throw new DriverNotSupportedError('mongodb', `where type "${w.type}"`)
+    }
+  }
+
+  private translateColumns(columns: (string | Expression)[]): Record<string, 1> | undefined {
+    if (columns.length === 1 && columns[0] === '*') return undefined
+    if (columns.some((c) => c instanceof Expression)) {
+      // Allow expressions only if they're simple strings (column names)
+      // For actual SQL expressions, throw
+      const hasRealExpressions = columns.some((c) => c instanceof Expression && (c.value.includes('(') || c.value.includes(' ')))
+      if (hasRealExpressions) {
+        throw new DriverNotSupportedError('mongodb', 'selectRaw with SQL expressions')
+      }
+    }
+
+    const projection: Record<string, 1> = {}
+    for (const col of columns) {
+      const name = col instanceof Expression ? col.value : col
+      projection[name] = 1
+    }
+    return projection
+  }
+
+  private translateOrders(orders: Array<{ column: string | Expression; direction: 'asc' | 'desc' }>): Record<string, 1 | -1> | undefined {
+    if (orders.length === 0) return undefined
+    const sort: Record<string, 1 | -1> = {}
+    for (const o of orders) {
+      if (o.column instanceof Expression) {
+        throw new DriverNotSupportedError('mongodb', 'orderBy with raw Expression')
+      }
+      sort[o.column] = o.direction === 'asc' ? 1 : -1
+    }
+    return sort
+  }
+
+  /** Converts SQL LIKE pattern to regex: % → .*, _ → . */
+  private likeToRegex(pattern: string): string {
+    return pattern
+      .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      .replace(/%/g, '.*')
+      .replace(/_/g, '.')
+  }
+
+  // ── Guards ────────────────────────────────────────────────────────────────
+
+  private guardNoJoins(state: QueryState): void {
+    if (state.joins.length > 0) {
+      throw new DriverNotSupportedError('mongodb', 'joins (use relationships or native $lookup instead)')
+    }
+  }
+
+  private guardNoHavings(state: QueryState): void {
+    if (state.havings.length > 0) {
+      throw new DriverNotSupportedError('mongodb', 'having (use native aggregation pipeline instead)')
+    }
+  }
 }
 
+// ── LazyMongoCollection — deferred collection resolution ────────────────────
+
 class LazyMongoCollection implements MongoCollectionContract {
   private _col: any = null
 

package/src/drivers/MySQLConnection.ts

@@ -1,5 +1,6 @@
 import type { DatabaseConnection } from '../contracts/Connection.ts'
 import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
+import { BaseSQLConnection } from './BaseSQLConnection.ts'
 import { QueryBuilder } from '../query/Builder.ts'
 import { MySQLGrammar } from './MySQLGrammar.ts'
 import { SchemaBuilderImpl } from '../schema/SchemaBuilder.ts'
@@ -15,12 +16,13 @@ export interface MySQLConfig {
   pool?: { min?: number; max?: number }
 }
 
-export class MySQLConnection implements DatabaseConnection {
+export class MySQLConnection extends BaseSQLConnection {
   readonly _grammar = new MySQLGrammar()
   private pool: any = null
   private config: MySQLConfig
 
   constructor(config: MySQLConfig) {
+    super()
     this.config = config
   }
 
@@ -79,18 +81,18 @@ export class MySQLConnection implements DatabaseConnection {
     const conn = await pool.getConnection()
     try {
       await conn.beginTransaction()
-      const txConn: DatabaseConnection = {
-        select: async (sql, b) => { const [rows] = await conn.query(sql, b); return rows as Record<string, any>[] },
-        statement: async (sql, b) => { const [r] = await conn.query(sql, b); return (r as any).affectedRows ?? 0 },
-        insertGetId: async (sql, b) => { const [r] = await conn.query(sql, b); return (r as any).insertId ?? 0 },
-        transaction: (cb) => cb(txConn),
-        table: (name) => new QueryBuilder(txConn, name),
+      const txConn: any = {
+        _grammar: this._grammar,
+        select: async (sql: string, b?: any[]) => { const [rows] = await conn.query(sql, b); return rows as Record<string, any>[] },
+        statement: async (sql: string, b?: any[]) => { const [r] = await conn.query(sql, b); return (r as any).affectedRows ?? 0 },
+        insertGetId: async (sql: string, b?: any[]) => { const [r] = await conn.query(sql, b); return (r as any).insertId ?? 0 },
+        transaction: (cb: any) => cb(txConn),
+        table: (name: string) => new QueryBuilder(txConn, name),
         schema: () => new SchemaBuilderImpl(txConn),
         getDriverName: () => 'mysql',
         getTablePrefix: () => '',
       }
-      // @ts-ignore — attach grammar
-      txConn._grammar = this._grammar
+      this.applyExecuteMethods(txConn)
       const result = await callback(txConn)
       await conn.commit()
       return result
@@ -102,10 +104,6 @@ export class MySQLConnection implements DatabaseConnection {
     }
   }
 
-  table(name: string): QueryBuilder {
-    return new QueryBuilder(this, name)
-  }
-
   schema(): SchemaBuilder {
     return new SchemaBuilderImpl(this)
   }
@@ -113,8 +111,4 @@ export class MySQLConnection implements DatabaseConnection {
   getDriverName(): string {
     return 'mysql'
   }
-
-  getTablePrefix(): string {
-    return ''
-  }
 }

package/src/drivers/PostgresConnection.ts

@@ -1,5 +1,6 @@
 import type { DatabaseConnection } from '../contracts/Connection.ts'
 import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
+import { BaseSQLConnection } from './BaseSQLConnection.ts'
 import { QueryBuilder } from '../query/Builder.ts'
 import { PostgresGrammar } from './PostgresGrammar.ts'
 import { SchemaBuilderImpl } from '../schema/SchemaBuilder.ts'
@@ -16,12 +17,13 @@ export interface PostgresConfig {
   pool?: { min?: number; max?: number }
 }
 
-export class PostgresConnection implements DatabaseConnection {
+export class PostgresConnection extends BaseSQLConnection {
   readonly _grammar = new PostgresGrammar()
   private client: any = null
   private config: PostgresConfig
 
   constructor(config: PostgresConfig) {
+    super()
     this.config = config
   }
 
@@ -83,19 +85,18 @@ export class PostgresConnection implements DatabaseConnection {
     const client = await pool.connect()
     try {
       await client.query('BEGIN')
-      // Create a transactional connection wrapper
-      const txConn: DatabaseConnection = {
-        select: async (sql, b) => { const r = await client.query(sql, b); return r.rows },
-        statement: async (sql, b) => { const r = await client.query(sql, b); return r.rowCount ?? 0 },
-        insertGetId: async (sql, b) => { const r = await client.query(sql, b); return r.rows[0]?.id ?? 0 },
-        transaction: (cb) => cb(txConn),
-        table: (name) => new QueryBuilder(txConn, name),
+      const txConn: any = {
+        _grammar: this._grammar,
+        select: async (sql: string, b?: any[]) => { const r = await client.query(sql, b); return r.rows },
+        statement: async (sql: string, b?: any[]) => { const r = await client.query(sql, b); return r.rowCount ?? 0 },
+        insertGetId: async (sql: string, b?: any[]) => { const r = await client.query(sql, b); return r.rows[0]?.id ?? 0 },
+        transaction: (cb: any) => cb(txConn),
+        table: (name: string) => new QueryBuilder(txConn, name),
         schema: () => new SchemaBuilderImpl(txConn),
         getDriverName: () => 'postgres',
         getTablePrefix: () => '',
       }
-      // @ts-ignore — attach grammar for the builder
-      txConn._grammar = this._grammar
+      this.applyExecuteMethods(txConn)
       const result = await callback(txConn)
       await client.query('COMMIT')
       return result
@@ -107,10 +108,6 @@ export class PostgresConnection implements DatabaseConnection {
     }
   }
 
-  table(name: string): QueryBuilder {
-    return new QueryBuilder(this, name)
-  }
-
   schema(): SchemaBuilder {
     return new SchemaBuilderImpl(this)
   }
@@ -118,8 +115,4 @@ export class PostgresConnection implements DatabaseConnection {
   getDriverName(): string {
     return 'postgres'
   }
-
-  getTablePrefix(): string {
-    return ''
-  }
 }

package/src/drivers/SQLiteConnection.ts

@@ -1,6 +1,7 @@
-import type { DatabaseConnection } from '../contracts/Connection.ts'
 import type { SchemaBuilder } from '../schema/SchemaBuilder.ts'
 import type { EventDispatcher } from '@mantiq/core'
+import type { DatabaseConnection } from '../contracts/Connection.ts'
+import { BaseSQLConnection } from './BaseSQLConnection.ts'
 import { QueryBuilder } from '../query/Builder.ts'
 import { SQLiteGrammar } from './SQLiteGrammar.ts'
 import { SchemaBuilderImpl } from '../schema/SchemaBuilder.ts'
@@ -12,7 +13,7 @@ export interface SQLiteConfig {
   database: string  // ':memory:' or file path
 }
 
-export class SQLiteConnection implements DatabaseConnection {
+export class SQLiteConnection extends BaseSQLConnection {
   readonly _grammar = new SQLiteGrammar()
   private db: import('bun:sqlite').Database | null = null
   private config: SQLiteConfig
@@ -21,6 +22,7 @@ export class SQLiteConnection implements DatabaseConnection {
   static _dispatcher: EventDispatcher | null = null
 
   constructor(config: SQLiteConfig) {
+    super()
     this.config = config
   }
 
@@ -102,10 +104,6 @@ export class SQLiteConnection implements DatabaseConnection {
     await SQLiteConnection._dispatcher?.emit(new QueryExecuted(sql, bindings, time, 'sqlite'))
   }
 
-  table(name: string): QueryBuilder {
-    return new QueryBuilder(this, name)
-  }
-
   schema(): SchemaBuilder {
     return new SchemaBuilderImpl(this)
   }
@@ -114,10 +112,6 @@ export class SQLiteConnection implements DatabaseConnection {
     return 'sqlite'
   }
 
-  getTablePrefix(): string {
-    return ''
-  }
-
   close(): void {
     this.db?.close()
     this.db = null

package/src/errors/DriverNotSupportedError.ts

@@ -0,0 +1,6 @@
+export class DriverNotSupportedError extends Error {
+  constructor(driver: string, feature: string) {
+    super(`"${feature}" is not supported by the ${driver} driver.`)
+    this.name = 'DriverNotSupportedError'
+  }
+}

package/src/index.ts

@@ -21,6 +21,7 @@ export type {
 export { QueryError } from './errors/QueryError.ts'
 export { ModelNotFoundError } from './errors/ModelNotFoundError.ts'
 export { ConnectionError } from './errors/ConnectionError.ts'
+export { DriverNotSupportedError } from './errors/DriverNotSupportedError.ts'
 
 // ── Query Builder ─────────────────────────────────────────────────────────────
 export { QueryBuilder } from './query/Builder.ts'
@@ -34,6 +35,9 @@ export { PostgresGrammar } from './drivers/PostgresGrammar.ts'
 export { MySQLGrammar } from './drivers/MySQLGrammar.ts'
 export { MSSQLGrammar } from './drivers/MSSQLGrammar.ts'
 
+// ── Base Connection ──────────────────────────────────────────────────────────
+export { BaseSQLConnection } from './drivers/BaseSQLConnection.ts'
+
 // ── SQL Connections ───────────────────────────────────────────────────────────
 export { SQLiteConnection } from './drivers/SQLiteConnection.ts'
 export type { SQLiteConfig } from './drivers/SQLiteConnection.ts'
@@ -76,7 +80,8 @@ export type { ModelStatic } from './orm/Model.ts'
 export { ModelQueryBuilder } from './orm/ModelQueryBuilder.ts'
 export { Collection } from './orm/Collection.ts'
 
-// ── MongoDB Document ORM ──────────────────────────────────────────────────────
+// ── MongoDB Document ORM (deprecated — use Model with MongoDB connection) ────
+/** @deprecated Use Model with a MongoDB connection instead */
 export { Document } from './orm/Document.ts'
 
 // ── Seeders & Factories ───────────────────────────────────────────────────────

package/src/orm/Model.ts

@@ -12,6 +12,8 @@ export interface ModelStatic<T extends Model> {
   connection: DatabaseConnection | null
   table: string
   primaryKey: string
+  incrementing: boolean
+  keyType: 'int' | 'string'
   fillable: string[]
   guarded: string[]
   hidden: string[]
@@ -56,6 +58,8 @@ export abstract class Model {
   static connection: DatabaseConnection | null = null
   static table: string = ''
   static primaryKey: string = 'id'
+  static incrementing = true
+  static keyType: 'int' | 'string' = 'int'
   static fillable: string[] = []
   static guarded: string[] = ['id']
   static hidden: string[] = []
@@ -470,7 +474,7 @@ export abstract class Model {
       }
 
       const id = await ctor.connection.table(table).insertGetId(this._attributes)
-      this._attributes[ctor.primaryKey] = Number(id)
+      this._attributes[ctor.primaryKey] = ctor.incrementing ? Number(id) : id
       this._original = { ...this._attributes }
       this._exists = true
 

package/src/query/Builder.ts

@@ -92,11 +92,10 @@ export class QueryBuilder {
     return this
   }
 
-  // ── Where conditions ─────────────────────────────────────────────────────
+  // ── Where conditions ───────────────────────────────────────────────────────
 
   where(column: string | ((q: QueryBuilder) => void), operatorOrValue?: any, value?: any): this {
     if (typeof column === 'function') {
-      const nested: WhereClause[] = []
       const sub = new QueryBuilder(this._connection, this.state.table)
       column(sub)
       this.state.wheres.push({ type: 'nested', boolean: 'and', nested: sub.state.wheres })
@@ -224,7 +223,7 @@ export class QueryBuilder {
     return this.whereRaw(`strftime('%H:%M:%S', ${column}) ${op} ?`, [val])
   }
 
-  // ── Joins ─────────────────────────────────────────────────────────────────
+  // ── Joins ───────────────────────────────────────────────────────────────────
 
   join(table: string, first: string, operator: string, second: string): this {
     this.state.joins.push({ type: 'inner', table, first, operator, second })
@@ -241,7 +240,7 @@ export class QueryBuilder {
     return this
   }
 
-  // ── Ordering / Grouping ───────────────────────────────────────────────────
+  // ── Ordering / Grouping ─────────────────────────────────────────────────────
 
   orderBy(column: string | Expression, direction: 'asc' | 'desc' = 'asc'): this {
     this.state.orders.push({ column, direction })
@@ -267,7 +266,7 @@ export class QueryBuilder {
     return this
   }
 
-  // ── Pagination ────────────────────────────────────────────────────────────
+  // ── Pagination ──────────────────────────────────────────────────────────────
 
   limit(value: number): this {
     this.state.limitValue = value
@@ -282,11 +281,10 @@ export class QueryBuilder {
   take = this.limit
   skip = this.offset
 
-  // ── Execution ─────────────────────────────────────────────────────────────
+  // ── Execution ───────────────────────────────────────────────────────────────
 
   async get(): Promise<Record<string, any>[]> {
-    const { sql, bindings } = this.grammar().compileSelect(this.state)
-    return this._connection.select(sql, bindings)
+    return this._connection.executeSelect(this.state)
   }
 
   async first(): Promise<Record<string, any> | null> {
@@ -315,8 +313,7 @@ export class QueryBuilder {
   }
 
   async exists(): Promise<boolean> {
-    const row = await this.selectRaw('1 as exists_check').limit(1).first()
-    return row !== null
+    return this._connection.executeExists(this.state)
   }
 
   async doesntExist(): Promise<boolean> {
@@ -333,52 +330,43 @@ export class QueryBuilder {
     return results[0]!
   }
 
-  // ── Aggregates ────────────────────────────────────────────────────────────
+  // ── Aggregates ──────────────────────────────────────────────────────────────
 
   async count(column = '*'): Promise<number> {
-    const row = await this.selectRaw(`COUNT(${column}) as aggregate`).first()
-    return Number(row?.['aggregate'] ?? 0)
+    return this._connection.executeAggregate(this.state, 'count', column)
   }
 
   async sum(column: string): Promise<number> {
-    const row = await this.selectRaw(`SUM(${column}) as aggregate`).first()
-    return Number(row?.['aggregate'] ?? 0)
+    return this._connection.executeAggregate(this.state, 'sum', column)
   }
 
   async avg(column: string): Promise<number> {
-    const row = await this.selectRaw(`AVG(${column}) as aggregate`).first()
-    return Number(row?.['aggregate'] ?? 0)
+    return this._connection.executeAggregate(this.state, 'avg', column)
   }
 
   async min(column: string): Promise<any> {
-    const row = await this.selectRaw(`MIN(${column}) as aggregate`).first()
-    return row?.['aggregate']
+    return this._connection.executeAggregate(this.state, 'min', column)
   }
 
   async max(column: string): Promise<any> {
-    const row = await this.selectRaw(`MAX(${column}) as aggregate`).first()
-    return row?.['aggregate']
+    return this._connection.executeAggregate(this.state, 'max', column)
   }
 
-  // ── Writes ────────────────────────────────────────────────────────────────
+  // ── Writes ──────────────────────────────────────────────────────────────────
 
   async insert(data: Record<string, any> | Record<string, any>[]): Promise<void> {
     const rows = Array.isArray(data) ? data : [data]
     for (const row of rows) {
-      const { sql, bindings } = this.grammar().compileInsert(this.state.table, row)
-      await this._connection.statement(sql, bindings)
+      await this._connection.executeInsert(this.state.table, row)
     }
   }
 
-  async insertGetId(data: Record<string, any>): Promise<number> {
-    const { sql, bindings } = this.grammar().compileInsertGetId(this.state.table, data)
-    const id = await this._connection.insertGetId(sql, bindings)
-    return Number(id)
+  async insertGetId(data: Record<string, any>): Promise<number | string> {
+    return this._connection.executeInsertGetId(this.state.table, data)
   }
 
   async update(data: Record<string, any>): Promise<number> {
-    const { sql, bindings } = this.grammar().compileUpdate(this.state.table, this.state, data)
-    return this._connection.statement(sql, bindings)
+    return this._connection.executeUpdate(this.state.table, this.state, data)
   }
 
   async updateOrInsert(
@@ -396,19 +384,19 @@ export class QueryBuilder {
   }
 
   async delete(): Promise<number> {
-    const { sql, bindings } = this.grammar().compileDelete(this.state.table, this.state)
-    return this._connection.statement(sql, bindings)
+    return this._connection.executeDelete(this.state.table, this.state)
   }
 
   async truncate(): Promise<void> {
-    const sql = this.grammar().compileTruncate(this.state.table)
-    await this._connection.statement(sql, [])
+    return this._connection.executeTruncate(this.state.table)
   }
 
-  // ── Pagination ────────────────────────────────────────────────────────────
+  // ── Pagination ──────────────────────────────────────────────────────────────
 
   async paginate(page = 1, perPage = 15): Promise<PaginationResult> {
-    const total = await this.clone().count()
+    const countQuery = this.clone()
+    countQuery.state.orders = []
+    const total = await countQuery.count()
     const lastPage = Math.max(1, Math.ceil(total / perPage))
     const currentPage = Math.min(page, lastPage)
     const data = await this.clone().limit(perPage).offset((currentPage - 1) * perPage).get()
@@ -417,14 +405,20 @@ export class QueryBuilder {
     return { data, total, perPage, currentPage, lastPage, from, to, hasMore: currentPage < lastPage }
   }
 
-  // ── Utilities ─────────────────────────────────────────────────────────────
+  // ── Utilities ───────────────────────────────────────────────────────────────
 
+  /** Returns the SQL for this query. Only works on SQL connections. */
   toSql(): string {
-    return this.grammar().compileSelect(this.state).sql
+    const grammar = this.getGrammar()
+    if (!grammar) throw new Error('toSql() is only available on SQL connections')
+    return grammar.compileSelect(this.state).sql
   }
 
+  /** Returns the bindings for this query. Only works on SQL connections. */
   getBindings(): any[] {
-    return this.grammar().compileSelect(this.state).bindings
+    const grammar = this.getGrammar()
+    if (!grammar) throw new Error('getBindings() is only available on SQL connections')
+    return grammar.compileSelect(this.state).bindings
   }
 
   clone(): QueryBuilder {
@@ -445,10 +439,9 @@ export class QueryBuilder {
     return this.state
   }
 
-  // ── Grammar (driver-specific SQL) ─────────────────────────────────────────
-
-  protected grammar() {
-    return (this._connection as any)._grammar as import('../contracts/Grammar.ts').Grammar
+  /** Returns the Grammar if this is a SQL connection, null otherwise. */
+  protected getGrammar(): import('../contracts/Grammar.ts').Grammar | null {
+    return (this._connection as any)._grammar ?? null
   }
 }