Skip to content

Commit c7a3516

Browse files
bpamiriclaude
andauthored
docs: propagate schema_migrations → wheels_migrator_versions rename to sibling v4 docs (#2801)
Carryover from PR #2799. Commit eacf4f6 fixed three stale references in v4-0-0/basics/migrations.mdx; the same family of references still appeared in three siblings and is fixed here in one pass: - v4-0-0/basics/seeding.mdx:26 - v4-0-1-snapshot/basics/migrations.mdx:28,36,49 - v4-0-1-snapshot/basics/seeding.mdx:26 The on-disk table has been wheels_migrator_versions since the c_o_r_e_* → wheels_* rename; no schema_migrations table exists anywhere in vendor/wheels/, cli/, or app/. The line-49 fix in v4-0-1-snapshot/basics/migrations.mdx also mirrors the "keys on the filename" → "keys on the timestamp prefix" wording fix from eacf4f6, since the tracking table stores only the timestamp version (e.g., 20260420143000), not the full filename. v3-0-0/command-line-tools/cli-guides/migrations.md:632-633 intentionally left as-is: v3 used a different table name pre-rename, so the references are historical and accurate. Verified: \`grep -rn schema_migrations web/sites/guides/src/content/docs/v4-0-0 web/sites/guides/src/content/docs/v4-0-1-snapshot\` now returns zero matches. Refs #2780, #2798, #2799 Signed-off-by: Peter Amiri <peter@alurium.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent a96b02f commit c7a3516

3 files changed

Lines changed: 5 additions & 5 deletions

File tree

web/sites/guides/src/content/docs/v4-0-0/basics/seeding.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Seeds are the records your app can't live without — system roles, feature flag
2323

2424
## Why seeds — and not migrations
2525

26-
Seeds are idempotent. You can run them on a brand-new database, on a database that already has most of the records, or on one that has all of them — the outcome is the same and nothing breaks. Migrations are the opposite: each one runs exactly once per database, carries the schema forward, and lands a permanent row in `schema_migrations`. Edit a migration that's already been applied in production and the edit never runs.
26+
Seeds are idempotent. You can run them on a brand-new database, on a database that already has most of the records, or on one that has all of them — the outcome is the same and nothing breaks. Migrations are the opposite: each one runs exactly once per database, carries the schema forward, and lands a permanent row in `wheels_migrator_versions`. Edit a migration that's already been applied in production and the edit never runs.
2727

2828
Mix those responsibilities and you get drift. A row inserted by a migration on Tuesday can't be updated by re-running the migration on Thursday; you need a second migration for that. A row inserted by `seedOnce()` in `seeds.cfm` can be changed by editing the seed file and re-running — or left alone if it's already there. Production data that should exist on every deployment (system roles, feature flags, tenant defaults, lookup tables) belongs in seeds. Schema changes belong in migrations.
2929

web/sites/guides/src/content/docs/v4-0-1-snapshot/basics/migrations.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,15 @@ Migrations are versioned CFCs that carry your schema forward and back. Each one
2525

2626
## Running migrations
2727

28-
Four subcommands cover the day-to-day workflow. Each one connects to your app's datasource and reads the migration history out of `schema_migrations`, so the app has to be running (or at least reachable) for them to work — see [Installing Wheels](/v4-0-1-snapshot/start-here/installing/) for the server setup.
28+
Four subcommands cover the day-to-day workflow. Each one connects to your app's datasource and reads the migration history out of `wheels_migrator_versions`, so the app has to be running (or at least reachable) for them to work — see [Installing Wheels](/v4-0-1-snapshot/start-here/installing/) for the server setup.
2929

3030
```bash {test:cli cmd="wheels --version" asserts-stdout="Wheels"}
3131
wheels --version
3232
```
3333

3434
- `wheels migrate latest` — apply every pending migration in order. The most common command; you'll run it after pulling someone else's changes.
3535
- `wheels migrate up` — apply exactly one pending migration. Useful when you want to watch the effect of a single file.
36-
- `wheels migrate down` — roll back the most recently applied migration. Runs the `down()` method of the newest row in `schema_migrations`.
36+
- `wheels migrate down` — roll back the most recently applied migration. Runs the `down()` method of the newest row in `wheels_migrator_versions`.
3737
- `wheels migrate info` — show which migrations have run and which are still pending. Read-only; safe any time.
3838

3939
The runner wraps each migration in a transaction so a failing `up()` or `down()` rolls back cleanly — the schema either moves fully or not at all.
@@ -46,7 +46,7 @@ The generator scaffolds a CFC with `up()` and `down()` stubs and drops it in `ap
4646
wheels generate migration CreatePosts
4747
```
4848

49-
That produces a file named like `20260420143000_create_posts_table.cfc`. The prefix is `YYYYMMDDHHMMSS` — generated from the clock at creation time — and the runner applies migrations in filename order, so the timestamp is what puts your change after everyone else's. Never rename or reorder migration files after they've been committed: the history in `schema_migrations` keys on the filename, and a renamed file looks like a brand-new migration to the runner.
49+
That produces a file named like `20260420143000_create_posts_table.cfc`. The prefix is `YYYYMMDDHHMMSS` — generated from the clock at creation time — and the runner applies migrations in filename order, so the timestamp is what puts your change after everyone else's. Never rename or reorder migration files after they've been committed: the history in `wheels_migrator_versions` keys on the timestamp prefix, and a renamed file looks like a brand-new migration to the runner.
5050

5151
## Writing a migration — full example
5252

web/sites/guides/src/content/docs/v4-0-1-snapshot/basics/seeding.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Seeds are the records your app can't live without — system roles, feature flag
2323

2424
## Why seeds — and not migrations
2525

26-
Seeds are idempotent. You can run them on a brand-new database, on a database that already has most of the records, or on one that has all of them — the outcome is the same and nothing breaks. Migrations are the opposite: each one runs exactly once per database, carries the schema forward, and lands a permanent row in `schema_migrations`. Edit a migration that's already been applied in production and the edit never runs.
26+
Seeds are idempotent. You can run them on a brand-new database, on a database that already has most of the records, or on one that has all of them — the outcome is the same and nothing breaks. Migrations are the opposite: each one runs exactly once per database, carries the schema forward, and lands a permanent row in `wheels_migrator_versions`. Edit a migration that's already been applied in production and the edit never runs.
2727

2828
Mix those responsibilities and you get drift. A row inserted by a migration on Tuesday can't be updated by re-running the migration on Thursday; you need a second migration for that. A row inserted by `seedOnce()` in `seeds.cfm` can be changed by editing the seed file and re-running — or left alone if it's already there. Production data that should exist on every deployment (system roles, feature flags, tenant defaults, lookup tables) belongs in seeds. Schema changes belong in migrations.
2929

0 commit comments

Comments
 (0)