dzql 0.5.28 → 0.5.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.5.28",
+  "version": "0.5.30",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",

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

@@ -243,6 +243,7 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
 
   /**
    * Generate SAVE function for composite primary keys
+   * Uses INSERT ... ON CONFLICT DO UPDATE (UPSERT) to avoid race conditions
    * @private
    */
   _generateCompositePKSaveFunction(helpers) {
@@ -259,22 +260,12 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
 
     const pkDescription = this.primaryKey.join(', ');
 
-    // Generate WHERE clause for composite PK lookup
+    // Generate WHERE clause for composite PK lookup (used for permission checks and v_before)
     // e.g., "entity_type = (p_data->>'entity_type') AND entity_id = (p_data->>'entity_id')::int"
     const whereClause = this.primaryKey.map(col => {
       return `${col} = (p_data->>'${col}')${this._getTypeCast(col)}`;
     }).join(' AND ');
 
-    // For use inside format() string literal with %L placeholders
-    // e.g., "entity_type = %L AND entity_id = %L"
-    const whereClauseForFormat = this.primaryKey.map(col => `${col} = %L`).join(' AND ');
-
-    // Format arguments for the WHERE clause (to be passed to format())
-    // e.g., "(p_data->>'entity_type'), (p_data->>'entity_id')::int"
-    const whereClauseFormatArgs = this.primaryKey.map(col => {
-      return `(p_data->>'${col}')${this._getTypeCast(col)}`;
-    }).join(', ');
-
     // Check if all PK fields are present in p_data
     const pkNullCheck = this.primaryKey.map(col => `p_data->>'${col}' IS NULL`).join(' OR ');
 
@@ -286,7 +277,12 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
     const m2mExpansionCompositePK = this._generateM2MExpansionCompositePK();
     const m2mExpansionForBeforeCompositePK = this._generateM2MExpansionForBeforeCompositePK();
 
+    // Generate ON CONFLICT clause for composite PK
+    // e.g., "(entity_type, entity_id)"
+    const onConflictPK = `(${this.primaryKey.join(', ')})`;
+
     return `-- SAVE operation for ${this.tableName} (composite primary key: ${pkDescription})
+-- Uses UPSERT (INSERT ... ON CONFLICT DO UPDATE) to prevent race conditions
 CREATE OR REPLACE FUNCTION save_${this.tableName}(
   p_user_id INT,
   p_data JSONB
@@ -298,68 +294,76 @@ DECLARE
   v_before JSONB;
   v_is_insert BOOLEAN := false;
   v_notify_users INT[];
+  v_columns TEXT;
+  v_values TEXT;
+  v_update_set TEXT;
 ${m2mVariables}
 BEGIN
 ${m2mExtraction}
-  -- Determine if this is insert or update (composite PK: ${pkDescription})
-  IF ${pkNullCheck} THEN
-    -- Missing one or more PK fields - this is an insert
-    v_is_insert := true;
-  ELSE
-    -- Try to fetch existing record by composite PK
+  -- Check if this might be an update (all PK fields present)
+  -- We still need to check for existing record for permission checks and v_before
+  IF NOT (${pkNullCheck}) THEN
     SELECT * INTO v_existing
     FROM ${this.tableName}
     WHERE ${whereClause};
 
-    v_is_insert := NOT FOUND;
-  END IF;
-
-  -- Check permissions
-  IF v_is_insert THEN
-    IF NOT can_create_${this.tableName}(p_user_id, p_data) THEN
-      RAISE EXCEPTION 'Permission denied: create on ${this.tableName}';
+    IF FOUND THEN
+      -- Check update permission on existing record
+      IF NOT can_update_${this.tableName}(p_user_id, to_jsonb(v_existing)) THEN
+        RAISE EXCEPTION 'Permission denied: update on ${this.tableName}';
+      END IF;
+      -- Store before state for M2M expansion
+      v_before := to_jsonb(v_existing);
+${m2mExpansionForBeforeCompositePK}
+    ELSE
+      -- Record doesn't exist yet, this will be an insert
+      IF NOT can_create_${this.tableName}(p_user_id, p_data) THEN
+        RAISE EXCEPTION 'Permission denied: create on ${this.tableName}';
+      END IF;
     END IF;
   ELSE
-    IF NOT can_update_${this.tableName}(p_user_id, to_jsonb(v_existing)) THEN
-      RAISE EXCEPTION 'Permission denied: update on ${this.tableName}';
+    -- Missing PK fields - must be a new insert
+    IF NOT can_create_${this.tableName}(p_user_id, p_data) THEN
+      RAISE EXCEPTION 'Permission denied: create on ${this.tableName}';
     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);
-${m2mExpansionForBeforeCompositePK}
-  END IF;
 ${fieldDefaults}
-  -- Perform UPSERT
-  IF v_is_insert THEN
-    -- Dynamic INSERT from JSONB
-    EXECUTE (
-      SELECT format(
-        'INSERT INTO ${this.tableName} (%s) VALUES (%s) RETURNING *',
-        string_agg(quote_ident(key), ', '),
-        string_agg(quote_nullable(value), ', ')
-      )
-      FROM jsonb_each_text(p_data) kv(key, value)
+  -- Build column and value lists for UPSERT
+  SELECT
+    string_agg(quote_ident(key), ', '),
+    string_agg(quote_nullable(value), ', ')
+  INTO v_columns, v_values
+  FROM jsonb_each_text(p_data) kv(key, value);
+
+  -- Build UPDATE SET clause (excluding PK columns)
+  SELECT string_agg(quote_ident(key) || ' = EXCLUDED.' || quote_ident(key), ', ')
+  INTO v_update_set
+  FROM jsonb_each_text(p_data) kv(key, value)
+  WHERE ${this.primaryKey.map(col => `key != '${col}'`).join(' AND ')};
+
+  -- Perform atomic UPSERT to avoid race conditions
+  IF v_update_set IS NOT NULL AND v_update_set != '' THEN
+    -- Has non-PK fields to update
+    EXECUTE format(
+      'INSERT INTO ${this.tableName} (%s) VALUES (%s) ' ||
+      'ON CONFLICT ${onConflictPK} DO UPDATE SET %s ' ||
+      'RETURNING *',
+      v_columns, v_values, v_update_set
     ) INTO v_result;
   ELSE
-    -- Dynamic UPDATE from JSONB (only if there are non-PK fields to update)
-    IF (SELECT COUNT(*) FROM jsonb_object_keys(p_data) WHERE ${pkFieldsExclusion}) > 0 THEN
-      EXECUTE (
-        SELECT format(
-          'UPDATE ${this.tableName} SET %s WHERE ${whereClauseForFormat} RETURNING *',
-          string_agg(quote_ident(key) || ' = ' || quote_nullable(value), ', '),
-          ${whereClauseFormatArgs}
-        )
-        FROM jsonb_each_text(p_data) kv(key, value)
-        WHERE ${this.primaryKey.map(col => `key != '${col}'`).join(' AND ')}
-      ) INTO v_result;
-    ELSE
-      -- No fields to update (only M2M fields were provided), just fetch existing
-      v_result := v_existing;
-    END IF;
+    -- Only PK fields provided - insert or return existing
+    EXECUTE format(
+      'INSERT INTO ${this.tableName} (%s) VALUES (%s) ' ||
+      'ON CONFLICT ${onConflictPK} DO UPDATE SET ${this.primaryKey[0]} = EXCLUDED.${this.primaryKey[0]} ' ||
+      'RETURNING *',
+      v_columns, v_values
+    ) INTO v_result;
   END IF;
 
+  -- Determine if this was an insert by checking if v_existing was found
+  -- (if v_existing was NOT FOUND, then this was an insert)
+  v_is_insert := v_existing.${this.primaryKey[0]} IS NULL;
+
 ${m2mSyncCompositePK}
 
   -- Prepare output with M2M fields (BEFORE event creation for real-time notifications!)

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

@@ -129,6 +129,8 @@ export class SubscribableParser {
    */
   _cleanString(str) {
     if (!str) return '';
+    // Handle SQL NULL keyword - return empty string for null values
+    if (str.trim().toUpperCase() === 'NULL') 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

package/src/database/migrations/009_subscriptions.sql

@@ -11,7 +11,7 @@ CREATE TABLE IF NOT EXISTS dzql.subscribables (
   name TEXT PRIMARY KEY,
   permission_paths JSONB NOT NULL DEFAULT '{}'::jsonb,
   param_schema JSONB NOT NULL DEFAULT '{}'::jsonb,
-  root_entity TEXT NOT NULL,
+  root_entity TEXT,  -- NULL allowed for dashboard mode (pure collections)
   relations JSONB NOT NULL DEFAULT '{}'::jsonb,
   scope_tables TEXT[] NOT NULL DEFAULT '{}',
   created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
@@ -31,7 +31,7 @@ COMMENT ON COLUMN dzql.subscribables.param_schema IS
   'Parameter schema defining subscription key (e.g., {"venue_id": "int"})';
 
 COMMENT ON COLUMN dzql.subscribables.root_entity IS
-  'Root table for the subscribable document';
+  'Root table for the subscribable document. NULL for dashboard mode (pure collections).';
 
 COMMENT ON COLUMN dzql.subscribables.relations IS
   'Related entities to include (e.g., {"org": "organisations", "sites": {"entity": "sites", "filter": "venue_id=$venue_id"}})';

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

@@ -16,8 +16,12 @@ DECLARE
   v_entity TEXT;
   v_nested JSONB;
 BEGIN
-  -- Start with root entity
-  v_tables := ARRAY[p_root_entity];
+  -- Start with root entity (may be NULL for dashboard mode)
+  IF p_root_entity IS NOT NULL AND p_root_entity != '' THEN
+    v_tables := ARRAY[p_root_entity];
+  ELSE
+    v_tables := ARRAY[]::TEXT[];
+  END IF;
 
   -- Return early if no relations
   IF p_relations IS NULL OR p_relations = '{}'::jsonb THEN
@@ -85,8 +89,11 @@ BEGIN
     RAISE EXCEPTION 'Subscribable name cannot be empty';
   END IF;
 
-  IF p_root_entity IS NULL OR p_root_entity = '' THEN
-    RAISE EXCEPTION 'Root entity cannot be empty';
+  -- NULL root_entity is allowed for dashboard mode (pure collections)
+  -- But if relations is also empty, that's an error
+  IF (p_root_entity IS NULL OR p_root_entity = '') AND
+     (p_relations IS NULL OR p_relations = '{}'::jsonb) THEN
+    RAISE EXCEPTION 'Subscribable must have either a root entity or relations';
   END IF;
 
   -- Extract scope tables from root entity and relations
@@ -106,7 +113,7 @@ BEGIN
     p_name,
     COALESCE(p_permission_paths, '{}'::jsonb),
     COALESCE(p_param_schema, '{}'::jsonb),
-    p_root_entity,
+    NULLIF(p_root_entity, ''),  -- Store empty string as NULL
     COALESCE(p_relations, '{}'::jsonb),
     v_scope_tables,
     NOW(),