wheels generate model

Generate a model with properties, validations, and associations.

Synopsis

wheels generate model name=<modelName> [options]

#Can also be used as:
wheels g model name=<modelName> [options]

Parameter Syntax

CommandBox supports multiple parameter formats:

• Named parameters: name=value (e.g., name=User, properties=name:string,email:string)
• Flag parameters: --flag equals flag=true (e.g., --migration equals migration=true)
• Flag with value: --flag=value equals flag=value (e.g., --primaryKey=uuid)

Note: Flag syntax (--flag) avoids positional/named parameter conflicts and is recommended for boolean options.

Description

The wheels generate model command creates a new model CFC file with optional properties, associations, and database migrations. Models represent database tables and contain business logic, validations, and relationships.

Arguments

| Argument | Description | Default | |----------|-------------|---------| | name | Model name (singular) | Required |

Options

| Option | Description | Valid Values | Default | |--------|-------------|--------------|---------| | properties | Model properties (format: name:type,name2:type2) | Property format: name:type[,name2:type2] where type is valid column type | "" | | belongsTo | Parent model relationships (comma-separated) | Valid model names (PascalCase), comma-separated | "" | | hasMany | Child model relationships (comma-separated) | Valid model names (PascalCase), comma-separated | "" | | hasOne | One-to-one relationships (comma-separated) | Valid model names (PascalCase), comma-separated | "" | | primaryKey | Primary key column name(s) | Valid column name (alphanumeric, underscore) | id | | tableName | Custom database table name | Valid table name (alphanumeric, underscore) | "" | | description | Model description | Any descriptive text | "" | | migration | Generate database migration | true, false | true | | force | Overwrite existing files | true, false | false |

Parameter Validation

Required Parameters

• name: Cannot be empty, must be valid CFML component name (alphanumeric, starts with letter)

Property Types Validation

Valid property types for the properties parameter:

| Type | Database Type | Validation | |------|---------------|------------| | string | VARCHAR(255) | Default string type | | text | TEXT | For longer text content | | integer | INTEGER | Whole numbers | | biginteger | BIGINT | Large whole numbers | | float | FLOAT | Decimal numbers | | decimal | DECIMAL(10,2) | Precise decimal numbers | | boolean | BOOLEAN | true/false values | | date | DATE | Date values | | datetime | DATETIME | Date and time values | | timestamp | TIMESTAMP | Timestamp values | | binary | BLOB | Binary data | | uuid | VARCHAR(35) | UUID strings |

Model Name Validation

• Must be singular (User, not Users)
• Must be PascalCase (User, BlogPost)
• Cannot contain spaces or special characters
• Must be valid CFML component name

Relationship Validation

• Relationship model names must follow model naming conventions
• Models referenced in relationships should exist or be created
• Comma-separated values cannot contain spaces around commas

Examples

Basic model

wheels generate model name=User

Creates:

• /models/User.cfc
• Migration file (if enabled)

Model with properties

wheels generate model name=User --properties="firstName:string,lastName:string,email:string,age:integer"

Model with associations

wheels generate model name=Post --belongsTo="User" --hasMany="Comments"

Model without migration

wheels generate model name=Setting --migration=false

Complex model

wheels generate model name=Product --properties="name:string,price:decimal,stock:integer,active:boolean" --belongsTo="Category,Brand" --hasMany="Reviews,OrderItems"

Validation Examples

✅ Valid Examples

# Valid model name and properties
wheels generate model name=User --properties="firstName:string,lastName:string,email:string,age:integer"

# Valid relationships
wheels generate model name=Post --belongsTo="User,Category" --hasMany="Comments,Tags"

# Valid property types
wheels generate model name=Product --properties="name:string,description:text,price:decimal,inStock:boolean,createdAt:datetime"

❌ Invalid Examples and Errors

Invalid Model Names

# Error: Model name cannot be empty
wheels generate model name=""
# Result: Invalid model name error

# Error: Model name should be singular
wheels generate model name=Users
# Result: Warning about plural name

