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 request

create() 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:

env
NODABASE_JOBS_ENABLED=true
DATABASE_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

js
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:

js
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:

MethodReturnsNotes
create({ name, schedule, request })the new job rowvalidates before insert
get(id)job row, or null
list()all job rows, newest first
update(id, changes)updated row, or nullpartial — only what you pass changes
delete(id)true / falsetrue when a row was removed
pause(id)job row with enabled: false
resume(id)job row with enabled: true

Getting jobs

js
const job = await nodabase.jobs.get(jobId); // the row, or null
 
const jobs = await nodabase.jobs.list(); // every job, created_at DESC

Updating

js
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

js
await nodabase.jobs.pause(id); // enabled: false — the runner skips it
await nodabase.jobs.resume(id); // enabled: true

Deleting

js
await nodabase.jobs.delete(id); // true if it was there

The job row

FieldsWritten by
name, schedule, method, url, headers, body, enabledyou, through the client
id, created_at, updated_atPostgreSQL
last_run_at, last_run_status, next_run_atthe 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 — localhost points at the runner itself, not at your app.
  • Validation happens before anything is written: name and schedule are required non-empty strings, and request.url is required. Errors name the missing piece.
  • Job definitions live in jobs.jobs and run history in job_runs; those tables belong to Nodabase, while public is for your application's own tables. Run history is not part of the client API — the runner records every attempt in job_runs in PostgreSQL.
  • Without NODABASE_JOBS_ENABLED=true and DATABASE_URL, nodabase.jobs is absent from the client — the same pattern as db and cache.

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