masterrecord 0.3.13 → 0.3.15

package/Migrations/cli.js

@@ -35,6 +35,19 @@ function __getMigrationTimestamp(file){
   }
 }
 
+// Helper to cleanup context and exit
+async function __cleanupAndExit(contextInstance, exitCode = 0) {
+  try {
+    if (contextInstance && typeof contextInstance.close === 'function') {
+      await contextInstance.close();
+    }
+  } catch(err) {
+    console.error('Warning: Error during cleanup:', err.message);
+  } finally {
+    process.exit(exitCode);
+  }
+}
+
 
 const [,, ...args] = process.argv
 
@@ -52,39 +65,44 @@ program.option('-V', 'output the version');
   .command('enable-migrations <contextFileName>')
   .alias('em')
   .description('Enables the migration in your project by creating a configuration class called ContextSnapShot.json')
-  .action(function(contextFileName){
-
-        var migration = new Migration();
-        // location of folder where command is being executed..
-        var executedLocation = process.cwd();
-        // find context file from main folder location
-        var contextFile = migration.findContextFile(executedLocation, contextFileName);
-        if(!contextFile){
-          console.error(`\n❌ Error - Cannot read or find Context file '${contextFileName}.js'`);
-          console.error(`\nSearched in: ${executedLocation}`);
-          console.error(`\nMake sure your Context file exists and is named correctly.`);
-          return;
-        }
-        var snap = {
-          file : contextFile,
-          executedLocation : executedLocation,
-          contextEntities : [],
-          contextFileName: contextFileName.toLowerCase()
-        }
-
-        migration.createSnapShot(snap);
-        console.log("✓ Migration enabled successfully")
+  .action(async function(contextFileName){
+        try {
+          var migration = new Migration();
+          // location of folder where command is being executed..
+          var executedLocation = process.cwd();
+          // find context file from main folder location
+          var contextFile = migration.findContextFile(executedLocation, contextFileName);
+          if(!contextFile){
+            console.error(`\n❌ Error - Cannot read or find Context file '${contextFileName}.js'`);
+            console.error(`\nSearched in: ${executedLocation}`);
+            console.error(`\nMake sure your Context file exists and is named correctly.`);
+            process.exit(1);
+          }
+          var snap = {
+            file : contextFile,
+            executedLocation : executedLocation,
+            contextEntities : [],
+            contextFileName: contextFileName.toLowerCase()
+          }
 
+          migration.createSnapShot(snap);
+          console.log("✓ Migration enabled successfully")
+          process.exit(0);
+        } catch(err) {
+          console.error('Error:', err);
+          process.exit(1);
+        }
   });
 
   program
   .command('ensure-database <contextFileName>')
   .alias('ed')
   .description('Ensure the target database exists for the given context (MySQL)')
-  .action(function(contextFileName){
+  .action(async function(contextFileName){
     var executedLocation = process.cwd();
     contextFileName = contextFileName.toLowerCase();
     var migration = new Migration();
+    var contextInstance = null;
     try{
       var files = globSearch.sync(`**/*${contextFileName}_contextSnapShot.json`, { cwd: executedLocation, dot: true, windowsPathsNoEscape: true, nocase: true });
       var file = files && files[0] ? path.resolve(executedLocation, files[0]) : null;
@@ -107,7 +125,7 @@ program.option('-V', 'output the version');
       migrationFiles = (migrationFiles || []).map(f => path.resolve(migBase, f));
       if(!(migrationFiles && migrationFiles.length)){
         console.log("Error - Cannot read or find migration file");
-        return;
+        process.exit(1);
       }
       var mFiles = migrationFiles.slice().sort(function(a, b){
         return __getMigrationTimestamp(a) - __getMigrationTimestamp(b);
@@ -125,33 +143,41 @@ program.option('-V', 'output the version');
           console.error(`\nStack trace:`);
           console.error(err.stack);
         }
-        return;
+        process.exit(1);
       }
 
       // Use the migration class (extends schema) so createdatabase is available
       var MigrationCtor = require(mFile);
       var mig = new MigrationCtor(ContextCtor);
+      contextInstance = mig._context || mig.context || null;
+
       if(typeof mig.createdatabase === 'function'){
         try{
           mig.createdatabase();
           console.log('✓ Database ensured');
+          await __cleanupAndExit(contextInstance, 0);
         }catch(err){
           console.error(`\n❌ Error creating database:`);
           console.error(err.message);
+          await __cleanupAndExit(contextInstance, 1);
         }
       } else if(typeof mig.createDatabase === 'function'){
         try{
           mig.createDatabase();
           console.log('✓ Database ensured');
+          await __cleanupAndExit(contextInstance, 0);
         }catch(err){
           console.error(`\n❌ Error creating database:`);
           console.error(err.message);
+          await __cleanupAndExit(contextInstance, 1);
         }
       } else {
         console.error('❌ Error - Migration class missing createDatabase method');
+        await __cleanupAndExit(contextInstance, 1);
       }
     }catch(e){
       console.log('Error - Cannot read or find file ', e);
+      await __cleanupAndExit(contextInstance, 1);
     }
   });
 
@@ -193,7 +219,7 @@ program.option('-V', 'output the version');
   program
   .command('add-migration <name> <contextFileName>')
   .alias('am')
-  .action(function(name, contextFileName){
+  .action(async function(name, contextFileName){
     var executedLocation = process.cwd();
     contextFileName = contextFileName.toLowerCase();
     var migration = new Migration();
@@ -263,12 +289,28 @@ program.option('-V', 'output the version');
         }
         var migrationDate = Date.now();
         var outputFile = `${migBase}/${migrationDate}_${name}_migration.js`
-        fs.writeFile(outputFile, newEntity, 'utf8', function (err) {
-          if (err) return console.log("--- Error running cammand, re-run command add-migration ---- ", err);
+        fs.writeFile(outputFile, newEntity, 'utf8', async function (err) {
+          if (err) {
+            console.log("--- Error running cammand, re-run command add-migration ---- ", err);
+            if (contextInstance && typeof contextInstance.close === 'function') {
+              await contextInstance.close();
+            }
+            process.exit(1);
+          }
+          console.log(`✓ Migration '${name}' created successfully at ${outputFile}`);
+
+          // Close database connections to prevent hanging
+          if (contextInstance && typeof contextInstance.close === 'function') {
+            await contextInstance.close();
+          }
+          process.exit(0);
         });
-        console.log(`✓ Migration '${name}' created successfully at ${outputFile}`);
        }catch (e){
          console.log("Error - Cannot read or find file ", e);
+         if (contextInstance && typeof contextInstance.close === 'function') {
+           await contextInstance.close();
+         }
+         process.exit(1);
       }
   });
 
@@ -276,10 +318,11 @@ program.option('-V', 'output the version');
   .command('update-database <contextFileName>')
   .alias('ud')
   .description('Apply pending migrations to database - up method call')
-  .action(function(contextFileName){
+  .action(async function(contextFileName){
     var executedLocation = process.cwd();
     contextFileName = contextFileName.toLowerCase();
     var migration = new Migration();
+    var contextInstance = null;
       try{
          console.log(`\n🔍 Searching for context snapshot '${contextFileName}_contextSnapShot.json'...`);
          // find context snapshot (cwd-based glob)
@@ -291,7 +334,7 @@ program.option('-V', 'output the version');
            console.error(`\nSearched for: ${contextFileName}_contextSnapShot.json`);
            console.error(`Searched in: ${executedLocation}`);
            console.error(`\n💡 Solution: Run 'masterrecord enable-migrations ${contextFileName}' first`);
-           return;
+           await __cleanupAndExit(contextInstance, 1);
          }
 
          console.log(`✓ Found snapshot: ${file}`);
@@ -303,7 +346,7 @@ program.option('-V', 'output the version');
            console.error(`\n❌ Error - Cannot load context snapshot`);
            console.error(`\nFile: ${file}`);
            console.error(`Details: ${err.message}`);
-           return;
+           await __cleanupAndExit(contextInstance, 1);
          }
 
          const snapDir = path.dirname(file);
@@ -318,7 +361,7 @@ program.option('-V', 'output the version');
            console.error(`\n❌ Error - No migration files found`);
            console.error(`\nSearched in: ${migBase}`);
            console.error(`\n💡 Solution: Run 'masterrecord add-migration Init ${contextFileName}' to create your first migration`);
-           return;
+           await __cleanupAndExit(contextInstance, 1);
          }
 
          // sort by timestamp prefix or file mtime as fallback
@@ -343,13 +386,12 @@ program.option('-V', 'output the version');
              console.error(`\nStack trace:`);
              console.error(err.stack);
            }
-           return;
+           await __cleanupAndExit(contextInstance, 1);
          }
 
          console.log(`✓ Context file loaded successfully`);
          console.log(`\n🔍 Instantiating Context (this will create the database if it doesn't exist)...`);
 
-         var contextInstance;
          try{
            contextInstance = new ContextCtor();
          }catch(err){
@@ -367,7 +409,7 @@ program.option('-V', 'output the version');
            }
            console.error(`\n💡 Check your environment config file (e.g., config/environments/env.development.json)`);
            console.error(`💡 Make sure you're running: master=development masterrecord update-database ${contextFileName}`);
-           return;
+           await __cleanupAndExit(contextInstance, 1);
          }
 
          console.log(`✓ Context instantiated successfully`);
@@ -414,7 +456,7 @@ program.option('-V', 'output the version');
              console.error(`\nStack trace:`);
              console.error(err.stack);
            }
-           return;
+           await __cleanupAndExit(contextInstance, 1);
          }
 
          console.log(`\n💾 Updating snapshot...`);
@@ -441,6 +483,7 @@ program.option('-V', 'output the version');
            }
          }
 
+         await __cleanupAndExit(contextInstance, 0);
         }catch (e){
           console.error(`\n❌ Unexpected error during update-database`);
           console.error(`\nDetails: ${e.message}`);
@@ -448,6 +491,7 @@ program.option('-V', 'output the version');
             console.error(`\nStack trace:`);
             console.error(e.stack);
           }
