Wheels 4.2 adds recurring background jobs and one-at-a-time migrations

Wheels 4.2 is out, and a lot of it is for apps that run on more than one server. Jobs run on a schedule, models get callbacks that wait for the commit, and migrations take turns. Then come the breaking changes, and the upgrade.

Slide text

v4.2.0

Wheels 4.2 adds recurring background jobs and one-at-a-time migrations

config/schedules.cfm afterCommit migrate: true wheels jobs drain

Recurring jobs are defined in config/schedules.cfm. Each schedule names a job, then a cron expression with a time zone, or an interval such as every 15 minutes. Each due slot is enqueued once, however many servers check, and after downtime only the newest missed slot runs.

<cfscript>
schedule("digest")
  .job("DigestJob")
  .cron("0 7 * * MON")
  .timezone("America/New_York");

schedule("canary")
  .job("CanaryJob")
  .every(15, "minutes");
</cfscript>

Jobs also get controls for running on several servers. With a unique key, a duplicate enqueue writes nothing. An exclusive job can't start a second run anywhere while one is running. A long job can call heartbeat, so it isn't reclaimed and run twice. And wheels jobs drain with wait holds a deploy until the running jobs finish.

Models get two new callbacks. afterCommit runs only once the transaction commits, so it's where you enqueue a job or send mail. afterRollback runs when it rolls back. Both need a transaction that Wheels manages. And transaction savepoint lets a nested unit undo only its own writes.

afterCommit(methods="enqueueSearchIndex", on="create,update");
afterRollback("releaseReservation");

Instances that share a database now take turns migrating, under a lock. With wheels deploy, add migrate true to deploy.yml, and migrations run once per deploy, on one host. A failed one stops the deploy. If a lock gets stuck, wheels migrate unlock names the holder, and the force flag clears it.

migrate: true

$ wheels migrate unlock
$ wheels migrate unlock --force

The first breaking change: findAll with returnAs structs now returns an array, as documented, instead of a struct keyed by row number. StructCount, and loops over its keys, need to change. Use ArrayLen and loop over the rows. Indexing by position still works, and the result serializes to a JSON array.

StructCount(rows)
for (key in rows) { rows[key] }

ArrayLen(rows)
for (row in rows) { row }

Two more breaking changes involve the network. X-Forwarded-Proto now makes absolute URLs https only when trustProxyHeaders is on, so behind a proxy that handles TLS, set it before upgrading. And in wheels deploy, an accessory's port must name a bind address. A bare port now fails validation.

These changes can also affect existing code. An empty string in a where condition now matches stored empty strings, in updateAll and deleteAll too. A failed enqueue throws. Job timestamps move to UTC. And the dev server listens only on your own machine, unless you pass a host.

To upgrade, update the CLI first. Then wheels upgrade check, to 4.2.0, fails on the items that break at runtime on 4.2, and wheels upgrade apply swaps the framework, keeping a backup. App tests now need a separate test datasource. And if your job servers don't run on UTC, upgrade once the queue is empty.

$ brew upgrade wheels
$ wheels upgrade check --to=4.2.0
$ wheels upgrade apply