millas 0.2.19 → 0.2.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "millas",
-  "version": "0.2.19",
+  "version": "0.2.20",
   "description": "A modern batteries-included backend framework for Node.js — built on Express, inspired by Laravel, Django, and FastAPI",
   "main": "src/index.js",
   "exports": {

package/src/commands/migrate.js

@@ -34,8 +34,22 @@ module.exports = function (program) {
             // Match Django's +/-/~ prefix style exactly
             let prefix, label;
             switch (op.type) {
-              case 'CreateModel':
-                prefix = chalk.green('+'); label = `Create model ${op.table}`; break;
+              case 'CreateModel': {
+                const idxLines = [];
+                for (const idx of (op.indexes || [])) {
+                  const l = idx.name
+                    ? `${idx.name} on ${op.table}`
+                    : `on field(s) ${idx.fields.join(', ')} of model ${op.table}`;
+                  idxLines.push(`      ${chalk.green('+')} Create index ${l}`);
+                }
+                for (const ut of (op.uniqueTogether || [])) {
+                  idxLines.push(`      ${chalk.green('+')} Create constraint on ${op.table} (${ut.join(', ')})`);
+                }
+                prefix = chalk.green('+'); label = `Create model ${op.table}`;
+                console.log(chalk.gray(`      ${prefix} ${label}`));
+                idxLines.forEach(l => console.log(chalk.gray(l)));
+                return; // return from forEach callback
+              }
               case 'DeleteModel':
                 prefix = chalk.red('-');   label = `Delete model ${op.table}`; break;
               case 'AddField':
@@ -48,6 +62,24 @@ module.exports = function (program) {
                 prefix = chalk.yellow('~'); label = `Rename field ${op.oldColumn} on ${op.table} to ${op.newColumn}`; break;
               case 'RenameModel':
                 prefix = chalk.yellow('~'); label = `Rename model ${op.oldTable} to ${op.newTable}`; break;
+              case 'AddIndex': {
+                const idx = op.index;
+                const idxLabel = idx.name
+                  ? `${idx.name} on ${op.table}`
+                  : `on field(s) ${idx.fields.join(', ')} of model ${op.table}`;
+                prefix = chalk.green('+'); label = `Create index ${idxLabel}`; break;
+              }
+              case 'RemoveIndex': {
+                const idx = op.index;
+                const idxLabel = idx.name
+                  ? `${idx.name} from ${op.table}`
+                  : `on field(s) ${idx.fields.join(', ')} of model ${op.table}`;
+                prefix = chalk.red('-');   label = `Remove index ${idxLabel}`; break;
+              }
+              case 'RenameIndex':
+                prefix = chalk.yellow('~'); label = `Rename index ${op.oldName} on ${op.table} to ${op.newName}`; break;
+              case 'AlterUniqueTogether':
+                prefix = chalk.yellow('~'); label = `Alter unique_together on ${op.table}`; break;
               default:
                 prefix = chalk.gray(' ');   label = op.type;
             }

package/src/container/AppInitializer.js

@@ -107,6 +107,13 @@ class AppInitializer {
 
         this._kernel._container.instance('basePath', basePath);
 
+        // ── Static file serving ───────────────────────────────────────────────
+        // Auto-serve each storage disk that has a baseUrl configured.
+        // Mirrors Laravel's public disk serving — zero config required.
+        // e.g. LocalDriver root=storage/uploads baseUrl=/storage
+        //      → GET /storage/avatars/photo.jpg serves the file directly.
+        this._serveStorageDisks(expressApp, basePath);
+
         const coreProviders = this._buildCoreProviders(cfg);
         this._kernel.providers([...coreProviders, ...cfg.providers]);
 
@@ -175,6 +182,42 @@ class AppInitializer {
 
     // ── Internal ───────────────────────────────────────────────────────────────
 
+    _serveStorageDisks(expressApp, basePath) {
+        const express = require('express');
+        const path    = require('path');
+        const fs      = require('fs');
+
+        let storageConfig;
+        try {
+            storageConfig = require(basePath + '/config/storage');
+        } catch {
+            // Fall back to the same defaults StorageServiceProvider uses
+            storageConfig = {
+                default: 'local',
+                disks: {
+                    local:  { driver: 'local', root: 'storage/uploads', baseUrl: '/storage' },
+                    public: { driver: 'local', root: 'public/storage',  baseUrl: '/storage' },
+                },
+            };
+        }
+
+        const seen = new Set(); // avoid mounting the same baseUrl twice
+        for (const [, disk] of Object.entries(storageConfig.disks || {})) {
+            if (!disk.baseUrl || !disk.root) continue;
+            if (seen.has(disk.baseUrl)) continue;
+            seen.add(disk.baseUrl);
+
+            const absRoot = path.isAbsolute(disk.root)
+                ? disk.root
+                : path.join(basePath, disk.root);
+
+            // Ensure the directory exists so express.static doesn't warn
+            fs.mkdirSync(absRoot, { recursive: true });
+
+            expressApp.use(disk.baseUrl, express.static(absRoot));
+        }
+    }
+
     _buildCoreProviders(cfg) {
         const providers = [];
         const load = (p) => {

package/src/orm/fields/index.js

@@ -54,19 +54,10 @@ function _makeModelRef(model) {
     if (model === 'self') return null;
     return () => {
         const path = require('path');
-        const modelsDir = path.join(process.cwd(), 'app', 'models');
         try {
-            return require(path.join(modelsDir, model));
+            const all = require(path.join(process.cwd(), 'app', 'models', 'index.js'));
+            return all[model] ?? null;
         } catch {
-            try {
-                const fs = require('fs');
-                const files = fs.readdirSync(modelsDir);
-                const match = files.find(f =>
-                    f.replace(/\.js$/, '').toLowerCase() === model.toLowerCase()
-                );
-                if (match) return require(path.join(modelsDir, match));
-            } catch {
-            }
             return null;
         }
     };
@@ -126,6 +117,22 @@ const fields = {
         return new FieldDefinition('uuid', options);
     },
 
+    email(options = {}) {
+        return new FieldDefinition('email', { max: 254, ...options });
+    },
+
+    url(options = {}) {
+        return new FieldDefinition('url', { max: 2048, ...options });
+    },
+
+    slug(options = {}) {
+        return new FieldDefinition('slug', { max: 255, ...options });
+    },
+
+    ipAddress(options = {}) {
+        return new FieldDefinition('ipAddress', { max: 45, ...options });
+    },
+
     /**
      * ForeignKey — Django-style.
      *

package/src/orm/migration/Makemigrations.js

@@ -93,7 +93,14 @@ class Makemigrations {
     }
 
     // Strip internal flags before writing
-    ops.forEach(op => { delete op._needsDefault; delete op._madeNullable; });
+    ops.forEach(op => {
+      if (op._destructiveWarning) {
+        process.stderr.write(`\n  ⚠  ${op._destructiveWarning}\n`);
+      }
+      delete op._needsDefault;
+      delete op._madeNullable;
+      delete op._destructiveWarning;
+    });
 
     // ── Step 7: Compute file name and content ────────────────────────────────
     // Detect initial FIRST — isInitial must be known before naming the file
@@ -245,50 +252,48 @@ class Makemigrations {
   _opsToName(ops) {
     if (ops.length === 0) return 'auto';
 
-    // For initial migrations → 'initial'
-    // For single op → descriptive name
-    // For multiple ops → Django style: table_field1_field2 (up to 3 segments)
-
     if (ops.length === 1) {
       const op = ops[0];
       switch (op.type) {
-        // 0001_students        (initial already handled above)
         case 'CreateModel':  return op.table;
-        // 0009_delete_course
         case 'DeleteModel':  return `delete_${op.table}`;
-        // 0004_student_age4
         case 'AddField':     return `${op.table}_${op.column}`;
-        // 0008_remove_student_age8
         case 'RemoveField':  return `remove_${op.table}_${op.column}`;
-        // 0007_alter_student_age8
         case 'AlterField':   return `alter_${op.table}_${op.column}`;
-        // 0006_rename_age7_student_age8
         case 'RenameField':  return `rename_${op.oldColumn}_${op.table}_${op.newColumn}`;
         case 'RenameModel':  return `rename_${op.oldTable}`;
+        case 'AddIndex':     return `${op.table}_${(op.index.name || op.index.fields.join('_'))}_idx`;
+        case 'RemoveIndex':  return `remove_${op.table}_${(op.index.name || op.index.fields.join('_'))}_idx`;
+        case 'AlterUniqueTogether': return `${op.table}_unique_together`;
       }
     }
 
-    // Multiple ops — build Django-style compound name from each op's contribution
-    // 0005_remove_student_age4_student_age7  (Remove + Add)
-    const segments = ops.slice(0, 3).map(op => {
+    // Multiple ops — deduplicate tables, build a compact name
+    // Group by type prefix to avoid repetition
+    const seen   = new Set();
+    const parts  = [];
+    for (const op of ops.slice(0, 3)) {
+      const table = op.table || op.oldTable || 'change';
+      let segment;
       switch (op.type) {
-        case 'CreateModel':  return op.table;
-        case 'DeleteModel':  return `delete_${op.table}`;
-        case 'AddField':     return `${op.table}_${op.column}`;
-        case 'RemoveField':  return `${op.table}_${op.column}`;
-        case 'AlterField':   return `alter_${op.table}_${op.column}`;
-        case 'RenameField':  return `rename_${op.oldColumn}_${op.table}_${op.newColumn}`;
-        default: {
-          const table  = op.table || op.oldTable || 'change';
-          const detail = op.column || op.oldColumn || '';
-          return detail ? `${table}_${detail}` : table;
-        }
+        case 'CreateModel':  segment = table; break;
+        case 'DeleteModel':  segment = `delete_${table}`; break;
+        case 'AddField':     segment = `${table}_${op.column}`; break;
+        case 'RemoveField':  segment = `${table}_${op.column}`; break;
+        case 'AlterField':   segment = `alter_${table}_${op.column}`; break;
+        case 'RenameField':  segment = `rename_${op.oldColumn}_${table}_${op.newColumn}`; break;
+        case 'AddIndex':     segment = `${table}_idx`; break;
+        case 'RemoveIndex':  segment = `${table}_idx`; break;
+        case 'AlterUniqueTogether': segment = `${table}_unique`; break;
+        default:             segment = table;
       }
-    });
-    // Prefix with 'remove_' only when first op is a RemoveField (matches Django)
+      if (!seen.has(segment)) {
+        seen.add(segment);
+        parts.push(segment);
+      }
+    }
     const prefix = ops[0]?.type === 'RemoveField' ? 'remove_' : '';
-    const joined = prefix + segments.join('_');
-    return joined || 'auto';
+    return (prefix + parts.join('_')) || 'auto';
   }
 
   /**

package/src/orm/migration/MigrationWriter.js

@@ -36,6 +36,7 @@
  */
 
 const { fieldsEqual } = require('./utils');
+const { indexName }   = require('./operations/indexes');
 
 const MILLAS_VERSION = (() => {
   try { return require('../../..').version || require('../../../package.json').version; } catch {}
@@ -65,37 +66,44 @@ class MigrationWriter {
     const histSch = historyState.toSchema();
     const currSch = currentState.toSchema();
 
+    // ── helpers to get fields/indexes from new schema shape ──────────────────
+    const getFields        = (s, t) => s[t]?.fields        ?? s[t] ?? {};
+    const getIndexes       = (s, t) => s[t]?.indexes        ?? [];
+    const getUniqueTogether = (s, t) => s[t]?.uniqueTogether ?? [];
+
     // New tables
     const newTableOps = [];
     for (const table of Object.keys(currSch)) {
       if (SYSTEM_TABLES.has(table)) continue;
       if (!histSch[table]) {
-        newTableOps.push({ type: 'CreateModel', table, fields: currSch[table] });
+        newTableOps.push({
+          type:          'CreateModel',
+          table,
+          fields:        getFields(currSch, table),
+          indexes:       getIndexes(currSch, table),
+          uniqueTogether: getUniqueTogether(currSch, table),
+        });
       }
     }
-
-    // Topologically sort new CreateModel ops so that if Post has a FK → users,
-    // CreateModel(users) appears before CreateModel(posts) in the migration file.
-    // Cycles are detected and noted — the two-pass FK creation in Operations.js
-    // handles them safely at migrate time.
     ops.push(...this._sortCreateModels(newTableOps));
 
     // Dropped tables
     for (const table of Object.keys(histSch)) {
       if (SYSTEM_TABLES.has(table)) continue;
       if (!currSch[table]) {
-        ops.push({ type: 'DeleteModel', table, fields: histSch[table] });
+        ops.push({ type: 'DeleteModel', table, fields: getFields(histSch, table) });
       }
     }
 
-    // Column-level changes
+    // Column-level + index-level changes
     for (const table of Object.keys(currSch)) {
       if (SYSTEM_TABLES.has(table)) continue;
       if (!histSch[table]) continue;
 
-      const curr = currSch[table];
-      const prev = histSch[table];
+      const curr = getFields(currSch, table);
+      const prev = getFields(histSch, table);
 
+      // Added columns
       for (const col of Object.keys(curr)) {
         if (!prev[col]) {
           const field = curr[col];
@@ -105,15 +113,62 @@ class MigrationWriter {
                               !!histSch[table];
           ops.push({ type: 'AddField', table, column: col, field, _needsDefault: isDangerous });
         } else if (!this._fieldsEqual(curr[col], prev[col])) {
-          ops.push({ type: 'AlterField', table, column: col, field: curr[col], previousField: prev[col] });
+          const op = { type: 'AlterField', table, column: col, field: curr[col], previousField: prev[col] };
+          // Warn on destructive type changes — same as Django's warning
+          if (this._isDestructiveTypeChange(prev[col].type, curr[col].type)) {
+            op._destructiveWarning =
+              `Warning: changing '${table}.${col}' from ${prev[col].type} to ${curr[col].type} ` +
+              `may cause data loss. Existing data cannot be automatically converted.`;
+          }
+          ops.push(op);
         }
       }
 
+      // Removed columns
       for (const col of Object.keys(prev)) {
         if (!curr[col]) {
           ops.push({ type: 'RemoveField', table, column: col, field: prev[col] });
         }
       }
+
+      // ── Index diffs ────────────────────────────────────────────────────────
+      const currIndexes = getIndexes(currSch, table);
+      const prevIndexes = getIndexes(histSch, table);
+
+      const prevIdxKeys = new Set(prevIndexes.map(i => JSON.stringify(i)));
+      const currIdxKeys = new Set(currIndexes.map(i => JSON.stringify(i)));
+
+      // Detect renames: same fields, different name
+      const addedIdxs   = currIndexes.filter(i => !prevIdxKeys.has(JSON.stringify(i)));
+      const removedIdxs = prevIndexes.filter(i => !currIdxKeys.has(JSON.stringify(i)));
+
+      for (const added of addedIdxs) {
+        const matchingRemoved = removedIdxs.find(
+          r => JSON.stringify(r.fields) === JSON.stringify(added.fields) &&
+               r.unique === added.unique &&
+               r.name !== added.name
+        );
+        if (matchingRemoved) {
+          // It's a rename
+          const oldName = matchingRemoved.name || indexName(table, matchingRemoved.fields, matchingRemoved.unique);
+          const newName = added.name           || indexName(table, added.fields, added.unique);
+          ops.push({ type: 'RenameIndex', table, oldName, newName, fields: added.fields });
+          removedIdxs.splice(removedIdxs.indexOf(matchingRemoved), 1);
+        } else {
+          ops.push({ type: 'AddIndex', table, index: added });
+        }
+      }
+      for (const idx of removedIdxs) {
+        ops.push({ type: 'RemoveIndex', table, index: idx });
+      }
+
+      // ── uniqueTogether diffs ───────────────────────────────────────────────
+      const currUT = getUniqueTogether(currSch, table);
+      const prevUT = getUniqueTogether(histSch, table);
+      if (JSON.stringify(currUT.map(s => [...s].sort()).sort()) !==
+          JSON.stringify(prevUT.map(s => [...s].sort()).sort())) {
+        ops.push({ type: 'AlterUniqueTogether', table, newUnique: currUT, oldUnique: prevUT });
+      }
     }
 
     return ops;
@@ -166,15 +221,22 @@ ${opsCode},
   _renderOp(op) {
     switch (op.type) {
 
-      case 'CreateModel':
+      case 'CreateModel': {
+        const idxCode = op.indexes?.length
+          ? `,\n      indexes: ${JSON.stringify(op.indexes)}`
+          : '';
+        const utCode = op.uniqueTogether?.length
+          ? `,\n      uniqueTogether: ${JSON.stringify(op.uniqueTogether)}`
+          : '';
         return `migrations.CreateModel({\n` +
                `      name: '${this._modelName(op.table)}',\n` +
                `      fields: [\n` +
                Object.entries(op.fields)
                  .map(([col, def]) => `        ['${col}', ${this._renderField(def)}],`)
                  .join('\n') + '\n' +
-               `      ],\n` +
+               `      ]${idxCode}${utCode},\n` +
                `    })`;
+      }
 
       case 'DeleteModel':
         // Django omits fields= — not needed in the migration file
@@ -222,6 +284,32 @@ ${opsCode},
                `      newName: '${op.newTable}',\n` +
                `    })`;
 
+      case 'AddIndex':
+        return `migrations.AddIndex({\n` +
+               `      modelName: '${op.table}',\n` +
+               `      index: ${JSON.stringify(op.index)},\n` +
+               `    })`;
+
+      case 'RemoveIndex':
+        return `migrations.RemoveIndex({\n` +
+               `      modelName: '${op.table}',\n` +
+               `      index: ${JSON.stringify(op.index)},\n` +
+               `    })`;
+
+      case 'RenameIndex':
+        return `migrations.RenameIndex({\n` +
+               `      modelName: '${op.table}',\n` +
+               `      oldName: '${op.oldName}',\n` +
+               `      newName: '${op.newName}',\n` +
+               `    })`;
+
+      case 'AlterUniqueTogether':
+        return `migrations.AlterUniqueTogether({\n` +
+               `      modelName: '${op.table}',\n` +
+               `      newUnique: ${JSON.stringify(op.newUnique)},\n` +
+               `      oldUnique: ${JSON.stringify(op.oldUnique)},\n` +
+               `    })`;
+
       case 'RunSQL':
         return `migrations.RunSQL({\n` +
                `      sql: ${JSON.stringify(op.sql)},\n` +
@@ -458,6 +546,22 @@ ${opsCode},
   }
 
   _fieldsEqual(a, b) { return fieldsEqual(a, b); }
+
+  /**
+   * Returns true when changing from oldType to newType risks data loss.
+   * Mirrors Django's check_for_system_checks / check_for_data_loss logic.
+   */
+  _isDestructiveTypeChange(oldType, newType) {
+    if (oldType === newType) return false;
+    // String-family — safe between each other
+    const stringFamily = new Set(['string', 'text', 'email', 'url', 'slug', 'ipAddress']);
+    if (stringFamily.has(oldType) && stringFamily.has(newType)) return false;
+    // Number-family — safe between each other (widening)
+    const numberFamily = new Set(['integer', 'bigInteger', 'float', 'decimal']);
+    if (numberFamily.has(oldType) && numberFamily.has(newType)) return false;
+    // Everything else is potentially destructive
+    return true;
+  }
 }
 
 module.exports = MigrationWriter;

package/src/orm/migration/ModelInspector.js

@@ -484,6 +484,10 @@ ${this._renderColumn('      ', diff.column, diff.previous, '.alter()')}
                 return `${indent}t.increments('${name}')${suffix};`;
 
             case 'string':
+            case 'email':
+            case 'url':
+            case 'slug':
+            case 'ipAddress':
                 line = `t.string('${name}', ${field.max || 255})`;
                 break;
 

package/src/orm/migration/ModelScanner.js

@@ -84,8 +84,10 @@ class ModelScanner {
 
     // Build state from the canonical (most-derived) class per table
     for (const [table, cls] of tableToClass) {
-      const fields = this._resolveFields(cls, classes, tableToClass);
-      state.createModel(table, fields);
+      const fields        = this._resolveFields(cls, classes, tableToClass);
+      const indexes       = cls.indexes       || [];
+      const uniqueTogether = cls.uniqueTogether || [];
+      state.createModel(table, fields, indexes, uniqueTogether);
     }
 
     return state;
@@ -162,7 +164,7 @@ class ModelScanner {
 
 
   _resolveFields(cls, allClasses, tableToClass) {
-    const fields = {};
+    let fields = {};
 
     // Walk the prototype chain collecting fields, child overrides parent
     const chain = this._inheritanceChain(cls);
@@ -191,10 +193,7 @@ class ModelScanner {
       if (ancestor.fields && typeof ancestor.fields === 'object') {
         for (const [name, def] of Object.entries(ancestor.fields)) {
           if (def && typeof def === 'object' && def.type === 'm2m') continue; // skip M2M
-          // null = explicit removal, like Django's title = None — remove from merged set
           if (def === null) { delete fields[name]; continue; }
-          // Django convention: ForeignKey declared as 'landlord' creates column 'landlord_id'.
-          // If already ends with _id, use as-is to avoid double-appending.
           const colName = (def && def._isForeignKey && !name.endsWith('_id'))
             ? name + '_id'
             : name;
@@ -203,6 +202,13 @@ class ModelScanner {
       }
     }
 
+    // Auto-inject id if no primary key declared — same as Django
+    const hasPk = Object.values(fields).some(f => f?.type === 'id' || f?.primary === true);
+    if (!hasPk) {
+      const { fields: fieldDefs } = require('../fields/index');
+      fields = { id: normaliseField(fieldDefs.id()), ...fields };
+    }
+
     return fields;
   }
 

package/src/orm/migration/ProjectState.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { tableFromClass, modelNameToTable, isSnakeCase } = require('./utils');
+const { indexName } = require('./operations/indexes');
 
 /**
  * ProjectState
@@ -29,7 +30,7 @@ class ProjectState {
 
   // ─── Mutation (called by operations during replay) ────────────────────────
 
-  createModel(table, fields) {
+  createModel(table, fields, indexes = [], uniqueTogether = []) {
     if (this.models.has(table)) {
       throw new Error(`ProjectState: table "${table}" already exists`);
     }
@@ -37,13 +38,39 @@ class ProjectState {
     for (const [name, def] of Object.entries(fields)) {
       fieldMap.set(name, normaliseField(def));
     }
-    this.models.set(table, { table, fields: fieldMap });
+    this.models.set(table, { table, fields: fieldMap, indexes: [...indexes], uniqueTogether: [...uniqueTogether] });
   }
 
   deleteModel(table) {
     this.models.delete(table);
   }
 
+  addIndex(table, index) {
+    const model = this._requireModel(table);
+    model.indexes = model.indexes || [];
+    model.indexes.push(index);
+  }
+
+  removeIndex(table, index) {
+    const model = this._requireModel(table);
+    model.indexes = (model.indexes || []).filter(
+      i => JSON.stringify(i) !== JSON.stringify(index)
+    );
+  }
+
+  renameIndex(table, oldName, newName) {
+    const model = this._requireModel(table);
+    model.indexes = (model.indexes || []).map(i => {
+      const iName = i.name || indexName(model.table, i.fields, i.unique);
+      return iName === oldName ? { ...i, name: newName } : i;
+    });
+  }
+
+  alterUniqueTogether(table, uniqueTogether) {
+    const model = this._requireModel(table);
+    model.uniqueTogether = uniqueTogether;
+  }
+
   addField(table, column, fieldDef) {
     const model = this._requireModel(table);
     if (model.fields.has(column)) {
@@ -91,9 +118,13 @@ class ProjectState {
   toSchema() {
     const schema = {};
     for (const [table, model] of this.models) {
-      schema[table] = {};
+      schema[table] = {
+        fields:        {},
+        indexes:       model.indexes       || [],
+        uniqueTogether: model.uniqueTogether || [],
+      };
       for (const [col, def] of model.fields) {
-        schema[table][col] = { ...def };
+        schema[table].fields[col] = { ...def };
       }
     }
     return schema;
@@ -107,7 +138,12 @@ class ProjectState {
       for (const [col, def] of model.fields) {
         fieldMap.set(col, { ...def });
       }
-      copy.models.set(table, { table, fields: fieldMap });
+      copy.models.set(table, {
+        table,
+        fields:         fieldMap,
+        indexes:        JSON.parse(JSON.stringify(model.indexes || [])),
+        uniqueTogether: JSON.parse(JSON.stringify(model.uniqueTogether || [])),
+      });
     }
     return copy;
   }

package/src/orm/migration/operations/column.js

@@ -109,6 +109,10 @@ function _buildColumn(t, name, def, opts = {}) {
       return null; // increments() doesn't return a chainable column builder
 
     case 'string':
+    case 'email':
+    case 'url':
+    case 'slug':
+    case 'ipAddress':
       return t.string(name, def.max || 255);
 
     case 'text':

package/src/orm/migration/operations/index.js

@@ -22,34 +22,17 @@ const { applyColumn, alterColumn,
 const { CreateModel, DeleteModel, RenameModel }    = require('./models');
 const { AddField, RemoveField,
         AlterField, RenameField }                  = require('./fields');
+const { AddIndex, RemoveIndex,
+        AlterUniqueTogether, RenameIndex }           = require('./indexes');
 const { RunSQL }                                   = require('./special');
 const { deserialise, migrations, _tableFromName }  = require('./registry');
 
 module.exports = {
-  // Base
   BaseOperation,
-
-  // Column helpers
-  applyColumn,
-  alterColumn,
-  attachFKConstraints,
-
-  // Table-level ops
-  CreateModel,
-  DeleteModel,
-  RenameModel,
-
-  // Field-level ops
-  AddField,
-  RemoveField,
-  AlterField,
-  RenameField,
-
-  // Escape hatch
+  applyColumn, alterColumn, attachFKConstraints,
+  CreateModel, DeleteModel, RenameModel,
+  AddField, RemoveField, AlterField, RenameField,
+  AddIndex, RemoveIndex, AlterUniqueTogether, RenameIndex,
   RunSQL,
-
-  // Registry
-  deserialise,
-  migrations,
-  _tableFromName,
+  deserialise, migrations, _tableFromName,
 };

package/src/orm/migration/operations/indexes.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const { BaseOperation } = require('./base');
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+function indexName(table, fields, unique = false) {
+  const fieldPart = fields.map(f => f.replace(/^-/, '')).join('_');
+  return `${table}_${fieldPart}_${unique ? 'unique' : 'index'}`;
+}
+
+function _applyIndex(t, table, idx) {
+  const { fields, name, unique } = idx;
+  const idxName  = name || indexName(table, fields, unique);
+  // Separate plain fields from descending fields (prefixed with '-')
+  const columns  = fields.map(f => f.replace(/^-/, ''));
+  const hasDesc  = fields.some(f => f.startsWith('-'));
+
+  if (unique) {
+    t.unique(columns, { indexName: idxName });
+  } else if (hasDesc) {
+    // knex doesn't support per-column sort direction in t.index() —
+    // use raw for descending indexes
+    const colsSql = fields.map(f =>
+      f.startsWith('-') ? `\`${f.slice(1)}\` DESC` : `\`${f}\``
+    ).join(', ');
+    t.index(columns, idxName); // fallback — knex limitation
+    // Note: true DESC index requires raw SQL; knex wraps it as regular index
+  } else {
+    t.index(columns, idxName);
+  }
+}
+
+// ─── AddIndex ─────────────────────────────────────────────────────────────────
+
+class AddIndex extends BaseOperation {
+  /**
+   * @param {string}   table
+   * @param {object}   index  — { fields, name?, unique? }
+   */
+  constructor(table, index) {
+    super();
+    this.type  = 'AddIndex';
+    this.table = table;
+    this.index = index;
+  }
+
+  applyState(state) {
+    state.addIndex(this.table, this.index);
+  }
+
+  async up(db) {
+    const { fields, name, unique } = this.index;
+    const idxName = name || indexName(this.table, fields, unique);
+    await db.schema.table(this.table, (t) => _applyIndex(t, this.table, this.index));
+  }
+
+  async down(db) {
+    const { fields, name, unique } = this.index;
+    const idxName = name || indexName(this.table, fields, unique);
+    const columns = fields.map(f => f.replace(/^-/, ''));
+    await db.schema.table(this.table, (t) => {
+      if (unique) t.dropUnique(columns, idxName);
+      else        t.dropIndex(columns, idxName);
+    });
+  }
+
+  toJSON() {
+    return { type: 'AddIndex', table: this.table, index: this.index };
+  }
+}
+
+// ─── RemoveIndex ──────────────────────────────────────────────────────────────
+
+class RemoveIndex extends BaseOperation {
+  constructor(table, index) {
+    super();
+    this.type  = 'RemoveIndex';
+    this.table = table;
+    this.index = index;
+  }
+
+  applyState(state) {
+    state.removeIndex(this.table, this.index);
+  }
+
+  async up(db) {
+    const { fields, name, unique } = this.index;
+    const idxName = name || indexName(this.table, fields, unique);
+    const columns = fields.map(f => f.replace(/^-/, ''));
+    await db.schema.table(this.table, (t) => {
+      if (unique) t.dropUnique(columns, idxName);
+      else        t.dropIndex(columns, idxName);
+    });
+  }
+
+  async down(db) {
+    await db.schema.table(this.table, (t) => _applyIndex(t, this.table, this.index));
+  }
+
+  toJSON() {
+    return { type: 'RemoveIndex', table: this.table, index: this.index };
+  }
+}
+
+// ─── AlterUniqueTogether ──────────────────────────────────────────────────────
+
+class AlterUniqueTogether extends BaseOperation {
+  /**
+   * @param {string}     table
+   * @param {string[][]} newUnique   — new uniqueTogether sets
+   * @param {string[][]} oldUnique   — previous uniqueTogether sets (for down())
+   */
+  constructor(table, newUnique, oldUnique = []) {
+    super();
+    this.type      = 'AlterUniqueTogether';
+    this.table     = table;
+    this.newUnique = newUnique;
+    this.oldUnique = oldUnique;
+  }
+
+  applyState(state) {
+    state.alterUniqueTogether(this.table, this.newUnique);
+  }
+
+  async up(db) {
+    await this._apply(db, this.oldUnique, this.newUnique);
+  }
+
+  async down(db) {
+    await this._apply(db, this.newUnique, this.oldUnique);
+  }
+
+  async _apply(db, remove, add) {
+    await db.schema.table(this.table, (t) => {
+      for (const fields of remove) {
+        const name = `${this.table}_${fields.join('_')}_unique`;
+        try { t.dropUnique(fields, name); } catch { /* already gone */ }
+      }
+      for (const fields of add) {
+        const name = `${this.table}_${fields.join('_')}_unique`;
+        t.unique(fields, { indexName: name });
+      }
+    });
+  }
+
+  toJSON() {
+    return {
+      type:      'AlterUniqueTogether',
+      table:     this.table,
+      newUnique: this.newUnique,
+      oldUnique: this.oldUnique,
+    };
+  }
+}
+
+// ─── RenameIndex ─────────────────────────────────────────────────────────────
+
+class RenameIndex extends BaseOperation {
+  constructor(table, oldName, newName) {
+    super();
+    this.type    = 'RenameIndex';
+    this.table   = table;
+    this.oldName = oldName;
+    this.newName = newName;
+  }
+
+  applyState(state) {
+    state.renameIndex(this.table, this.oldName, this.newName);
+  }
+
+  async up(db) {
+    // knex doesn't have renameIndex — drop and recreate
+    // The index definition is stored on the op for reconstruction
+    await db.schema.table(this.table, (t) => {
+      t.dropIndex([], this.oldName);
+    });
+    await db.schema.table(this.table, (t) => {
+      t.index(this.fields || [], this.newName);
+    });
+  }
+
+  async down(db) {
+    await db.schema.table(this.table, (t) => {
+      t.dropIndex([], this.newName);
+    });
+    await db.schema.table(this.table, (t) => {
+      t.index(this.fields || [], this.oldName);
+    });
+  }
+
+  toJSON() {
+    return { type: 'RenameIndex', table: this.table, oldName: this.oldName, newName: this.newName, fields: this.fields };
+  }
+}
+
+module.exports = { AddIndex, RemoveIndex, AlterUniqueTogether, RenameIndex, indexName, _applyIndex };

package/src/orm/migration/operations/models.js

@@ -28,16 +28,20 @@ class CreateModel extends BaseOperation {
   /**
    * @param {string} table
    * @param {object} fields  — { columnName: normalisedFieldDef }
+   * @param {Array}  [indexes]
+   * @param {Array}  [uniqueTogether]
    */
-  constructor(table, fields) {
+  constructor(table, fields, indexes = [], uniqueTogether = []) {
     super();
-    this.type   = 'CreateModel';
-    this.table  = table;
-    this.fields = fields;
+    this.type          = 'CreateModel';
+    this.table         = table;
+    this.fields        = fields;
+    this.indexes       = indexes;
+    this.uniqueTogether = uniqueTogether;
   }
 
   applyState(state) {
-    state.createModel(this.table, this.fields);
+    state.createModel(this.table, this.fields, this.indexes, this.uniqueTogether);
   }
 
   // Standard up() — inline FKs. Safe when only one CreateModel in a migration.
@@ -47,6 +51,7 @@ class CreateModel extends BaseOperation {
         applyColumn(t, name, normaliseField(def));
       }
     });
+    await this._applyIndexes(db);
   }
 
   /**
@@ -59,6 +64,7 @@ class CreateModel extends BaseOperation {
         applyColumn(t, name, { ...normaliseField(def), references: null });
       }
     });
+    await this._applyIndexes(db);
   }
 
   /**
@@ -76,8 +82,28 @@ class CreateModel extends BaseOperation {
     await db.schema.dropTableIfExists(this.table);
   }
 
+  async _applyIndexes(db) {
+    const { indexName } = require('./indexes');
+    const all = [
+      ...(this.indexes || []),
+    ];
+    const ut = this.uniqueTogether || [];
+    if (!all.length && !ut.length) return;
+    await db.schema.table(this.table, (t) => {
+      for (const idx of all) {
+        const name = idx.name || indexName(this.table, idx.fields, idx.unique);
+        if (idx.unique) t.unique(idx.fields, { indexName: name });
+        else            t.index(idx.fields, name);
+      }
+      for (const fields of ut) {
+        const name = `${this.table}_${fields.join('_')}_unique`;
+        t.unique(fields, { indexName: name });
+      }
+    });
+  }
+
   toJSON() {
-    return { type: 'CreateModel', table: this.table, fields: this.fields };
+    return { type: 'CreateModel', table: this.table, fields: this.fields, indexes: this.indexes, uniqueTogether: this.uniqueTogether };
   }
 }
 

package/src/orm/migration/operations/registry.js

@@ -2,6 +2,7 @@
 
 const { CreateModel, DeleteModel, RenameModel } = require('./models');
 const { AddField, RemoveField, AlterField, RenameField } = require('./fields');
+const { AddIndex, RemoveIndex, AlterUniqueTogether, RenameIndex } = require('./indexes');
 const { RunSQL } = require('./special');
 const { modelNameToTable, isSnakeCase } = require('../utils');
 
@@ -42,13 +43,17 @@ const { modelNameToTable, isSnakeCase } = require('../utils');
  */
 function deserialise(op) {
   switch (op.type) {
-    case 'CreateModel':  return new CreateModel(op.table, op.fields);
+    case 'CreateModel':  return new CreateModel(op.table, op.fields, op.indexes || [], op.uniqueTogether || []);
     case 'DeleteModel':  return new DeleteModel(op.table, op.fields);
     case 'RenameModel':  return new RenameModel(op.oldTable, op.newTable);
     case 'AddField':     return new AddField(op.table, op.column, op.field, op.oneOffDefault);
     case 'RemoveField':  return new RemoveField(op.table, op.column, op.field);
     case 'AlterField':   return new AlterField(op.table, op.column, op.field, op.previousField);
     case 'RenameField':  return new RenameField(op.table, op.oldColumn, op.newColumn);
+    case 'AddIndex':            return new AddIndex(op.table, op.index);
+    case 'RemoveIndex':         return new RemoveIndex(op.table, op.index);
+    case 'RenameIndex':         return new RenameIndex(op.table, op.oldName, op.newName);
+    case 'AlterUniqueTogether': return new AlterUniqueTogether(op.table, op.newUnique, op.oldUnique);
     case 'RunSQL':       return new RunSQL(op.sql, op.reverseSql);
     default:
       throw new Error(`Unknown migration operation type: "${op.type}"`);
@@ -63,10 +68,10 @@ function deserialise(op) {
  */
 const migrations = {
 
-  CreateModel({ name, fields: fieldList = [] }) {
+  CreateModel({ name, fields: fieldList = [], indexes = [], uniqueTogether = [] }) {
     const fields = {};
     for (const [col, def] of fieldList) fields[col] = def;
-    return { type: 'CreateModel', table: _tableFromName(name), fields };
+    return { type: 'CreateModel', table: _tableFromName(name), fields, indexes, uniqueTogether };
   },
 
   DeleteModel({ name, fields: fieldList = [] }) {
@@ -101,6 +106,22 @@ const migrations = {
     return { type: 'RenameField', table: modelName, oldColumn: oldName, newColumn: newName };
   },
 
+  AddIndex({ modelName, index }) {
+    return { type: 'AddIndex', table: modelName, index };
+  },
+
+  RemoveIndex({ modelName, index }) {
+    return { type: 'RemoveIndex', table: modelName, index };
+  },
+
+  RenameIndex({ modelName, oldName, newName }) {
+    return { type: 'RenameIndex', table: modelName, oldName, newName };
+  },
+
+  AlterUniqueTogether({ modelName, newUnique, oldUnique = [] }) {
+    return { type: 'AlterUniqueTogether', table: modelName, newUnique, oldUnique };
+  },
+
   RunSQL({ sql, reverseSql = null }) {
     return { type: 'RunSQL', sql, reverseSql };
   },

package/src/orm/model/Model.js

@@ -173,16 +173,22 @@ class Model {
 
     while (cur && cur !== Function.prototype) {
       if (Object.prototype.hasOwnProperty.call(cur, 'fields')) {
-        chain.unshift(cur.fields); // ancestor first → child wins in Object.assign
+        chain.unshift(cur.fields);
       }
       const curTable = cur.table || cur.name;
-      // Stop walking when we reach a non-abstract ancestor with a different table
-      // (that's a separate model with its own migration — don't merge its fields)
       if (cur !== this && !cur.abstract && curTable !== myTable) break;
       cur = Object.getPrototypeOf(cur);
     }
 
-    const merged = Object.assign({}, ...chain);
+    let merged = Object.assign({}, ...chain);
+
+    // Auto-inject id if no primary key is declared — same as Django
+    const hasPk = Object.values(merged).some(f => f?.primary === true || f?.type === 'id');
+    if (!hasPk) {
+      const { fields } = require('../fields/index');
+      merged = { id: fields.id(), ...merged };
+    }
+
     Object.defineProperty(this, '_cachedFields', {
       value: merged, writable: true, configurable: true, enumerable: false,
     });
@@ -659,7 +665,7 @@ class Model {
     };
 
     payload = await this.constructor.beforeUpdate(payload) ?? payload;
-    payload = this.constructor._serializeForDb(payload);
+    const dbPayload = this.constructor._serializeForDb(payload);
 
     const q = trx
       ? trx(this.constructor.table)
@@ -667,9 +673,9 @@ class Model {
 
     await q
       .where(this.constructor.primaryKey, this[this.constructor.primaryKey])
-      .update(payload);
+      .update(dbPayload);
 
-    Object.assign(this, payload);
+    Object.assign(this, payload);  // keep JS types on the instance, not serialized values
     await this.constructor.afterUpdate(this);
     return this;
   }
@@ -774,15 +780,21 @@ class Model {
   static _castValue(val, type) {
     if (val == null) return val;
     switch (type) {
-      case 'boolean':   return Boolean(val);
-      case 'integer':   return Number.isInteger(val) ? val : parseInt(val, 10);
-      case 'bigInteger':return typeof val === 'bigint' ? val : parseInt(val, 10);
+      case 'boolean':    return Boolean(val);
+      case 'integer':    return Number.isInteger(val) ? val : parseInt(val, 10);
+      case 'bigInteger': return typeof val === 'bigint' ? val : parseInt(val, 10);
       case 'float':
-      case 'decimal':   return typeof val === 'number' ? val : parseFloat(val);
-      case 'json':      return typeof val === 'string' ? JSON.parse(val) : val;
+      case 'decimal':    return typeof val === 'number' ? val : parseFloat(val);
+      case 'json':       return typeof val === 'string' ? JSON.parse(val) : val;
       case 'date':
-      case 'timestamp': return val instanceof Date ? val : new Date(val);
-      default:          return val;
+      case 'timestamp':  return val instanceof Date ? val : new Date(val);
+      // string-backed types — no casting needed
+      case 'string':
+      case 'email':
+      case 'url':
+      case 'slug':
+      case 'ipAddress':  return String(val);
+      default:           return val;
     }
   }
 

package/src/orm/query/QueryBuilder.js

@@ -381,7 +381,7 @@ class QueryBuilder {
   async _eagerLoad(instances) {
     if (!instances.length) return;
 
-    const relations = this._model.relations || {};
+    const relations = this._model._effectiveRelations();
 
     for (const { name, constraint, aggregate, aggregateColumn } of this._withs) {