docs(api): validate Migrator section

vendor/wheels/public/docs/reference/migration/addcolumn.txt

@@ -1 +1,22 @@
-addColumn(table='members', columnType='string', columnName='status', limit=50);
+// 1. Add a simple string column to an existing table
+addColumn(table="members", columnType="string", columnName="status", limit=50);
+
+// 2. Add a boolean column with a default value and no NULLs allowed
+addColumn(
+    table="members",
+    columnType="boolean",
+    columnName="isActive",
+    default=1,
+    allowNull=false
+);
+
+// 3. Add a decimal column with precision and scale (e.g. for a price field)
+addColumn(
+    table="products",
+    columnType="decimal",
+    columnName="price",
+    precision=10,
+    scale=2,
+    default=0,
+    allowNull=false
+);

vendor/wheels/public/docs/reference/migration/addforeignkey.txt

@@ -0,0 +1,31 @@
+// 1. Add a foreign key from orders.customerId to customers.id
+addForeignKey(
+    table="orders",
+    referenceTable="customers",
+    column="customerId",
+    referenceColumn="id"
+);
+
+// 2. Add a foreign key from comments.postId to posts.id
+addForeignKey(
+    table="comments",
+    referenceTable="posts",
+    column="postId",
+    referenceColumn="id"
+);
+
+// 3. Use addForeignKey in a migration's up() and remove it in down()
+// In your migration CFC:
+//
+// public void function up() {
+//     addForeignKey(
+//         table="order_items",
+//         referenceTable="orders",
+//         column="orderId",
+//         referenceColumn="id"
+//     );
+// }
+//
+// public void function down() {
+//     dropForeignKey(table="order_items", keyName="FK_order_items_orders");
+// }

vendor/wheels/public/docs/reference/migration/addindex.txt

@@ -1 +1,12 @@
-addIndex(table='members', columnNames='username', unique=true);
+// 1. Add a basic index on a single column
+addIndex(table="users", columnNames="email");
+
+// 2. Add a unique index to enforce uniqueness on a column
+addIndex(table="members", columnNames="username", unique=true);
+
+// 3. Add a composite index on multiple columns
+addIndex(table="orders", columnNames="customerId,createdAt");
+
+// 4. Add an index with a custom index name
+// (defaults to tableName_firstColumnName, e.g. "posts_publishedAt")
+addIndex(table="posts", columnNames="publishedAt", indexName="idx_posts_published");

vendor/wheels/public/docs/reference/migration/addrecord.txt

