Skip to main content

CLI: Running jobs

To run Graphile Worker, simply run the graphile-worker binary passing your PostgreSQL connection string via the -c entry. Worker manages its own database schema (graphile_worker) into which jobs are stored; when you start Graphile Worker it will automatically create or update this schema if necessary.

npx graphile-worker -c "postgres:///my_db"

npx looks for the graphile-worker binary locally; it's often better to use the "scripts" entry in package.json instead.


Graphile Worker expects the Postgres role used at runtime to be the same as the role used while running the migrations. If you need to run your migrations as a different role, one solution is to explicitly change the owner of the graphile_worker.* tables to be the same role as is used at runtime.

CLI options

The following CLI options are available:

--help Show help [boolean]
--version Show version number [boolean]
-c, --connection Database connection string, defaults to the
'DATABASE_URL' envvar [string]
-s, --schema The database schema in which Graphile Worker is
(to be) located
[string] [default: "graphile_worker"]
--schema-only Just install (or update) the database schema,
then exit [boolean] [default: false]
--once Run until there are no runnable jobs left, then
exit [boolean] [default: false]
--crontab override path to crontab file [string]
-j, --jobs number of jobs to run concurrently
[number] [default: 1]
-m, --max-pool-size maximum size of the PostgreSQL pool
[number] [default: 10]
--poll-interval how long to wait between polling for jobs in
milliseconds (for jobs scheduled in the
future/retries) [number] [default: 2000]
--no-prepared-statements set this flag if you want to disable prepared
statements, e.g. for compatibility with
pgBouncer [boolean] [default: false]

Connection string

A PostgreSQL connection string looks like this:


Where each of the [...] placeholders are optional. Here are some examples:

  • postgres:///my_db connect to database my_db on the default host (localhost) and default port (5432)
  • postgres://
  • postgres://
  • postgres://postgres:[email protected]:5432/my_db
  • postgres://postgres:[email protected]:5432/my_db?ssl=1
Three ants crawling atop the footer