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
shopproject from Build a Go and React app with Connect RPC. Any Forge project withdb/migrationsworks. - Forge v1.6 or later. Inside Reliant, run it as
reliant forge, and check the version withreliant forge --versioninside 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)
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 Before a tick runs,
generate reads it back from there:internal/workers/digest/worker.go
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
cron worker started WITHOUT tick claims. That warning is expected here.5
Watch it tick locally
Start the stack with The count dropped after a product was archived between the two ticks. The claims are rows you can query:cronkit creates this table on first use and prunes rows older than a day. Stop the stack with
reliant forge env up dev, then read the API log. The worker runs inside the api process:terminal
Output (trimmed)
terminal
reliant forge env down dev.6
Check what production deploys
terminal
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:This sandbox project kept the scaffold’s default
terminal
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"indeploy/kclbecomes a Kubernetes CronJob, and Reliant hosting does not run those yet. Binding one toforge.OnHostedfails the render withcron 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
Runmust never overlap itself, hold apkg/leaselease 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
cron worker started WITHOUT tick claims: every replica fires every tick
cron worker started WITHOUT tick claims: every replica fires every tick
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.workload 'digest' cannot run on the hosted runtime: schedule: cron is not available on hosted until metering covers it
workload 'digest' cannot run on the hosted runtime: schedule: cron is not available on hosted until metering covers it
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