masterrecord 0.3.29 → 0.3.30

package/Entity/entityModel.js

@@ -111,8 +111,16 @@ class EntityModel {
 
     unique(){
         this.obj.unique = true; // yes
-        return this; 
+        return this;
+
+    }
 
+    index(indexName){
+        if(!this.obj.indexes){
+            this.obj.indexes = [];
+        }
+        this.obj.indexes.push(indexName || true);
+        return this;
     }
 
     // this means that it can be an empty field

package/Migrations/migrationMySQLQuery.js

@@ -232,6 +232,20 @@ class migrationMySQLQuery {
         return `ALTER TABLE \`${table.tableName}\` RENAME COLUMN \`${table.name}\` TO \`${table.newName}\``
     }
 
+    createIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `CREATE INDEX \`${indexName}\` ON \`${indexInfo.tableName}\`(\`${indexInfo.columnName}\`)`;
+    }
+
+    dropIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `DROP INDEX \`${indexName}\` ON \`${indexInfo.tableName}\``;
+    }
+
     /**
      * SEED DATA METHODS
      * Support for inserting seed data during migrations

package/Migrations/migrationPostgresQuery.js

@@ -219,6 +219,20 @@ class migrationPostgresQuery {
         return `ALTER TABLE "${table.tableName}" RENAME COLUMN "${table.name}" TO "${table.newName}"`;
     }
 
+    createIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `CREATE INDEX IF NOT EXISTS "${indexName}" ON "${indexInfo.tableName}"("${indexInfo.columnName}")`;
+    }
+
+    dropIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `DROP INDEX IF EXISTS "${indexName}"`;
+    }
+
     /**
      * SEED DATA METHODS
      * Support for inserting seed data during migrations

package/Migrations/migrationSQLiteQuery.js

@@ -187,6 +187,20 @@ class migrationSQLiteQuery {
         return `ALTER TABLE ${table.tableName} RENAME COLUMN ${table.name} TO ${table.newName}`
     }
 
+    createIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `CREATE INDEX IF NOT EXISTS ${indexName} ON ${indexInfo.tableName}(${indexInfo.columnName})`;
+    }
+
+    dropIndex(indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+        return `DROP INDEX IF EXISTS ${indexName}`;
+    }
+
     /**
      * SEED DATA METHODS
      * Support for inserting seed data during migrations

package/Migrations/migrationTemplate.js

@@ -82,6 +82,44 @@ module.exports = ${this.name};
         }
     }
 
+    createIndex(type, indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+
+        const indexInfoStr = JSON.stringify({
+            tableName: indexInfo.tableName,
+            columnName: indexInfo.columnName,
+            indexName: indexInfo.indexName
+        });
+
+        if(type === "up"){
+            this.#up += os.EOL + `     this.createIndex(${indexInfoStr});`
+        }
+        else{
+            this.#down += os.EOL + `     this.dropIndex(${indexInfoStr});`
+        }
+    }
+
+    dropIndex(type, indexInfo){
+        const indexName = indexInfo.indexName === true
+            ? `idx_${indexInfo.tableName.toLowerCase()}_${indexInfo.columnName.toLowerCase()}`
+            : indexInfo.indexName;
+
+        const indexInfoStr = JSON.stringify({
+            tableName: indexInfo.tableName,
+            columnName: indexInfo.columnName,
+            indexName: indexInfo.indexName
+        });
+
+        if(type === "up"){
+            this.#up += os.EOL + `     this.dropIndex(${indexInfoStr});`
+        }
+        else{
+            this.#down += os.EOL + `     this.createIndex(${indexInfoStr});`
+        }
+    }
+
 }
 
 module.exports = MigrationTemplate;

package/Migrations/migrations.js

@@ -24,7 +24,9 @@ class Migrations{
                         newColumns : [],
                         newTables : [],
                         deletedColumns : [],
-                        updatedColumns : []
+                        updatedColumns : [],
+                        newIndexes : [],
+                        deletedIndexes : []
                     }
                     tables.push(table);
                 });
@@ -38,7 +40,9 @@ class Migrations{
                         newColumns : [],
                         newTables : [],
                         deletedColumns : [],
-                        updatedColumns : []
+                        updatedColumns : [],
+                        newIndexes : [],
+                        deletedIndexes : []
                     }
                     
                     oldSchema.forEach(function (oldItem, index) {
@@ -156,11 +160,101 @@ class Migrations{
     #buildMigrationObject(oldSchema, newSchema){
 
         var tables = this.#organizeSchemaByTables(oldSchema, newSchema);
-        
+
         tables = this.#findNewTables(tables);
         tables = this.#findNewColumns(tables);
         tables = this.#findDeletedColumns(tables);
         tables = this.#findUpdatedColumns(tables);
+        tables = this.#findNewIndexes(tables);
+        tables = this.#findDeletedIndexes(tables);
+        return tables;
+    }
+
+    #findNewIndexes(tables){
+        tables.forEach(function (item, index) {
+            if(item.new && item.old){
+                Object.keys(item.new).forEach(function (key) {
+                    if(typeof item.new[key] === "object" && item.new[key].indexes){
+                        var columnName = item.new[key].name;
+                        var newIndexes = item.new[key].indexes;
+
+                        // Check if this column existed before
+                        var oldColumn = null;
+                        Object.keys(item.old).forEach(function (oldKey) {
+                            if(typeof item.old[oldKey] === "object" && item.old[oldKey].name === columnName){
+                                oldColumn = item.old[oldKey];
+                            }
+                        });
+
+                        // If column didn't exist before, or didn't have indexes, all indexes are new
+                        if(!oldColumn || !oldColumn.indexes){
+                            newIndexes.forEach(function(indexName){
+                                item.newIndexes.push({
+                                    tableName: item.name,
+                                    columnName: columnName,
+                                    indexName: indexName
+                                });
+                            });
+                        } else {
+                            // Check for new indexes that weren't in the old column
+                            newIndexes.forEach(function(indexName){
+                                if(!oldColumn.indexes.includes(indexName)){
+                                    item.newIndexes.push({
+                                        tableName: item.name,
+                                        columnName: columnName,
+                                        indexName: indexName
+                                    });
+                                }
+                            });
+                        }
+                    }
+                });
+            }
+        });
+        return tables;
+    }
+
+    #findDeletedIndexes(tables){
+        tables.forEach(function (item, index) {
+            if(item.new && item.old){
+                Object.keys(item.old).forEach(function (key) {
+                    if(typeof item.old[key] === "object" && item.old[key].indexes){
+                        var columnName = item.old[key].name;
+                        var oldIndexes = item.old[key].indexes;
+
+                        // Check if this column still exists
+                        var newColumn = null;
+                        Object.keys(item.new).forEach(function (newKey) {
+                            if(typeof item.new[newKey] === "object" && item.new[newKey].name === columnName){
+                                newColumn = item.new[newKey];
+                            }
+                        });
+
+                        // If column doesn't exist anymore, or doesn't have indexes, all indexes are deleted
+                        if(!newColumn || !newColumn.indexes){
+                            oldIndexes.forEach(function(indexName){
+                                item.deletedIndexes.push({
+                                    tableName: item.name,
+                                    columnName: columnName,
+                                    indexName: indexName
+                                });
+                            });
+                        } else {
+                            // Check for indexes that were removed
+                            oldIndexes.forEach(function(indexName){
+                                if(!newColumn.indexes.includes(indexName)){
+                                    item.deletedIndexes.push({
+                                        tableName: item.name,
+                                        columnName: columnName,
+                                        indexName: indexName
+                                    });
+                                }
+                            });
+                        }
+                    }
+                });
+            }
+        });
         return tables;
     }
 
@@ -302,6 +396,8 @@ class Migrations{
                (t.newColumns && t.newColumns.length) ||
                (t.deletedColumns && t.deletedColumns.length) ||
                (t.updatedColumns && t.updatedColumns.length) ||
+               (t.newIndexes && t.newIndexes.length) ||
+               (t.deletedIndexes && t.deletedIndexes.length) ||
                (t.old === null) || (t.new === null)){
                 return true;
             }
@@ -348,6 +444,14 @@ class Migrations{
                 }
             });
 
+            item.newIndexes.forEach(function (indexInfo, index) {
+                MT.createIndex("up", indexInfo);
+            });
+
+            item.deletedIndexes.forEach(function (indexInfo, index) {
+                MT.dropIndex("up", indexInfo);
+            });
+
         });
 
        return MT.get();

package/Migrations/schema.js

@@ -110,6 +110,22 @@ class schema{
                     var query = queryBuilder.createTable(table);
                     this.context._execute(query);
                 }
+
+                // Create indexes for columns that have .index() defined
+                const self = this;
+                Object.keys(table).forEach(function(key){
+                    if(typeof table[key] === "object" && table[key].indexes && !key.startsWith('__')){
+                        const columnName = table[key].name;
+                        table[key].indexes.forEach(function(indexName){
+                            const indexInfo = {
+                                tableName: tableName,
+                                columnName: columnName,
+                                indexName: indexName
+                            };
+                            self.createIndex(indexInfo);
+                        });
+                    }
+                });
             }
         }else{
             console.log("Table that you're trying to create is undefined. Please check if there are any changes that need to be made");
@@ -394,6 +410,56 @@ class schema{
         }
     }
 
+    createIndex(indexInfo){
+        if(indexInfo){
+            if(this.context.isSQLite){
+                var sqliteQuery = require("./migrationSQLiteQuery");
+                var queryBuilder = new sqliteQuery();
+                var query = queryBuilder.createIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isMySQL){
+                var sqlquery = require("./migrationMySQLQuery");
+                var queryBuilder = new sqlquery();
+                var query = queryBuilder.createIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isPostgres){
+                var postgresQuery = require("./migrationPostgresQuery");
+                var queryBuilder = new postgresQuery();
+                var query = queryBuilder.createIndex(indexInfo);
+                this.context._execute(query);
+            }
+        }
+    }
+
+    dropIndex(indexInfo){
+        if(indexInfo){
+            if(this.context.isSQLite){
+                var sqliteQuery = require("./migrationSQLiteQuery");
+                var queryBuilder = new sqliteQuery();
+                var query = queryBuilder.dropIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isMySQL){
+                var sqlquery = require("./migrationMySQLQuery");
+                var queryBuilder = new sqlquery();
+                var query = queryBuilder.dropIndex(indexInfo);
+                this.context._execute(query);
+            }
+
+            if(this.context.isPostgres){
+                var postgresQuery = require("./migrationPostgresQuery");
+                var queryBuilder = new postgresQuery();
+                var query = queryBuilder.dropIndex(indexInfo);
+                this.context._execute(query);
+            }
+        }
+    }
+
     seed(tableName, rows){
         if(!tableName || !rows){ return; }
         const items = Array.isArray(rows) ? rows : [rows];

package/package.json

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

@@ -1790,6 +1790,116 @@ try {
 
 ---
 
+## Field Constraints & Indexes
+
+Define database constraints and performance indexes using the fluent API:
+
+```javascript
+class User {
+    id(db) {
+        db.integer().primary().auto();
+    }
+
+    email(db) {
+        db.string()
+          .notNullable()
+          .unique()
+          .index();  // Creates performance index
+    }
+
+    username(db) {
+        db.string()
+          .notNullable()
+          .index('idx_username_custom');  // Custom index name
+    }
+
+    status(db) {
+        db.string().nullable();
+    }
+
+    created_at(db) {
+        db.timestamp().default('CURRENT_TIMESTAMP');
+    }
+}
+```
+
+### Available Constraint Methods
+
+- `.notNullable()` - Column cannot be NULL
+- `.nullable()` - Column can be NULL (default)
+- `.unique()` - Unique constraint (enforces uniqueness at DB level)
+- `.index()` - Creates performance index (auto-generated name: `idx_tablename_columnname`)
+- `.index('custom_name')` - Creates index with custom name
+- `.primary()` - Primary key (automatically indexed)
+- `.default(value)` - Default value
+
+### Index vs Unique Constraint
+
+**Understanding the difference:**
+
+- `.unique()` creates a UNIQUE constraint (prevents duplicate values, enforces data integrity)
+- `.index()` creates a performance index (improves query speed, allows duplicates)
+- You can use both together: `.unique().index()` creates a unique index for both integrity and performance
+
+**Examples:**
+
+```javascript
+// Email must be unique (no performance index)
+email(db) {
+    db.string().notNullable().unique();
+}
+
+// Username indexed for fast lookups (allows duplicates)
+username(db) {
+    db.string().notNullable().index();
+}
+
+// Email with both unique constraint AND performance index
+email(db) {
+    db.string().notNullable().unique().index();
+}
+```
+
+### Automatic Index Migration
+
+When you add `.index()` to a field, MasterRecord automatically generates migration code:
+
+```javascript
+// In your entity
+class User {
+    email(db) {
+        db.string().notNullable().index();
+    }
+}
+
+// Generated migration (automatic)
+class Migration_20250101 extends masterrecord.schema {
+    async up(table) {
+        this.init(table);
+        this.createIndex({
+            tableName: 'User',
+            columnName: 'email',
+            indexName: 'idx_user_email'
+        });
+    }
+
+    async down(table) {
+        this.init(table);
+        this.dropIndex({
+            tableName: 'User',
+            columnName: 'email',
+            indexName: 'idx_user_email'
+        });
+    }
+}
+```
+
+**Rollback support:**
+
+Migrations automatically include rollback logic. Running `masterrecord migrate down` will drop all indexes created by that migration.
+
+---
+
 ## Business Logic Validation
 
 Add validators to your entity definitions for automatic validation on property assignment.
@@ -2301,20 +2411,60 @@ await db.saveChanges();  // Batch insert
 
 ### 3. Use Indexes
 
+Define indexes directly in your entity using `.index()`:
+
 ```javascript
 class User {
-    constructor() {
-        this.email = {
-            type: 'string',
-            unique: true  // Automatically creates index
-        };
+    id(db) {
+        db.integer().primary().auto();  // Primary keys are automatically indexed
+    }
+
+    email(db) {
+        db.string()
+          .notNullable()
+          .unique()
+          .index();  // Creates: idx_user_email
+    }
+
+    last_name(db) {
+        db.string().index();  // Creates: idx_user_last_name
+    }
+
+    status(db) {
+        db.string().index('idx_user_status');  // Custom index name
     }
 }
+```
+
+**Migration automatically generates:**
 
-// For complex queries, add database indexes manually
-// CREATE INDEX idx_user_status ON User(status);
+```javascript
+// In migration file (generated automatically)
+this.createIndex({
+    tableName: 'User',
+    columnName: 'email',
+    indexName: 'idx_user_email'
+});
 ```
 
+**Rollback support:**
+
+```javascript
+// Down migration automatically includes
+this.dropIndex({
+    tableName: 'User',
+    columnName: 'email',
+    indexName: 'idx_user_email'
+});
+```
+
+**Best practices:**
+- Index columns used in WHERE clauses
+- Index foreign key columns for join performance
+- Don't over-index - each index adds write overhead
+- Primary keys are automatically indexed (no need for `.index()`)
+- Use `.unique()` for data integrity, `.index()` for query performance
+
 ### 4. Limit Result Sets
 
 ```javascript