Migrations That Survive a Team: the Wheels 4.0 Migrator

[bpamiri]

Next in the post-GA how-to series. We've done the model side, the AI surface, and the extension model — this one takes the migrator and answers the question that comes up the moment a second person clones the repo: how do you write migrations that don't fall apart on someone else's checkout against a shared dev database?

Read: https://blog.wheels.dev/posts/migrations-that-survive-a-team

This is a broad, worked how-to rather than a release post — write a migration, drive the table builder, seed data, run the CLI, reconcile drift. It covers:

• The shape of a migration — a Migration.cfc under app/migrator/migrations/ with up()/down(), the 3–14-digit version filename regex (and the fact that non-matching files are silently ignored — no error, no listing, no run).
• The builder is lazy — createTable() returns an in-memory TableDefinition. Chaining t.string(...), t.references(...), t.timestamps(...) runs no DDL. The CREATE TABLE only fires on the terminal t.create() (or t.change() for the changeTable() path). Forget the terminal call and the migration "succeeds" with no table and still records itself applied — the single most common silent footgun in the whole subsystem.
• One argument convention — every column helper prefers columnNames (plural), and most accept a comma-list (t.string(columnNames="title,slug")) to add several columns at once. The singular columnName is an alias. primaryKey() is the deliberate exception: it never splits on commas, so a composite key means calling it once per column.
• timestamps() adds THREE columns — createdAt, updatedAt, AND deletedAt (the soft-delete marker), named from the framework's timestamp/soft-delete settings. The post is explicit about not hand-rolling those three.
• references() and the suffix flag — builds the FK column plus a constraint to the pluralized table's id, but the column name (authorid vs author_id) is governed by useUnderscoreReferenceColumns, read at runtime per migration. Framework default is false; wheels new apps default it to true. Same migration code, different column names across apps — worth knowing when you copy a migration between projects.
• Seeding with inline SQL — execute() takes ONLY a sql string. There is no parameters argument; a binding array would just be ignored. Use inline SQL with NOW() for portable dates, and addRecord()/updateRecord() when you genuinely need parameterized inserts.
• Transactional execution — each migration's up()/down() runs in its own transaction. On failure, that one rolls back and the loop stops, so you're never left half-applied with a tracking table that lies. "I ran migrate latest and only some applied" almost always means an earlier one failed.
• The team-survival commands — migrate info flags orphan tracking rows (a version with no matching file — the classic shared-DB case) with [?]; migrate doctor is a pure-read health report (orphans, pending, applied, a one-line summary, healthy iff zero orphans and zero pending); and migrate forget/pretend --yes reconcile, each with a guard that refuses the wrong move (forget won't run if a matching file exists — use migrate down for that; pretend won't run if there's no file or it's already applied).

The shared-database reconciliation story has its own deep treatment in the 4.0.2 release notes, so this post deliberately treats it as one section and points there for the full arc — here it's the get-started-and-stay-out-of-trouble version.

Discussion

A couple of things I'd genuinely like input on:

• Is the lazy-builder model (build columns → call .create()) the right ergonomic tradeoff, or would an auto-commit-on-scope-exit feel safer for newcomers? The current design buys you one assembled statement with all columns and FKs, but the mandatory terminal call clearly surprises people.
• For shared dev databases specifically — has the orphan/doctor/forget/pretend workflow matched how your team actually hits drift, or are there scenarios it doesn't cover yet?

Feedback on the post — what's unclear, what's missing, what you'd want a future migrator post to dig into — welcome in this thread.