Required dependencies

npm install pg graphile-config @graphile/logger tslib user@example.com
npm install --save-dev @types/pg typescript

No native modules, pod installs, or Android linking steps are required. This is a pure Node.js package.

Project setup

1. Drop the source into your project at src/worker-source/ (or any path you prefer).

2. Database migration - graphile-worker needs its schema in Postgres before any worker runs:

   import { runMigrations } from "./worker-source";
   await runMigrations({ connectionString: process.env.DATABASE_URL });
   

3. Create a tasks/ directory at your project root (or configure taskDirectory). Each file exports a default Task function.

4. tsconfig - ensure resolveJsonModule and esModuleInterop are enabled:

   {
     "compilerOptions": {
       "esModuleInterop": true,
       "resolveJsonModule": true,
       "module": "CommonJS",
       "target": "ES2019"
     }
   }
   

5. Environment variables:

   • DATABASE_URL - PostgreSQL connection string (e.g. postgres://user:pass@localhost/mydb)
   • NO_LOG_SUCCESS - set to 1 to suppress success log lines
   • GRAPHILE_ENABLE_DANGEROUS_LOGS - set to 1 to enable verbose internal logs

6. Run via the high-level run export or the CLI (graphile-worker -c "$DATABASE_URL").

Public API

run

import { run } from "./worker-source";

const runner = await run({
  connectionString: string;
  taskDirectory?: string;
  concurrency?: number;
  // ...additional SharedOptions
});
// runner.promise resolves when the runner stops
await runner.promise;

Starts the full worker pool: connects to Postgres, loads tasks from taskDirectory, and begins polling. Use this as your main long-running process entry point. Call runner.stop() for graceful shutdown.

makeWorkerUtils

import { makeWorkerUtils } from "./worker-source";

const utils = await makeWorkerUtils({ connectionString: string });
await utils.addJob("send-email", { to: "user@example.com" });
await utils.release();

Creates a standalone utility object for adding jobs outside of a worker context - ideal for web servers or scripts that only enqueue work. Always call release() when finished.

runTaskList

import { runTaskList } from "./worker-source";
import { Pool } from "pg";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const workerPool = await runTaskList(compiledOptions, taskList, pool);

Lower-level API that accepts an already-compiled options object and an explicit TaskList map. Use when you need fine-grained control over task loading or when integrating with an existing pg Pool.

parseCrontab

import { parseCrontab } from "./worker-source";

const items = parseCrontab(`
  0 * * * * send-digest ?fill=1h
`);

Parses a crontab-format string into ParsedCronItem[]. Use to validate or programmatically generate cron schedules before passing them to run.

Working examples

Scenario - Basic background worker process

Start a worker that processes tasks from the tasks/ directory. Each task file exports a default async function.

import { run } from "./worker-source";

async function main() {
  const runner = await run({
    connectionString: process.env.DATABASE_URL!,
    concurrency: 5,
    taskDirectory: `${__dirname}/tasks`,
  });

  process.once("SIGTERM", () => runner.stop());
  await runner.promise;
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

// tasks/send-email.ts
import { Task } from "./worker-source";

const task: Task = async (payload, helpers) => {
  const { to } = payload as { to: string };
  helpers.logger.info(`Sending email to ${to}`);
  // ... call your email service
};

export default task;

Scenario - Enqueue jobs from an Express route

Add jobs from HTTP request handlers without starting a worker pool in the same process.

import express from "express";
import { makeWorkerUtils } from "./worker-source";

const app = express();
app.use(express.json());

let workerUtils: Awaited<ReturnType<typeof makeWorkerUtils>>;

async function bootstrap() {
  workerUtils = await makeWorkerUtils({
    connectionString: process.env.DATABASE_URL!,
  });

  app.post("/send-email", async (req, res) => {
    await workerUtils.addJob("send-email", { to: req.body.to });
    res.json({ queued: true });
  });

  app.listen(3000);
}

bootstrap().catch(console.error);

process.on("SIGTERM", async () => {
  await workerUtils.release();
  process.exit(0);
});

Scenario - Recurring cron jobs with typed task payloads

Declare task payload types via declaration merging and schedule recurring work.

// types/graphile-worker.d.ts
declare global {
  namespace GraphileWorker {
    interface Tasks {
      "daily-digest": { userId: string };
      "send-email": { to: string; subject: string };
    }
  }
}

// worker.ts
import { run, parseCrontab } from "./worker-source";
import type { Task } from "./worker-source";

const dailyDigest: Task = async (payload, helpers) => {
  const { userId } = payload as GraphileWorker.Tasks["daily-digest"];
  helpers.logger.info(`Generating digest for ${userId}`);
};

async function main() {
  const runner = await run({
    connectionString: process.env.DATABASE_URL!,
    taskList: { "daily-digest": dailyDigest },
    crontab: `0 9 * * * daily-digest`,
  });
  await runner.promise;
}

main().catch(console.error);

File walkthrough

• index.ts - Barrel re-export of all public symbols; the only import path consumers should use.
• interfaces.ts - Canonical TypeScript definitions for Task, Job, WorkerPool, AddJobFunction, WorkerEvents, and all other shared types.
• runner.ts - Implements run, runOnce, runMigrations - the three high-level entry points most applications use.
• main.ts - Implements runTaskList and runTaskListOnce; manages the worker pool lifecycle, LISTEN/NOTIFY, and retry logic.
• worker.ts - Single-worker unit; checks out one job from the queue, calls the matching task function, reports success or failure.
• workerUtils.ts - Provides makeWorkerUtils and quickAddJob for job enqueueing without a full worker context.
• localQueue.ts - Batches database job fetches to reduce round-trips; manages STARTING/POLLING/WAITING/TTL_EXPIRED/RELEASED state machine.
• cron.ts - Drives the cron scheduling loop; compares known crontabs against parsed items and triggers backfill or new job creation.
• crontab.ts - Parses crontab text format into structured ParsedCronItem objects.
• lib.ts - Internal shared logic: option compilation, retry delay calculation, error coercion, sleep, safeEmit.
• logger.ts - Thin logging abstraction over @graphile/logger; re-exports Logger and consoleLogFactory.
• migrate.ts - Runs SQL migrations to install or upgrade the graphile_worker schema in Postgres.
• helpers.ts - Factory functions for creating withPgClient wrappers from a Pool or PoolClient.
• preset.ts - Exports WorkerPreset, the default graphile-config preset wiring everything together.
• signals.ts - Registers OS signal handlers (SIGTERM, SIGINT) and triggers graceful pool shutdown.
• sql/ - Individual SQL query modules (completeJobs, failJobs, getJobs, returnJobs, resetLockedAt) called by the worker internals.
• plugins/ - LoadTaskFromJsPlugin and LoadTaskFromExecutableFilePlugin for task discovery strategies.
• generated/sql.ts - Auto-generated query type bindings; do not edit manually.

Common pitfalls and fixes

• Missing database schema: worker crashes with "relation graphile_worker.jobs does not exist" - fix by calling runMigrations or running graphile-worker --migrate before starting any worker.
• DATABASE_URL not set: processSharedOptions will throw at startup - always provide connectionString explicitly or set DATABASE_URL in your environment.
• ESM/CJS interop: if your project uses "type": "module", import graphile-worker via the npm package name, not relative source paths, or set "module": "CommonJS" in tsconfig.
• Task file not found: run silently finds no tasks if taskDirectory points to a compiled dist/ path that doesn't exist yet - ensure you build before running or use ts-node/tsx.
• Pool exhaustion under high concurrency: each worker holds a pg client during job execution; set concurrency no higher than your pg pool max minus headroom for migrations and cron.
• Graceful shutdown not triggering: if you do not await runner.promise or call runner.stop(), the process may exit before in-flight jobs complete - always wire SIGTERM to runner.stop().

Vibe-coding prompt template

I have purchased the graphile-worker source block. The source files are in `src/worker-source/` and the integration guide is in `USAGE.md`.

The upstream npm package is `user@example.com`.

Please help me integrate this into my existing Node.js/TypeScript/Express project step by step:

1. Read `USAGE.md` and `src/worker-source/index.ts` to understand all available exports.
2. Run the database migration so the graphile_worker schema exists in my Postgres instance (connection string is in DATABASE_URL env var).
3. Create a `src/tasks/` directory and add a sample task called `send-email` that logs the payload.
4. Add a worker process entry point at `src/workerProcess.ts` that calls `run` with concurrency 5, pointing at `src/tasks/`.
5. Add a helper module at `src/jobQueue.ts` that exports an initialized `makeWorkerUtils` instance so Express routes can call `addJob`.
6. Wire a POST `/queue/send-email` route in my Express app to enqueue a `send-email` job.
7. Add TypeScript declaration merging for my task payload types in `src/types/graphile-worker.d.ts`.
8. Show me how to handle graceful shutdown on SIGTERM for both the worker process and the utils instance.

Use only the exports visible in `src/worker-source/index.ts` and described in `USAGE.md`. Do not invent APIs.

License and credit

graphile-worker is released under the MIT License. See the upstream repository at https://www.npmjs.com/package/graphile-worker and https://github.com/graphile/worker for full license text, changelog, and official documentation at worker.graphile.org.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.