graphile-worker

library0.16.6jsnpmunverified

Graphile Worker is a job queue for PostgreSQL that runs background tasks with ease. It uses PostgreSQL as the job store, leveraging LISTEN/NOTIFY for real-time job scheduling. Current stable version is 0.16.6, released with a steady cadence. Key differentiators: no external dependencies like Redis, built-in job scheduling, cron-like repeatability, and full TypeScript support. It is designed for high reliability and performance, suitable for production use.

database devops

npm install graphile-worker

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHILE-WORKER

graphile-worker

databasejavascriptv0.16.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

run

✓ import { run } from 'graphile-worker'

✗ const { run } = require('graphile-worker')

ESM-only since v0.13; requires 'type': 'module' in package.json or .mjs extension.

WorkerUtils

✓ import { WorkerUtils } from 'graphile-worker'

✗ import WorkerUtils from 'graphile-worker'

Named export, not default.

GraphileWorker

✓ import type { GraphileWorker } from 'graphile-worker'

✗ import { GraphileWorker } from 'graphile-worker'

TypeScript type import; not a runtime value.

Sets up a worker with a simple 'hello' task, adds a job to the queue, and handles graceful shutdown.

import { run } from 'graphile-worker'; import { Client } from 'pg'; const client = new Client({ connectionString: process.env.DATABASE_URL ?? 'postgres:///myapp' }); await client.connect(); const runner = await run({ pgPool: client, concurrency: 5, pollInterval: 1000, taskList: { hello: async (payload, helpers) => { const { name } = payload; console.log(`Hello, ${name}!`); }, }, }); // Add a job await runner.addJob('hello', { name: 'world' }); // Graceful shutdown process.on('SIGINT', () => { runner.stop().then(() => process.exit(0)); });

Debug

Known issues

breakingVersion 0.16.0 changed the default job queue schema from 'graphile_worker' to 'graphile_worker' (same? Actual change: rename from graphile_worker to graphile_worker? Check release notes).

fix

Ensure your database schema matches the new default, or explicitly set schema in options.

affects: >=0.16.0

deprecatedThe 'pgClient' option is deprecated; use 'pgPool' instead.

fix

Replace { pgClient: client } with { pgPool: client.pool } or similar.

affects: >=0.13.0

gotchaThe worker requires PostgreSQL's LISTEN/NOTIFY capability; ensure your connection allows that.

fix

Check PostgreSQL configuration and network setup for LISTEN/NOTIFY support.

affects: all

breakingVersion 0.15.0 dropped support for Node.js 12.

fix

Upgrade Node.js to version 14 or higher.

affects: >=0.15.0

Errors

Common errors & fixes

Error: listen EADDRINUSE :::5432

Another process is using the PostgreSQL port 5432 on localhost.

fix

Stop the conflicting service or change the PostgreSQL port in connection string.

Cannot find module 'graphile-worker'

Package is not installed or ESM import is used in CommonJS without configuration.

fix

Run 'npm install graphile-worker' and ensure you use ESM imports (import rather than require).

TypeError: Cannot read properties of undefined (reading 'query')

WorkerUtils or job added with invalid connection details.

fix

Check that the pgPool is correctly initialized and connected before using worker functions.

Upgrade

Version history

0.16.6latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client required for database connectivity

Agent activity

13 hits · last 30 days

node

Resources

githubssh://git@github.com/graphile/worker ↗

packagegraphile-worker ↗

homepagehttps://github.com/graphile/worker#readme ↗