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.

完整安装指南与集成提示词将在购买后解锁。