Cron jobs

A job runs a command inside a running container on a cron schedule. Every job belongs to one target, an app or a database, and targetKind names which ("app" or "database"). Runs and their output are gated on manage_crons, not on view: stdout can carry whatever the command printed.

Reading

appCronJobs

Needs manage_crons. Returns CronJobsView.

An app's cron jobs, its master switch and its pickable services.

query {
  appCronJobs(appId: "prj_9f1c2ab7d3e4f5a6") {
    enabled
    services
    jobs {
      id
      name
      schedule
    }
  }
}

databaseCronJobs

Needs manage_crons. Returns CronJobsView.

A database's cron jobs and its master switch.

query {
  databaseCronJobs(databaseId: "db_9f1c2ab7d3e4f5a6") {
    enabled
    services
    jobs {
      id
      name
      schedule
    }
  }
}

cronRuns

Needs manage_crons. Returns [CronRun!].

One job's run history, newest first. Gated on manage_crons and not on view: stdout can carry whatever the command printed.

query {
  cronRuns(jobId: "cron_9f1c2ab7d3e4f5a6") {
    id
    status
    exitCode
    startedAt
  }
}

Jobs

createCronJob

Needs manage_crons. Returns CronJob.

Add a job to an app or a database. targetKind is app or database.

mutation {
  createCronJob(
    targetKind: "app"
    targetId: "prj_9f1c2ab7d3e4f5a6"
    input: { name: "nightly-report", schedule: "0 3 * * *", command: "node scripts/report.js", timezone: "Europe/Rome" }
  ) {
    id
    name
    nextRunAt
  }
}

updateCronJob

Needs manage_crons. Returns CronJob.

Edit a job. Every omitted field is left as it is.

mutation {
  updateCronJob(
    id: "cron_9f1c2ab7d3e4f5a6"
    input: { name: "nightly-report", schedule: "0 3 * * *", command: "node scripts/report.js", timezone: "Europe/Rome" }
  ) {
    id
    name
    schedule
    enabled
    nextRunAt
  }
}

deleteCronJob

Needs manage_crons. Returns Boolean.

Delete a job and its run history.

mutation {
  deleteCronJob(id: "cron_9f1c2ab7d3e4f5a6")
}

setCronEnabled

Needs manage_crons. Returns Boolean.

Turn cron jobs on or off for one target. Off stops the schedule and keeps the jobs; runs already in flight are left to finish.

mutation {
  setCronEnabled(targetKind: "app", targetId: "prj_9f1c2ab7d3e4f5a6", enabled: false)
}

Runs

runCronJobNow

Needs manage_crons. Returns CronRun.

Run a job now, outside its schedule. Honours the overlap setting: while a run is in flight, a job set to skip answers with a skipped run.

mutation {
  runCronJobNow(id: "brun_9f1c2ab7d3e4f5a6") {
    id
    status
    exitCode
    startedAt
  }
}

cancelCronRun

Needs manage_crons. Returns Boolean.

Stop a run that is in flight.

mutation {
  cancelCronRun(id: "brun_9f1c2ab7d3e4f5a6")
}

See also