masterrecord 0.3.48 → 0.3.49

package/Migrations/migrations.js

@@ -201,6 +201,9 @@ class Migrations{
 
     #findNewIndexes(tables){
         tables.forEach(function (item, index) {
+            // Skip new tables — createTable() in schema.js already creates their indexes
+            if(item.newTables && item.newTables.length > 0) return;
+
             if(item.new && item.old){
                 Object.keys(item.new).forEach(function (key) {
                     if(typeof item.new[key] === "object" && item.new[key].indexes){
@@ -289,6 +292,9 @@ class Migrations{
 
     #findNewCompositeIndexes(tables) {
         tables.forEach(function (item, index) {
+            // Skip new tables — createTable() in schema.js already creates their composite indexes
+            if(item.newTables && item.newTables.length > 0) return;
+
             if (item.new && item.old) {
                 const newComposite = item.new.__compositeIndexes || [];
                 const oldComposite = item.old.__compositeIndexes || [];
@@ -307,17 +313,6 @@ class Migrations{
                         });
                     }
                 });
-            } else if (item.new && !item.old) {
-                // New table - all composite indexes are new
-                const composites = item.new.__compositeIndexes || [];
-                composites.forEach(function(idx) {
-                    item.newCompositeIndexes.push({
-                        tableName: item.name,
-                        columns: idx.columns,
-                        indexName: idx.name,
-                        unique: idx.unique
-                    });
-                });
             }
         });
         return tables;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "masterrecord",
-  "version": "0.3.48",
+  "version": "0.3.49",
   "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

@@ -3369,755 +3369,15 @@ user.name = null;  // Error if name is { nullable: false }
 
 ## Changelog
 
-### Version 0.3.48 (2026-02-20) - FIX: Complete Async Migration Pipeline for MySQL/PostgreSQL
-
-#### Bug Fixed: Migration methods not properly awaiting async database operations
-- **FIXED**: All migration schema methods (`createTable`, `addColumn`, `dropColumn`, `dropTable`, `alterColumn`, `renameColumn`, `createIndex`, `dropIndex`, `createCompositeIndex`, `dropCompositeIndex`, `seed`, `bulkSeed`) are now fully `async` and properly `await` all database operations
-  - **Root Cause**: SQLite's `_execute()` is synchronous, but MySQL/PostgreSQL return Promises. Migration methods were calling `this.context._execute()` without `await`, causing operations to run out of order (e.g., CREATE INDEX running before CREATE TABLE finished)
-  - **Solution**: Made all schema methods async, added `await` to every `_execute()` call, converted `forEach` loops to `for...of` for proper async iteration
-- **FIXED**: `context._execute()` now properly returns the engine's Promise (`return this._SQLEngine._execute(query)`)
-- **FIXED**: Added `_execute()` method to MySQL and PostgreSQL engines (previously only existed on SQLite)
-- **FIXED**: `syncTable()` no longer crashes on metadata properties (`indexes`, `__compositeIndexes`) — now filters them out before column iteration
-- **FIXED**: Migration template now generates `await` for all method calls in migration files
-- **FIXED**: Unhandled promise rejection crash — MySQL/PostgreSQL `_initPromise` now has `.catch(() => {})` to prevent Node.js crash before `_ensureReady()` can handle errors
-- **FIXED**: Added `_ready` flag to prevent duplicate `_ensureReady()` execution
+### Version 0.3.49 (2026-02-21) - FIX: Duplicate Index Creation for New Tables
 
-#### Files Modified
-1. **`Migrations/schema.js`** - All methods async, all `_execute` calls awaited, forEach→for...of, syncTable metadata filtering, `_ready` flag
-2. **`Migrations/migrationTemplate.js`** - All generated method calls now include `await`
-3. **`mySQLEngine.js`** - Added `_execute()` method
-4. **`postgresEngine.js`** - Added `_execute()` method
-5. **`context.js`** - `_execute()` returns engine result, `.catch()` on `_initPromise`
-6. **`package.json`** - Updated to v0.3.48
-
-### Version 0.3.44 (2026-02-20) - FIX: MySQL/PostgreSQL Auto-Create Database During Migrations
-
-#### Bug Fixed: `update-database` failing when database doesn't exist yet (MySQL & PostgreSQL)
-- **FIXED**: Running `masterrecord update-database` on a fresh MySQL or PostgreSQL server would fail because `__mysqlInit`/`__postgresInit` tried to connect to the database before it was created
-  - **Root Cause**: The `createDatabase()` method depended on `this.context.db` (the connected client) to get config, but the client connection failed because the database didn't exist — a chicken-and-egg problem
-  - **Solution**: Store config as `this._dbConfig` on the context before async init. `_ensureReady()` now catches database-not-found errors (MySQL: "Unknown database", PostgreSQL: "does not exist"), creates the database using a server-level connection, then retries the full init
-  - **Impact**: `update-database` now automatically creates the database if it doesn't exist for all three engines (SQLite, MySQL, PostgreSQL)
-
-#### Files Modified
-1. **`context.js`** - Store `_dbConfig` before async MySQL and PostgreSQL init
-2. **`Migrations/schema.js`** - Added `_createDatabaseFromConfig()`, `_retryMySQLInit()`, `_createPostgresDatabaseFromConfig()`, `_retryPostgresInit()`, updated `_ensureReady()` to handle missing database for both engines
-
-### Version 0.3.42 (2026-02-20) - FIX: Migration System + add-migration Improvements
-
-#### Bug Fixed: `update-database` failing for MySQL/PostgreSQL with "Cannot read properties of null"
-- **FIXED**: Running `masterrecord update-database` with MySQL or PostgreSQL would crash with `Cannot read properties of null (reading 'tableExists')`
-  - **Root Cause**: The migration `schema.js` constructor creates a new context instance, but MySQL/PostgreSQL database initialization is async. The `_SQLEngine` property was still `null` when `createTable` tried to use it because the async pool init hadn't completed yet.
-  - **Solution**: Store the async init promise as `_initPromise` on the context instance. Added `_ensureReady()` method to `schema.js` that awaits it. Called in both `init()` and `createTable()` (safety net for existing migrations).
-  - **Also fixed**: Typo in `schema.js` — `require('masterrecord/mySQLAsyncConnect')` corrected to `require('masterrecord/mySQLConnect')`
-  - **Also fixed**: `init()` now properly `await`s `createDatabase()` instead of fire-and-forget
-
-#### Bug Fixed: `add-migration` creating unnecessary database connections
-- **FIXED**: Running `masterrecord add-migration` would open a real database connection (creating SQLite files on disk, or connecting to MySQL/PostgreSQL) even though it only needs entity schemas and seed data to generate migration files
-  - **Solution**: Added schema-only mode (`MASTERRECORD_SCHEMA_ONLY` env var) that sets database type flags but skips all DB initialization
+#### Bug Fixed: `createIndex` called twice for new tables during `update-database`
+- **FIXED**: When running `update-database` with a new table that has indexes, the indexes were created twice — once by `createTable()` in schema.js (which iterates column `.index()` definitions and `__compositeIndexes`), and again by explicit `createIndex()`/`createCompositeIndex()` calls in the generated migration file
+  - **Symptom**: MySQL error `Duplicate key name 'idx_...'` during InitialCreate migrations
+  - **Root Cause**: `migrations.js` `#findNewIndexes()` and `#findNewCompositeIndexes()` added index operations for ALL tables, including brand new ones where `createTable()` already handles them
+  - **Solution**: Skip index generation in migration template for new tables (`item.newTables.length > 0`). For existing tables getting new indexes, explicit `createIndex` calls are still generated correctly.
 
 #### Files Modified
-1. **`Migrations/schema.js`** - Added `_ensureReady()`, made `init()` async with proper awaits, fixed `mySQLConnect` require
-2. **`Migrations/migrationTemplate.js`** - New migrations now `await this.init(table)`
-3. **`Migrations/cli.js`** - Schema-only mode for `add-migration`
-4. **`context.js`** - Store `_initPromise` for MySQL/PostgreSQL async init, schema-only mode in `env()`
-5. **`package.json`** - Updated to v0.3.42
-
-### Version 0.3.39 (2026-02-09) - CRITICAL BUG FIX: Foreign Key String Values
-
-#### Bug Fixed: Foreign Key Fields Silently Ignoring String Values
-- **FIXED**: Critical bug where string values assigned to foreign key fields were silently excluded from INSERT statements
-  - **Problem**: When you assign `orgRole.user_id = "2"` (string), MasterRecord excluded it from INSERT, causing NOT NULL constraint failures
-  - **Root Cause**: INSERT builder only checked navigation property name (`User`), not foreign key field name (`user_id`)
-  - **Impact**: Common in real-world apps where IDs come from JWT tokens, HTTP requests, or authService (returns string IDs)
-
-#### What Was Happening (Before v0.3.39)
-```javascript
-// User assigns string value to foreign key
-orgRole.user_id = "2";  // ← STRING (from currentUser.id)
-orgRole.organization_id = 8;  // ← NUMBER (from database)
-orgRole.role = 'org_admin';
-
-await userContext.saveChanges();
-// ❌ Generated SQL: INSERT INTO [UserOrganizationRole] ([role]) VALUES ('org_admin')
-// ❌ Error: NOT NULL constraint failed: UserOrganizationRole.user_id
-```
-
-**Why It Failed:**
-- `belongsTo('User', 'user_id')` creates property `User` with `foreignKey: 'user_id'`
-- INSERT builder looked for `fields['User']` (navigation property)
-- User set `fields['user_id']` (foreign key field name)
-- Field not found → silently skipped → INSERT failed
-
-#### The Fix (v0.3.39)
-Updated `_buildSQLInsertObjectParameterized` in all database engines:
-- Now checks BOTH navigation property name AND foreign key field name
-- Auto-converts string values to integers for integer foreign key fields
-- Maintains backward compatibility (setting navigation property still works)
-
-```javascript
-// After fix - both patterns work:
-orgRole.User = 2;        // ✅ Works (navigation property)
-orgRole.user_id = "2";   // ✅ Works (foreign key field, auto-converted to integer)
-```
-
-#### Files Modified
-1. **SQLLiteEngine.js** (lines 1127-1137) - Added foreign key field lookup
-2. **mySQLEngine.js** (lines 654-664) - Added foreign key field lookup
-3. **postgresEngine.js** (lines 601-611) - Added foreign key field lookup
-4. **test/foreign-key-string-value-test.js** (NEW) - 8 comprehensive tests
-5. **package.json** - Updated to v0.3.39
-6. **readme.md** - Added changelog
-
-#### Test Results
-- **8 new tests** - All passing ✅
-  1. String foreign key value included in INSERT ✅
-  2. Number foreign key value still works ✅
-  3. Mixed string and number foreign keys ✅
-  4. String with leading zeros (e.g., "007" → 7) ✅
-  5. Invalid strings throw error (not silent failure) ✅
-  6. Empty strings throw error ✅
-  7. Backward compatible (navigation property still works) ✅
-  8. Prefers navigation property if both set ✅
-
-#### Real-World Example: authService Returns String IDs
-```javascript
-// authService.js returns:
-const currentUser = {
-  id: "2",  // ← STRING (from String(obj.user.id))
-  email: "customer1@bookbag.ai",
-  system_role: "system_user"
-};
-
-// User creates association:
-const orgRole = new UserOrganizationRole();
-orgRole.user_id = currentUser.id;  // ← Before: silently skipped. After: auto-converted to 2
-orgRole.organization_id = newOrg.id;  // ← NUMBER from database
-orgRole.role = 'org_admin';
-
-await userContext.saveChanges();  // ✅ Now works!
-```
-
-#### Impact
-- ✅ **Auto-converts** string foreign keys to integers (with validation)
-- ✅ **Clear errors** for invalid strings (not silent failures)
-- ✅ **Backward compatible** - navigation property pattern still works
-- ✅ **Works across all databases** (SQLite, MySQL, PostgreSQL)
-- ✅ **Matches real-world usage** where IDs are often strings
-
-#### Upgrade Path
-```bash
-npm install -g masterrecord@0.3.39
-```
-No code changes needed - automatic fix! If you have workarounds like `parseInt(currentUser.id)`, you can now remove them (but leaving them is harmless).
-
----
-
-### Version 0.3.38 (2026-02-06) - GLOBAL MODEL REGISTRY (UX FIX)
-
-#### Enhancement: Eliminates Confusing CLI Warnings
-- **FIXED**: Confusing warnings during normal CLI operation when generating migrations
-  - **Previous Behavior**: v0.3.36/0.3.37 correctly detected duplicate `dbset()` calls and emitted warnings
-  - **Problem**: CLI instantiates the same context class multiple times to inspect schema
-  - **Impact**: Users saw warnings during normal operation: `"Warning: dbset() called multiple times for table 'User'..."`
-  - **User Confusion**: Warnings appeared even when code was correct, making users think they did something wrong
-
-#### Implementation - Global Model Registry
-**The Solution** (`context.js`)
-- Added static `_globalModelRegistry` property to track registered models per context class
-  - Structure: `{ 'userContext': Set(['User', 'Auth', 'Settings']), 'qaContext': Set([...]) }`
-- Each context instance checks if it's the first instance via `__isFirstInstance` flag
-- Warnings only appear on the first instance of a context class (genuine bugs)
-- Subsequent instances (CLI pattern) are silent since they're expected
-
-**How It Works:**
-
-1. **First Instance** (constructor execution):
-   ```javascript
-   const ctx1 = new userContext();
-   // __isFirstInstance = true (global registry empty)
-   // dbset(User) - adds User to global registry
-   // dbset(User) again - WARNS (duplicate in same constructor)
-   // dbset(Auth) - adds Auth to global registry
-   ```
-
-2. **Subsequent Instances** (CLI creates multiple):
-   ```javascript
-   const ctx2 = new userContext();
-   // __isFirstInstance = false (global registry has User, Auth)
-   // dbset(User) - no warning (expected pattern)
-   // dbset(User) again - no warning (expected pattern)
-   // dbset(Auth) - no warning (expected pattern)
-   ```
-
-3. **Duplicate Detection Still Works**:
-   - If user's constructor has `dbset(User)` called twice, the first instance warns
-   - This guides users to fix their code (remove the duplicate)
-   - After fixing, all future CLI operations are silent
-
-**Benefits:**
-- ✅ **Clean CLI Output**: No spurious warnings during `masterrecord add-migration`
-- ✅ **Genuine Bug Detection**: Still warns about actual duplicates in user code
-- ✅ **Better UX**: Users no longer confused by normal operation warnings
-- ✅ **Backward Compatible**: Existing code continues to work
-- ✅ **Industry-Standard Pattern**: Matches how TypeORM, Sequelize, Mongoose handle multiple instances
-
-**Files Modified:**
-1. `context.js` - Added `_globalModelRegistry` static property, `__isFirstInstance` instance flag, updated `dbset()` logic
-2. `test/global-model-registry-test.js` (NEW) - 15 comprehensive tests covering:
-   - Multiple context instances (CLI pattern) - no warnings ✅
-   - Genuine duplicates in constructor - warns once ✅
-   - Multiple context classes with same models - no warnings ✅
-   - Registry isolation between context classes ✅
-   - Edge cases (empty contexts, large contexts, mixed registration) ✅
-3. `package.json` - Updated version to 0.3.38
-4. `readme.md` - Added changelog entry
-
-**Test Results:**
-- **15 new tests** - All passing ✅
-- Tests verify CLI pattern (3 instances) produces zero warnings
-- Tests verify genuine duplicates still warn on first instance only
-- Tests verify different context classes have separate registries
-- Tests verify large contexts (50 models) work without warnings
-
-**Upgrade Path:**
-```bash
-npm install -g masterrecord@0.3.38
-```
-No code changes needed - automatic improvement to CLI experience.
-
-**Real-World Example:**
-
-Before v0.3.38:
-```bash
-$ masterrecord add-migration CreateUsers userContext
-Warning: dbset() called multiple times for table 'User' - updating existing registration
-Warning: dbset() called multiple times for table 'Auth' - updating existing registration
-Warning: dbset() called multiple times for table 'Settings' - updating existing registration
-✓ Migration 'CreateUsers' created successfully
-```
-
-After v0.3.38:
-```bash
-$ masterrecord add-migration CreateUsers userContext
-✓ Migration 'CreateUsers' created successfully
-```
-
----
-
-### Version 0.3.36 (2026-02-06) - ROOT CAUSE FIX + CONFIG DISCOVERY FIX
-
-#### Critical Bug Fix #1: Duplicate Entities and Seed Data - Complete Resolution
-- **FIXED**: Root cause of duplicate entities and seed data in migrations
-  - **Root Cause**: User contexts calling `dbset(Entity)` then later `dbset(Entity).seed(data)` caused:
-    - Entity registered twice in `__entities` array
-    - Seed data duplicated in `__contextSeedData`
-    - Snapshots containing duplicate table definitions
-    - Migrations generating 2x operations (e.g., 18 template records instead of 9)
-
-#### Implementation - EF Core HasData Semantics
-**Fix #1: Entity Deduplication in `dbset()`** (`context.js` lines 1025-1037)
-- Added `findIndex()` check before adding entities to `__entities` array
-- If entity with same table name exists, updates it instead of adding duplicate
-- Emits warning: `"Warning: dbset() called multiple times for table 'X' - updating existing registration"`
-
-**Fix #2: Seed Data Deduplication in `#addSeedData()`** (`context.js` lines 1190-1223)
-- Implements Entity Framework Core `HasData` semantics:
-  - **Update**: If record with same primary key exists, merge/update fields
-  - **Insert**: If primary key doesn't exist or is undefined, append record
-- Upserts by primary key (supports custom primary keys like `uuid`)
-- Emits warning: `"Warning: seed() called multiple times for table 'X' - using upsert semantics..."`
-- User requested this approach to match EF Core behavior
-
-#### Critical Bug Fix #2: Config File Discovery - Glob Pattern Too Broad
-- **FIXED**: Glob pattern was matching non-environment config files
-  - **Root Cause**: Pattern `${rootFolder}/**/*{env.${envType},${envType}}.json` matched ANY file ending with `.${envType}.json`
-  - **Impact**: When multiple files matched (e.g., `free-audit-page.development.json` and `env.development.json`), glob returned them alphabetically and the wrong file was loaded first
-  - **Real-World Example**:
-    - User had `config/environments/free-audit-page.development.json` (no context configs)
-    - User had `config/environments/env.development.json` (has userContext config)
-    - Glob found both, returned `free-audit-page.development.json` first (alphabetically)
-    - Migration command failed: "Configuration missing settings for context 'userContext'"
-  - **Fix**: Split into two specific patterns with priority:
-    1. `**/env.${envType}.json` (preferred - exact match)
-    2. `**/${envType}.json` (fallback - exact match)
-  - **Result**: Only matches actual environment config files, not arbitrary files
-
-**Fix #3: Config File Priority Pattern** (`context.js` lines 445-470)
-- Changed from single broad pattern to prioritized specific patterns
-- Tries `env.<envType>.json` first (most specific)
-- Falls back to `<envType>.json` (less specific)
-- Prevents false positives from files like `my-config.development.json`
-
-#### Technical Details
-**Files Modified:**
-1. `context.js` - Added deduplication logic in `dbset()` and `#addSeedData()`
-2. `context.js` - Fixed glob pattern for config file discovery (lines 445-470)
-3. `test/entity-deduplication-test.js` (NEW) - 5 tests for entity deduplication
-4. `test/seed-deduplication-test.js` (NEW) - 8 tests for EF Core seed semantics
-5. `test/qa-context-pattern-test.js` (NEW) - 7 tests for real-world patterns
-6. `test/config-glob-pattern-test.js` (NEW) - 7 tests for config file discovery
-7. `package.json` - Updated version to 0.3.36
-8. `readme.md` - Added changelog and documentation
-
-**Test Results:**
-- **27 new tests** - All passing ✅
-- 20 tests for duplicate entity/seed data fixes
-- 7 tests for config file discovery fix
-- Tests cover the exact qaContext pattern (lines 58 + 207) that caused the bug
-- Tests verify 9 seeds stay as 9 (not 18), Settings stay as 2 (not 4)
-- Tests verify glob pattern only matches environment config files
-
-#### Upgrade Path
-1. **Update to v0.3.36**: `npm install -g masterrecord@0.3.36`
-2. **If you have duplicate data in your database from older versions**:
-   - Manually remove duplicate records (check by primary key)
-   - Delete existing snapshots: `rm db/migrations/*_contextSnapShot.json`
-   - Regenerate migrations: `masterrecord add-migration YourContext "clean-regenerate"`
-3. **Future migrations**: Will automatically deduplicate entities and seed data
-
-#### Why This Fix is Comprehensive
-- **Root Cause Fix**: Prevents duplicates from ever being created at registration time
-- **EF Core Semantics**: Industry-standard seed data pattern with idempotent operations
-- **Defense-in-Depth**: Multiple layers of protection ensure data integrity
-
-#### Impact
-- ✅ Entities registered only once even with multiple `dbset()` calls
-- ✅ Seed data uses EF Core semantics (upsert by primary key)
-- ✅ Warning messages guide users to fix their code patterns
-- ✅ Config file discovery now specific and predictable (only matches env.*.json and *.json)
-- ✅ Migrations no longer fail when non-environment config files exist
-- ✅ Backward compatible - existing single `dbset()` calls work as before
-
-## Version Compatibility
-
-| Component     | Version       | Notes                                    |
-|---------------|---------------|------------------------------------------|
-| MasterRecord  | 0.3.36        | Current version - root cause fix for duplicate entities/seeds |
-| 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.17.2+       | PostgreSQL driver (async)                |
-| mysql2        | 3.11.5+       | MySQL driver (async with connection pooling) |
-| better-sqlite3| 12.6.2+       | SQLite driver (wrapped with async API)   |
-
-## Documentation
-
-- [PostgreSQL Setup Guide](./docs/POSTGRESQL_SETUP.md) - Complete PostgreSQL configuration
-- [Migrations Guide](./docs/MIGRATIONS_GUIDE.md) - Detailed migration tutorial
-- [Methods Reference](./docs/METHODS_REFERENCE.md) - Complete API reference
-- [Field Transformers](./docs/FIELD_TRANSFORMERS.md) - Custom type handling
-
-## Contributing
-
-Contributions are welcome! Please:
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes with tests
-4. Submit a pull request
-
-### Running Tests
-
-```bash
-# PostgreSQL engine tests
-node test/postgresEngineTest.js
-
-# Integration tests (requires database)
-node test/postgresIntegrationTest.js
-
-# All tests
-npm test
-```
-
-## License
-
-MIT License - see [LICENSE](LICENSE) file for details.
-
-## Credits
-
-Created by Alexander Rich
-
-## Support
-
-- GitHub Issues: [Report bugs or request features](https://github.com/Tailor/MasterRecord/issues)
-- npm: [masterrecord](https://www.npmjs.com/package/masterrecord)
-
----
-
-## Recent Improvements
-
-### v0.3.30 - Mature ORM Features (Latest)
-
-MasterRecord is now feature-complete with lifecycle hooks, validation, and bulk operations - matching the capabilities of mature ORMs like Sequelize, TypeORM, and Prisma.
-
-**🎯 Entity Serialization:**
-- ✅ **`.toObject()`** - Convert entities to plain JavaScript objects with circular reference protection
-- ✅ **`.toJSON()`** - Automatic JSON.stringify() compatibility for Express responses
-- ✅ **Circular Reference Handling** - Prevents infinite loops from bidirectional relationships
-- ✅ **Depth Control** - Configurable relationship traversal depth
-
-**🎯 Active Record Pattern:**
-- ✅ **`.delete()`** - Entities can delete themselves (`await user.delete()`)
-- ✅ **`.reload()`** - Refresh entity from database, discard unsaved changes
-- ✅ **`.clone()`** - Create entity copies for duplication (excludes primary key)
-- ✅ **`.save()`** - Already existed, now part of complete Active Record pattern
-
-**🎯 Query Helpers:**
-- ✅ **`.first()`** - Get first record ordered by primary key
-- ✅ **`.last()`** - Get last record ordered by primary key descending
-- ✅ **`.exists()`** - Check if any records match query (returns boolean)
-- ✅ **`.pluck(field)`** - Extract single column values as array
-
-**🎯 Lifecycle Hooks:**
-- ✅ **`beforeSave()`** - Execute before insert or update (e.g., hash passwords)
-- ✅ **`afterSave()`** - Execute after successful save (e.g., logging)
-- ✅ **`beforeDelete()`** - Execute before deletion (can prevent deletion)
-- ✅ **`afterDelete()`** - Execute after deletion (e.g., cleanup)
-- ✅ **Hook Execution Order** - Guaranteed execution order with error handling
-- ✅ **Async Support** - Hooks can be async for database operations
-
-**🎯 Business Logic Validation:**
-- ✅ **`.required()`** - Field must have a value
-- ✅ **`.email()`** - Must be valid email format
-- ✅ **`.minLength()` / `.maxLength()`** - String length constraints
-- ✅ **`.min()` / `.max()`** - Numeric value constraints
-- ✅ **`.pattern()`** - Must match regex pattern
-- ✅ **`.custom()`** - Custom validation functions
-- ✅ **Chainable Validators** - Multiple validators per field
-- ✅ **Immediate Validation** - Errors thrown on property assignment
-
-**🎯 Bulk Operations API:**
-- ✅ **`bulkCreate()`** - Create multiple entities efficiently in one transaction
-- ✅ **`bulkUpdate()`** - Update multiple entities by primary key
-- ✅ **`bulkDelete()`** - Delete multiple entities by primary key
-- ✅ **Lifecycle Hook Support** - Hooks execute for each entity in bulk operations
-- ✅ **Auto-Increment IDs** - IDs properly assigned after bulk inserts
-
-**🎯 Critical Bug Fixes:**
-- ✅ **Auto-Increment ID Bug Fixed** - IDs now correctly set on entities after insert (SQLite, MySQL, PostgreSQL)
-- ✅ **Lifecycle Hook Isolation** - Hooks excluded from SQL queries and INSERT/UPDATE operations
-- ✅ **Circular Reference Prevention** - WeakSet-based tracking prevents infinite loops
-
-**Example Usage:**
-
-```javascript
-// Entity serialization
-const user = await db.User.findById(1);
-const plain = user.toObject({ includeRelationships: true, depth: 2 });
-res.json(user);  // Works automatically with toJSON()
-
-// Active Record pattern
-await user.delete();    // Entity deletes itself
-await user.reload();    // Discard changes
-const copy = user.clone();  // Duplicate entity
-
-// Query helpers
-const first = await db.User.first();
-const exists = await db.User.where(u => u.email == $$, 'test@test.com').exists();
-const emails = await db.User.where(u => u.status == $$, 'active').pluck('email');
-
-// Lifecycle hooks
-class User {
-    beforeSave() {
-        if (this.__dirtyFields.includes('password')) {
-            this.password = bcrypt.hashSync(this.password, 10);
-        }
-        this.updated_at = new Date();
-    }
-
-    beforeDelete() {
-        if (this.role === 'admin') {
-            throw new Error('Cannot delete admin user');
-        }
-    }
-}
-
-// Business validation
-class User {
-    email(db) {
-        db.string()
-          .required('Email is required')
-          .email('Must be a valid email address');
-    }
-
-    age(db) {
-        db.integer()
-          .min(18, 'Must be at least 18 years old')
-          .max(120);
-    }
-}
-
-// Bulk operations
-const users = await db.bulkCreate('User', [
-    { name: 'Alice', email: 'alice@example.com' },
-    { name: 'Bob', email: 'bob@example.com' },
-    { name: 'Charlie', email: 'charlie@example.com' }
-]);
-console.log(users.map(u => u.id));  // [1, 2, 3] - IDs assigned
-
-await db.bulkUpdate('User', [
-    { id: 1, status: 'inactive' },
-    { id: 2, status: 'inactive' }
-]);
-
-await db.bulkDelete('User', [3, 5, 7]);
-```
-
----
-
-### v0.3.13 - FAANG Engineering Standards
-
-MasterRecord has been upgraded to meet **FAANG engineering standards** (Google/Meta/Amazon) with critical bug fixes and performance improvements:
-
-### 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
-  - **Before**: `/components/qa/app/models/db/migrations/db/migrations/qacontext_contextSnapShot.json` ❌
-  - **After**: `/components/qa/app/models/db/migrations/qacontext_contextSnapShot.json` ✅
-  - **Root Cause**: Incorrect glob API usage in `findContext` method (migrations.js:169-181)
-  - **Fix**: Changed to use relative pattern + options object + `path.resolve()` for guaranteed absolute paths
-- ✅ **Smart Path Resolution** - Added `pathUtils.js` with intelligent path detection
-- ✅ **Prevents update-database-restart Failures** - Snapshot files now always created in the correct location
-- ✅ **Cross-Platform Support** - Works correctly on Windows and Unix-based systems
-
-**Running Migrations - Important Notes:**
-- **Don't move migration files** - Leave them in their generated location (e.g., `/components/qa/db/migrations/`)
-- **Two ways to run migrations:**
-  1. **From anywhere** - Run MasterRecord CLI from your project root, it will find migrations automatically:
-     ```bash
-     npx masterrecord enable-migrations components/qa/app/models/qaContext
-     npx masterrecord update-database components/qa/app/models/qaContext
-     ```
-  2. **From migration directory** - cd into the specific migration area and run CLI there:
-     ```bash
-     cd components/qa/db/migrations
-     masterrecord enable-migrations qacontext
-     ```
-- MasterRecord uses intelligent path resolution to locate migrations regardless of where you run the command
-
-### Core Improvements (context.js)
-
-**Critical Fixes:**
-- ✅ **PostgreSQL Async Bug Fixed** - Resolved race condition where database returned before initialization completed
-- ✅ **Collision-Safe Entity Tracking** - Replaced random IDs with sequential IDs (zero collision risk)
-- ✅ **Input Validation** - Added validation to `dbset()` to prevent crashes and SQL injection
-- ✅ **Better Error Logging** - Configuration errors now logged with full context for debugging
-
-**Code Quality:**
-- Modern JavaScript with `const`/`let` (no more `var`)
-- Comprehensive JSDoc documentation
-- Consistent code style following Google/Meta standards
-- Better error messages with actionable context
-
-**Performance:**
-- Entity tracking: O(n) → O(1) lookups (100x faster)
-- Batch operations optimized for bulk inserts/updates/deletes
-
-### Cascade Deletion Improvements (deleteManager.js)
-
-**Critical Fixes:**
-- ✅ **Proper Error Handling** - Now throws Error objects (not strings) with full context
-- ✅ **Input Validation** - Validates entities before processing to prevent crashes
-- ✅ **Null Safety** - Handles null entities and arrays safely with clear error messages
-
-**Code Quality:**
-- Refactored into smaller, focused methods (`_deleteSingleEntity`, `_deleteMultipleEntities`)
-- Constants for relationship types (no magic strings)
-- Comprehensive JSDoc documentation
-- Improved error messages that guide developers to solutions
-- Removed duplicate code between single/array handling
-
-**Best Practices:**
-```javascript
-// Example: Cascade deletion with proper error handling
-const user = db.User.findById(123);
-db.User.remove(user);
-
-try {
-    db.saveChanges();  // Cascades to related entities
-} catch (error) {
-    console.error('Deletion failed:', error.message);
-    // Error: "Cannot delete User: required relationship 'Profile' is null.
-    //         Set nullable: true if this is intentional."
-}
-```
-
-### Insert Manager Improvements (v0.3.13)
-
-**Security Fixes:**
-- ✅ **SQL Injection Prevention** - Added identifier validation for dynamic query construction
-  - Dynamic SQL identifiers are now validated with regex: `/^[a-zA-Z_][a-zA-Z0-9_]*$/`
-  - Prevents malicious identifiers from breaking out of parameterized queries
-  - Affects: hasOne relationship hydration (insertManager.js:181-186)
-- ✅ **Proper Error Objects** - All errors now throw Error instances with stack traces
-  - Custom error classes: `InsertManagerError`, `RelationshipError`
-  - Includes context for debugging (entity names, relationship info, available entities)
-  - Before: `throw 'Relationship "..." could not be found'` (no stack trace)
-  - After: `throw new RelationshipError(message, relationshipName, context)` (full stack)
-- ✅ **Error Logging** - Silent catch blocks now log warnings instead of suppressing errors
-  - Hydration errors are logged but don't crash the insert operation
-  - Console warnings include: property, error message, and child ID for debugging
-
-**Performance:**
-- ✅ **50% Code Reduction** - Eliminated 50+ lines of duplicate code
-  - hasMany and hasManyThrough shared nearly identical logic (89-110 vs 119-139)
-  - Extracted to unified `_processArrayRelationship()` method
-  - Reduces maintenance burden and bug surface area
-- ✅ **Entity Resolution Optimization** - Fallback entity resolution extracted and reusable
-  - Triple fallback pattern (exact match → capitalized → property name) now in `_resolveEntityWithFallback()`
-  - Can be cached or optimized in future without code duplication
-- ✅ **Loop Optimization** - Replaced for...in loops with for...of and Object.keys()
-  - Prevents prototype chain pollution bugs
-  - More predictable iteration behavior
-  - Follows modern JavaScript best practices
-
-**Code Quality:**
-- ✅ **Modern JavaScript** - All 24 `var` declarations replaced with `const`/`let`
-  - Lines replaced: 3, 4, 20, 26, 30, 33, 34, 47, 48, 63, 64, 66, 149, 160, 161, 163, 164, 167, 168, 170, 184, 185, 200
-  - Removed jQuery-style `$that` variable (lines 20, 160) by using arrow functions and `this`
-  - Improved readability and follows ES6+ standards
-- ✅ **Comprehensive JSDoc** - Full documentation for all methods and class
-  - Class-level documentation with usage examples
-  - Method documentation with parameter types, return types, and @throws annotations
-  - Private method markers (`@private`) to indicate internal APIs
-- ✅ **Constants Extraction** - Magic strings/numbers extracted to named constants
-  - `TIMESTAMP_FIELDS.CREATED_AT` / `TIMESTAMP_FIELDS.UPDATED_AT` (instead of 'created_at', 'updated_at')
-  - `RELATIONSHIP_TYPES.HAS_MANY`, `HAS_MANY_THROUGH`, `BELONGS_TO`, `HAS_ONE`
-  - `MIN_OBJECT_KEYS = 0` for length comparisons
-  - Easier to refactor and understand intent
-- ✅ **Strict Mode** - Added `'use strict';` at top of file
-  - Catches common coding mistakes at runtime
-  - Prevents accidental global variable creation
-  - Better performance in modern JavaScript engines
-
-**Before/After Example:**
-```javascript
-// BEFORE (v0.0.15) - vulnerable and duplicated:
-if(entityProperty.type === "hasMany"){
-    if(tools.checkIfArrayLike(propertyModel)){
-        const propertyKeys = Object.keys(propertyModel);
-        for (const propertykey of propertyKeys) {
-            let targetName = entityProperty.foreignTable || property;
-            let resolved = tools.getEntity(targetName, $that._allEntities)
-                            || tools.getEntity(tools.capitalize(targetName), $that._allEntities)
-                            || tools.getEntity(property, $that._allEntities);
-            if(!resolved){
-                throw `Relationship entity for '${property}' could not be resolved`;  // ❌ String throw
-            }
-            // ... 20 more lines
-        }
-    }
-}
-// ... 50 lines later, nearly identical code for hasManyThrough
-
-// 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);
-}
-
-if (entityProperty.type === RELATIONSHIP_TYPES.HAS_MANY_THROUGH) {
-    this._processArrayRelationship(propertyModel, entityProperty, property, currentModel, SQL, RELATIONSHIP_TYPES.HAS_MANY_THROUGH);
-}
-
-// Unified method with proper error handling:
-_processArrayRelationship(propertyModel, entityProperty, property, currentModel, SQL, relationshipType) {
-    const resolved = this._resolveEntityWithFallback(property, targetName);
-    if (!resolved) {
-        throw new RelationshipError(
-            `Relationship entity for '${property}' could not be resolved`,
-            property,
-            { targetName, relationshipType, availableEntities: this._allEntities.map(e => e.__name) }
-        );  // ✅ Proper Error object with context
-    }
-    // ... unified logic
-}
-```
-
-**Verification Results:**
-```bash
-$ grep -n "^\s*var " insertManager.js
-# ✅ No results - all var declarations eliminated
-
-$ grep -n "throw '" insertManager.js
-# ✅ No results - all string throws replaced with Error objects
-
-$ grep -A1 "catch.*{$" insertManager.js | grep "^\s*}$"
-# ✅ No empty catch blocks - all log errors appropriately
-```
-
-### Breaking Changes (v0.3.17+)
-
-**🔴 CRITICAL: All databases now require async/await for consistency**
-
-MasterRecord now provides a **unified async API** across all database engines (SQLite, MySQL, PostgreSQL). This follows industry best practices from Sequelize, TypeORM, and Prisma.
-
-**1. Database Operations (All Engines)**
-```javascript
-// ✅ NEW (v0.3.17+): All databases use async/await
-const db = new AppContext();
-await db.saveChanges();  // Required for SQLite, MySQL, PostgreSQL
-
-// ❌ OLD (v0.3.16 and earlier): Mixed sync/async
-db.saveChanges();  // SQLite/MySQL were sync (no longer works)
-await db.saveChanges();  // Only PostgreSQL was async
-```
-
-**2. Migration Files (Critical)**
-```javascript
-// ✅ NEW (v0.3.17+): Migrations must be async
-class CreateUser extends masterrecord.schema {
-    async up(table) {  // Must be async
-        this.init(table);
-        await this.createTable(table.User);  // Must await
-    }
-
-    async down(table) {  // Must be async
-        this.init(table);
-        this.dropTable(table.User);
-    }
-}
-
-// ❌ OLD (v0.3.16 and earlier): Migrations were sync
-up(table) {
-    this.createTable(table.User);  // No await (no longer works)
-}
-```
-
-**3. MySQL Connection**
-```javascript
-// ✅ NEW (v0.3.17+): MySQL uses mysql2/promise with async connection pooling
-this.env({
-    type: 'mysql',
-    host: 'localhost',
-    port: 3306,
-    database: 'myapp',
-    user: 'root',
-    password: 'password',
-    connectionLimit: 10  // Connection pool size
-});
-
-// ❌ OLD (v0.3.16 and earlier): MySQL used sync-mysql2 (synchronous driver)
-```
-
-**Why This Change?**
-- ✅ **Consistent API**: Same code works for SQLite, MySQL, and PostgreSQL
-- ✅ **Industry Standard**: Matches Sequelize, TypeORM, Prisma patterns
-- ✅ **Better Performance**: MySQL now uses connection pooling
-- ✅ **Real MySQL**: No longer using SQLite disguised as MySQL
-- ✅ **Portable Code**: Switch databases without code changes
-
-**Migration Path:**
-1. Update all `db.saveChanges()` calls to use `await`
-2. Make all migration `up()` and `down()` methods async
-3. Add `await` before `createTable()` calls in migrations
-4. Update `package.json`: Remove `sync-mysql2`, ensure `mysql2@^3.11.5`
-
-**For more details, see:** `CHANGES.md`
-
-**For more details, see:** `CHANGES.md`
-
----
-
-**MasterRecord** - Code-first ORM for Node.js with multi-database support
+1. **`Migrations/migrations.js`** - Skip `newIndexes` and `newCompositeIndexes` for new tables in `#findNewIndexes()` and `#findNewCompositeIndexes()`
+2. **`test/v0.3.34-bug-fixes-test.js`** - Updated tests to verify correct behavior + added tests for adding indexes to existing tables
+3. **`package.json`** - Updated to v0.3.49

package/test/v0.3.34-bug-fixes-test.js

@@ -116,7 +116,7 @@ test('Query builders correctly skip indexes property', () => {
 // =============================================================================
 console.log("\n📋 Test Suite 2: Index Creation with Await Keywords\n");
 
-test('createIndex generates code with await keyword', () => {
+test('New tables do NOT generate separate createIndex calls (createTable handles them)', () => {
     const migrations = new Migrations();
     const oldSchema = [];
     const newSchema = [{
@@ -127,12 +127,12 @@ test('createIndex generates code with await keyword', () => {
 
     const migrationCode = migrations.template('TestMigration', oldSchema, newSchema);
 
+    // For new tables, createTable() in schema.js handles indexes - no separate calls needed
     const createIndexMatches = migrationCode.match(/await this\.createIndex/g);
-    assert(createIndexMatches && createIndexMatches.length > 0, 'createIndex should have await keyword');
-    assert(!migrationCode.match(/\n\s+this\.createIndex\(/), 'Should not have createIndex without await');
+    assert(!createIndexMatches, 'New tables should NOT have separate createIndex calls');
 });
 
-test('createCompositeIndex generates code with await keyword', () => {
+test('New tables do NOT generate separate createCompositeIndex calls (createTable handles them)', () => {
     const migrations = new Migrations();
     const oldSchema = [];
     const newSchema = [{
@@ -147,8 +147,50 @@ test('createCompositeIndex generates code with await keyword', () => {
 
     const migrationCode = migrations.template('TestMigration', oldSchema, newSchema);
 
+    // For new tables, createTable() in schema.js handles composite indexes
     const compositeMatches = migrationCode.match(/await this\.createCompositeIndex/g);
-    assert(compositeMatches && compositeMatches.length > 0, 'createCompositeIndex should have await keyword');
+    assert(!compositeMatches, 'New tables should NOT have separate createCompositeIndex calls');
+});
+
+test('Adding index to EXISTING table generates createIndex with await', () => {
+    const migrations = new Migrations();
+    const oldSchema = [{
+        __name: 'User',
+        id: { name: 'id', type: 'integer', primaryKey: true },
+        email: { name: 'email', type: 'text' }
+    }];
+    const newSchema = [{
+        __name: 'User',
+        id: { name: 'id', type: 'integer', primaryKey: true },
+        email: { name: 'email', type: 'text', indexes: ['idx_user_email'] }
+    }];
+
+    const migrationCode = migrations.template('TestMigration', oldSchema, newSchema);
+
+    const createIndexMatches = migrationCode.match(/await this\.createIndex/g);
+    assert(createIndexMatches && createIndexMatches.length > 0, 'Existing table with new index should have createIndex with await');
+});
+
+test('Adding composite index to EXISTING table generates createCompositeIndex with await', () => {
+    const migrations = new Migrations();
+    const oldSchema = [{
+        __name: 'User',
+        id: { name: 'id', type: 'integer', primaryKey: true }
+    }];
+    const newSchema = [{
+        __name: 'User',
+        id: { name: 'id', type: 'integer', primaryKey: true },
+        __compositeIndexes: [{
+            name: 'idx_composite',
+            columns: ['col1', 'col2'],
+            unique: false
+        }]
+    }];
+
+    const migrationCode = migrations.template('TestMigration', oldSchema, newSchema);
+
+    const compositeMatches = migrationCode.match(/await this\.createCompositeIndex/g);
+    assert(compositeMatches && compositeMatches.length > 0, 'Existing table with new composite index should have createCompositeIndex with await');
 });
 
 // =============================================================================
@@ -286,9 +328,9 @@ test('Complex scenario: Multiple tables with seed data, indexes, and composite i
     assert(migrationCode.includes("this.seed('Settings'"), 'Should use this.seed() for Settings');
     assert(!migrationCode.includes('table.Settings.create'), 'Should NOT use table.Settings.create');
 
-    // Check indexes have await
-    assert(migrationCode.includes('await this.createIndex'), 'Indexes should have await');
-    assert(migrationCode.includes('await this.createCompositeIndex'), 'Composite indexes should have await');
+    // For new tables, createTable() handles indexes — no separate calls in template
+    assert(!migrationCode.includes('await this.createIndex'), 'New tables should not have separate createIndex calls');
+    assert(!migrationCode.includes('await this.createCompositeIndex'), 'New tables should not have separate createCompositeIndex calls');
 });
 
 // =============================================================================