# Error: Invalid characters
wheels generate model name="Blog Post"
# Result: Invalid model name error

Invalid Property Types

# Error: Invalid property type
wheels generate model name=User --properties="name:varchar,age:int"
# Result: Use 'string' instead of 'varchar', 'integer' instead of 'int'

# Error: Missing property type
wheels generate model name=User --properties="name,email:string"
# Result: Property format must be 'name:type'

Invalid Relationships

# Error: Invalid model name format
wheels generate model name=Post --belongsTo="user,blog_category"
# Result: Use PascalCase: 'User,BlogCategory'

# Error: Spaces in comma-separated values
wheels generate model name=Post --belongsTo="User, Category"
# Result: Remove spaces: 'User,Category'

Property Types

| Type | Database Type | CFML Type | |------|---------------|-----------| | string | VARCHAR(255) | string | | text | TEXT | string | | integer | INTEGER | numeric | | biginteger | BIGINT | numeric | | float | FLOAT | numeric | | decimal | DECIMAL(10,2) | numeric | | boolean | BOOLEAN | boolean | | date | DATE | date | | datetime | DATETIME | date | | timestamp | TIMESTAMP | date | | binary | BLOB | binary | | uuid | VARCHAR(35) | string |

Generated Code

Basic Model

component extends="Model" {

    function init() {
        // Table name (optional if following conventions)
        table("users");
        
        // Validations
        validatesPresenceOf("email");
        validatesUniquenessOf("email");
        validatesFormatOf("email", regex="^[^@]+@[^@]+\.[^@]+$");
        
        // Callbacks
        beforeCreate("setDefaultValues");
    }
    
    private function setDefaultValues() {
        if (!StructKeyExists(this, "createdAt")) {
            this.createdAt = Now();
        }
    }

}

Model with Properties

component extends="Model" {

    function init() {
        // Properties
        property(name="firstName", label="First Name");
        property(name="lastName", label="Last Name");
        property(name="email", label="Email Address");
        property(name="age", label="Age");
        
        // Validations
        validatesPresenceOf("firstName,lastName,email");
        validatesUniquenessOf("email");
        validatesFormatOf("email", regex="^[^@]+@[^@]+\.[^@]+$");
        validatesNumericalityOf("age", onlyInteger=true, greaterThan=0, lessThan=150);
    }

}

Model with Associations

component extends="Model" {

    function init() {
        // Associations
        belongsTo("user");
        hasMany("comments", dependent="deleteAll");
        
        // Nested properties
        nestedProperties(associations="comments", allowDelete=true);
        
        // Validations
        validatesPresenceOf("title,content,userId");
        validatesLengthOf("title", maximum=255);
    }

}

Validations

Common validation methods:

// Presence
validatesPresenceOf("name,email");

// Uniqueness
validatesUniquenessOf("email,username");

// Format
validatesFormatOf("email", regex="^[^@]+@[^@]+\.[^@]+$");
validatesFormatOf("phone", regex="^\d{3}-\d{3}-\d{4}$");

// Length
validatesLengthOf("username", minimum=3, maximum=20);
validatesLengthOf("bio", maximum=500);

// Numerical
validatesNumericalityOf("age", onlyInteger=true, greaterThan=0);
validatesNumericalityOf("price", greaterThan=0);

// Inclusion/Exclusion
validatesInclusionOf("status", list="active,inactive,pending");
validatesExclusionOf("username", list="admin,root,system");

// Confirmation
validatesConfirmationOf("password");

// Custom
validate("customValidation");

Associations

Belongs To

belongsTo("user");
belongsTo(name="author", modelName="user", foreignKey="authorId");

Has Many

hasMany("comments");
hasMany(name="posts", dependent="deleteAll", orderBy="createdAt DESC");

Has One

hasOne("profile");
hasOne(name="address", dependent="delete");

Many to Many

hasMany("categorizations");
hasMany(name="categories", through="categorizations");

Callbacks

Lifecycle callbacks:

// Before callbacks
beforeCreate("method1,method2");
beforeUpdate("method3");
beforeSave("method4");
beforeDelete("method5");
beforeValidation("method6");

