sqlite-zod-orm 3.2.1 → 3.3.1

package/README.md

@@ -207,66 +207,11 @@ const db = new Database(':memory:', schemas, {
 
 ---
 
-## Reactivity — Three Ways to React to Changes
+## Reactivity — `select().subscribe()`
 
-sqlite-zod-orm provides three reactivity mechanisms for different use cases:
-
-| System | Detects | Scope | Overhead | Best for |
-|---|---|---|---|---|
-| **CRUD Events** | insert, update, delete | In-process, per table | Zero (synchronous) | Side effects, caching, logs |
-| **Smart Polling** | insert, delete, update* | Any query result | Lightweight fingerprint check | Live UI, dashboards |
-| **Change Tracking** | insert, update, delete | Per table or global | Trigger-based WAL | Cross-process sync, audit |
-
-\* Smart polling detects UPDATEs automatically when `changeTracking` is enabled. Without it, only inserts and deletes are detected.
-
----
-
-### 1. CRUD Events — `db.table.subscribe(event, callback)`
-
-Synchronous callbacks fired immediately after each CRUD operation. Zero overhead; the callback runs inline.
+One API to watch any query for changes. Detects **all** mutations (inserts, updates, deletes) with zero disk overhead.
 
 ```typescript
-// Listen for new users
-db.users.subscribe('insert', (user) => {
-  console.log('New user:', user.name);   // fires on every db.users.insert(...)
-});
-
-// Listen for updates
-db.users.subscribe('update', (user) => {
-  console.log('Updated:', user.name, '→', user.role);
-});
-
-// Listen for deletes
-db.users.subscribe('delete', (user) => {
-  console.log('Deleted:', user.name);
-});
-
-// Stop listening
-db.users.unsubscribe('update', myCallback);
-```
-
-**Use cases:**
-- Invalidating a cache after writes
-- Logging / audit trail
-- Sending notifications
-- Keeping derived data in sync (e.g., a counter table)
-
-The database also extends Node's `EventEmitter`, so you can use `db.on()`:
-
-```typescript
-db.on('insert', (tableName, entity) => {
-  console.log(`New row in ${tableName}:`, entity.id);
-});
-```
-
----
-
-### 2. Smart Polling — `select().subscribe(callback, options)`
-
-Query-level polling that watches *any query result* for changes. Instead of re-fetching all rows every tick, it runs a **lightweight fingerprint query** (`SELECT COUNT(*), MAX(id)`) with the same WHERE clause. The full query only re-executes when the fingerprint changes.
-
-```typescript
-// Watch for admin list changes, poll every second
 const unsub = db.users.select()
   .where({ role: 'admin' })
   .orderBy('name', 'asc')
@@ -283,113 +228,63 @@ unsub();
 | Option | Default | Description |
 |---|---|---|
 | `interval` | `500` | Polling interval in milliseconds |
-| `immediate` | `true` | Whether to fire the callback immediately with the current result |
+| `immediate` | `true` | Fire callback immediately with current data |
 
-**How the fingerprint works:**
+### How it works
 
 ```
-┌─────────────────────────────────────┐
-│  Every {interval}ms:                │
-│                                     │
-│  1. Run: SELECT COUNT(*), MAX(id)   │
-│     FROM users WHERE role = 'admin' │
-│                                     │  ← fast, no data transfer
-│  2. Compare fingerprint to last     │
-│                                     │
-│  3. If changed → re-run full query  │  ← only when needed
-│     and call your callback          │
-└─────────────────────────────────────┘
+┌──────────────────────────────────────────────────┐
+│  Every {interval}ms:                             │
+│                                                  │
+│  1. Check revision (in-memory + data_version)    │
+│  2. Run: SELECT COUNT(*), MAX(id)                │
+│     FROM users WHERE role = 'admin'              │
+│                                                  │
+│  3. Combine into fingerprint: "count:max:rev:dv" │
+│                                                  │
+│  4. If fingerprint changed → re-run full query   │
+│     and call your callback                       │
+└──────────────────────────────────────────────────┘
 ```
 
-**What it detects:**
+Two signals combine to detect **all** changes from **any** source:
 
-| Operation | Without `changeTracking` | With `changeTracking` |
+| Signal | Catches | How |
 |---|---|---|
-| INSERT | ✅ (MAX(id) increases) | ✅ |
-| DELETE | ✅ (COUNT changes) | ✅ |
-| UPDATE | ❌ (fingerprint unchanged) | ✅ (change sequence bumps) |
-
-> **Tip:** Enable `changeTracking: true` if you need `.subscribe()` to react to UPDATEs.
-> The overhead is minimal — one trigger per table that appends to a `_changes` log.
-
-**Use cases:**
-- Live dashboards (poll every 1-5s)
-- Real-time chat message lists
-- Auto-refreshing data tables
-- Watching filtered subsets of data
-
----
-
-### 3. Change Tracking — `changeTracking: true`
+| **In-memory revision** | Same-process writes | Bumped by CRUD methods |
+| **PRAGMA data_version** | Cross-process writes | SQLite bumps it on external commits |
 
-A trigger-based WAL (write-ahead log) that records every INSERT, UPDATE, and DELETE to a `_changes` table. This is the foundation for cross-process sync and audit trails.
-
-```typescript
-const db = new Database(':memory:', schemas, {
-  changeTracking: true,
-});
-```
+| Operation | Detected | Source |
+|---|---|---|
+| INSERT | ✅ | Same or other process |
+| DELETE | ✅ | Same or other process |
+| UPDATE | ✅ | Same or other process |
 
-When enabled, the ORM creates:
-- A `_changes` table: `(id, table_name, row_id, action, changed_at)`
-- An index on `(table_name, id)` for fast lookups
-- Triggers on each table for INSERT, UPDATE, and DELETE
+No triggers. No `_changes` table. Zero disk overhead. WAL mode is enabled by default for concurrent read/write.
 
-**Reading changes:**
+### Multi-process example
 
 ```typescript
-// Get the current sequence number (latest change ID)
-const seq = db.getChangeSeq();            // global
-const seq = db.getChangeSeq('users');     // per table
-
-// Get all changes since a sequence number
-const changes = db.getChangesSince(0);    // all changes ever
-const changes = db.getChangesSince(seq);  // new changes since seq
-
-// Each change looks like:
-// { id: 42, table_name: 'users', row_id: 7, action: 'UPDATE', changed_at: '2024-...' }
+// Process A — watches for new/edited messages
+const unsub = db.messages.select()
+  .orderBy('id', 'asc')
+  .subscribe((messages) => {
+    console.log('Messages:', messages);
+  }, { interval: 200 });
+
+// Process B — writes to the same DB file (different process)
+// sqlite3 chat.db "INSERT INTO messages (text, author) VALUES ('hello', 'Bob')"
+// → Process A's callback fires with updated message list!
 ```
 
-**Polling for changes (external sync pattern):**
-
-```typescript
-let lastSeq = 0;
-
-setInterval(() => {
-  const changes = db.getChangesSince(lastSeq);
-  if (changes.length > 0) {
-    lastSeq = changes[changes.length - 1].id;
-    for (const change of changes) {
-      console.log(`${change.action} on ${change.table_name} row ${change.row_id}`);
-    }
-  }
-}, 1000);
-```
+Run `bun examples/messages-demo.ts` for a full working demo.
 
 **Use cases:**
-- Syncing between processes (e.g., worker → main thread)
-- Building an event-sourced system
-- Replication to another database
-- Audit logging with timestamps
-- Powering smart polling UPDATE detection
-
----
-
-### Choosing the Right System
-
-```
-Do you need to react to your own writes?
-  → CRUD Events (db.table.subscribe)
-
-Do you need to watch a query result set?
-  → Smart Polling (select().subscribe)
-  → Enable changeTracking if you need UPDATE detection
-
-Do you need cross-process sync or audit?
-  → Change Tracking (changeTracking: true + getChangesSince)
-```
-
-All three systems can be used together. `changeTracking` enhances smart polling automatically — no code changes needed.
+- Live dashboards (poll every 1-5s)
+- Real-time chat / message lists
+- Auto-refreshing data tables
+- Watching filtered subsets of data
+- Cross-process data synchronization
 
 ---
 
@@ -424,12 +319,7 @@ bun test                    # 91 tests
 | `entity.update(data)` | Update entity in-place |
 | `entity.delete()` | Delete entity |
 | **Reactivity** | |
-| `db.table.subscribe(event, cb)` | CRUD events: `'insert'`, `'update'`, `'delete'` |
-| `db.table.unsubscribe(event, cb)` | Remove CRUD event listener |
-| `db.on(event, cb)` | EventEmitter: listen across all tables |
-| `select().subscribe(cb, opts?)` | Smart polling (fingerprint-based) |
-| `db.getChangeSeq(table?)` | Current change sequence number |
-| `db.getChangesSince(seq, table?)` | Changes since sequence (change tracking) |
+| `select().subscribe(cb, opts?)` | Watch any query for changes (all mutations) |
 
 ## License
 

package/dist/index.js

@@ -12,7 +12,6 @@ var __export = (target, all) => {
 
 // src/database.ts
 import { Database as SqliteDatabase } from "bun:sqlite";
-import { EventEmitter } from "events";
 
 // src/ast.ts
 var wrapNode = (val) => val !== null && typeof val === "object" && ("type" in val) ? val : { type: "literal", value: val };
@@ -174,14 +173,14 @@ class QueryBuilder {
   singleExecutor;
   joinResolver;
   conditionResolver;
-  changeSeqGetter;
-  constructor(tableName, executor, singleExecutor, joinResolver, conditionResolver, changeSeqGetter) {
+  revisionGetter;
+  constructor(tableName, executor, singleExecutor, joinResolver, conditionResolver, revisionGetter) {
     this.tableName = tableName;
     this.executor = executor;
     this.singleExecutor = singleExecutor;
     this.joinResolver = joinResolver ?? null;
     this.conditionResolver = conditionResolver ?? null;
-    this.changeSeqGetter = changeSeqGetter ?? null;
+    this.revisionGetter = revisionGetter ?? null;
     this.iqo = {
       selects: [],
       wheres: [],
@@ -335,8 +334,8 @@ class QueryBuilder {
       try {
         const fpRows = this.executor(fingerprintSQL.sql, fingerprintSQL.params, true);
         const fpRow = fpRows[0];
-        const changeSeq = this.changeSeqGetter?.() ?? 0;
-        const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}:${changeSeq}`;
+        const rev = this.revisionGetter?.() ?? "0";
+        const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}:${rev}`;
         if (currentFingerprint !== lastFingerprint) {
           lastFingerprint = currentFingerprint;
           const rows = this.all();
@@ -4652,26 +4651,23 @@ function transformFromStorage(row, schema) {
 }
 
 // src/database.ts
-class _Database extends EventEmitter {
+class _Database {
   db;
   schemas;
   relationships;
-  subscriptions;
   options;
+  _revisions = {};
   constructor(dbFile, schemas, options = {}) {
-    super();
     this.db = new SqliteDatabase(dbFile);
+    this.db.run("PRAGMA journal_mode = WAL");
     this.db.run("PRAGMA foreign_keys = ON");
     this.schemas = schemas;
     this.options = options;
-    this.subscriptions = { insert: {}, update: {}, delete: {} };
     this.relationships = options.relations ? parseRelationsConfig(options.relations, schemas) : [];
     this.initializeTables();
     this.runMigrations();
     if (options.indexes)
       this.createIndexes(options.indexes);
-    if (options.changeTracking)
-      this.setupChangeTracking();
     for (const entityName of Object.keys(schemas)) {
       const key = entityName;
       const accessor = {
@@ -4683,8 +4679,6 @@ class _Database extends EventEmitter {
         },
         upsert: (conditions, data) => this.upsert(entityName, data, conditions),
         delete: (id) => this.delete(entityName, id),
-        subscribe: (event, callback) => this.subscribe(event, entityName, callback),
-        unsubscribe: (event, callback) => this.unsubscribe(event, entityName, callback),
         select: (...cols) => this._createQueryBuilder(entityName, cols),
         _tableName: entityName
       };
@@ -4706,66 +4700,34 @@ class _Database extends EventEmitter {
     }
   }
   runMigrations() {
-    this.db.run(`CREATE TABLE IF NOT EXISTS _schema_meta (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      table_name TEXT NOT NULL,
-      column_name TEXT NOT NULL,
-      added_at TEXT DEFAULT (datetime('now')),
-      UNIQUE(table_name, column_name)
-    )`);
     for (const [entityName, schema] of Object.entries(this.schemas)) {
-      const existingCols = new Set(this.db.query(`PRAGMA table_info(${entityName})`).all().map((c) => c.name));
+      const existingColumns = this.db.query(`PRAGMA table_info(${entityName})`).all();
+      const existingNames = new Set(existingColumns.map((c) => c.name));
       const storableFields = getStorableFields(schema);
       for (const field of storableFields) {
-        if (!existingCols.has(field.name)) {
-          this.db.run(`ALTER TABLE ${entityName} ADD COLUMN ${field.name} ${zodTypeToSqlType(field.type)}`);
-          this.db.query(`INSERT OR IGNORE INTO _schema_meta (table_name, column_name) VALUES (?, ?)`).run(entityName, field.name);
+        if (!existingNames.has(field.name)) {
+          const sqlType = zodTypeToSqlType(field.type);
+          this.db.run(`ALTER TABLE ${entityName} ADD COLUMN ${field.name} ${sqlType}`);
         }
       }
     }
   }
-  createIndexes(indexDefs) {
-    for (const [tableName, indexes] of Object.entries(indexDefs)) {
-      if (!this.schemas[tableName])
-        throw new Error(`Cannot create index on unknown table '${tableName}'`);
-      const indexList = Array.isArray(indexes) ? indexes : [indexes];
-      for (const indexDef of indexList) {
-        const columns = Array.isArray(indexDef) ? indexDef : [indexDef];
-        const indexName = `idx_${tableName}_${columns.join("_")}`;
-        this.db.run(`CREATE INDEX IF NOT EXISTS ${indexName} ON ${tableName} (${columns.join(", ")})`);
+  createIndexes(indexes) {
+    for (const [tableName, indexDefs] of Object.entries(indexes)) {
+      for (const def of indexDefs) {
+        const cols = Array.isArray(def) ? def : [def];
+        const idxName = `idx_${tableName}_${cols.join("_")}`;
+        this.db.run(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${tableName} (${cols.join(", ")})`);
       }
     }
   }
