dzql 0.3.5 → 0.3.7

package/bin/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env bun
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
-import { resolve } from 'path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { resolve, join } from 'path';
 import { DZQLCompiler } from '../src/compiler/compiler.js';
+import postgres from 'postgres';
 
 const command = process.argv[2];
 const args = process.argv.slice(3);
@@ -21,6 +22,19 @@ switch (command) {
   case 'compile':
     await runCompile(args);
     break;
+  case 'migrate:new':
+  case 'migrate:init':
+    await runMigrateNew(args);
+    break;
+  case 'migrate:up':
+    await runMigrateUp(args);
+    break;
+  case 'migrate:down':
+    await runMigrateDown(args);
+    break;
+  case 'migrate:status':
+    await runMigrateStatus(args);
+    break;
   case '--version':
   case '-v':
     const pkg = await import('../package.json', { assert: { type: 'json' } });
@@ -31,17 +45,24 @@ switch (command) {
 DZQL CLI
 
 Usage:
-  dzql create <app-name>     Create a new DZQL application
-  dzql dev                   Start development server
-  dzql db:up                 Start PostgreSQL database
-  dzql db:down               Stop PostgreSQL database
-  dzql compile <input>       Compile entity definitions to SQL
-  dzql --version             Show version
+  dzql create <app-name>        Create a new DZQL application
+  dzql dev                      Start development server
+  dzql db:up                    Start PostgreSQL database
+  dzql db:down                  Stop PostgreSQL database
+  dzql compile <input>          Compile entity definitions to SQL
+
+  dzql migrate:new <name>       Create a new migration file
+  dzql migrate:up               Apply pending migrations
+  dzql migrate:down             Rollback last migration
+  dzql migrate:status           Show migration status
+
+  dzql --version                Show version
 
 Examples:
   dzql create my-venue-app
-  dzql dev
-  dzql compile database/init_db/009_venues_domain.sql -o compiled/
+  dzql compile entities/blog.sql -o init_db/
+  dzql migrate:new add_user_avatars
+  dzql migrate:up
 `);
 }
 
@@ -126,27 +147,56 @@ Examples:
       console.log(`\n📝 Writing compiled files to: ${options.output}`);
 
       // Write core DZQL infrastructure
-      const coreSQL = `-- DZQL Core Schema and Events System
+      const coreSQL = `-- DZQL Core Schema and Tables
 
 CREATE SCHEMA IF NOT EXISTS dzql;
 
+-- Meta information
+CREATE TABLE IF NOT EXISTS dzql.meta (
+  installed_at timestamptz DEFAULT now(),
+  version text NOT NULL
+);
+
+INSERT INTO dzql.meta (version) VALUES ('3.0.0') ON CONFLICT DO NOTHING;
+
+-- Entity Configuration Table
+CREATE TABLE IF NOT EXISTS dzql.entities (
+  table_name text PRIMARY KEY,
+  label_field text NOT NULL,
+  searchable_fields text[] NOT NULL,
+  fk_includes jsonb DEFAULT '{}',
+  soft_delete boolean DEFAULT false,
+  temporal_fields jsonb DEFAULT '{}',
+  notification_paths jsonb DEFAULT '{}',
+  permission_paths jsonb DEFAULT '{}',
+  graph_rules jsonb DEFAULT '{}',
+  field_defaults jsonb DEFAULT '{}',
+  many_to_many jsonb DEFAULT '{}'
+);
+
+-- Registry of callable functions
+CREATE TABLE IF NOT EXISTS dzql.registry (
+  fn_regproc regproc PRIMARY KEY,
+  description text
+);
+
 -- Event Audit Table for real-time notifications
 CREATE TABLE IF NOT EXISTS dzql.events (
   event_id bigserial PRIMARY KEY,
   table_name text NOT NULL,
-  op text NOT NULL,              -- 'insert', 'update', 'delete'
-  pk jsonb NOT NULL,             -- primary key of affected record
-  before jsonb,                  -- old values (NULL for insert)
-  after jsonb,                   -- new values (NULL for delete)
-  user_id int,                   -- who made the change
-  notify_users int[],            -- who should be notified
-  at timestamptz DEFAULT now()   -- when the change occurred
+  op text NOT NULL,
+  pk jsonb NOT NULL,
+  data jsonb,
+  user_id int,
+  notify_users int[],
+  at timestamptz DEFAULT now()
 );
 
 CREATE INDEX IF NOT EXISTS dzql_events_table_pk_idx ON dzql.events (table_name, pk, at);
+CREATE INDEX IF NOT EXISTS dzql_events_user_idx ON dzql.events (user_id, at);
 CREATE INDEX IF NOT EXISTS dzql_events_event_id_idx ON dzql.events (event_id);
 
--- Event notification trigger - sends real-time notifications via pg_notify
+-- Event notification trigger
 CREATE OR REPLACE FUNCTION dzql.notify_event()
 RETURNS TRIGGER LANGUAGE plpgsql AS $$
 BEGIN
@@ -155,14 +205,11 @@ BEGIN
     'table', NEW.table_name,
     'op', NEW.op,
     'pk', NEW.pk,
-    'data', COALESCE(NEW.after, NEW.before),
-    'before', NEW.before,
-    'after', NEW.after,
+    'data', NEW.data,
     'user_id', NEW.user_id,
     'at', NEW.at,
     'notify_users', NEW.notify_users
   )::text);
-
   RETURN NULL;
 END $$;
 
@@ -289,3 +336,278 @@ $$;
     process.exit(1);
   }
 }
+
+// ============================================================================
+// Migration Commands
+// ============================================================================
+
+async function runMigrateNew(args) {
+  const migrationName = args[0];
+
+  if (!migrationName) {
+    console.error('Error: Migration name required');
+    console.log('Usage: dzql migrate:new <name>');
+    console.log('Example: dzql migrate:new add_user_avatars');
+    process.exit(1);
+  }
+
+  // Create migrations directory if it doesn't exist
+  const migrationsDir = './migrations';
+  if (!existsSync(migrationsDir)) {
+    mkdirSync(migrationsDir, { recursive: true });
+  }
+
+  // Find next migration number
+  const fs = await import('fs/promises');
+  const files = await fs.readdir(migrationsDir).catch(() => []);
+  const existingNumbers = files
+    .filter(f => /^\d{3}_/.test(f))
+    .map(f => parseInt(f.substring(0, 3)))
+    .filter(n => !isNaN(n));
+
+  const nextNumber = existingNumbers.length > 0 ? Math.max(...existingNumbers) + 1 : 1;
+  const paddedNumber = String(nextNumber).padStart(3, '0');
+  const fileName = `${paddedNumber}_${migrationName}.sql`;
+  const filePath = resolve(migrationsDir, fileName);
+
+  if (existsSync(filePath)) {
+    console.error(`Error: Migration ${fileName} already exists`);
+    process.exit(1);
+  }
+
+  // Generate migration template
+  const template = `-- ============================================================================
+-- Migration ${paddedNumber}: ${migrationName.replace(/_/g, ' ')}
+-- Generated: ${new Date().toISOString().split('T')[0]}
+-- ============================================================================
+
+BEGIN;
+
+-- Part 1: Schema Changes
+-- ALTER TABLE example ADD COLUMN IF NOT EXISTS new_field TEXT;
+
+-- Part 2: Drop Old DZQL Functions (if updating entity)
+-- DROP FUNCTION IF EXISTS save_entity_name(INT, JSONB);
+-- DROP FUNCTION IF EXISTS get_entity_name(INT, INT, TIMESTAMPTZ);
+-- etc.
+
+-- Part 3: Install New Compiled Functions
+-- Compile your entities first: bun run compile
+-- Then paste the compiled function SQL here from init_db/entity_name.sql
+
+-- Part 4: Custom Functions (optional)
+-- CREATE OR REPLACE FUNCTION my_custom_function(
+--   p_user_id INT,
+--   p_params JSONB
+-- ) RETURNS JSONB AS $$
+-- BEGIN
+--   -- Your logic
+--   RETURN jsonb_build_object('result', 'success');
+-- END;
+-- $$ LANGUAGE plpgsql SECURITY DEFINER;
+
+-- Part 5: Register Custom Functions (optional)
+-- INSERT INTO dzql.registry (fn_regproc, description)
+-- VALUES
+--   ('my_custom_function'::regproc, 'Description of function')
+-- ON CONFLICT DO NOTHING;
+
+COMMIT;
+
+-- ============================================================================
+-- Rollback (for migrate:down support)
+-- ============================================================================
+-- To support rollback, add reverse operations in comments:
+--
+-- ROLLBACK INSTRUCTIONS:
+-- 1. Drop new functions
+-- 2. Restore old functions
+-- 3. Remove columns (if safe)
+-- 4. Drop tables (if safe)
+-- ============================================================================
+`;
+
+  writeFileSync(filePath, template, 'utf-8');
+
+  console.log(`\n✅ Created migration: ${fileName}`);
+  console.log(`📝 Edit: ${filePath}`);
+  console.log(`\n💡 Next steps:`);
+  console.log(`   1. Update your entity definitions (entities/*.sql)`);
+  console.log(`   2. Run: bun run compile (generates updated functions in init_db/)`);
+  console.log(`   3. Copy compiled functions into migration file`);
+  console.log(`   4. Test migration: psql $DATABASE_URL -f ${filePath}`);
+  console.log(`   5. Apply to production: dzql migrate:up\n`);
+}
+
+async function runMigrateUp(args) {
+  const databaseUrl = process.env.DATABASE_URL;
+
+  if (!databaseUrl) {
+    console.error('Error: DATABASE_URL environment variable not set');
+    console.log('Set it to your PostgreSQL connection string:');
+    console.log('  export DATABASE_URL="postgresql://user:pass@localhost:5432/dbname"');
+    process.exit(1);
+  }
+
+  const migrationsDir = './migrations';
+  if (!existsSync(migrationsDir)) {
+    console.error(`Error: Migrations directory not found: ${migrationsDir}`);
+    console.log('Create it with: dzql migrate:new <name>');
+    process.exit(1);
+  }
+
+  const sql = postgres(databaseUrl);
+
+  try {
+    console.log('🔌 Connected to database');
+
+    // 1. Create migrations table
+    await sql`
+      CREATE TABLE IF NOT EXISTS dzql.migrations (
+        id SERIAL PRIMARY KEY,
+        name TEXT NOT NULL UNIQUE,
+        applied_at TIMESTAMPTZ DEFAULT NOW()
+      );
+    `;
+
+    // 2. Get applied migrations
+    const appliedRows = await sql`SELECT name, applied_at FROM dzql.migrations ORDER BY applied_at`;
+    const appliedMigrations = new Set(appliedRows.map(row => row.name));
+
+    if (appliedRows.length > 0) {
+      console.log('\n📋 Already applied migrations:');
+      appliedRows.forEach(row => {
+        console.log(`   ✓ ${row.name} (${new Date(row.applied_at).toISOString()})`);
+      });
+    } else {
+      console.log('\n📋 No migrations applied yet.');
+    }
+
+    // 3. Read migration files
+    console.log('📂 Reading migrations from:', migrationsDir);
+
+    const files = readdirSync(migrationsDir)
+      .filter(f => f.endsWith('.sql'))
+      .sort(); // Alphabetical order (001, 002, 003...)
+
+    console.log(`\n📁 Found ${files.length} migration file(s)\n`);
+
+    // 4. Apply new migrations
+    let appliedCount = 0;
+    for (const file of files) {
+      if (appliedMigrations.has(file)) {
+        console.log(`   ⏭  Skipping ${file} (already applied)`);
+        continue;
+      }
+
+      console.log(`\n🚀 Applying migration: ${file}`);
+      const content = readFileSync(join(migrationsDir, file), 'utf-8');
+
+      try {
+        // Execute migration (it should have its own BEGIN/COMMIT)
+        await sql.unsafe(content);
+
+        // Record migration
+        await sql`INSERT INTO dzql.migrations (name) VALUES (${file})`;
+
+        console.log(`✅ Applied: ${file}`);
+        appliedCount++;
+      } catch (err) {
+        console.error(`\n❌ Failed to apply ${file}:`);
+        console.error(err.message);
+        console.error('\n💡 Check your migration file for errors.');
+        console.error('   If migration has BEGIN/COMMIT, it should have rolled back.');
+        process.exit(1);
+      }
+    }
+
+    if (appliedCount === 0) {
+      console.log('\n✨ No new migrations to apply. Database is up to date.');
+    } else {
+      console.log(`\n✨ Successfully applied ${appliedCount} migration(s).`);
+    }
+  } catch (err) {
+    console.error('❌ Migration failed:', err.message);
+    process.exit(1);
+  } finally {
+    await sql.end();
+  }
+}
+
+async function runMigrateDown(args) {
+  console.log('\n🚧 Migration:down command - Coming soon!');
+  console.log('\nThis command will:');
+  console.log('  1. Find last applied migration');
+  console.log('  2. Parse rollback instructions');
+  console.log('  3. Execute rollback');
+  console.log('  4. Remove from dzql.migrations table\n');
+}
+
+async function runMigrateStatus(args) {
+  const databaseUrl = process.env.DATABASE_URL;
+
+  if (!databaseUrl) {
+    console.error('Error: DATABASE_URL environment variable not set');
+    process.exit(1);
+  }
+
+  const migrationsDir = './migrations';
+  if (!existsSync(migrationsDir)) {
+    console.log('📂 No migrations directory found');
+    return;
+  }
+
+  const sql = postgres(databaseUrl);
+
+  try {
+    console.log('🔌 Connected to database\n');
+
+    // Create migrations table if it doesn't exist
+    await sql`
+      CREATE TABLE IF NOT EXISTS dzql.migrations (
+        id SERIAL PRIMARY KEY,
+        name TEXT NOT NULL UNIQUE,
+        applied_at TIMESTAMPTZ DEFAULT NOW()
+      );
+    `;
+
+    // Get applied migrations
+    const appliedRows = await sql`SELECT name, applied_at FROM dzql.migrations ORDER BY applied_at`;
+    const appliedMigrations = new Set(appliedRows.map(row => row.name));
+
+    // Get all migration files
+    const files = readdirSync(migrationsDir)
+      .filter(f => f.endsWith('.sql'))
+      .sort();
+
+    console.log('📊 Migration Status\n');
+    console.log(`Total migrations: ${files.length}`);
+    console.log(`Applied: ${appliedRows.length}`);
+    console.log(`Pending: ${files.length - appliedRows.length}\n`);
+
+    if (appliedRows.length > 0) {
+      console.log('✅ Applied Migrations:');
+      appliedRows.forEach(row => {
+        console.log(`   ${row.name} - ${new Date(row.applied_at).toLocaleString()}`);
+      });
+    }
+
+    const pendingFiles = files.filter(f => !appliedMigrations.has(f));
+    if (pendingFiles.length > 0) {
+      console.log('\n⏳ Pending Migrations:');
+      pendingFiles.forEach(file => {
+        console.log(`   ${file}`);
+      });
+      console.log('\nRun "dzql migrate:up" to apply pending migrations.');
+    } else {
+      console.log('\n✨ Database is up to date.');
+    }
+
+    console.log();
+  } catch (err) {
+    console.error('❌ Failed to get migration status:', err.message);
+    process.exit(1);
+  } finally {
+    await sql.end();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -22,7 +22,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "bun test",
+    "test": "bun test ../../tests/core/*.test.js",
     "prepublishOnly": "echo '✅ Publishing DZQL v0.3.5...'"
   },
   "dependencies": {

package/src/client/stores/README.md

@@ -0,0 +1,95 @@
+# DZQL Canonical Pinia Stores
+
+**The official, AI-friendly Pinia stores for DZQL Vue.js applications.**
+
+## Why These Stores Exist
+
+When building DZQL apps, developers (and AI assistants) often struggle with:
+
+1. **Three-phase lifecycle** - connecting → login → ready
+2. **WebSocket connection management** - reconnection, error handling
+3. **Authentication flow** - token storage, profile management  
+4. **Router integration** - navigation, state synchronization
+5. **Inconsistent patterns** - every project does it differently
+
+These canonical stores solve all of these problems with a **simple, consistent pattern** that AI can easily understand and replicate.
+
+## The Stores
+
+### `useWsStore` - WebSocket & Auth
+
+Manages:
+- WebSocket connection (with auto-reconnect)
+- User authentication (login/register/logout)
+- Connection state tracking
+- Three-phase app lifecycle
+
+### `useAppStore` - Application State
+
+Manages:
+- App initialization
+- Router integration
+- Entity metadata caching
+- Navigation helpers
+- UI state (sidebars, panels)
+
+## Quick Example
+
+```vue
+<script setup>
+import { computed } from 'vue'
+import { useWsStore, useAppStore } from 'dzql/client/stores'
+
+const wsStore = useWsStore()
+const appStore = useAppStore()
+
+const state = computed(() => wsStore.appState)
+const ws = wsStore.getWs()
+
+// Use DZQL API
+const venues = await ws.api.search.venues({ limit: 50 })
+</script>
+
+<template>
+  <!-- Three-phase lifecycle -->
+  <div v-if="state === 'connecting'">Connecting...</div>
+  <LoginView v-else-if="state === 'login'" />
+  <MainApp v-else-if="state === 'ready'" />
+</template>
+```
+
+## Documentation
+
+- **[Quick Start](../../../docs/reference/client.md)** - Get running in 5 minutes
+- **[Complete Guide](../../../docs/guides/client-stores.md)** - Full API reference and patterns
+
+## Files
+
+- `useWsStore.js` - WebSocket connection and authentication
+- `useAppStore.js` - Application state and navigation
+- `index.js` - Exports both stores
+
+## For AI Assistants
+
+When helping users with DZQL apps:
+
+1. **Always use these stores** - Don't create custom connection logic
+2. **Follow the three-phase lifecycle** - connecting → login → ready
+3. **Use computed for reactive state** - `const profile = computed(() => wsStore.profile)`
+4. **Get WS instance for API calls** - `const ws = wsStore.getWs()`
+
+**Example prompt for AI:**
+
+> "I'm using the canonical DZQL stores from `dzql/client/stores`. The pattern is:
+> 1. useWsStore for WebSocket connection (three phases: connecting, login, ready)
+> 2. useAppStore for app state and navigation
+> 3. Access DZQL API via `wsStore.getWs().api.get.venues({ id: 1 })`
+> Please follow this pattern."
+
+## Version
+
+These stores are available in DZQL v0.1.6+
+
+## License
+
+MIT

package/src/compiler/codegen/operation-codegen.js

@@ -78,6 +78,7 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     const m2mExtraction = this._generateM2MExtraction();
     const m2mSync = this._generateM2MSync();
     const m2mExpansion = this._generateM2MExpansion();
+    const fieldDefaults = this._generateFieldDefaults();
 
     return `-- SAVE operation for ${this.tableName}
 CREATE OR REPLACE FUNCTION save_${this.tableName}(
@@ -88,6 +89,7 @@ DECLARE
   v_result ${this.tableName}%ROWTYPE;
   v_existing ${this.tableName}%ROWTYPE;
   v_output JSONB;
+  v_before JSONB;
   v_is_insert BOOLEAN := false;
   v_notify_users INT[];
 ${m2mVariables}
@@ -116,6 +118,12 @@ ${m2mExtraction}
     END IF;
   END IF;
 
+  -- Expand M2M for existing record (for UPDATE events "before" field)
+  IF NOT v_is_insert THEN
+    v_before := to_jsonb(v_existing);
+${this._generateM2MExpansionForBefore()}
+  END IF;
+${fieldDefaults}
   -- Perform UPSERT
   IF v_is_insert THEN
     -- Dynamic INSERT from JSONB
@@ -547,6 +555,49 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     };
   }
 
+  /**
+   * Generate M2M expansion for existing record in SAVE (for "before" field)
+   * COMPILE TIME: Loop to generate code
+   * RUNTIME: Direct SQL queries (NO loops!)
+   * @private
+   */
+  _generateM2MExpansionForBefore() {
+    const manyToMany = this.entity.manyToMany || {};
+    if (Object.keys(manyToMany).length === 0) return '';
+
+    const expansions = [];
+
+    // COMPILE TIME LOOP: Generate code for each M2M relationship
+    for (const [relationKey, config] of Object.entries(manyToMany)) {
+      const idField = config.id_field;
+      const junctionTable = config.junction_table;
+      const localKey = config.local_key;
+      const foreignKey = config.foreign_key;
+      const targetEntity = config.target_entity;
+      const expand = config.expand || false;
+
+      // Always add ID array (static SQL)
+      expansions.push(`
+    v_before := v_before || jsonb_build_object('${idField}',
+      (SELECT COALESCE(jsonb_agg(${foreignKey} ORDER BY ${foreignKey}), '[]'::jsonb)
+       FROM ${junctionTable} WHERE ${localKey} = v_existing.id)
+    );`);
+
+      // Conditionally expand full objects (known at compile time!)
+      if (expand) {
+        expansions.push(`
+    v_before := v_before || jsonb_build_object('${relationKey}',
+      (SELECT COALESCE(jsonb_agg(to_jsonb(t.*) ORDER BY t.id), '[]'::jsonb)
+       FROM ${junctionTable} jt
+       JOIN ${targetEntity} t ON t.id = jt.${foreignKey}
+       WHERE jt.${localKey} = v_existing.id)
+    );`);
+      }
+    }
+
+    return expansions.join('');
+  }
+
   /**
    * Generate M2M expansion for GET operation
    * COMPILE TIME: Loop to generate code
@@ -616,21 +667,84 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
   );`);
       } else {
         // Direct FK: single object
-        const fkField = key.endsWith('_id') ? key : key + '_id';
+        // Use JSONB to check field existence (like resolve_direct_fk)
         expansions.push(`
   -- Expand ${key} (foreign key)
-  IF v_record.${fkField} IS NOT NULL THEN
-    v_result := v_result || jsonb_build_object(
-      '${key}',
-      (SELECT to_jsonb(t.*) FROM ${targetTable} t WHERE t.id = v_record.${fkField})
-    );
-  END IF;`);
+  DECLARE
+    v_fk_id INT;
+  BEGIN
+    -- Try field name directly first, then with _id suffix
+    IF to_jsonb(v_record) ? '${key}' THEN
+      v_fk_id := v_record.${key};
+    ELSIF to_jsonb(v_record) ? '${key}_id' THEN
+      v_fk_id := v_record.${key}_id;
+    END IF;
+
+    IF v_fk_id IS NOT NULL THEN
+      v_result := v_result || jsonb_build_object(
+        '${key}',
+        (SELECT to_jsonb(t.*) FROM ${targetTable} t WHERE t.id = v_fk_id)
+      );
+    END IF;
+  END;`);
       }
     }
 
     return expansions.join('');
   }
 
+  /**
+   * Generate field defaults application
+   * COMPILE TIME: Loop to generate code for each default
+   * RUNTIME: Direct value assignment (NO loops!)
+   * @private
+   */
+  _generateFieldDefaults() {
+    const fieldDefaults = this.entity.fieldDefaults || {};
+    if (Object.keys(fieldDefaults).length === 0) return '';
+
+    const defaults = [];
+
+    // COMPILE TIME LOOP: Generate separate IF block for each field default
+    for (const [fieldName, defaultValue] of Object.entries(fieldDefaults)) {
+      if (defaultValue.startsWith('@')) {
+        // Resolve variable defaults (@user_id, @now, @today)
+        const resolved = this._resolveDefaultVariable(defaultValue, fieldName);
+        defaults.push(`
+  -- Apply field default: ${fieldName} = ${defaultValue}
+  IF v_is_insert AND NOT (p_data ? '${fieldName}') THEN
+    p_data := p_data || jsonb_build_object('${fieldName}', ${resolved});
+  END IF;`);
+      } else {
+        // Literal default value
+        defaults.push(`
+  -- Apply field default: ${fieldName} = ${defaultValue}
+  IF v_is_insert AND NOT (p_data ? '${fieldName}') THEN
+    p_data := p_data || jsonb_build_object('${fieldName}', '${defaultValue}');
+  END IF;`);
+      }
+    }
+
+    return defaults.join('');
+  }
+
+  /**
+   * Resolve a variable default (@user_id, @now, @today) to SQL expression
+   * @private
+   */
+  _resolveDefaultVariable(variable, fieldName) {
+    switch (variable) {
+      case '@user_id':
+        return 'p_user_id';
+      case '@now':
+        return `to_char(NOW(), 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`;
+      case '@today':
+        return `to_char(CURRENT_DATE, 'YYYY-MM-DD')`;
+      default:
+        throw new Error(`Unknown field default variable: ${variable} for field ${fieldName}`);
+    }
+  }
+
   /**
    * Generate temporal filter
    * @private
@@ -731,15 +845,13 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     table_name,
     op,
     pk,
-    before,
-    after,
+    data,
     user_id,
     notify_users
   ) VALUES (
     '${this.tableName}',
     CASE WHEN v_is_insert THEN 'insert' ELSE 'update' END,
     jsonb_build_object('id', v_result.id),
-    CASE WHEN NOT v_is_insert THEN to_jsonb(v_existing) ELSE NULL END,
     v_output,
     p_user_id,
     v_notify_users
@@ -754,15 +866,13 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     table_name,
     op,
     pk,
-    before,
-    after,
+    data,
     user_id,
     notify_users
   ) VALUES (
     '${this.tableName}',
     'delete',
     jsonb_build_object('id', v_result.id),
-    to_jsonb(v_result),
     NULL,
     p_user_id,
     v_notify_users

package/src/compiler/parser/entity-parser.js

@@ -72,7 +72,17 @@ export class EntityParser {
       params.push(currentParam.trim());
     }
 
-    return params;
+    // Strip SQL comments (-- ...) from each parameter
+    return params.map(param => {
+      // Remove everything after -- (SQL line comment)
+      return param.split('\n').map(line => {
+        const commentIndex = line.indexOf('--');
+        if (commentIndex !== -1) {
+          return line.substring(0, commentIndex);
+        }
+        return line;
+      }).join('\n').trim();
+    });
   }
 
   /**
@@ -108,11 +118,11 @@ export class EntityParser {
    */
   _cleanString(str) {
     if (!str) return '';
-    // Remove outer quotes, SQL comments, then any remaining quotes and whitespace
-    let cleaned = str.replace(/^['"]|['"]$/g, '');  // Remove outer quotes
-    cleaned = cleaned.replace(/--[^\n]*/g, '');     // Remove SQL comments
-    cleaned = cleaned.replace(/['"\s]+$/g, '');     // Remove trailing quotes/whitespace
-    return cleaned.trim();
+    // Remove SQL comments first, then outer quotes
+    let cleaned = str.replace(/--[^\n]*/g, '');     // Remove SQL comments
+    cleaned = cleaned.trim();                        // Remove whitespace
+    cleaned = cleaned.replace(/^['"]|['"]$/g, '');  // Remove outer quotes
+    return cleaned;
   }
 
   /**

package/src/database/migrations/001_schema.sql

@@ -38,10 +38,9 @@ CREATE TABLE IF NOT EXISTS dzql.registry (
 CREATE TABLE IF NOT EXISTS dzql.events (
   event_id bigserial PRIMARY KEY,
   table_name text NOT NULL,
-  op text NOT NULL,              -- 'INSERT', 'UPDATE', 'DELETE'
+  op text NOT NULL,              -- 'insert', 'update', 'delete'
   pk jsonb NOT NULL,             -- primary key of affected record
-  before jsonb,                  -- old values (NULL for INSERT)
-  after jsonb,                   -- new values (NULL for DELETE)
+  data jsonb,                    -- record state after this event (NULL for delete)
   user_id int,                   -- who made the change
   notify_users int[],            -- who should be notified (NULL = everyone)
   at timestamptz DEFAULT now()  -- when the change occurred

package/src/database/migrations/002_functions.sql

@@ -749,7 +749,26 @@ BEGIN
       CONTINUE;
     END IF;
 
-    -- Check valid trigger types
+    -- Check for simpler CASCADE/SET NULL/RESTRICT format: {"delete": {"entity_name": "CASCADE"}}
+    IF l_trigger_key IN ('delete', 'update', 'create') AND jsonb_typeof(l_trigger_rules) = 'object' THEN
+      -- This is the simpler format - validate CASCADE/SET NULL/RESTRICT values
+      DECLARE
+        l_entity_name text;
+        l_action_value text;
+      BEGIN
+        FOR l_entity_name, l_action_value IN SELECT * FROM jsonb_each_text(l_trigger_rules)
+        LOOP
+          IF l_action_value NOT IN ('CASCADE', 'SET NULL', 'RESTRICT') THEN
+            RAISE WARNING 'Invalid graph rule action for entity %: %. Must be CASCADE, SET NULL, or RESTRICT', l_entity_name, l_action_value;
+            RETURN false;
+          END IF;
+        END LOOP;
+        -- Valid simpler format - skip complex validation
+        CONTINUE;
+      END;
+    END IF;
+
+    -- Check valid trigger types for complex format
     IF l_trigger_key NOT IN ('on_create', 'on_update', 'on_delete', 'on_field_change') THEN
       RAISE WARNING 'Invalid trigger type: %', l_trigger_key;
       RETURN false;

package/src/database/migrations/003_operations.sql

@@ -370,6 +370,62 @@ BEGIN
     END IF;
   END IF;
 
+  -- Expand M2M relationships in existing record (for UPDATE events)
+  IF NOT l_is_insert AND l_existing_record IS NOT NULL AND l_entity_config.many_to_many IS NOT NULL AND l_entity_config.many_to_many != '{}'::jsonb THEN
+    DECLARE
+      l_m2m_key text;
+      l_m2m_config jsonb;
+      l_id_field text;
+      l_junction_table text;
+      l_local_key text;
+      l_foreign_key text;
+      l_target_entity text;
+      l_expand boolean;
+      l_record_id text;
+      l_id_array jsonb;
+      l_expanded_objects jsonb;
+    BEGIN
+      -- Get the primary key value from the existing record
+      l_record_id := l_existing_record->>l_pk_cols[1];  -- Assume single PK for now
+
+      FOR l_m2m_key IN SELECT jsonb_object_keys(l_entity_config.many_to_many)
+      LOOP
+        l_m2m_config := l_entity_config.many_to_many->l_m2m_key;
+        l_id_field := l_m2m_config->>'id_field';
+        l_junction_table := l_m2m_config->>'junction_table';
+        l_local_key := l_m2m_config->>'local_key';
+        l_foreign_key := l_m2m_config->>'foreign_key';
+        l_target_entity := l_m2m_config->>'target_entity';
+        l_expand := COALESCE((l_m2m_config->>'expand')::boolean, false);
+
+        -- Always include array of IDs
+        EXECUTE format('
+          SELECT COALESCE(jsonb_agg(%I), ''[]''::jsonb)
+          FROM %I
+          WHERE %I = $1::int
+        ', l_foreign_key, l_junction_table, l_local_key)
+        INTO l_id_array
+        USING l_record_id;
+
+        l_existing_record := l_existing_record || jsonb_build_object(l_id_field, l_id_array);
+
+        -- Conditionally include expanded objects if expand: true
+        IF l_expand THEN
+          EXECUTE format('
+            SELECT COALESCE(jsonb_agg(to_jsonb(t.*)), ''[]''::jsonb)
+            FROM %I jt
+            JOIN %I t ON t.id = jt.%I
+            WHERE jt.%I = $1::int
+          ', l_junction_table, l_target_entity, l_foreign_key, l_local_key)
+          INTO l_expanded_objects
+          USING l_record_id;
+
+          l_existing_record := l_existing_record || jsonb_build_object(l_m2m_key, l_expanded_objects);
+        END IF;
+      END LOOP;
+    END;
+  END IF;
+
   IF NOT l_is_insert THEN
     -- UPDATE: Merge with existing record
 
@@ -389,12 +445,14 @@ BEGIN
     LOOP
       -- Don't update any primary key columns
       IF NOT (l_col_name = ANY(l_pk_cols)) THEN
-        -- Skip M2M ID fields (they're not real table columns)
+        -- Skip M2M ID fields and expanded fields (they're not real table columns)
         IF l_entity_config.many_to_many IS NOT NULL THEN
           DECLARE
             l_m2m_id_field text;
+            l_m2m_key text;
             l_skip boolean := false;
           BEGIN
+            -- Skip M2M ID fields (e.g., tag_ids)
             FOR l_m2m_id_field IN
               SELECT value->>'id_field'
               FROM jsonb_each(l_entity_config.many_to_many)
@@ -405,6 +463,19 @@ BEGIN
               END IF;
             END LOOP;
 
+            -- Skip M2M expanded fields (e.g., tags)
+            IF NOT l_skip THEN
+              FOR l_m2m_key IN
+                SELECT key
+                FROM jsonb_each(l_entity_config.many_to_many)
+              LOOP
+                IF l_col_name = l_m2m_key THEN
+                  l_skip := true;
+                  EXIT;
+                END IF;
+              END LOOP;
+            END IF;
+
             IF NOT l_skip THEN
               l_set_clauses := l_set_clauses || format('%I = %L', l_col_name, l_merged_data ->> l_col_name);
             END IF;
@@ -640,8 +711,7 @@ BEGIN
     table_name,
     op,
     pk,
-    before,
-    after,
+    data,
     user_id,
     notify_users
   ) VALUES (
@@ -651,7 +721,6 @@ BEGIN
       SELECT jsonb_object_agg(col, l_result ->> col)
       FROM unnest(l_pk_cols) AS col
     ),
-    CASE WHEN NOT l_is_insert THEN l_existing_record ELSE NULL END,
     l_result,
     p_user_id,
     dzql.resolve_notification_paths(p_entity, l_result)
@@ -736,6 +805,106 @@ BEGIN
     RAISE EXCEPTION 'Permission denied: delete on %', p_entity;
   END IF;
 
+  -- Apply CASCADE/SET NULL/RESTRICT rules from child entities
+  DECLARE
+    l_child_entity record;
+    l_child_graph_rules jsonb;
+    l_delete_rules jsonb;
+    l_rule_name text;
+    l_rule_action text;
+    l_fk_field text;
+    l_fk_key text;
+    l_child_count int;
+  BEGIN
+    -- Find all entities that reference this entity
+    FOR l_child_entity IN
+      SELECT * FROM dzql.entities
+      WHERE fk_includes IS NOT NULL
+        AND fk_includes != '{}'
+    LOOP
+      -- Check if this child entity has an FK pointing to the entity being deleted
+      FOR l_fk_key IN SELECT jsonb_object_keys(l_child_entity.fk_includes)
+      LOOP
+        IF l_child_entity.fk_includes->>l_fk_key = p_entity THEN
+          -- This child entity references the parent being deleted
+          l_child_graph_rules := l_child_entity.graph_rules;
+
+          IF l_child_graph_rules IS NOT NULL AND l_child_graph_rules != '{}' THEN
+            l_delete_rules := l_child_graph_rules->'delete';
+
+            IF l_delete_rules IS NOT NULL AND l_delete_rules != '{}' THEN
+              -- Check rules for this child entity
+              FOR l_rule_name, l_rule_action IN SELECT * FROM jsonb_each_text(l_delete_rules)
+              LOOP
+                -- The rule_name should match the child entity name
+                IF l_rule_name = l_child_entity.table_name THEN
+                  -- Determine FK field name (try direct match then _id suffix)
+                  l_fk_field := l_fk_key;
+                  IF NOT EXISTS (
+                    SELECT 1 FROM information_schema.columns
+                    WHERE table_name = l_child_entity.table_name
+                    AND column_name = l_fk_field
+                  ) THEN
+                    l_fk_field := l_fk_key || '_id';
+                  END IF;
+
+                  -- Apply the rule action
+                  CASE l_rule_action
+                    WHEN 'CASCADE' THEN
+                      -- Delete child records via generic_delete to trigger events
+                      DECLARE
+                        l_child_record record;
+                      BEGIN
+                        FOR l_child_record IN
+                          EXECUTE format(
+                            'SELECT * FROM %I WHERE %I = %L',
+                            l_child_entity.table_name,
+                            l_fk_field,
+                            l_record->>'id'
+                          )
+                        LOOP
+                          -- Call generic_delete for each child to ensure events are created
+                          PERFORM dzql.generic_delete(
+                            l_child_entity.table_name,
+                            jsonb_build_object('id', l_child_record.id),
+                            p_user_id
+                          );
+                        END LOOP;
+                      END;
+
+                    WHEN 'SET NULL' THEN
+                      -- Set FK to NULL in child records
+                      EXECUTE format(
+                        'UPDATE %I SET %I = NULL WHERE %I = %L',
+                        l_child_entity.table_name,
+                        l_fk_field,
+                        l_fk_field,
+                        l_record->>'id'
+                      );
+
+                    WHEN 'RESTRICT' THEN
+                      -- Check if children exist, prevent delete if so
+                      EXECUTE format(
+                        'SELECT COUNT(*) FROM %I WHERE %I = %L',
+                        l_child_entity.table_name,
+                        l_fk_field,
+                        l_record->>'id'
+                      ) INTO l_child_count;
+
+                      IF l_child_count > 0 THEN
+                        RAISE EXCEPTION 'Cannot delete % - % child records exist in %',
+                          p_entity, l_child_count, l_child_entity.table_name;
+                      END IF;
+                  END CASE;
+                END IF;
+              END LOOP;
+            END IF;
+          END IF;
+        END IF;
+      END LOOP;
+    END LOOP;
+  END;
+
   -- Execute graph rules for delete
   l_graph_rules_result := dzql.execute_graph_rules(
     p_entity,
@@ -760,8 +929,7 @@ BEGIN
     table_name,
     op,
     pk,
-    before,
-    after,
+    data,
     user_id,
     notify_users
   ) VALUES (
@@ -771,7 +939,6 @@ BEGIN
       SELECT jsonb_object_agg(col, l_record ->> col)
       FROM unnest(l_pk_cols) AS col
     ),
-    l_record,
     NULL,
     p_user_id,
     dzql.resolve_notification_paths(p_entity, l_record)
@@ -867,6 +1034,11 @@ BEGIN
 
   l_where_clause := l_where_clause || l_temporal_filter;
 
+  -- Add soft delete filter if enabled for this entity
+  IF l_entity_config.soft_delete THEN
+    l_where_clause := l_where_clause || ' AND t.deleted_at IS NULL';
+  END IF;
+
   IF l_is_compound_key AND l_entity_config.fk_includes IS NOT NULL AND l_entity_config.fk_includes != '{}' THEN
     -- For compound keys with FK includes, build full dereferenced labels
     l_sql_stmt := format(

package/src/database/migrations/004_search.sql

@@ -349,6 +349,11 @@ BEGIN
     l_where_clause := l_where_clause || format(' AND dzql.check_permission(%L, ''view'', %L, to_jsonb(t.*))', p_user_id, p_entity);
   END IF;
 
+  -- Add soft delete filter if enabled for this entity
+  IF l_entity_config.soft_delete THEN
+    l_where_clause := l_where_clause || ' AND t.deleted_at IS NULL';
+  END IF;
+
   -- Build base SQL
   l_base_sql := format('FROM %I t %s', p_entity, l_where_clause);
 

package/src/database/migrations/005_entities.sql

@@ -125,15 +125,13 @@ BEGIN
     table_name,
     op,
     pk,
-    before,
-    after,
+    data,
     user_id,
     notify_users
   ) VALUES (
     p_entity,
     'insert',
     jsonb_build_object('id', p_data->>'id'),
-    NULL,
     p_data,
     p_user_id,
     dzql.resolve_notification_paths(p_entity, p_data)
@@ -179,20 +177,17 @@ BEGIN
   EXECUTE l_sql_stmt;
 
   -- Create event for graph rule action
-  -- Note: We don't have the before/after data here, just logging the update occurred
   INSERT INTO dzql.events (
     table_name,
     op,
     pk,
-    before,
-    after,
+    data,
     user_id,
     notify_users
   ) VALUES (
     p_entity,
     'update',
     p_match,
-    NULL,  -- We don't have the before state in this context
     p_data,
     p_user_id,
     '[]'::int[]  -- Graph rule updates don't have notification paths
@@ -232,15 +227,13 @@ BEGIN
     table_name,
     op,
     pk,
-    before,
-    after,
+    data,
     user_id,
     notify_users
   ) VALUES (
     p_entity,
     'delete',
     p_match,
-    NULL,  -- We don't have the before state in this context
     NULL,
     p_user_id,
     '[]'::int[]  -- Graph rule deletes don't have notification paths

package/src/database/migrations/007_events.sql

@@ -10,15 +10,12 @@ CREATE OR REPLACE FUNCTION dzql.notify_event()
 RETURNS TRIGGER LANGUAGE plpgsql AS $$
 BEGIN
   -- Send real-time notification to single channel
-  -- For DELETE operations, send the 'before' data since 'after' is NULL
   PERFORM pg_notify('dzql', jsonb_build_object(
     'event_id', NEW.event_id,
     'table', NEW.table_name,
     'op', NEW.op,
     'pk', NEW.pk,
-    'data', COALESCE(NEW.after, NEW.before),
-    'before', NEW.before,
-    'after', NEW.after,
+    'data', NEW.data,
     'user_id', NEW.user_id,
     'at', NEW.at,
     'notify_users', NEW.notify_users

package/src/database/migrations/010_fix_m2m_events.sql

@@ -0,0 +1,94 @@
+-- ============================================================================
+-- Migration 010: Fix M2M in Event "before" Field
+-- ============================================================================
+--
+-- Issue: UPDATE events don't include M2M data in the "before" field
+-- Root cause: l_existing_record in generic_save doesn't expand M2M relationships
+-- Fix: Create a helper function to expand M2M, then update generic_save to use it
+--
+-- This ensures UPDATE events have complete before/after state including M2M data
+-- ============================================================================
+
+DO $$ BEGIN
+  RAISE NOTICE 'Migration 010: Fixing M2M in event before field...';
+END $$;
+
+-- Create helper function to expand M2M relationships for a record
+CREATE OR REPLACE FUNCTION dzql.expand_m2m_for_record(
+  p_entity text,
+  p_record jsonb,
+  p_entity_config record,
+  p_pk_cols text[]
+) RETURNS jsonb
+LANGUAGE plpgsql
+AS $$
+DECLARE
+  l_result jsonb := p_record;
+  l_m2m_key text;
+  l_m2m_config jsonb;
+  l_id_field text;
+  l_junction_table text;
+  l_local_key text;
+  l_foreign_key text;
+  l_target_entity text;
+  l_expand boolean;
+  l_record_id text;
+  l_id_array jsonb;
+  l_expanded_objects jsonb;
+BEGIN
+  -- Only expand if entity has M2M configuration
+  IF p_entity_config.many_to_many IS NULL OR p_entity_config.many_to_many = '{}'::jsonb THEN
+    RETURN l_result;
+  END IF;
+
+  -- Get the primary key value from the record
+  l_record_id := l_result->>p_pk_cols[1];  -- Assume single PK for now
+
+  IF l_record_id IS NULL THEN
+    RETURN l_result;
+  END IF;
+
+  -- Loop through all M2M relationships
+  FOR l_m2m_key IN SELECT jsonb_object_keys(p_entity_config.many_to_many)
+  LOOP
+    l_m2m_config := p_entity_config.many_to_many->l_m2m_key;
+    l_id_field := l_m2m_config->>'id_field';
+    l_junction_table := l_m2m_config->>'junction_table';
+    l_local_key := l_m2m_config->>'local_key';
+    l_foreign_key := l_m2m_config->>'foreign_key';
+    l_target_entity := l_m2m_config->>'target_entity';
+    l_expand := COALESCE((l_m2m_config->>'expand')::boolean, false);
+
+    -- Always include array of IDs
+    EXECUTE format('
+      SELECT COALESCE(jsonb_agg(%I ORDER BY %I), ''[]''::jsonb)
+      FROM %I
+      WHERE %I = $1::int
+    ', l_foreign_key, l_foreign_key, l_junction_table, l_local_key)
+    INTO l_id_array
+    USING l_record_id;
+
+    l_result := l_result || jsonb_build_object(l_id_field, l_id_array);
+
+    -- Conditionally include expanded objects if expand: true
+    IF l_expand THEN
+      EXECUTE format('
+        SELECT COALESCE(jsonb_agg(to_jsonb(t.*) ORDER BY t.id), ''[]''::jsonb)
+        FROM %I jt
+        JOIN %I t ON t.id = jt.%I
+        WHERE jt.%I = $1::int
+      ', l_junction_table, l_target_entity, l_foreign_key, l_local_key)
+      INTO l_expanded_objects
+      USING l_record_id;
+
+      l_result := l_result || jsonb_build_object(l_m2m_key, l_expanded_objects);
+    END IF;
+  END LOOP;
+
+  RETURN l_result;
+END $$;
+
+DO $$ BEGIN
+  RAISE NOTICE 'Migration 010: M2M expansion helper function created';
+  RAISE NOTICE 'Note: generic_save still needs updating to use this helper - will be done in next migration';
+END $$;