Skip to content

Upgrading

TaskQ's schema migrations are forward-only by design. There is no down migration mechanism and none is planned — this section explains why, and what to do if you need to undo a change.

Forward-only migration policy

The migration runner (taskq.migrate) discovers *.sql files bundled under taskq.migrations in lexicographic order ({ver}_{nn}_{pre|post}_{description}.sql), applies any not already recorded in {schema}.schema_migrations, and records a SHA-256 checksum of the rendered SQL after each successful apply.

There is no down operation. To revert a migration, restore the database from a backup taken before it was applied.

This is a deliberate tradeoff, not a missing feature:

  • Down migrations are rarely exercised in practice and rot quietly until the one time they're needed — at which point they often don't work.
  • A schema rollback that isn't paired with a data rollback (e.g., a dropped column that already lost data) is not actually safe to run automatically.
  • Point-in-time recovery / backup restore is the operation you actually want for "undo a bad deploy" in a durable job queue, since job state itself needs to roll back together with the schema.

Before upgrading TaskQ

  1. Take a backup. Since there is no automated rollback, a recent backup (or PITR window) is your only revert path.
  2. Check the Changelog for the target version — TaskQ is pre-1.0 (see the Stability note in the README), so breaking changes, including schema changes, may land in minor version bumps (0.x.0), not only majors.
  3. Review pending migrations before applying them:
taskq migrate status

This lists every discovered migration and whether it has already been applied, without changing anything.

  1. Apply migrations explicitly, or let the worker apply them at startup via TASKQ_MIGRATE_ON_START=true:
taskq migrate up

The command is idempotent — migrations already recorded in {schema}.schema_migrations are skipped. See cli.md for the full option reference (--phase, --target, --max-steps).

If a migration goes wrong

  • Stop workers pointed at the affected schema to avoid further writes.
  • Restore the database from the pre-migration backup.
  • Pin taskq-py back to the previous version until the issue is resolved, since the previous version's code may not be compatible with the new schema.