Skip to main content
The Worker runs your app’s background jobs. Your app puts jobs on its queue. Meridian starts your worker when jobs are waiting and puts it to sleep when the queue is empty. You don’t size it or switch it on and off: Meridian runs one worker when there is work and none when there isn’t. The Worker is a paid runtime add-on with its own page: Hosting → Add-ons → Worker. Each environment has one worker, and one worker can watch several queues. The Worker is for a queue that your code fills. For a command that runs on a schedule, such as a nightly export, use a long task of the Scheduler instead.

Choose your queue

The Worker page starts with the queue your app uses: Both run the same way: the worker starts when jobs arrive and sleeps when the queue is empty. Advanced is closed by default and shows only what the chosen queue needs:
  • BullMQ: the key prefix (bull by default) and the queue names. Leave the names empty to watch every queue under the prefix.
  • pg-boss: the schema (pgboss by default) and the queue names. Leave the names empty to watch every queue.
Queues written with Bull (versions 3 and 4, the library BullMQ replaced) use the same Redis keys and work too. Choose BullMQ and list the queue names under Advanced: Bull queues cannot be found automatically.
BullMQ
pg-boss

Create it

  1. Open Hosting → Add-ons and select the Worker card. It opens the Worker page.
  2. Choose the queue.
  3. Enter the start command, as you would run it in a terminal, for example npm run worker.
  4. Choose a tier (see Hours and tiers) and select Create worker.
When the environment has already been deployed, the worker is set up from its live release within a few minutes, asleep until jobs arrive. Otherwise it starts with the first deploy. It runs the same image as your web app, with the same environment variables (REDIS_URL and DATABASE_URL included), started with your command.

How it runs

  • Waking. Meridian checks your queue about every 30 seconds. When jobs are waiting, the worker starts, usually within a minute. A delayed job wakes it when it is due.
  • Sleeping. Once the queue is empty and no job is running, the worker goes to sleep. Jobs in progress finish first.
  • pg-boss schedules. pg-boss only turns a schedule (a cron) into a job from a running process. Meridian reads your schedules and has the worker awake a few minutes before each one is due, so they fire on time. A schedule that runs every few minutes keeps the worker awake, and uses hours, around the clock.
With pg-boss, the worker can only be woken once pg-boss has created its tables, which it does the first time it starts in your app. If only the worker starts pg-boss, Meridian starts the worker once after about ten minutes so the tables exist.

Pause and resume

Pause on the Worker page stops the worker from waking. A job that is running finishes first, then the worker sleeps. Jobs added meanwhile wait in the queue. Resume lets it wake again.

Settings

Hours and tiers

The Worker is sold by the hours it runs in a month. Hours count only while the worker is awake, across the app’s environments. Every tier runs the worker on 1 vCPU. The worker’s memory comes from its tier, not from your app’s hosting size, so a small web app can run a 2 GB worker. The Worker page shows the hours used this month:
  • At 80% the page warns you and the organization’s owners get an email.
  • At 100% the worker stops waking until the next billing period. The page says the hours are used up, and jobs wait in the queue. Move to a higher tier to start it again at once.
  • The 730 hour tier covers the whole month, so it never runs out.
Changing tier. Pick another tier under Add-on billing. A higher tier is charged for the rest of the period and applies as soon as the payment goes through. A lower tier applies at the next renewal.

Activity and logs

The Worker page lists the last wake-ups and sleeps with their date and time and the number of jobs waiting. Logs opens the live console on the Worker source, which shows only what your worker writes.

Removing it

Cancel the Worker under Add-on billing on its page. The Redis add-on cannot be deleted while a BullMQ worker reads it, and the database cannot be deleted while a pg-boss worker reads it: remove the Worker first. Ending the Redis add-on also ends the Worker when the app’s workers all use BullMQ.
Last modified on November 17, 2026