logo
Shipmate
Index
Cloud service

Cron job

A cron job is a time-based scheduling mechanism you can attach to your service. It allows you to automate the execution of CLI commands at predefined intervals. Cron jobs are commonly used for recurring tasks like database cleanups or batch processing.

Configuration as code

To configure a cron job in your code editor, use the following variables in the service's configuration as code file.

Example

# service: ...

cron_jobs:
  - name: backup
    schedule: '0 * * * *'
    command: php backup-database.php

Variables

name
required
string

The name of the cron job must use snake_case notation. In addition, cron jobs within a service cannot share the same name.

schedule
required
string

The schedule that defines when the cron job is executed. It consists of five fields representing the time and date when the job should run.

* * * * *
| | | | |
| | | | +----- Day of the week (0 - 7) (Sunday = 0 or 7)
| | | +------- Month (1 - 12)
| | +--------- Day of the month (1 - 31)
| +----------- Hour (0 - 23)
+------------- Minute (0 - 59)

Each field can be:

  • a specific number (1)
  • a list of numbers (1,4)
  • a range of numbers (1-4)
  • an asterisk *, which means any

The combination of these fields allows for a wide range of scheduling options. Some examples:

  • * * * * * -> Every minute
  • 45 23 * * 6 -> Every Saturday at 23:45 (11:45 PM)
  • 0 9 * * 1,4 -> Every Monday and Thursday at 09:00 (9:00 AM)
  • 0 10,22 * * 1-5 -> Every weekday (Mon-Fri) at 10:00 (10:00 AM) and 22:00 (10:00 PM)
default: * * * * *
command
required
string

The CLI command to execute.

Example:

  • php backup_database.php
timezone
required
string

The timezone that is used to evaluate the schedule.

For some timezones, daylight saving can cause cron jobs to run or not run unexpectedly. When a time occurs twice (such as when clocks go backward), a cron job might observe execution anomalies. If your cron job requires a specific cadence, consider choosing a timezone that does not observe daylight saving time, like UTC.

Examples:

  • Etc/UTC
  • Europe/Brussels
  • America/New_York
  • Asia/Shanghai
default: Etc/UTC
retries
required
integer

The number of times the execution of the cron job is automatically retried after a failure.

minimum: 0
maximum: 5
default: 0
timeout
required
string

The number of seconds after which the execution of the cron job times out.

default: 30
deadline
optional
string

If the execution of the cron job doesn't complete within this timeframe, the execution is marked as failed. The deadline must be a duration in seconds, terminated by an s.

minimum: 15s
maximum: 1800s
LaravelJob queue