+          await __cleanupAndExit(contextInstance, 1);
         }
   });
 
@@ -456,10 +500,11 @@ program.option('-V', 'output the version');
   .command('update-database-down <contextFileName>')
   .alias('udd')
   .description('Run the latest migration down method for the given context')
-  .action(function(contextFileName){
+  .action(async function(contextFileName){
     var executedLocation = process.cwd();
     contextFileName = contextFileName.toLowerCase();
     var migration = new Migration();
+    var contextInstance = null;
     try{
        var files = globSearch.sync(`**/*${contextFileName}_contextSnapShot.json`, { cwd: executedLocation, dot: true, windowsPathsNoEscape: true, nocase: true });
        var file = files && files[0] ? path.resolve(executedLocation, files[0]) : null;
@@ -541,9 +586,11 @@ program.option('-V', 'output the version');
        }
        migration.createSnapShot(snap);
        console.log("✓ Database rolled back successfully");
+       await __cleanupAndExit(contextInstance, 0);
 
     }catch (e){
       console.log("Error - Cannot read or find file ", e);
+      await __cleanupAndExit(contextInstance, 1);
     }
   });
 
@@ -552,10 +599,11 @@ program.option('-V', 'output the version');
   .command('update-database-restart <contextFileName>')
   .alias('udr')
   .description('Apply pending migrations to database - up method call')
-  .action(function(contextFileName){
+  .action(async function(contextFileName){
     var executedLocation = process.cwd();
     contextFileName = contextFileName.toLowerCase();
     var migration = new Migration();
+    var contextInstance = null;
       try{
          // find context snapshot (cwd-based glob)
          var files = globSearch.sync(`**/*${contextFileName}_contextSnapShot.json`, { cwd: executedLocation, dot: true, windowsPathsNoEscape: true, nocase: true });
@@ -629,13 +677,15 @@ program.option('-V', 'output the version');
                contextEntities : cleanEntities,
                contextFileName: contextFileName
              }
- 
+
          migration.createSnapShot(snap);
          console.log("✓ Database restarted and updated successfully");
- 
+         await __cleanupAndExit(contextInstance, 0);
+
         }
         catch (e){
           console.log("Error - Cannot read or find file ", e);
+          await __cleanupAndExit(contextInstance, 1);
         }
   });
 
@@ -677,10 +727,11 @@ program.option('-V', 'output the version');
   .command('update-database-target <migrationFileName>')
   .alias('udt')
   .description('Apply pending migrations to database - down method call')
-  .action(function(migrationFileName){
+  .action(async function(migrationFileName){
   // this will call all the down methods until it gets to the one your looking for. First it needs to validate that there is such a file.
     var executedLocation = process.cwd();
     var migration = new Migration();
+    var contextInstance = null;
     try{
       // Accept either a bare filename or a path; normalize to basename
       var targetName = path.basename(migrationFileName);
@@ -785,9 +836,11 @@ program.option('-V', 'output the version');
       }
       migration.createSnapShot(snap);
       console.log("✓ Database rolled back to target migration successfully");
+      await __cleanupAndExit(contextInstance, 0);
 
     }catch (e){
       console.log("Error - Cannot read or find file ", e);
+      await __cleanupAndExit(contextInstance, 1);
     }
   });
 
@@ -796,8 +849,9 @@ program.option('-V', 'output the version');
   .command('add-migration-all <name>')
   .alias('ama')
   .description('Create a migration with the given name for all detected contexts')
-  .action(function(name){
+  .action(async function(name){
     var executedLocation = process.cwd();
+    var contextInstances = [];
     try{
       var snapshotFiles = globSearch.sync('**/*_contextSnapShot.json', { cwd: executedLocation, dot: true, windowsPathsNoEscape: true, nocase: true });
       if(!(snapshotFiles && snapshotFiles.length)){
@@ -825,6 +879,7 @@ program.option('-V', 'output the version');
           let contextInstance;
           try{
             contextInstance = new ContextCtor();
+            contextInstances.push(contextInstance);
           }catch(err){
             console.error(`⚠️  Skipping ${path.basename(contextAbs)}: failed to construct Context`);
             console.error(`   Details: ${err.message}`);
@@ -854,8 +909,22 @@ program.option('-V', 'output the version');
       if(created === 0){
         console.log('No migrations created.');
       }
+      // Cleanup all contexts
+      for(const ctx of contextInstances) {
+        if (ctx && typeof ctx.close === 'function') {
+          await ctx.close();
+        }
+      }
+      process.exit(0);
     }catch(e){
       console.log('Error - Cannot create migrations for all contexts ', e);
+      // Cleanup all contexts
+      for(const ctx of contextInstances) {
+        if (ctx && typeof ctx.close === 'function') {
+          await ctx.close();
+        }
+      }
+      process.exit(1);
     }
   });
 
@@ -863,8 +932,9 @@ program.option('-V', 'output the version');
   .command('update-database-all')
   .alias('uda')
   .description('Scan the project for *Context.js files and run update-database on each')
-  .action(function(){
+  .action(async function(){
     var executedLocation = process.cwd();
+    var contextInstances = [];
     try{
       // Find all context snapshots and run update per snapshot (avoids unrelated framework contexts)
       var snapshotFiles = globSearch.sync('**/*_contextSnapShot.json', { cwd: executedLocation, dot: true, windowsPathsNoEscape: true, nocase: true });
@@ -924,6 +994,7 @@ program.option('-V', 'output the version');
           var contextInstance;
           try{
             contextInstance = new ContextCtor();
+            contextInstances.push(contextInstance);
           }catch(err){
             console.error(`⚠️  Skipping ${entry.ctxName}: failed to construct Context`);
             console.error(`   Details: ${err.message}`);
@@ -947,8 +1018,22 @@ program.option('-V', 'output the version');
           console.log('Error updating context: ', errCtx);
         }
       }
+      // Cleanup all contexts
+      for(const ctx of contextInstances) {
+        if (ctx && typeof ctx.close === 'function') {
+          await ctx.close();
+        }
+      }
+      process.exit(0);
     }catch(e){
       console.log('Error - Cannot read or find file ', e);
+      // Cleanup all contexts
+      for(const ctx of contextInstances) {
+        if (ctx && typeof ctx.close === 'function') {
+          await ctx.close();
+        }
+      }
+      process.exit(1);
     }
   });
 

package/context.js

@@ -988,6 +988,9 @@ class context {
                 case 'delete':
                     toDelete.push(currentModel);
                     break;
+                case 'track':
+                    // Entity is tracked but unmodified - skip during saveChanges
+                    break;
                 default:
                     console.warn(`[Context] Unknown entity state: ${currentModel.__state}`);
             }
@@ -1277,6 +1280,32 @@ class context {
         this.clearQueryCache();
     }
 
+    /**
+     * Close database connections and cleanup resources
+     *
+     * Call this when shutting down your application or after CLI operations
+     * to properly close database connection pools and prevent hanging processes.
+     *
+     * @returns {Promise<void>|void} Promise for async databases (PostgreSQL), void for sync databases
+     *
+     * @example
+     * // PostgreSQL (async)
+     * const db = new AppContext();
+     * // ... do work ...
+     * await db.close();  // Close connection pool
+     *
+     * @example
+     * // MySQL/SQLite (sync)
+     * const db = new AppContext();
+     * // ... do work ...
+     * db.close();  // Close connections
+     */
+    async close() {
+        if (this._SQLEngine && typeof this._SQLEngine.close === 'function') {
+            return await this._SQLEngine.close();
+        }
+    }
+
     /**
      * Attach a detached entity and mark it as modified
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "masterrecord",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "An Object-relational mapping for the Master framework. Master Record connects classes to relational database tables to establish a database with almost zero-configuration ",
   "main": "MasterRecord.js",
   "bin": {

package/readme.md

@@ -64,9 +64,9 @@ npm install masterrecord better-sqlite3  # SQLite
 ### Dependencies
 
 MasterRecord includes the following database drivers by default:
-- `pg@^8.16.3` - PostgreSQL
+- `pg@^8.17.2` - PostgreSQL
 - `sync-mysql2@^1.0.8` - MySQL
-- `better-sqlite3@^12.6.0` - SQLite
+- `better-sqlite3@^12.6.2` - SQLite
 
 ## Two Patterns: Entity Framework & Active Record
 
@@ -152,7 +152,7 @@ masterrecord enable-migrations AppContext
 masterrecord add-migration InitialCreate AppContext
 
 # Apply migrations
-masterrecord migrate AppContext
+masterrecord update-database AppContext
 ```
 
 ### 4. Query Your Data
@@ -421,7 +421,7 @@ console.log(loaded.tags);  // ['admin', 'moderator'] - JavaScript array!
 
 ```javascript
 // Find all
-const users = db.User.all();
+const users = db.User.toList();
 
 // Find by primary key
 const user = db.User.findById(123);
@@ -578,7 +578,7 @@ masterrecord enable-migrations AppContext
 masterrecord add-migration MigrationName AppContext
 
 # Apply migrations
-masterrecord migrate AppContext
+masterrecord update-database AppContext
 
 # List migrations
 masterrecord get-migrations AppContext
@@ -586,7 +586,7 @@ masterrecord get-migrations AppContext
 # Multi-context commands
 masterrecord enable-migrations-all          # Enable for all contexts
 masterrecord add-migration-all Init         # Create migration for all
-masterrecord migrate-all                    # Apply all pending migrations
+masterrecord update-database-all            # Apply all pending migrations
 ```
 
 ### Migration File Structure
@@ -859,7 +859,7 @@ Configure caching via environment variables:
 
 ```bash
 # Development (.env)
-QUERY_CACHE_TTL=5000               # TTL in milliseconds (default: 5 seconds - request-scoped)
+QUERY_CACHE_TTL=5000               # TTL in milliseconds (5000ms = 5 seconds - request-scoped)
 QUERY_CACHE_SIZE=1000              # Max cache entries (default: 1000)
 QUERY_CACHE_ENABLED=true           # Enable/disable globally (default: true)
 
@@ -885,7 +885,7 @@ const liveData = db.Analytics
     .toList();  // No caching (default)
 
 // OPT-IN: Cache reference data
-const categories = db.Categories.cache().toList();  // Cached for 5 minutes
+const categories = db.Categories.cache().toList();  // Cached for 5 seconds (default TTL)
 const settings = db.Settings.cache().toList();  // Cached
 const countries = db.Countries.cache().toList();  // Cached
 
@@ -1155,7 +1155,7 @@ await analyticsDb.saveChanges();
 
 ```bash
 # Migrate all contexts at once
-masterrecord migrate-all
+masterrecord update-database-all
 ```
 
 ### Raw SQL Queries
@@ -1163,6 +1163,10 @@ masterrecord migrate-all
 When you need full control:
 
 ```javascript
+// ⚠️ Advanced: Direct SQL execution (using internal API)
+// For complex queries not supported by the query builder
+// Note: This is an internal API. Prefer using the query builder when possible.
+
 // PostgreSQL parameterized query
 const users = await db._SQLEngine.exec(
     'SELECT * FROM "User" WHERE age > $1 AND status = $2',
@@ -1220,12 +1224,11 @@ context.setQueryCacheEnabled(bool)   // Enable/disable caching
 .cache()                         // Enable caching for this query (opt-in)
 
 // Terminal methods (execute query)
-.toList()                        // Return array
+.toList()                        // Return array of all records
 .single()                        // Return one or null
 .first()                         // Return first or null
 .count()                         // Return count
 .any()                           // Return boolean
-.all()                           // Return all records
 
 // Convenience methods
 .findById(id)                    // Find by primary key
@@ -1456,7 +1459,7 @@ const recentUsers = db.User
     .toList();
 
 // ❌ BAD: Load everything
-const allUsers = db.User.all();
+const allUsers = db.User.toList();
 ```
 
 ### 5. Use Connection Pooling (PostgreSQL)
@@ -1513,7 +1516,7 @@ function getUser(userId) {
 
 ```bash
 # Error: Cannot find module 'pg'
-npm install pg@^8.16.3
+npm install pg@^8.17.2
 
 # Error: Connection refused
 # Check PostgreSQL is running: sudo service postgresql status
@@ -1543,7 +1546,7 @@ GRANT ALL PRIVILEGES ON myapp.* TO 'user'@'localhost';
 # Cannot find context file
 # Ensure you're running from project root
 cd /path/to/project
-masterrecord migrate AppContext
+masterrecord update-database AppContext
 
 # No migrations found
 # Check migrations directory exists
@@ -1577,14 +1580,14 @@ user.name = null;  // Error if name is { nullable: false }
 
 | Component     | Version       | Notes                                    |
 |---------------|---------------|------------------------------------------|
-| MasterRecord  | 0.3.0+        | Current version with PostgreSQL support  |
+| MasterRecord  | 0.3.13        | Current version with PostgreSQL support  |
 | Node.js       | 14+           | Async/await support required             |
 | PostgreSQL    | 9.6+ (12+)    | Tested with 12, 13, 14, 15, 16          |
 | MySQL         | 5.7+ (8.0+)   | Tested with 8.0+                        |
 | SQLite        | 3.x           | Any recent version                       |
-| pg            | 8.16.3+       | PostgreSQL driver                        |
+| pg            | 8.17.2+       | PostgreSQL driver                        |
 | sync-mysql2   | 1.0.8+        | MySQL driver                            |
-| better-sqlite3| 12.6.0+       | SQLite driver                           |
+| better-sqlite3| 12.6.2+       | SQLite driver                           |
 
 ## Documentation
 
@@ -1630,11 +1633,11 @@ Created by Alexander Rich
 
 ---
 
-## Recent Improvements (v1.0.1)
+## Recent Improvements (v0.3.13)
 
 MasterRecord has been upgraded to meet **FAANG engineering standards** (Google/Meta/Amazon) with critical bug fixes and performance improvements:
 
-### Migration System Fixes (v1.0.1)
+### Migration System Fixes (v0.3.13)
 
 **Critical Path Bug Fixed:**
 - ✅ **Duplicate db/migrations Path Fixed** - Resolved bug where snapshot files were created with duplicate nested paths
@@ -1657,7 +1660,7 @@ MasterRecord has been upgraded to meet **FAANG engineering standards** (Google/M
   2. **From migration directory** - cd into the specific migration area and run CLI there:
      ```bash
      cd components/qa/db/migrations
-     npx masterrecord update-database ../../app/models/qaContext
+     masterrecord enable-migrations qacontext
      ```
 - MasterRecord uses intelligent path resolution to locate migrations regardless of where you run the command
 
@@ -1708,7 +1711,7 @@ try {
 }
 ```
 
-### Insert Manager Improvements (v1.0.1)
+### Insert Manager Improvements (v0.3.13)
 
 **Security Fixes:**
 - ✅ **SQL Injection Prevention** - Added identifier validation for dynamic query construction
@@ -1776,7 +1779,7 @@ if(entityProperty.type === "hasMany"){
 }
 // ... 50 lines later, nearly identical code for hasManyThrough
 
-// AFTER (v1.0.0) - secure and DRY:
+// AFTER (v0.3.13) - secure and DRY:
 if (entityProperty.type === RELATIONSHIP_TYPES.HAS_MANY) {
     this._processArrayRelationship(propertyModel, entityProperty, property, currentModel, SQL, RELATIONSHIP_TYPES.HAS_MANY);
 }
@@ -1815,12 +1818,13 @@ $ grep -A1 "catch.*{$" insertManager.js | grep "^\s*}$"
 
 **PostgreSQL users must now await `env()`:**
 ```javascript
-// OLD:
+// PostgreSQL (async/await REQUIRED):
 const db = new AppContext();
+await db.env('./config/environments');  // Must await for PostgreSQL
 
-// NEW:
+// MySQL/SQLite (synchronous - no await):
 const db = new AppContext();
-await db.env('./config/environments');  // Must await for PostgreSQL
+db.env('./config/environments');  // No await needed for MySQL/SQLite
 ```
 
 **For more details, see:** `CHANGES.md`