HomeAPIBlog
Edit

wheels dbmigrate create table

Generate a migration file for creating a new database table.

Synopsis

wheels dbmigrate create table name=<table_name> [--force] [--id] primaryKey=<key_name>

Alias: wheels db create table

CommandBox Parameter Syntax

This command supports multiple parameter formats:

  • Named parameters: name=value (e.g., name=users, primaryKey=userId)

  • Flag parameters: --flag equals flag=true (e.g., --force equals force=true)

  • Flag with value: --flag=value equals flag=value (e.g., --id=false)

Parameter Mixing Rules:

✅ ALLOWED:

  • All named: name=users primaryKey=userId

  • Named + flags: name=users --force --id=false

❌ NOT ALLOWED:

  • Positional parameters: This command does not support positional parameters

Recommendation: Use named for required parameters, flags for booleans: name=users --force

Description

The dbmigrate create table command generates a migration file that creates a new database table. The generated migration includes the table structure following Wheels conventions.

Parameters

Parameter
Type
Required
Default
Description

name

string

Yes

-

The name of the table to create

--force

boolean

No

false

Force the creation of the table

--id

boolean

No

true

Auto create ID column as autoincrement ID

primaryKey

string

No

"id"

Overrides the default primary key column name

Notes About Column Definition

The generated migration file will contain a basic table structure. You'll need to manually edit the migration file to add columns with their types and options. The migration template includes comments showing how to add columns.

Examples

Create a basic table

# Named parameter (required)
wheels dbmigrate create table name=users

Create table without ID column

# Named + flag (recommended)
wheels dbmigrate create table name=user_roles --id=false

# OR all named
wheels db create table name=user_roles id=false

Create table with custom primary key

# Named parameters (recommended)
wheels dbmigrate create table name=products primaryKey=productCode

Force creation (overwrite existing)

# Named + flag (recommended)
wheels dbmigrate create table name=users --force

# OR all named
wheels db create table name=users force=true

Generated Migration Example

For the command:

wheels dbmigrate create table name=users

Generates a migration file that you can customize:

component extends="wheels.migrator.Migration" hint="create users table" {

    function up() {
        transaction {
            t = createTable(name="users", force=false, id=true, primaryKey="id");
            // Add your columns here
            // t.string(columnNames="name");
            // t.integer(columnNames="age");
            t.timestamps();
            t.create();
        }
    }

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

}

Use Cases

Standard Entity Table

Create a typical entity table:

# Generate the migration
wheels dbmigrate create table name=customer

# Then edit the migration file to add columns

Join Table for Many-to-Many

Create a join table without primary key:

wheels dbmigrate create table name=products_categories --id=false

Table with Custom Primary Key

Create a table with non-standard primary key:

wheels dbmigrate create table name=legacy_customer primaryKey=customer_code

Best Practices

1. Use Singular Table Names

Wheels conventions expect singular table names:

# Good
wheels dbmigrate create table name=user
wheels dbmigrate create table name=product

# Avoid
wheels dbmigrate create table name=users
wheels dbmigrate create table name=products

2. Edit Migration Files

After generating the migration, edit it to add columns:

// In the generated migration file
t = createTable(name="orders", force=false, id=true, primaryKey="id");
t.integer(columnNames="customer_id");
t.decimal(columnNames="total", precision=10, scale=2);
t.string(columnNames="status", default="pending");
t.timestamps();
t.create();

3. Plan Your Schema

Think through your table structure before creating:

  • Primary key strategy

  • Required columns and their types

  • Foreign key relationships

  • Indexes needed for performance

Working with the Generated Migration

The command generates a basic migration template. You'll need to edit it to add columns:

component extends="wheels.migrator.Migration" {
    function up() {
        transaction {
            t = createTable(name="tableName", force=false, id=true, primaryKey="id");
            // Add your columns here:
            t.string(columnName="name");
            t.integer(columnName="age");
            t.boolean(columnName="active", default=true);
            t.text(columnName="description");
            // MySQL only: use size parameter for larger text fields
            t.text(columnName="content", size="mediumtext"); // 16MB
            t.text(columnName="largeContent", size="longtext"); // 4GB
            t.timestamps();
            t.create();
        }
    }
    
    function down() {
        transaction {
            dropTable("tableName");
        }
    }
}

Notes

  • Table names should follow your database naming conventions

  • The migration automatically handles rollback with dropTable()

  • Column order in the command is preserved in the migration

  • Use wheels dbmigrate up to run the generated migration

Related Commands

Previouswheels dbmigrate create blankNextwheels dbmigrate create column

Last updated

Was this helpful?