Skip to content

scheduling.md

Latest commit

 

History

History
126 lines (89 loc) · 4.17 KB

scheduling.md

File metadata and controls

126 lines (89 loc) · 4.17 KB
Raw

Backup Scheduling

mysql-backup can be run either once, doing a backup and exiting, or as a long-running task, backing up on schedule.

There are several options for scheduling how often a backup should run:

  • run just once and exit.
  • run every x minutes, optionally delaying the first one by a certain amount of time
  • run on a schedule.

Order of Priority

The scheduling options have an order of priority:

  1. If run once is set, it will run immediately and exit, ignoring all other scheduling options.
  2. If cron is set, it runs according to the cron schedule, ignoring frequency and delayed start.
  3. Frequency and optionally delayed start are used.

Scheduling Options

Run once

You can set it to run just once via:

  • Environment variable: DB_DUMP_ONCE=true
  • CLI flag: dump --once
  • Config file:
dump:
    schedule:
        once: true

If you set it to run just once, the backup will run once and then exit.

This overrides all other scheduling options.

This is useful for one-offs, or if mysql-backup is being run via an external scheduler, such as cron or kubernetes cron jobs, and thus don't want mysql-backup to do the scheduling internally.

Cron Scheduling

You can set a cron schedule via:

  • Environment variable: DB_DUMP_CRON=0 * * * *
  • CLI flag: dump --cron="0 * * * *"
  • Config file:
dump:
    schedule:
        cron: 0 * * * *

The cron dump schedule option uses standard crontab syntax, a single line.

When cron is configured, mysql-backup waits for the next matching cron time. It does not run an immediate startup backup and it ignores the frequency and delayed start options.

If a cron-scheduled backup takes longer than the beginning of the next backup window, it will be skipped. For example, if your cron line is scheduled to backup every hour, and the backup that runs at 13:00 finishes at 14:05, the next backup will not be immediate, but rather at 15:00.

Note: cron will be evaluated in UTC zero time zone by default.

If you want to evaluate in a specific time zone, provide it as part of the cron terminology in the configuration as CRON_TZ= , for example, to set it to America/Anchorage:

dump:
    schedule:
        cron: CRON_TZ=America/Anchorage 0 * * * *

You can obtain your local timezone via cat /etc/timezone.

Frequency and Delayed Start

If neither run once nor cron is set, then mysql-backup will use the frequency and optional delayed start options.

The frequency value is in minutes. Thus, you can set backup to run every hour by setting the frequency to 60. For a relative delayed start, prefix the number of minutes with +; for example, +120 delays the first backup by 2 hours.

An absolute delayed start uses a four-digit 24-hour time followed by its timezone:

  • 0400Z means 04:00 UTC.
  • 0400+08:00 means 04:00 at a fixed UTC+08:00 offset.
  • 0400@local means 04:00 in the timezone of the computer or container. The local timezone is obtained from the TZ environment variable or the platform timezone configuration.
  • 0400@America/New_York means 04:00 in the named IANA timezone, including daylight-saving rules.

A zoneless value such as 0400 continues to mean UTC for compatibility with existing deployments, but is considered legacy. Prefer an explicit Z, offset, @local, or IANA timezone.

You can set the frequency start via:

  • Environment variable: DB_DUMP_FREQUENCY=60
  • CLI flag: dump --frequency=60
  • Config file:
dump:
    schedule:
        frequency: 60

You can set the delayed start via:

  • Environment variable: DB_DUMP_BEGIN=+120
  • CLI flag: dump --begin=+120
  • Config file:
dump:
    schedule:
        begin: "+120"

For example, to begin at the next 04:00 in New York:

mysql-backup dump --frequency=1440 --begin=0400@America/New_York

begin determines the first run. Later runs use the configured frequency as an elapsed number of minutes. Consequently, a frequency of 1440 may shift by one local hour after a daylight-saving transition; use a timezone-aware cron schedule when every run must remain at the same local time.