> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the public docs of Meridian for Shopify apps: hosting, billing (Plan Builder and the @the-meridian/sdk package), CRM, emails and automations for Shopify app developers.
> Start with these pages: Meridian MCP (https://help.the-meridian.ai/mcp-server.md) to connect a coding agent, AI coding agents (https://help.the-meridian.ai/ai-agents.md) for the agent skill, SDK quickstart (https://help.the-meridian.ai/sdk-quickstart.md), Running your app with the CLI (https://help.the-meridian.ai/cli-dev.md), Deployment (https://help.the-meridian.ai/deployment.md), and Errors (https://help.the-meridian.ai/errors.md) to look up an error code or message.
> Fetch one page at a time as Markdown (the page URL followed by .md), using the index in https://help.the-meridian.ai/llms.txt. llms-full.txt holds every page in one file of about 900 KB, so avoid loading it whole.
> With Meridian MCP connected, search these docs with docs_search and docs_get, and read live facts (feature and event keys, plan ids, environments, deployments, logs) from the MCP tools instead of guessing them.

# Worker: background jobs on BullMQ or pg-boss

> Run background jobs with the Worker add-on: BullMQ queues on Redis or pg-boss queues on PostgreSQL, a start command, sleep when the queue is empty, monthly hours, pause and tiers.

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](https://help.the-meridian.ai/scheduler.md#coming-from-heroku-scheduler) instead.

## Choose your queue

The Worker page starts with the queue your app uses:

| Queue | Where the jobs live | What the environment needs |
| - | - | - |
| **BullMQ** (default) | Redis | The [Redis](https://help.the-meridian.ai/redis.md) add-on |
| **pg-boss** | Your database | A [PostgreSQL database](https://help.the-meridian.ai/database.md) |

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.

> [!NOTE]
>
> 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.

```js BullMQ theme={null}
import { Worker } from "bullmq"
import IORedis from "ioredis"

const connection = new IORedis(process.env.REDIS_URL, { maxRetriesPerRequest: null })

new Worker("emails", async (job) => { /* your job */ }, { connection })
```

```js pg-boss theme={null}
import { PgBoss } from "pg-boss"

const boss = new PgBoss(process.env.DATABASE_URL)
await boss.start()

await boss.work("emails", async ([job]) => { /* your job */ })
```

## 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](#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

| Setting | What it does | Applies |
| - | - | - |
| Queue | BullMQ or pg-boss | At once |
| Key prefix or schema, queue names | Which queues to watch (Advanced) | At once |
| Start command | The command your worker runs | On the next deploy |

## 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.

| Tier | Hours a month | Worker memory | Price a month |
| - | - | - | - |
| Worker 100 hours | 100 | 1 GB | \$25 |
| Worker 350 hours | 350 | 1 GB | \$55 |
| Worker 730 hours | 730, a full month | 2 GB | \$95 |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.