View Source Oban.Plugins.Cron (Oban v2.15.0)

Periodically enqueue jobs through CRON based scheduling.

This plugin registers workers a cron-like schedule and enqueues jobs automatically. Periodic jobs are declared as a list of {cron, worker} or {cron, worker, options} tuples.

🌟 DynamicCron

This plugin only loads the crontab statically, at boot time. To configure cron schedules dynamically at runtime, across your entire cluster, see the DynamicCron plugin in Oban Pro.


Using the Plugin

Schedule various jobs using {expr, worker} and {expr, worker, opts} syntaxes:

config :my_app, Oban,
  plugins: [
     crontab: [
       {"* * * * *", MyApp.MinuteWorker},
       {"0 * * * *", MyApp.HourlyWorker, args: %{custom: "arg"}},
       {"0 0 * * *", MyApp.DailyWorker, max_attempts: 1},
       {"0 12 * * MON", MyApp.MondayWorker, queue: :scheduled, tags: ["mondays"]},
       {"@daily", MyApp.AnotherDailyWorker}



  • :crontab — a list of cron expressions that enqueue jobs on a periodic basis. See Periodic Jobs in the Oban module docs for syntax and details.

  • :timezone — which timezone to use when scheduling cron jobs. To use a timezone other than the default of "Etc/UTC" you must have a timezone database like tz installed and configured.


Instrumenting with Telemetry

The Oban.Plugins.Cron plugin adds the following metadata to the [:oban, :plugin, :stop] event:

  • :jobs - a list of jobs that were inserted into the database

Link to this section Summary


Returns a specification to start this module under a supervisor.

Parse a crontab expression into a cron struct.

Link to this section Types

@type cron_input() :: {binary(), module()} | {binary(), module(), [Oban.Job.option()]}
@opaque expression()
@type option() ::
  | {:crontab, [cron_input()]}
  | {:timezone, Calendar.time_zone()}

Link to this section Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec parse(input :: binary()) :: {:ok, expression()} | {:error, Exception.t()}

Parse a crontab expression into a cron struct.

This is provided as a convenience for validating and testing cron expressions. As such, the cron struct itself is opaque and the internals may change at any time.

The parser can handle common expressions that use minutes, hours, days, months and weekdays, along with ranges and steps. It also supports common extensions, also called nicknames.

Returns {:error, %ArgumentError{}} with a detailed error if the expression cannot be parsed.



The following special nicknames are supported in addition to standard cron expressions:

  • @yearly—Run once a year, "0 0 1 1 *"
  • @annually—Same as @yearly
  • @monthly—Run once a month, "0 0 1 "
  • @weekly—Run once a week, "0 0 0"
  • @daily—Run once a day, "0 0 *"
  • @midnight—Same as @daily
  • @hourly—Run once an hour, "0 "
  • @reboot—Run once at boot



iex> Oban.Plugins.Cron.parse("@hourly")
{:ok, #Oban.Cron.Expression<...>}

iex> Oban.Plugins.Cron.parse("0 * * * *")
{:ok, #Oban.Cron.Expression<...>}

iex> Oban.Plugins.Cron.parse("60 * * * *")
{:error, %ArgumentError{message: "expression field 60 is out of range 0..59"}}