A tiny Rails engine that runs one-off data tasks exactly once — the way
db:migrate runs schema migrations exactly once — safely across any number
of concurrent deploy machines.
Three moving pieces:
Onetimer::Task(app/models/onetimer/task.rb) — anActiveRecordmodel backed by theonetimer_taskstable. One row per task, trackingname,status(running/completed),started_at,finished_at. A unique index onnameis what makes the whole thing safe.Onetimer::Runner(lib/onetimer/runner.rb) — the engine. It scansOnetimer.tasks_dirfor*.rbfiles, and for each one:- Skips it if a
completedrow already exists for that file's name. - Claims the task by inserting a
runningrow. Two processes racing to claim the same task hit the unique index — only oneINSERTsucceeds, so only one process actually runs it. requires the file, instantiatesOneTimers::<ClassName>, calls#run.- Marks the row
completedon success, or destroys the row and re-raises on failure (so a fixed version of the task can be retried on the next deploy).
- Skips it if a
Onetimer::Engine(lib/onetimer/engine.rb) — a standard Rails engine (isolate_namespace Onetimer) that wires upconfig.onetimerand loads the rake tasks.
There's no scheduler, no background worker, and no polling — Runner does
its work synchronously when invoked, exactly like rails db:migrate.
lib/one_timers/20260115120000_backfill_something.rb
│
▼
Runner.run_pending! ──> claim row in onetimer_tasks (unique on name)
│ │
│ won by one process
▼ ▼
require + OneTimers::BackfillSomething.new.run
│
▼
mark row completed (or destroy row + raise on error)# Gemfile
gem "onetimer"bundle install
bin/rails generate onetimer:install
bin/rails db:migrateThe generator (lib/generators/onetimer/install/install_generator.rb)
creates:
- a migration for the
onetimer_taskstable - an empty
lib/one_timers/directory
Generate a task:
bin/rake onetimer:new NAME=backfill_somethingThis writes lib/one_timers/<timestamp>_backfill_something.rb:
module OneTimers
class BackfillSomething
def run
# One-time task logic goes here.
end
end
endThe class name is derived from the filename minus the leading timestamp
(<timestamp>_backfill_something.rb → OneTimers::BackfillSomething), so
don't rename the file after generating it without also renaming the class.
Run everything pending:
bin/rake onetimer:runIdempotent — already-completed tasks are skipped. Wire it into your
deploy entrypoint right alongside db:migrate.
Verify the onetimer_tasks table has the required unique index on :name
(recommended in CI or right before a deploy):
bin/rake onetimer:doctorList what would run without running it:
bin/rake onetimer:pendingTwo settings, set in an initializer:
# config/initializers/onetimer.rb
Rails.application.config.onetimer.tasks_dir = Rails.root.join("lib/data_tasks")
Rails.application.config.onetimer.record_failures = truetasks_dir defaults to Rails.root.join("lib/one_timers")
(lib/onetimer/engine.rb).
record_failures defaults to false: a failed task's row is destroyed so
it retries on the next deploy. Set it to true to instead keep the row
marked failed with error_message set. Existing apps must add that
column first (add_column :onetimer_tasks, :error_message, :text) — if
record_failures is enabled without it, Runner logs a warning and falls
back to destroying the row.
There's currently no config for things like a custom table name — Task
hardcodes the onetimer_tasks table.
Onetimer::Task is a plain ActiveRecord model using only standard column
types (string, datetime, timestamps) and a unique index — nothing
Postgres/MySQL/SQLite-specific. It works on any database Rails/
ActiveRecord supports: PostgreSQL, MySQL/MariaDB, SQLite, and anything
else with a working AR adapter. The only real requirement is that unique
index enforcement works (true for all mainstream adapters), since that's
what prevents two deploy machines from double-running a task.
Known sharp edges when using Onetimer. Each entry links to a GitHub issue for discussion and possible fixes.
See also docs/GUIDE.md.
Renaming a task file after it ran is a no-op the second time, but a disaster if done before it runs on every machine. The task's identity is its filename (minus timestamp). Renaming after some machines have run it but before others have will cause it to run twice under two different names.
By default a failed task's row is still destroyed, not marked failed —
that's intentional, it lets you fix the task and retry on the next deploy.
Opt into keeping a persistent failed row with the error message via
Onetimer.record_failures (see Configuration); without
that opt-in, check Rails.logger output at deploy time.
Editing a task file after it is marked completed does nothing.
Runner only checks the filename, never the file contents or checksum.
Once completed, that name is permanently skipped — write a new task
file instead of editing an old one.
Concurrency safety depends entirely on the unique index on name. If
you hand-roll the migration instead of using the generator and forget
add_index :onetimer_tasks, :name, unique: true, two concurrent deploy
machines can both run the same task. Run bin/rake onetimer:doctor in CI
or before a deploy to catch this — see Running tasks.
bin/rake onetimer:run executes pending tasks immediately — it doesn't
support a dry-run flag. Use bin/rake onetimer:pending to list what would
run without running it; see Running tasks.
Tasks run in filename order (Dir.glob(...).sort), which is why the
generator prefixes files with a timestamp — do not break that ordering
by renaming files to remove or reorder the timestamp.