Scheduled jobs

Run schema syncs and tests on a schedule, with jobs in kater.config.yaml and one system cron line.

Audience

Platform admins

Prerequisites

A server account that runs Kater over the content root
A warehouse credential that signs in without a browser

Scheduled jobs keep your datasets in step with the warehouse and run your tests after every sync, so restated data shows up as a failing test before anyone reads a wrong number. You declare jobs in kater.config.yaml at the content root. System cron runs them through one kater job tick line.

Declare jobs

This is ShopTech’s file. It syncs the Snowflake connection at 02:00 UTC, then runs every test right after the sync succeeds.

1
jobs:
2
  sync_snowflake:
3
    command: kater sync
4
    connection: snowflake_prod_connection
5
    deployment: production
6
    schedule:
7
      enabled: false
8
      cron: "0 2 * * *" # Example: daily at 02:00 UTC. Choose a time after warehouse loads.
9
      timezone: UTC
10
  # Runs every test of the connection right after sync_snowflake succeeds, so data
11
  # restated upstream shows as failing tests in the header bell. No schedule of its own.
12
  test_snowflake:
13
    command: kater test
14
    connection: snowflake_prod_connection
15
    deployment: production
16
    after: sync_snowflake

Turn the schedule on

A schedule is off until enabled is true.

Key	What it does	Example
`command`	`kater sync` syncs the connection’s datasets. `kater test` runs every test of the connection’s shared layer and connection workspaces.	`kater sync`
`connection`	The connection the job runs on	`snowflake_prod_connection`
`deployment`	The deployment that runs it. A runner runs only its own deployment’s jobs. The default is `production`.	`production`
`schedule.cron`	When it runs, as a five-field cron expression	`"0 2 * * *"`
`schedule.timezone`	Always UTC	`UTC`
`schedule.enabled`	Whether the schedule runs. The default is false.	`true`
`after`	Run right after this job succeeds	`sync_snowflake`

One trigger. Give a job a schedule or an after, not both.
One job per command. Define one job per command, connection and deployment.
Chains end in a schedule. A job runs after a job of its own deployment and connection. A loop of after jobs is refused.
Plain cron. Use five fields with no H or R.
No browser sign-in. A job fails when its warehouse credential needs a person to sign in. Use a key pair or a password.
Test results reach the bell. A failing test run shows in the header bell. A passing run clears it.

Run jobs with cron

Print the cron line.

In the content root on the server, run kater job crontab --kater-root . --deployment production. It prints the line and never installs it.
Install it.

Add the line to the crontab of the account that runs Kater. It calls kater job tick once a minute, which runs the jobs due that minute and any still queued.
Add secrets, if you need to.

Pass --env-file with a dotenv file the deployment owns. Variables already in the environment win.

# Kater deployment jobs: UTC schedules are evaluated by the runner.
# Requires a configured trusted administrator identity in the runner environment.
* * * * * cd /srv/kater-content && /srv/kater/.venv/bin/python -m kater_cli job tick --kater-root /srv/kater-content --deployment production --json

The paths in your line are your own.

Check and run by hand

Command	What it does
`kater job list --kater-root . --deployment production`	List the deployment’s jobs, next runs and last runs.
`kater job run sync_snowflake --kater-root . --deployment production`	Run one job now, then the jobs set to follow it.
`kater job history --kater-root . --deployment production`	List earlier job runs, newest first. Add `--job` or `--limit`.
`kater logs job 0f3c9a6e2b8d4f17a5c1e9b04d72a6c3 --kater-root . --deployment production`	Show one job run’s result.

Run these in the content root on the server. Every kater job command needs --kater-root, and does not use a saved scope. Agents and the Files terminal refuse the job group.

Check it worked

kater job list shows a next run for each enabled job.
kater job history shows a run after the scheduled minute.
kater sync status shows when each dataset sync last succeeded.

Result cache settings

kater.config.yaml also holds cache, which sets how long Kater uses and keeps query results. See cache.

Next steps

kater.config.yaml: every key the file takes
Connections and schema sync
Tests