// After callbacks
afterCreate("method7");
afterUpdate("method8");
afterSave("method9");
afterDelete("method10");
afterValidation("method11");
afterFind("method12");
afterInitialization("method13");

Generated Migration

When --migration is enabled:

component extends="wheels.migrator.Migration" {

    function up() {
        transaction {
            t = createTable("users");
            t.string("firstName");
            t.string("lastName");
            t.string("email");
            t.integer("age");
            t.timestamps();
            t.create();
            
            addIndex(table="users", columnNames="email", unique=true);
        }
    }

    function down() {
        transaction {
            dropTable("users");
        }
    }

}

Common Validation Errors

Model Name Errors

• Empty name: name="" → Provide a valid model name
• Plural names: name=Users → Use singular form: name=User
• Invalid characters: name="Blog Post" → Use PascalCase: name=BlogPost
• Lowercase: name=user → Use PascalCase: name=User

Property Format Errors

• Missing colon: properties="name,email:string" → properties="name:string,email:string"
• Invalid types: properties="name:varchar" → properties="name:string"
• Extra spaces: properties="name: string" → properties="name:string"
• Missing type: properties="name:" → properties="name:string"

Boolean Parameter Errors

• Invalid boolean: --migration=yes → --migration=true or --migration=false
• Mixed syntax: migration=true --force → --migration=true --force

Relationship Format Errors

• Lowercase models: belongsTo="user" → belongsTo="User"
• Extra spaces: belongsTo="User, Category" → belongsTo="User,Category"
• Invalid separators: belongsTo="User;Category" → belongsTo="User,Category"

Best Practices

1. Naming: Use singular names (User, not Users)
2. Properties: Define all database columns with correct types
3. Validations: Add comprehensive validations in model code
4. Associations: Define all relationships using PascalCase
5. Callbacks: Use for automatic behaviors
6. Indexes: Add to migration for performance
7. Validation: Always validate parameters before running command

Common Patterns

Soft Deletes

function init() {
    softDeletes();
}

Calculated Properties

function init() {
    property(name="fullName", sql="firstName + ' ' + lastName");
}

Scopes

function scopeActive() {
    return where("active = ?", [true]);
}

function scopeRecent(required numeric days=7) {
    return where("createdAt >= ?", [DateAdd("d", -arguments.days, Now())]);
}

Default Values

function init() {
    beforeCreate("setDefaults");
}

private function setDefaults() {
    if (!StructKeyExists(this, "status")) {
        this.status = "pending";
    }
    if (!StructKeyExists(this, "priority")) {
        this.priority = 5;
    }
}

Testing

Generate model tests:

wheels generate model name=User --properties="email:string,name:string"
wheels generate test model name=User

Troubleshooting

Command Fails with "Invalid model name"

1. Check that name is not empty: name=User
2. Ensure PascalCase format: name=User (not name=user)
3. Use singular form: name=User (not name=Users)
4. Remove special characters: name=BlogPost (not name="Blog Post")

Properties Not Generated in Migration

1. Check property format: properties="name:string,email:string"
2. Ensure valid property types (see Property Types table above)
3. Remove extra spaces: name:string (not name: string)
4. Use comma separators: name:string,email:string

Relationships Not Working

1. Use PascalCase model names: belongsTo="User" (not belongsTo="user")
2. Remove spaces after commas: belongsTo="User,Category"
3. Ensure referenced models exist or will be created

Migration Not Generated

1. Check --migration=false wasn't set
2. Ensure you have write permissions in the directory
3. Verify migration directory exists: /app/migrator/migrations/

Boolean Parameters Not Working

1. Use --flag for flag=true: --force equals force=true
2. Use --flag=false for false values: --migration=false
3. Don't mix syntaxes: Use all flags or all named parameters

See Also

• wheels dbmigrate create table - Create migrations
• wheels generate property - Add properties to existing models
• wheels generate controller - Generate controllers
• wheels scaffold - Generate complete CRUD