Skip to main content
You will add digest, a scheduled job that counts the active products in shop once a minute, and watch it run locally and on Reliant hosting. The worker runs inside your existing server process, so a schedule needs no new process, queue or Kubernetes object, and it claims each tick in your app’s Postgres, so each tick fires on one replica. reliant forge agent skill load workers is the full reference.

Before you begin

  • The shop project from Build a Go and React app with Connect RPC. Any Forge project with db/migrations works.
  • Forge v1.6 or later. Inside Reliant, run it as reliant forge, and check the version with reliant forge --version inside the project.
  • No account for the local steps. The hosted step needs a Reliant organization with hosting billing.
1

Scaffold the cron worker

--schedule takes a five-field cron expression. Every minute is useful for trying it out:
terminal
Output (trimmed)
It wrote internal/workers/digest/worker.go and worker_test.go, and added a newDigest constructor to internal/app/compose.go, which hands the worker its logger, config and database. No deploy file changed. Without --kind cron you get a plain long-running worker instead: a Start loop on a 30-second ticker for you to replace with a queue or event stream. A plain worker runs on every replica; wrap it in a pkg/lease singleton if only one may run at a time.
2

Read the schedule

The schedule is a constant in the worker. That constant is the only place it is declared, and generate reads it back from there:
internal/workers/digest/worker.go
Before a tick runs, cronkit.Postgres inserts the worker name and the tick’s scheduled time into forge_cron_ticks. The replica whose insert succeeds runs the tick; the others skip it. Set PerReplica = true only for work every pod must do.
3

Write the tick

Run is one tick. Pass ctx to every call so shutdown cancels it. A returned error is logged and the schedule carries on:
internal/workers/digest/worker.go
cronkit.TickTime is the scheduled time, the same on every replica: a good key for an idempotent write. DB is an optional dependency, hence the nil check.
4

Run the scaffolded test

terminal
The start-and-stop test builds the worker with no database, so it logs cron worker started WITHOUT tick claims. That warning is expected here.
5

Watch it tick locally

Start the stack with reliant forge env up dev, then read the API log. The worker runs inside the api process:
terminal
Output (trimmed)
The count dropped after a product was archived between the two ticks. The claims are rows you can query:
terminal
cronkit creates this table on first use and prunes rows older than a day. Stop the stack with reliant forge env down dev.
6

Check what production deploys

terminal
The list is the same as before the worker existed: digest ships inside the api workload, which is why it can run on Reliant hosting.
7

Deploy it and see the ticks hosted

Build a release and promote it, as in Deploy a Go API with managed Postgres:
terminal
This sandbox project kept the scaffold’s default Run, which logs cron job executing. The hosted database holds the claims, so the boot log has no WITHOUT tick claims warning.
8

Set the real schedule

Change the constant, for example to const Schedule = "0 8 * * *" for 08:00 every day, and redeploy. The worker’s name is its claim key, so renaming the worker starts a fresh claim history.

What this does not do

  • No hosted cron-kind workloads. A workload declared with kind = "cron" in deploy/kcl becomes a Kubernetes CronJob, and Reliant hosting does not run those yet. Binding one to forge.OnHosted fails the render with cron is not available on hosted until metering covers it. Bind it to a cluster you run, or use a cron worker as in this guide, which runs hosted.
  • No catch-up. Each tick runs at most once. If the replica that claimed a tick crashes mid-run, that tick is lost, and ticks missed while the app was down are not replayed.
  • No overlap guard across replicas. Ticks on one replica never overlap, but a slow tick on one replica can still be running when the next tick starts on another. If Run must never overlap itself, hold a pkg/lease lease inside it (reliant forge project libraries lease).
  • No database, no claims. Without a database every replica fires every tick, and the worker logs a warning at start.

Troubleshooting

The worker got no database: the project has no db/migrations, or the process started without DATABASE_URL. Give it one, or set PerReplica = true if every replica should run each tick.
A kind = "cron" workload is bound to forge.OnHosted in an env’s main.k. Remove that workload and use the scaffolded cron worker, or bind the workload to a cluster you run.

Next steps

Add a custom RPC

Write a Connect RPC handler and call it through a typed hook

Add a table

Generate the CRUD API and pages for a new entity

Deploy a Go API

Ship the API, its workers and Postgres to Reliant hosting

Hosting overview

What hosting runs, and what it does not run yet