@@ -1,8 +1,32 @@
-addRecord(table='people',
-		id = 1,
-		title = "Mr",
-		firstname = "Bruce",
-		lastname = "Wayne", 
-		email = "bruce@wayneenterprises.com",
-		tel = "555-67869099", 
+// 1. Insert a simple seed record into a settings table
+addRecord(
+    table = "settings",
+    name = "siteName",
+    value = "My Wheels App"
 );
+
+// 2. Insert a record with multiple columns (extra keyword arguments become column/value pairs)
+addRecord(
+    table = "people",
+    id = 1,
+    title = "Mr",
+    firstName = "Bruce",
+    lastName = "Wayne",
+    email = "bruce@wayneenterprises.com",
+    phone = "555-678-9099"
+);
+
+// 3. Seed an admin user role during a migration's up() function
+component extends="wheels.migrator.Migration" {
+    function up() {
+        addRecord(
+            table = "roles",
+            id = 1,
+            name = "admin",
+            active = true
+        );
+    }
+    function down() {
+        removeRecord(table = "roles", where = "id = 1");
+    }
+}

vendor/wheels/public/docs/reference/migration/addreference.txt

@@ -0,0 +1,17 @@
+// 1. Add a foreign key from comments.postId to posts.id using a reference name
+// Equivalent to: addForeignKey(table="comments", referenceTable="posts", column="postId", referenceColumn="id")
+addReference(table="comments", referenceName="post");
+
+// 2. Add a foreign key from order_items.orderId to orders.id
+addReference(table="order_items", referenceName="order");
+
+// 3. Use addReference in a migration's up() and undo it with dropReference() in down()
+// In your migration CFC:
+//
+// public void function up() {
+//     addReference(table="comments", referenceName="post");
+// }
+//
+// public void function down() {
+//     dropReference(table="comments", referenceName="post");
+// }

vendor/wheels/public/docs/reference/migration/announce.txt

@@ -0,0 +1,44 @@
+// 1. Log a custom message during a migration's up() step
+function up() {
+	transaction {
+		try {
+			createTable(name="articles", force=true) {
+				t.string(columnNames="title", null=false);
+				t.text("body");
+				t.timestamps();
+			};
+			announce("Created articles table");
+		} catch (any e) {
+			local.exception = e;
+		}
+
+		if (StructKeyExists(local, "exception")) {
+			transaction action="rollback";
+			throw(errorCode="1", detail=local.exception.detail, message=local.exception.message, type="any");
+		} else {
+			transaction action="commit";
+		}
+	}
+}
+
+// 2. Announce multiple steps to provide granular feedback
+function up() {
+	transaction {
+		try {
+			addColumn(table="users", columnType="string", columnName="apiKey", limit=64, null=true);
+			announce("Added apiKey column to users");
+
+			addIndex(table="users", columnNames="apiKey", unique=true);
+			announce("Added unique index on users.apiKey");
+		} catch (any e) {
+			local.exception = e;
+		}
+
+		if (StructKeyExists(local, "exception")) {
+			transaction action="rollback";
+			throw(errorCode="1", detail=local.exception.detail, message=local.exception.message, type="any");
+		} else {
+			transaction action="commit";
+		}
+	}
+}

vendor/wheels/public/docs/reference/migration/changecolumn.txt

@@ -1 +1,11 @@
-changeColumn(table='members', columnType='string', columnName='status', limit=50);
+// 1. Change a string column's length limit
+changeColumn(table="members", columnName="status", columnType="string", limit=50);
+
+// 2. Change a column type and set a default value
+changeColumn(table="orders", columnName="quantity", columnType="integer", default=1);
+
+// 3. Change a decimal column with precision and scale
+changeColumn(table="products", columnName="price", columnType="decimal", precision=10, scale=2, allowNull=false);
+
+// 4. Change a text column and explicitly allow NULL values
+changeColumn(table="articles", columnName="summary", columnType="text", allowNull=true);

vendor/wheels/public/docs/reference/migration/changetable.txt

@@ -1,3 +1,15 @@
-t = changeTable(name='employees');
-t.string(columnNames="fullName", default="", allowNull=true, limit="255");
+// 1. Add a new string column to an existing table
+t = changeTable(name="employees");
+t.string(columnNames="fullName", default="", allowNull=true, limit=255);
 t.change();
+
+// 2. Modify multiple columns at once (change type and nullability)
+t = changeTable(name="products");
+t.integer(columnNames="stock", default=0, allowNull=false);
+t.boolean(columnNames="active", default=true, allowNull=false);
+t.change();
+
+// 3. Add a new column using addColumns=true so the migration fails gracefully if the column already exists
+t = changeTable(name="orders");
+t.datetime(columnNames="shippedAt", allowNull=true);
+t.change(addColumns=true);

vendor/wheels/public/docs/reference/migration/createtable.txt

@@ -1,25 +1,23 @@
-// Example: create a users table
-t = createTable(name='users'); 
-	t.string(columnNames='firstname,lastname', default='', allowNull=false, limit=50);
-	t.string(columnNames='email', default='', allowNull=false, limit=255); 
-	t.string(columnNames='passwordHash', default='', allowNull=true, limit=500);
-	t.string(columnNames='passwordResetToken,verificationToken', default='', allowNull=true, limit=500);
-	t.boolean(columnNames='passwordChangeRequired,verified', default=false); 
-	t.datetime(columnNames='passwordResetTokenAt,passwordResetAt,loggedinAt', default='', allowNull=true); 
-	t.integer(columnNames='roleid', default=0, allowNull=false, limit=3);
+// 1. Create a users table with standard columns and timestamps
+t = createTable(name="users");
+	t.string(columnNames="firstName,lastName", default="", allowNull=false, limit=50);
+	t.string(columnNames="email", default="", allowNull=false, limit=255);
+	t.string(columnNames="passwordHash", default="", allowNull=true, limit=500);
+	t.boolean(columnNames="verified", default=false);
+	t.integer(columnNames="roleId", default=0, allowNull=false);
 	t.timestamps();
 t.create();
 
-// Example: Create a table with a different Primary Key
-t = createTable(name='tokens', id=false);
-	t.primaryKey(name='id', allowNull=false, type="string", limit=35 );
+// 2. Create a table with a custom string primary key (disabling the auto integer id)
+t = createTable(name="tokens", id=false);
+	t.primaryKey(name="id", allowNull=false, type="string", limit=36);
+	t.string(columnNames="userId", allowNull=false, limit=36);
 	t.datetime(columnNames="expiresAt", allowNull=false);
-	t.integer(columnNames='requests', default=0, allowNull=false);
 	t.timestamps();
 t.create();
 
-// Example: Create a Join Table with composite primary keys
-t = createTable(name='userkintins', id=false); 
-	t.primaryKey(name="userid", allowNull=false, limit=11);
-	t.primaryKey(name='profileid', type="string", limit=11 );  
+// 3. Create a join table with composite primary keys and force=true to recreate if it already exists
+t = createTable(name="userRoles", id=false, force=true);
+	t.primaryKey(name="userId", allowNull=false, limit=11);
+	t.primaryKey(name="roleId", allowNull=false, limit=11);
 t.create();

vendor/wheels/public/docs/reference/migration/createview.txt

@@ -0,0 +1,21 @@
+// 1. Create a simple database view that joins users and roles
+v = createView(name="userRoles");
+v.selectStatement(sql="SELECT u.id, u.firstName, u.lastName, r.name AS roleName FROM users u INNER JOIN roles r ON u.roleId = r.id");
+v.create();
+
+// 2. Create a view for active (non-deleted) users using method chaining
+createView(name="activeUsers")
+    .selectStatement(sql="SELECT id, firstName, lastName, email FROM users WHERE deletedAt IS NULL")
+    .create();
+
+// 3. Full up/down migration using createView and dropView
+component extends="wheels.migrator.Migration" {
+    function up() {
+        createView(name="publishedArticles")
+            .selectStatement(sql="SELECT id, title, body, authorId, publishedAt FROM articles WHERE publishedAt IS NOT NULL")
+            .create();
+    }
+    function down() {
+        dropView(name="publishedArticles");
+    }
+}

vendor/wheels/public/docs/reference/migration/down.txt

@@ -1,17 +1,95 @@
+// 1. Reverse a table creation by dropping the table
+// Called automatically when rolling back this migration
 function down() {
 	transaction {
 		try {
-			// your code goes here
-			dropTable('myTable');
+			dropTable("employees");
 		} catch (any e) {
 			local.exception = e;
 		}
 
-		if (StructKeyExists(local, "exception")) {
+		if (structKeyExists(local, "exception")) {
 			transaction action="rollback";
-			throw(errorCode="1", detail=local.exception.detail, message=local.exception.message, type="any");
+			throw(
+				errorCode = "1",
+				detail    = local.exception.detail,
+				message   = local.exception.message,
+				type      = "any"
+			);
 		} else {
 			transaction action="commit";
 		}
 	}
 }
+
+// 2. Reverse an addColumn() call by removing the column
+function down() {
+	transaction {
+		try {
+			removeColumn(table="users", columnName="biography");
+		} catch (any e) {
+			local.exception = e;
+		}
+
+		if (structKeyExists(local, "exception")) {
+			transaction action="rollback";
+			throw(
+				errorCode = "1",
+				detail    = local.exception.detail,
+				message   = local.exception.message,
+				type      = "any"
+			);
+		} else {
+			transaction action="commit";
+		}
+	}
+}
+
+// 3. Paired up() and down() inside a full migration component
+component extends="[extends]" hint="Add status column to orders" {
+
+	function up() {
+		transaction {
+			try {
+				addColumn(table="orders", columnType="string", columnName="status", limit=50, default="pending");
+			} catch (any e) {
+				local.exception = e;
+			}
+
+			if (structKeyExists(local, "exception")) {
+				transaction action="rollback";
+				throw(
+					errorCode = "1",
+					detail    = local.exception.detail,
+					message   = local.exception.message,
+					type      = "any"
+				);
+			} else {
+				transaction action="commit";
+			}
+		}
+	}
+
+	function down() {
+		transaction {
+			try {
+				removeColumn(table="orders", columnName="status");
+			} catch (any e) {
+				local.exception = e;
+			}
+
+			if (structKeyExists(local, "exception")) {
+				transaction action="rollback";
+				throw(
+					errorCode = "1",
+					detail    = local.exception.detail,
+					message   = local.exception.message,
+					type      = "any"
+				);
+			} else {
+				transaction action="commit";
+			}
+		}
+	}
+
+}

vendor/wheels/public/docs/reference/migration/dropforeignkey.txt

@@ -0,0 +1,13 @@
+// 1. Drop a foreign key constraint by its explicit name
+// In the down() function, remove a foreign key added in up()
+dropForeignKey(table="orders", keyName="FK_orders_customers");
+
+// 2. Drop a foreign key that was created via addReference()
+// addReference() creates keys named FK_<table>_<pluralizedReference>
+// So addReference(table="comments", referenceName="post") creates "FK_comments_posts"
+dropForeignKey(table="comments", keyName="FK_comments_posts");
+
+// 3. Use inside a migration's down() to reverse an addForeignKey() call
+// up() called: addForeignKey(table="profiles", referenceTable="users", column="userId", referenceColumn="id")
+// down() reverses it:
+dropForeignKey(table="profiles", keyName="FK_profiles_users");

vendor/wheels/public/docs/reference/migration/dropreference.txt

@@ -0,0 +1,18 @@
+// 1. Drop the foreign key from comments.postId back to posts.id
+// Removes the constraint named FK_comments_posts
+dropReference(table="comments", referenceName="post");
+
+// 2. Drop a foreign key from order_items back to orders
+// Removes the constraint named FK_order_items_orders
+dropReference(table="order_items", referenceName="order");
+
+// 3. Use dropReference in the down() of a migration that added a reference in up()
+// In your migration CFC:
+//
+// public void function up() {
+//     addReference(table="comments", referenceName="post");
+// }
+//
+// public void function down() {
+//     dropReference(table="comments", referenceName="post");
+// }