Skip to content
This guide is for the queue-only version of Edge Worker. Main docs are here

# Configuration

You can pass an optional configuration object as the second argument to `EdgeWorker.start()` to tweak the worker’s behavior.

Zero Configuration

Edge Worker comes with sensible defaults for all configuration options.

You only need to provide a handler function:

    EdgeWorker.start(console.log);

Configuration Validation

Currently, configuration options are not validated at runtime. Please double-check your settings carefully.

### Default configuration

Section titled “Default configuration”

    EdgeWorker.start(handler, {  // name of the queue to poll for messages  queueName: 'tasks',
      // how many tasks are processed at the same time  maxConcurrent: 10,
      // how many connections to the database are opened  maxPgConnections: 4,
      // in-worker polling interval  maxPollSeconds: 5,
      // in-database polling interval  pollIntervalMs: 200,
      // how long to wait before retrying a failed job  retryDelay: 5,
      // how many times to retry a failed job  retryLimit: 5,
      // how long a job is invisible after reading  // if not successful, will reappear after this time  visibilityTimeout: 10,});

## Queue configuration

Section titled “Queue configuration”

You don’t need to create queues manually

The worker will automatically create a logged, non-partitioned queue with configured name during startup if it does not exist.

### `queueName`

Section titled “queueName”

Type: `string` Default: `'tasks'`

The name of the PGMQ queue to listen to for messages.

    EdgeWorker.start(handler, {  queueName: 'my_custom_queue'});

## Message Processing

Section titled “Message Processing”

### `visibilityTimeout`

Section titled “visibilityTimeout”

Type: `number` Default: `10`

The duration (in seconds) that a message remains invisible to other consumers while being processed.

Message Visibility and Processing

Keep `visibilityTimeout` higher than your task’s maximum processing time.

Here’s why:

- When a worker picks up a message, it becomes invisible for `visibilityTimeout` seconds
- If processing takes longer than `visibilityTimeout`, the message becomes visible again
- Other workers can then pick up and process the same message
- This leads to duplicate processing of the same task
- For example: with `visibilityTimeout: 3` and a task that takes 5 seconds, the message could be processed twice

    EdgeWorker.start(handler, {  visibilityTimeout: 5 // message will re-appear in queue after 5 seconds if not processed});

### `maxConcurrent`

Section titled “maxConcurrent”

Type: `number` Default: `10`

This option limits concurrency - the maximum number of messages that can be processed at the same time. Increase for IO-heavy tasks (network or db calls), decrease for CPU-heavy tasks.

    EdgeWorker.start(handler, {  maxConcurrent: 10 // Process up to 10 messages at once});

### `maxPgConnections`

Section titled “maxPgConnections”

Type: `number` Default: `4`

Maximum number of concurrent database connections. Increase for IO-heavy tasks (network or database operations), decrease for CPU-heavy tasks.

    EdgeWorker.start(handler, {  maxPgConnections: 10 // Use up to 10 connections to the database});

## Polling Behavior

Section titled “Polling Behavior”

### `maxPollSeconds`

Section titled “maxPollSeconds”

Type: `number` Default: `5`

Amount of seconds to wait for a message to be available in the queue.

Polling and Worker Health

Keep `maxPollSeconds` at 5 seconds or lower.

Here’s why:

- Heartbeats are sent once per main loop iteration
- Each iteration can take up to `maxPollSeconds` to complete
- Workers are considered inactive after 6 seconds without a heartbeat
- Therefore, `maxPollSeconds` must be lower than 5 seconds to account for any additional delays

    EdgeWorker.start(handler, {  maxPollSeconds: 5 // Long-poll for 5 seconds waiting for a message});

### `pollIntervalMs`

Section titled “pollIntervalMs”

Type: `number` Default: `200`

The interval (in milliseconds) between database polling attempts by `pgmq.read_with_poll`. The default value is suitable for most use cases.

Polling Intervals

Keep `pollIntervalMs` lower than `maxPollSeconds * 1000`.

Here’s why:

- The worker polls the database every `pollIntervalMs` milliseconds
- This polling continues until `maxPollSeconds` is reached
- If `pollIntervalMs` is too high, the worker might exit after just one poll
- For example: with `maxPollSeconds: 5` and `pollIntervalMs: 6000`, only one poll would occur

    EdgeWorker.start(handler, {  pollIntervalMs: 300 // Poll every 300ms});

## Retries

Section titled “Retries”

### `retryDelay`

Section titled “retryDelay”

Type: `number` Default: `5`

Amount of seconds to wait between retry attempts.

    EdgeWorker.start(handler, {  retryDelay: 5 // Wait 5 seconds between retries});

### `retryLimit`

Section titled “retryLimit”

Type: `number` Default: `5`

Maximum number of retry attempts for failed message processing before marking the message as dead.

Set to `0` to disable retries.

    EdgeWorker.start(handler, {  retryLimit: 0 // retries are disabled});