Jobs
What it is
nodabase.jobs schedules HTTP requests that run on a schedule, managed from your Node.js application. A job is a name, a cron schedule and the HTTP request to make. Definitions live in PostgreSQL, and the Nodabase Job Runner executes them.
Nothing runs inside your application process. You write a definition through the client, it is stored in PostgreSQL, and the Job Runner picks it up from there.
How it works
Node.js application
|
v
nodabase.jobs
|
v
PostgreSQL
|
v
Job Runner
|
v
scheduled HTTP requestcreate() writes the definition to the jobs.jobs table. The Job Runner reads what is due, computes the next run from the schedule, makes the HTTP request to the configured URL, and records the attempt.
Configuration
Two variables together:
NODABASE_JOBS_ENABLED=trueDATABASE_URL=postgres://user:password@localhost:5432/mydb
NODABASE_JOBS_ENABLED must be the exact string true, and DATABASE_URL must be set — job definitions are stored in PostgreSQL, so the module needs the database client too. Only when both are present does nodabase.jobs appear on the client. Inside the Nodabase platform, both bindings are provided for you.
Basic usage
import { nodabase } from "nodabase";const job = await nodabase.jobs.create({name: "nightly-report",schedule: "0 3 * * *",request: { method: "POST", url: "http://app:3000/report" },});
The schedule is a cron expression — the familiar five-field format, with six-field expressions including seconds also accepted. The request is what the Job Runner will send: method defaults to "POST", url is required, and headers and body are optional.
create resolves to the stored job row:
job.id;job.name;job.schedule;job.method;job.url;job.headers;job.body;job.enabled; // true
Common operations
The whole surface at a glance:
| Method | Returns | Notes |
|---|---|---|
create({ name, schedule, request }) | the new job row | validates before insert |
get(id) | job row, or null | |
list() | all job rows, newest first | |
update(id, changes) | updated row, or null | partial — only what you pass changes |
delete(id) | true / false | true when a row was removed |
pause(id) | job row with enabled: false | |
resume(id) | job row with enabled: true |
Getting jobs
const job = await nodabase.jobs.get(jobId); // the row, or nullconst jobs = await nodabase.jobs.list(); // every job, created_at DESC
Updating
await nodabase.jobs.update(job.id, { schedule: "0 4 * * *" });
Updates are partial at every level: fields you leave out — including fields inside request — keep their current values. The same validation as create runs on any name, schedule or request you pass.
Pausing and resuming
await nodabase.jobs.pause(id); // enabled: false — the runner skips itawait nodabase.jobs.resume(id); // enabled: true
Deleting
await nodabase.jobs.delete(id); // true if it was there
The job row
| Fields | Written by |
|---|---|
name, schedule, method, url, headers, body, enabled | you, through the client |
id, created_at, updated_at | PostgreSQL |
last_run_at, last_run_status, next_run_at | the Job Runner |
Read the runner's columns whenever you want to see where a job stands — next_run_at tells you the next scheduled time, and last_run_status what happened on the previous run.
Important notes
- The request URL is resolved by the Job Runner, not by your application. In Docker it must be a service name on the shared network —
localhostpoints at the runner itself, not at your app. - Validation happens before anything is written:
nameandscheduleare required non-empty strings, andrequest.urlis required. Errors name the missing piece. - Job definitions live in
jobs.jobsand run history injob_runs; those tables belong to Nodabase, whilepublicis for your application's own tables. Run history is not part of the client API — the runner records every attempt injob_runsin PostgreSQL. - Without
NODABASE_JOBS_ENABLED=trueandDATABASE_URL,nodabase.jobsis absent from the client — the same pattern asdbandcache.
Next steps
- Queues — publishing and consuming through NATS
- Database — PostgreSQL through
nodabase.db - Overview — how the client and the services fit together
- Quickstart — run the platform