> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Durable Execution Worker — Admin Guide

> Version: 1.0.0 Last Updated: 2026-03-18 Status: Active Module: FW

**Version:** 1.0.0\
**Last Updated:** 2026-03-18\
**Status:** Active\
**Module:** FW

***

## Overview

The durable execution worker processes queued workflow executions via pgmq. It runs on a per-minute cron schedule and processes batches per organization with semaphore-based concurrency control.

***

## Configuration

Worker settings are stored in `fw_module_settings` (one row per organization):

| Setting            | Column                                 | Default | Description                                                   |
| ------------------ | -------------------------------------- | ------- | ------------------------------------------------------------- |
| Worker Enabled     | `fw_execution_worker_enabled`          | `false` | Master toggle for the worker                                  |
| Batch Size         | `fw_worker_batch_size`                 | `10`    | Messages per batch (1–50)                                     |
| Visibility Timeout | `fw_worker_visibility_timeout_seconds` | `30`    | Seconds before unacked message becomes visible again (30–600) |

### Enabling the Worker

1. Navigate to **FW Settings** → **Worker** tab
2. Toggle **Enable Execution Worker** on
3. Adjust batch size and visibility timeout as needed
4. Save settings

### Recommended Settings

| Workload                     | Batch Size | Visibility Timeout |
| ---------------------------- | ---------- | ------------------ |
| Low volume (\<100/day)       | 5          | 30s                |
| Medium volume (100–1000/day) | 10         | 60s                |
| High volume (>1000/day)      | 25         | 120s               |

***

## Queue Monitoring

### Check Queue Depth

```sql theme={null}
SELECT count(*) AS pending_messages
FROM pgmq.q_workflow_execution_queue
WHERE vt <= now();
```

### Check Dead Letter Queue

```sql theme={null}
SELECT count(*) AS dlq_messages
FROM pgmq.q_workflow_dlq;

-- View DLQ message details
SELECT msg_id, enqueued_at, message->>'execution_id' AS execution_id,
       message->>'error' AS error, message->>'failed_at' AS failed_at
FROM pgmq.q_workflow_dlq
ORDER BY enqueued_at DESC
LIMIT 20;
```

### Worker Run History

```sql theme={null}
SELECT organization_id, worker_running, worker_last_run_at, worker_last_batch_size
FROM fw_module_settings
WHERE fw_execution_worker_enabled = true;
```

***

## DLQ Handling

Messages are routed to the DLQ after 5 failed attempts. To retry a DLQ message:

```sql theme={null}
-- Move a message back to the main queue
WITH dlq_msg AS (
  SELECT msg_id, message FROM pgmq.q_workflow_dlq WHERE msg_id = :msg_id
)
SELECT pgmq.send('workflow_execution_queue', 
  jsonb_set(message, '{attempt}', '1'::jsonb)
) FROM dlq_msg;

-- Then delete from DLQ
SELECT pgmq.delete('workflow_dlq', :msg_id);
```

### Purge Old DLQ Messages

```sql theme={null}
DELETE FROM pgmq.q_workflow_dlq
WHERE enqueued_at < now() - interval '30 days';
```

***

## Troubleshooting

See [Runbook](durable-execution-worker-runbook.md) for operational procedures.

***

## Related Documentation

* [FW-46 Cron Scheduling](../guides/cron-scheduling-fw-46.md)
* [FW-46 API Reference](durable-execution-worker-api-reference.md)
* [FW-46 Runbook](durable-execution-worker-runbook.md)
* [FW-46 Integration Doc](../architecture/integrations/durable-execution-worker-integration.md)