Laravel Jobs & Queues: Retry, Backoff, Failed Jobs & Idempotency
Series: Every Laravel Project Should Have These Building Blocks Part: 15 of 35 Level: Intermediate Prerequisites: Action Classes What You’ll Learn When to use a Job vs. a queued Event Listener The anatomy of a well-written Job class Retry configuration, backoff strategies, and failure handling The HeartBeat pattern — checking queue health on a schedule Unique jobs and idempotency Named queues and…
When working with Laravel jobs and queues, it is crucial to understand the various settings and configurations that help manage retries, backoff, failed jobs, and idempotency. This article will cover these topics in detail, explaining when and how to use them.
Laravel provides several settings for configuring jobs and queues, including $tries, $backoff, $timeout, and retryUntil(). Each of these settings plays a distinct role in controlling the behavior of jobs:
- $tries: This setting determines the maximum number of attempts a job can make before being moved to the failed_jobs table. The job property always takes precedence over the worker flag.
- $backoff: This setting specifies the delay in seconds between retries after an exception occurs. It can be an array to set a delay per attempt, with the last value repeating for any remaining attempts.
- $timeout: This setting defines the maximum time a job can run before being killed by the worker. It must be shorter than the connection's retry_after value to prevent duplicate runs of the job.
- retryUntil(): This setting defines a deadline for a job, causing it to retry until this time is reached, thereby ignoring the $tries setting. It is useful when a deadline is more critical than the number of attempts.
Additionally, $maxExceptions and $timeout settings are available for handling unhandled exceptions and job timeouts, respectively.
When setting up jobs and queues, it is essential to ensure the $timeout value is shorter than the retry_after value in the config/queue.php file. This ensures duplicate runs of the job are prevented.
To handle failed jobs, you can use the following commands:
- php artisan queue:failed: This command lists all failed jobs with their UUIDs.
- php artisan queue:retry {uuid}: This command retries a single failed job using its UUID.
- php artisan queue:retry all: This command retries all failed jobs.
- php artisan queue:retry --queue=emails: This command retries failed jobs from a specific queue.
- php artisan queue:forget {uuid}: This command deletes a failed job using its UUID.
- php artisan queue:prune-failed --hours=48: This command removes failed jobs older than 48 hours.
Before using the queue:retry all command, it is essential to fix the underlying cause of the failures, as mass-retry might simply refill the failed_jobs table.
To ensure idempotency and make retries safe, consider the following strategies:
1. Check for existing state before performing any side effects (e.g., charging a card or sending an email).
2. Enforce idempotency using a unique index on an idempotency key or implementing the ShouldBeUnique interface.
3. Prevent concurrent runs by using the WithoutOverlapping middleware, keyed by record ID.
By understanding and applying these settings and configurations, you can effectively manage Laravel jobs and queues, ensuring robust, reliable, and efficient processing of your application's background tasks.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
