View Source Oban.Plugins.Cron (Oban v2.18.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 scheduling at runtime, globally, across an entire cluster with scheduling guarantees and timezone overrides, 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: [
    {Oban.Plugins.Cron,
     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}
     ]}
  ]

Options

: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.

Identifying Cron Jobs

Jobs inserted by the Cron plugin are marked with a cron flag and the original expression is stored as cron_expr in the job's meta field. For example, the meta for a @daily cron job would look like this:

%Oban.Job{meta: %{"cron" => true, "cron_expr" => "@daily"}}

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

Summary

Types

cron_input()

expression()

option()

Functions

parse(input)

Parse a crontab expression into a cron struct.

Types

cron_input()

@type cron_input() :: {binary(), module()} | {binary(), module(), [Oban.Job.option()]}

expression()

@opaque expression()

option()

@type option() ::
  Oban.Plugin.option()
  | {:crontab, [cron_input()]}
  | {:timezone, Calendar.time_zone()}

Functions

parse(input)

@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.

Nicknames

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

Examples

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"}}