Schedules

A schedule connects a project source to a project worker, describes the backup format, and defines the gates that determine whether a restore check succeeds.

Create a schedule

Choose:

• a worker_id and source.id from the same project
• db_type: file, postgresql, mysql, mariadb, or mongodb
• a five-field cron expression and schedule_mode: hourly, daily, or weekly
• source path and file-selection rules: path is a folder relative to the source (only files directly in it count; date variables allowed, wildcards only in filename_pattern)
• at least one validation gate for a database schedule
• notify_mode: never, always, or on-error

scratch_size_gi is required: a whole number of GiB from 1 to 9313, the size of each restore's scratch volume. PATCH cannot clear it. A schedule saved before the field became required may return null; its checks fail until a size is set. See Scratch storage.

A database schedule can set database_resources, the Kubernetes requests and limits of the restore's database container: cpu_request_millicores and cpu_limit_millicores (1 to 1,000,000), memory_request_mib and memory_limit_mib (1 to 16,777,216). Each is optional; omit the object, send null or {} to set none. A request must not exceed the limit of the same resource. PATCH replaces the whole object. File schedules reject non-empty values because they have no database container. See CPU and memory for workers and Jobs.

For example, a database schedule may include:

{  "database_resources": {    "cpu_request_millicores": 500,    "cpu_limit_millicores": 2000,    "memory_request_mib": 2048,    "memory_limit_mib": 4096  }}

This applies only to the temporary database container. There is no separate BestEffort flag: if all four values are empty, the restore Pod uses its default BestEffort resource behavior. PATCH with {"database_resources": null} clears the values for future checks. A check keeps the configuration snapshot made when it was dispatched, and older agents can ignore this newer setting. See CPU and memory for workers and Jobs before relying on resource limits.

Database schedules require an exact db_version from the database engine catalog. File schedules use an empty gates list and do not use database restore parameters or backup-format layers.

Cron and time zone

cron is evaluated in UTC. A range in the minute field, such as 10-19 4 * * 1, is replaced by one minute chosen at random inside that range when the schedule is saved; the stored expression is what the API returns. next_run is the next planned UTC occurrence, or null while the schedule is paused or blocked. The check a run produces carries that occurrence as planned_run_at.

The console may display next_run in local time, but this does not change the UTC cron expression. See Time zones and dates for daylight-saving examples and date-variable behavior.

Backup decoding

source.backup_format has independent container, compression, and dump_format fields. auto asks the worker to detect a layer; an explicit value requires the backup to match it. SQL engines support plain SQL; MongoDB supports a packaged mongodump directory. See supported backup layouts.

source.encryption.mode is none, age, or age_passphrase. Encrypted modes require source.encryption.secret: {"id":"..."} referencing active metadata of the matching type. source.archive_password_secret: {"id":"..."} is available only for database backups whose container is auto or zip.

These fields belong inside the schedule's source object. On PATCH, source.backup_format and source.encryption merge one level deep. Setting either to null resets it to its defaults; setting source.encryption.mode to none clears its secret when no secret is supplied. Switching age modes requires a secret matching the new mode.

Gates and actions

Database gates can validate restore status, a query result, or the duration of a restore step. The API accepts up to 20 gates; names must be unique without regard to case, and a database schedule must retain at least one gate. Query gates take timeout_seconds (1 to 3600, default 300); every stored query gate carries the value that applies. MongoDB query gates use a typed mongo object instead of SQL query text.

Use the status action to pause or activate a schedule. A manual run queues a check and returns its ID. List filters support name, worker_id, status, and kind.

Count schedules without pagination

POST /v1/schedules/summary takes {"project_id":"..."} and requires v1.schedules:read. It returns data.total and data.by_status for all schedules in the project, independently of the list's page size or filters. For example:

{  "status": "success",  "data": {    "total": 12,    "by_status": { "active": 10, "paused": 2 }  }}

Missing or blank statuses count as unknown; zero-count buckets are omitted. A summary timeout returns 503.

Endpoint reference

• Create a schedule
• List schedules
• Summarize schedule statuses
• Get a schedule
• Update a schedule
• Set schedule status
• Start a manual run
• Remove a gate
• Delete a schedule

Required scopes are v1.schedules:read, v1.schedules:write, and v1.schedules:delete.