New post: Seeding Your Database the Idempotent Way

[bpamiri]

Seed data has the same shape in every app I've ever worked on: make sure this row exists; if it already does, leave it alone; do it the same way in every environment, every time, without blowing up on the second run. That property has a name — idempotency — and Wheels 4.0 ships a seeder built entirely around it.

Read: https://blog.wheels.dev/posts/idempotent-database-seeding

The whole post is a worked walkthrough of a surprisingly small surface: two file conventions and one helper function. Here's the shape of what it covers.

seedOnce()

The helper takes three named args — modelName, uniqueProperties (comma-delimited), and properties (the full struct). It builds a WHERE clause from the unique properties, calls findOne(), and creates the record only if nothing matches:

• match found → totalSkipped++, returns {model, action: "skipped", uniqueProperties}
• no match → model.new(properties).save(), returns {model, action: "created", key}
• validation failure → totalFailed++, returns {model, action: "failed", errors}

Run it once or a hundred times, you end up with exactly one admin role.

The file convention

app/db/seeds.cfm                <- runs first, in EVERY environment
app/db/seeds/development.cfm    <- runs after, environment-specific

seeds.cfm is shared (roles, settings, lookup tables). The environment file is a sibling seeds/ directory — seeds/development.cfm, not seeds-development.cfm. The hyphenated form is what the snippet template is named, and forgetting to rename it on the way into app/db/ is the easiest mistake to make.

The transaction is the interesting design call

The entire run — both files — is wrapped in one transaction. If any single seedOnce() entry fails validation, the whole run rolls back, including rows that already saved earlier in the same run, and returns success: false naming the failures.

This was deliberate (issue #2973). The alternative — commit what worked, report what didn't — was explicitly rejected, because a half-applied seed run must never look identical to a fully-applied one. And since seedOnce() is idempotent, recovery is trivial: fix the broken entry, re-run, everything that existed gets skipped and everything that didn't gets created.

CLI

wheels generate snippets seed-data      # scaffold (the ONLY scaffolder)
wheels seed                             # run (dev server must be running)
wheels seed --environment=production    # target an env

wheels seed runs over the dev-server bridge, so the server has to be up. --generate exists but is legacy random data — not idempotent, duplicates on repeat. And two non-commands to know: wheels db:seed and wheels generate seed both error. Use wheels seed and wheels generate snippets seed-data.

Sharp edges in the post

• It's a skip, never an upsert. seedOnce() checks existence and skips; it never updates an existing row.
• Every uniqueProperties name must be present in properties and be a simple value, or you get a specific thrown error.
• The unique-value WHERE is string-interpolated (quotes escaped), not parameter-bound — keep unique values simple.
• The result struct shape varies by action; result.key exists only on created.

Questions for the thread

• How are you handling seed data today — migrations, a hand-rolled script, the legacy --generate path? Curious how many people are still doing WHERE NOT EXISTS by hand.
• Does the rollback-on-any-failure behavior match your expectation, or would you have wanted commit-with-report? The reasoning in Seeder reports success and commits when individual seedOnce() entries failed #2973 is in the post; interested whether it holds up against real workflows.
• Anyone want an upsert mode (update-if-exists) as an opt-in alongside the skip-if-exists default? That's the one limitation people are most likely to hit.

Feedback on the post — what's unclear, what's missing — welcome here.