-  setupChangeTracking() {
-    this.db.run(`CREATE TABLE IF NOT EXISTS _changes (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      table_name TEXT NOT NULL,
-      row_id INTEGER NOT NULL,
-      action TEXT NOT NULL CHECK(action IN ('INSERT', 'UPDATE', 'DELETE')),
-      changed_at TEXT DEFAULT (datetime('now'))
-    )`);
-    this.db.run(`CREATE INDEX IF NOT EXISTS idx_changes_table ON _changes (table_name, id)`);
-    for (const entityName of Object.keys(this.schemas)) {
-      for (const action of ["insert", "update", "delete"]) {
-        const ref = action === "delete" ? "OLD" : "NEW";
-        this.db.run(`CREATE TRIGGER IF NOT EXISTS _trg_${entityName}_${action}
-          AFTER ${action.toUpperCase()} ON ${entityName}
-          BEGIN
-            INSERT INTO _changes (table_name, row_id, action) VALUES ('${entityName}', ${ref}.id, '${action.toUpperCase()}');
-          END`);
-      }
-    }
+  _bumpRevision(entityName) {
+    this._revisions[entityName] = (this._revisions[entityName] ?? 0) + 1;
   }
-  getChangeSeq(tableName) {
-    if (!this.options.changeTracking)
-      return -1;
-    const sql = tableName ? `SELECT MAX(id) as seq FROM _changes WHERE table_name = ?` : `SELECT MAX(id) as seq FROM _changes`;
-    const row = this.db.query(sql).get(...tableName ? [tableName] : []);
-    return row?.seq ?? 0;
-  }
-  getChangesSince(sinceSeq, tableName) {
-    const sql = tableName ? `SELECT * FROM _changes WHERE id > ? AND table_name = ? ORDER BY id ASC` : `SELECT * FROM _changes WHERE id > ? ORDER BY id ASC`;
-    return this.db.query(sql).all(...tableName ? [sinceSeq, tableName] : [sinceSeq]);
+  _getRevision(entityName) {
+    const rev = this._revisions[entityName] ?? 0;
+    const dataVersion = this.db.query("PRAGMA data_version").get()?.data_version ?? 0;
+    return `${rev}:${dataVersion}`;
   }
   insert(entityName, data) {
     const schema = this.schemas[entityName];
@@ -4777,8 +4739,7 @@ class _Database extends EventEmitter {
     const newEntity = this._getById(entityName, result.lastInsertRowid);
     if (!newEntity)
       throw new Error("Failed to retrieve entity after insertion");
-    this.emit("insert", entityName, newEntity);
-    this.subscriptions.insert[entityName]?.forEach((cb) => cb(newEntity));
+    this._bumpRevision(entityName);
     return newEntity;
   }
   _getById(entityName, id) {
@@ -4807,11 +4768,8 @@ class _Database extends EventEmitter {
       return this._getById(entityName, id);
     const setClause = Object.keys(transformed).map((key) => `${key} = ?`).join(", ");
     this.db.query(`UPDATE ${entityName} SET ${setClause} WHERE id = ?`).run(...Object.values(transformed), id);
+    this._bumpRevision(entityName);
     const updatedEntity = this._getById(entityName, id);
-    if (updatedEntity) {
-      this.emit("update", entityName, updatedEntity);
-      this.subscriptions.update[entityName]?.forEach((cb) => cb(updatedEntity));
-    }
     return updatedEntity;
   }
   _updateWhere(entityName, data, conditions) {
@@ -4827,12 +4785,8 @@ class _Database extends EventEmitter {
     const setClause = setCols.map((key) => `${key} = ?`).join(", ");
     const result = this.db.query(`UPDATE ${entityName} SET ${setClause} ${clause}`).run(...setCols.map((key) => transformed[key]), ...whereValues);
     const affected = result.changes ?? 0;
-    if (affected > 0 && (this.subscriptions.update[entityName]?.length || this.options.changeTracking)) {
-      for (const entity of this._findMany(entityName, conditions)) {
-        this.emit("update", entityName, entity);
-        this.subscriptions.update[entityName]?.forEach((cb) => cb(entity));
-      }
-    }
+    if (affected > 0)
+      this._bumpRevision(entityName);
     return affected;
   }
   _createUpdateBuilder(entityName, data) {
@@ -4862,8 +4816,7 @@ class _Database extends EventEmitter {
     const entity = this._getById(entityName, id);
     if (entity) {
       this.db.query(`DELETE FROM ${entityName} WHERE id = ?`).run(id);
-      this.emit("delete", entityName, entity);
-      this.subscriptions.delete[entityName]?.forEach((cb) => cb(entity));
+      this._bumpRevision(entityName);
     }
   }
   _attachMethods(entityName, entity) {
@@ -4960,15 +4913,6 @@ class _Database extends EventEmitter {
       throw new Error(`Transaction failed: ${error.message}`);
     }
   }
-  subscribe(event, entityName, callback) {
-    this.subscriptions[event][entityName] = this.subscriptions[event][entityName] || [];
-    this.subscriptions[event][entityName].push(callback);
-  }
-  unsubscribe(event, entityName, callback) {
-    if (this.subscriptions[event][entityName]) {
-      this.subscriptions[event][entityName] = this.subscriptions[event][entityName].filter((cb) => cb !== callback);
-    }
-  }
   _createQueryBuilder(entityName, initialCols) {
     const schema = this.schemas[entityName];
     const executor = (sql, params, raw) => {
@@ -4990,8 +4934,8 @@ class _Database extends EventEmitter {
         return { fk: "id", pk: reverse.foreignKey };
       return null;
     };
-    const changeSeqGetter = this.options.changeTracking ? () => this.getChangeSeq(entityName) : null;
-    const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, null, changeSeqGetter);
+    const revisionGetter = () => this._getRevision(entityName);
+    const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, null, revisionGetter);
     if (initialCols.length > 0)
       builder.select(...initialCols);
     return builder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-zod-orm",
-  "version": "3.2.1",
+  "version": "3.3.1",
   "description": "Type-safe SQLite ORM for Bun — Zod schemas, fluent queries, auto relationships, zero SQL",
   "type": "module",
   "main": "./dist/index.js",

package/src/database.ts

@@ -5,7 +5,6 @@
  * query builders, and event handling.
  */
 import { Database as SqliteDatabase } from 'bun:sqlite';
-import { EventEmitter } from 'events';
 import { z } from 'zod';
 import { QueryBuilder } from './query-builder';
 import { executeProxyQuery, type ProxyQueryResult } from './proxy-query';
@@ -25,25 +24,26 @@ import {
 // Database Class
 // =============================================================================
 
-class _Database<Schemas extends SchemaMap> extends EventEmitter {
+class _Database<Schemas extends SchemaMap> {
     private db: SqliteDatabase;
     private schemas: Schemas;
     private relationships: Relationship[];
-    private subscriptions: Record<'insert' | 'update' | 'delete', Record<string, ((data: any) => void)[]>>;
     private options: DatabaseOptions;
 
+    /** In-memory revision counter per table — bumps on every write (insert/update/delete).
+     *  Used by QueryBuilder.subscribe() fingerprint to detect ALL changes with zero overhead. */
+    private _revisions: Record<string, number> = {};
+
     constructor(dbFile: string, schemas: Schemas, options: DatabaseOptions = {}) {
-        super();
         this.db = new SqliteDatabase(dbFile);
+        this.db.run('PRAGMA journal_mode = WAL');  // WAL enables concurrent read + write
         this.db.run('PRAGMA foreign_keys = ON');
         this.schemas = schemas;
         this.options = options;
-        this.subscriptions = { insert: {}, update: {}, delete: {} };
         this.relationships = options.relations ? parseRelationsConfig(options.relations, schemas) : [];
         this.initializeTables();
         this.runMigrations();
         if (options.indexes) this.createIndexes(options.indexes);
-        if (options.changeTracking) this.setupChangeTracking();
 
         // Create typed entity accessors (db.users, db.posts, etc.)
         for (const entityName of Object.keys(schemas)) {
@@ -56,8 +56,6 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
                 },
                 upsert: (conditions, data) => this.upsert(entityName, data, conditions),
                 delete: (id) => this.delete(entityName, id),
-                subscribe: (event, callback) => this.subscribe(event, entityName, callback),
-                unsubscribe: (event, callback) => this.unsubscribe(event, entityName, callback),
                 select: (...cols: string[]) => this._createQueryBuilder(entityName, cols),
                 _tableName: entityName,
             };
@@ -90,85 +88,53 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
     }
 
     private runMigrations(): void {
-        this.db.run(`CREATE TABLE IF NOT EXISTS _schema_meta (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      table_name TEXT NOT NULL,
-      column_name TEXT NOT NULL,
-      added_at TEXT DEFAULT (datetime('now')),
-      UNIQUE(table_name, column_name)
-    )`);
-
         for (const [entityName, schema] of Object.entries(this.schemas)) {
-            const existingCols = new Set(
-                (this.db.query(`PRAGMA table_info(${entityName})`).all() as any[]).map(c => c.name)
-            );
-            const storableFields = getStorableFields(schema);
+            const existingColumns = this.db.query(`PRAGMA table_info(${entityName})`).all() as any[];
+            const existingNames = new Set(existingColumns.map(c => c.name));
 
+            const storableFields = getStorableFields(schema);
             for (const field of storableFields) {
-                if (!existingCols.has(field.name)) {
-                    this.db.run(`ALTER TABLE ${entityName} ADD COLUMN ${field.name} ${zodTypeToSqlType(field.type)}`);
-                    this.db.query(`INSERT OR IGNORE INTO _schema_meta (table_name, column_name) VALUES (?, ?)`).run(entityName, field.name);
+                if (!existingNames.has(field.name)) {
+                    const sqlType = zodTypeToSqlType(field.type);
+                    this.db.run(`ALTER TABLE ${entityName} ADD COLUMN ${field.name} ${sqlType}`);
                 }
             }
         }
     }
 
-    // ===========================================================================
-    // Indexes
-    // ===========================================================================
-
-    private createIndexes(indexDefs: Record<string, string | (string | string[])[]>): void {
-        for (const [tableName, indexes] of Object.entries(indexDefs)) {
-            if (!this.schemas[tableName]) throw new Error(`Cannot create index on unknown table '${tableName}'`);
-            const indexList = Array.isArray(indexes) ? indexes : [indexes];
-            for (const indexDef of indexList) {
-                const columns = Array.isArray(indexDef) ? indexDef : [indexDef];
-                const indexName = `idx_${tableName}_${columns.join('_')}`;
-                this.db.run(`CREATE INDEX IF NOT EXISTS ${indexName} ON ${tableName} (${columns.join(', ')})`);
+    private createIndexes(indexes: Record<string, (string | string[])[]>): void {
+        for (const [tableName, indexDefs] of Object.entries(indexes)) {
+            for (const def of indexDefs) {
+                const cols = Array.isArray(def) ? def : [def];
+                const idxName = `idx_${tableName}_${cols.join('_')}`;
+                this.db.run(`CREATE INDEX IF NOT EXISTS ${idxName} ON ${tableName} (${cols.join(', ')})`);
             }
         }
     }
 
     // ===========================================================================
-    // Change Tracking
+    // Revision Tracking (in-memory + cross-process)
     // ===========================================================================
 
-    private setupChangeTracking(): void {
-        this.db.run(`CREATE TABLE IF NOT EXISTS _changes (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      table_name TEXT NOT NULL,
-      row_id INTEGER NOT NULL,
-      action TEXT NOT NULL CHECK(action IN ('INSERT', 'UPDATE', 'DELETE')),
-      changed_at TEXT DEFAULT (datetime('now'))
-    )`);
-        this.db.run(`CREATE INDEX IF NOT EXISTS idx_changes_table ON _changes (table_name, id)`);
-
-        for (const entityName of Object.keys(this.schemas)) {
-            for (const action of ['insert', 'update', 'delete'] as const) {
-                const ref = action === 'delete' ? 'OLD' : 'NEW';
-                this.db.run(`CREATE TRIGGER IF NOT EXISTS _trg_${entityName}_${action}
-          AFTER ${action.toUpperCase()} ON ${entityName}
-          BEGIN
-            INSERT INTO _changes (table_name, row_id, action) VALUES ('${entityName}', ${ref}.id, '${action.toUpperCase()}');
-          END`);
-            }
-        }
-    }
-
-    public getChangeSeq(tableName?: string): number {
-        if (!this.options.changeTracking) return -1;
-        const sql = tableName
-            ? `SELECT MAX(id) as seq FROM _changes WHERE table_name = ?`
-            : `SELECT MAX(id) as seq FROM _changes`;
-        const row = this.db.query(sql).get(...(tableName ? [tableName] : [])) as any;
-        return row?.seq ?? 0;
+    /** Bump the revision counter for a table. Called on every write. */
+    private _bumpRevision(entityName: string): void {
+        this._revisions[entityName] = (this._revisions[entityName] ?? 0) + 1;
     }
 
-    public getChangesSince(sinceSeq: number, tableName?: string) {
-        const sql = tableName
-            ? `SELECT * FROM _changes WHERE id > ? AND table_name = ? ORDER BY id ASC`
-            : `SELECT * FROM _changes WHERE id > ? ORDER BY id ASC`;
-        return this.db.query(sql).all(...(tableName ? [sinceSeq, tableName] : [sinceSeq])) as any[];
+    /**
+     * Get a composite revision string for a table.
+     *
+     * Combines two signals:
+     *  - In-memory counter: catches writes from THIS process (our CRUD methods bump it)
+     *  - PRAGMA data_version: catches writes from OTHER processes (SQLite bumps it
+     *    whenever another connection commits, but NOT for the current connection)
+     *
+     * Together they detect ALL changes regardless of source, with zero disk overhead.
+     */
+    public _getRevision(entityName: string): string {
+        const rev = this._revisions[entityName] ?? 0;
+        const dataVersion = (this.db.query('PRAGMA data_version').get() as any)?.data_version ?? 0;
+        return `${rev}:${dataVersion}`;
     }
 
     // ===========================================================================
@@ -189,8 +155,7 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
         const newEntity = this._getById(entityName, result.lastInsertRowid as number);
         if (!newEntity) throw new Error('Failed to retrieve entity after insertion');
 
-        this.emit('insert', entityName, newEntity);
-        this.subscriptions.insert[entityName]?.forEach(cb => cb(newEntity));
+        this._bumpRevision(entityName);
         return newEntity;
     }
 
@@ -227,11 +192,8 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
         const setClause = Object.keys(transformed).map(key => `${key} = ?`).join(', ');
         this.db.query(`UPDATE ${entityName} SET ${setClause} WHERE id = ?`).run(...Object.values(transformed), id);
 
+        this._bumpRevision(entityName);
         const updatedEntity = this._getById(entityName, id);
-        if (updatedEntity) {
-            this.emit('update', entityName, updatedEntity);
-            this.subscriptions.update[entityName]?.forEach(cb => cb(updatedEntity));
-        }
         return updatedEntity;
     }
 
@@ -252,12 +214,7 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
         );
 
         const affected = (result as any).changes ?? 0;
-        if (affected > 0 && (this.subscriptions.update[entityName]?.length || this.options.changeTracking)) {
-            for (const entity of this._findMany(entityName, conditions)) {
-                this.emit('update', entityName, entity);
-                this.subscriptions.update[entityName]?.forEach(cb => cb(entity));
-            }
-        }
+        if (affected > 0) this._bumpRevision(entityName);
         return affected;
     }
 
@@ -292,8 +249,7 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
         const entity = this._getById(entityName, id);
         if (entity) {
             this.db.query(`DELETE FROM ${entityName} WHERE id = ?`).run(id);
-            this.emit('delete', entityName, entity);
-            this.subscriptions.delete[entityName]?.forEach(cb => cb(entity));
+            this._bumpRevision(entityName);
         }
     }
 
@@ -415,21 +371,6 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
         }
     }
 
-    // ===========================================================================
-    // Events
-    // ===========================================================================
-
-    private subscribe(event: 'insert' | 'update' | 'delete', entityName: string, callback: (data: any) => void): void {
-        this.subscriptions[event][entityName] = this.subscriptions[event][entityName] || [];
-        this.subscriptions[event][entityName].push(callback);
-    }
-
-    private unsubscribe(event: 'insert' | 'update' | 'delete', entityName: string, callback: (data: any) => void): void {
-        if (this.subscriptions[event][entityName]) {
-            this.subscriptions[event][entityName] = this.subscriptions[event][entityName].filter(cb => cb !== callback);
-        }
-    }
-
     // ===========================================================================
     // Query Builders
     // ===========================================================================
@@ -459,13 +400,11 @@ class _Database<Schemas extends SchemaMap> extends EventEmitter {
             if (reverse) return { fk: 'id', pk: reverse.foreignKey };
             return null;
         };
-        // Provide change sequence getter when change tracking is enabled
-        // This allows .subscribe() to detect row UPDATEs (not just inserts/deletes)
-        const changeSeqGetter = this.options.changeTracking
-            ? () => this.getChangeSeq(entityName)
-            : null;
 
-        const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, null, changeSeqGetter);
+        // Pass revision getter — allows .subscribe() to detect ALL changes
+        const revisionGetter = () => this._getRevision(entityName);
+
+        const builder = new QueryBuilder(entityName, executor, singleExecutor, joinResolver, null, revisionGetter);
         if (initialCols.length > 0) builder.select(...initialCols);
         return builder;
     }

package/src/query-builder.ts

@@ -167,7 +167,7 @@ export class QueryBuilder<T extends Record<string, any>> {
     private singleExecutor: (sql: string, params: any[], raw: boolean) => any | null;
     private joinResolver: ((fromTable: string, toTable: string) => { fk: string; pk: string } | null) | null;
     private conditionResolver: ((conditions: Record<string, any>) => Record<string, any>) | null;
-    private changeSeqGetter: (() => number) | null;
+    private revisionGetter: (() => string) | null;
 
     constructor(
         tableName: string,
@@ -175,14 +175,14 @@ export class QueryBuilder<T extends Record<string, any>> {
         singleExecutor: (sql: string, params: any[], raw: boolean) => any | null,
         joinResolver?: ((fromTable: string, toTable: string) => { fk: string; pk: string } | null) | null,
         conditionResolver?: ((conditions: Record<string, any>) => Record<string, any>) | null,
-        changeSeqGetter?: (() => number) | null,
+        revisionGetter?: (() => string) | null,
     ) {
         this.tableName = tableName;
         this.executor = executor;
         this.singleExecutor = singleExecutor;
         this.joinResolver = joinResolver ?? null;
         this.conditionResolver = conditionResolver ?? null;
-        this.changeSeqGetter = changeSeqGetter ?? null;
+        this.revisionGetter = revisionGetter ?? null;
         this.iqo = {
             selects: [],
             wheres: [],
@@ -423,9 +423,9 @@ export class QueryBuilder<T extends Record<string, any>> {
     /**
      * Subscribe to query result changes using smart interval-based polling.
      *
-     * Instead of re-fetching all rows every tick, it runs a lightweight
-     * fingerprint query (`SELECT COUNT(*), MAX(id)`) with the same WHERE clause.
-     * The full query is only re-executed when the fingerprint changes.
+     * Uses a lightweight fingerprint (`COUNT(*), MAX(id)`) combined with an
+     * in-memory revision counter to detect ALL changes (inserts, updates, deletes)
+     * with zero disk overhead.
      *
      * ```ts
      * const unsub = db.messages.select()
@@ -459,10 +459,10 @@ export class QueryBuilder<T extends Record<string, any>> {
                 // Run lightweight fingerprint check
                 const fpRows = this.executor(fingerprintSQL.sql, fingerprintSQL.params, true);
                 const fpRow = fpRows[0] as any;
-                // Include change sequence in fingerprint when change tracking is enabled.
-                // This ensures UPDATEs are detected (COUNT + MAX alone don't change on UPDATE).
-                const changeSeq = this.changeSeqGetter?.() ?? 0;
-                const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}:${changeSeq}`;
+                // Include revision in fingerprint (combines in-memory counter + PRAGMA data_version).
+                // This detects ALL changes: same-process and cross-process.
+                const rev = this.revisionGetter?.() ?? '0';
+                const currentFingerprint = `${fpRow?._cnt ?? 0}:${fpRow?._max ?? 0}:${rev}`;
 
                 if (currentFingerprint !== lastFingerprint) {
                     lastFingerprint = currentFingerprint;

package/src/types.ts

@@ -21,7 +21,6 @@ export type IndexDef = string | string[];
 
 /** Options for the Database constructor */
 export type DatabaseOptions<R extends RelationsConfig = RelationsConfig> = {
-    changeTracking?: boolean;
     indexes?: Record<string, IndexDef[]>;
     /**
      * Declare relationships between tables.
@@ -143,8 +142,6 @@ export type NavEntityAccessor<
     & ((data: Partial<Omit<z.input<S[Table & keyof S]>, 'id'>>) => UpdateBuilder<NavEntity<S, R, Table>>);
     upsert: (conditions?: Partial<z.infer<S[Table & keyof S]>>, data?: Partial<z.infer<S[Table & keyof S]>>) => NavEntity<S, R, Table>;
     delete: (id: number) => void;
-    subscribe: (event: 'insert' | 'update' | 'delete', callback: (data: NavEntity<S, R, Table>) => void) => void;
-    unsubscribe: (event: 'insert' | 'update' | 'delete', callback: (data: NavEntity<S, R, Table>) => void) => void;
     select: (...cols: (keyof z.infer<S[Table & keyof S]> & string)[]) => QueryBuilder<NavEntity<S, R, Table>>;
     _tableName: string;
     readonly _schema?: S[Table & keyof S];
@@ -170,8 +167,6 @@ export type EntityAccessor<S extends z.ZodType<any>> = {
     update: ((id: number, data: Partial<EntityData<S>>) => AugmentedEntity<S> | null) & ((data: Partial<EntityData<S>>) => UpdateBuilder<AugmentedEntity<S>>);
     upsert: (conditions?: Partial<InferSchema<S>>, data?: Partial<InferSchema<S>>) => AugmentedEntity<S>;
     delete: (id: number) => void;
-    subscribe: (event: 'insert' | 'update' | 'delete', callback: (data: AugmentedEntity<S>) => void) => void;
-    unsubscribe: (event: 'insert' | 'update' | 'delete', callback: (data: AugmentedEntity<S>) => void) => void;
     select: (...cols: (keyof InferSchema<S> & string)[]) => QueryBuilder<AugmentedEntity<S>>;
     _tableName: string;
     readonly _schema?: S;