Queue Maintenance Commands

This document covers commands for maintaining queue health and operational continuity. These commands handle worker lifecycle management, queue data cleanup, and batch job operations.

For active job processing commands, see Work Command and Listen Command. For failed job management, see Failed Job Management Commands. For queue monitoring, see Monitor Command.

Overview

The Hypervel Queue package provides three categories of maintenance commands:

Command	Class	Purpose
queue:restart	RestartCommand	Signal all running workers to gracefully restart
queue:clear	ClearCommand	Remove all jobs from a queue
queue:retry-batch	RetryBatchCommand	Retry all jobs in a failed batch
queue:prune-batches	PruneeBatchesCommand	Remove old batch records from storage

These commands are registered in ConfigProvider.php40-53 and provide essential operational capabilities for production queue management.

Sources: src/ConfigProvider.php

Command Registration and Dependencies

Sources: src/ConfigProvider.php, publish/queue.php

Restart Command

Purpose

The queue:restart command signals all running queue workers to gracefully terminate after completing their current job. This enables zero-downtime deployments by allowing workers to reload updated code without interrupting job processing.

Command Syntax

Signal Mechanism

The restart command operates by writing a restart signal to a shared storage backend (typically Redis or cache). Workers continuously check for this signal during their daemon loop referenced in Worker System.

Worker Detection

Workers detect the restart signal by comparing their startup timestamp with the restart signal timestamp. When the signal timestamp is newer than the worker's startup time, the worker terminates gracefully. See Worker Class for details on the daemon loop and exit conditions.

Use Cases

Scenario	Usage
Code Deployment	Restart workers to load new application code
Configuration Changes	Apply updated queue configuration without manual process killing
Memory Leak Recovery	Scheduled restarts to prevent memory accumulation
Maintenance Windows	Coordinated worker restart before maintenance operations

Sources: src/Console/RestartCommand.php (inferred), src/ConfigProvider.php

Clear Command

Purpose

The queue:clear command removes all jobs from a specified queue. This is useful for emergency queue draining, clearing stuck jobs, or resetting development environments.

Command Syntax

Arguments and Options

Parameter	Type	Description
connection	Argument	Queue connection name (default from config)
--queue	Option	Queue name to clear (default: 'default')

Driver Support

The clear operation is only supported by queue drivers that implement the ClearableQueue interface. Currently supported drivers:

Behavior

For Redis-based queues, the clear operation removes jobs from:

• Pending jobs list (queues:{queue})
• Delayed jobs sorted set (queues:{queue}:delayed)
• Reserved jobs sorted set (queues:{queue}:reserved)

For SQS queues, the clear operation uses the AWS PurgeQueue API to delete all messages.

Warning

The clear operation is irreversible. Jobs cannot be recovered after clearing. For production systems, consider:

• Moving jobs to a backup queue first
• Using the failed job system to handle problematic jobs
• Implementing job archival before clearing

Sources: src/Console/ClearCommand.php (inferred), src/Contracts/ClearableQueue.php (inferred), publish/queue.php

Batch Management Commands

Job batching allows multiple jobs to be grouped together and tracked as a unit. Batch management commands handle retry and cleanup operations for batch jobs.

Configuration

Batch operations require database configuration in queue.php120-123:

The job_batches table stores batch metadata including:

• Batch ID (UUID)
• Batch name
• Total jobs count
• Pending jobs count
• Failed jobs count
• Timestamps and options

Sources: publish/queue.php

Retry Batch Command

Purpose

The queue:retry-batch command retries all failed jobs within a specific batch. This is useful when a batch partially fails due to temporary issues like network errors or rate limits.

Command Syntax

Processing Flow

Batch State Updates

When retrying batch jobs, the command updates batch counters:

Counter	Change
failed_jobs	Decremented for each retried job
pending_jobs	Incremented for each retried job
failed_job_ids	Failed job IDs removed from list

Sources: src/Console/RetryBatchCommand.php (inferred), publish/queue.php

Prune Batches Command

Purpose

The queue:prune-batches command removes old batch records from the database. Batches accumulate over time and can bloat the database if not regularly cleaned.

Command Syntax

Options

Option	Type	Default	Description
--hours	Integer	24	Age threshold in hours
--unfinished	Integer	0	Include unfinished batches (0 or 1)
--cancelled	Boolean	false	Only prune cancelled batches

Pruning Logic

Recommended Schedule

For production environments, schedule regular batch pruning:

This prevents unbounded growth of the job_batches table while retaining sufficient history for debugging.

Sources: src/Console/PruneBatchesCommand.php (inferred), publish/queue.php

Command Dependencies and Integration

Dependency Injection

All maintenance commands receive dependencies through the DI container:

The QueueManager is resolved through the FactoryContract interface registered in ConfigProvider.php34 ensuring commands receive a fully configured manager instance with exception handling setup from QueueManagerFactory.php14-33

Configuration Dependencies

Commands read configuration from queue.php:

Command	Configuration Section	Usage
RestartCommand	N/A	Cache key prefix only
ClearCommand	connections	Connection and queue selection
RetryBatchCommand	batching	Database connection and table
PruneBatchesCommand	batching	Database connection and table

Sources: src/ConfigProvider.php, src/QueueManagerFactory.php, publish/queue.php

Error Handling and Edge Cases

RestartCommand

Scenario	Behavior
Cache unavailable	Command fails with connection error
No workers running	Signal written but no effect until workers start
Multiple executions	Last signal timestamp wins

ClearCommand

Scenario	Behavior
Non-clearable driver	Error: "Queue does not support clearing"
Connection not found	InvalidArgumentException from QueueManager
Empty queue	Success with zero jobs cleared

RetryBatchCommand

Scenario	Behavior
Batch not found	Error: "Unable to find batch"
No failed jobs	Info message, no retries performed
Database unavailable	Connection exception

PruneBatchesCommand

Scenario	Behavior
No batches to prune	Success with zero deletions
Invalid --hours value	Validation error
Database locked	Wait or timeout based on driver

Sources: src/Console/* (inferred)

Integration with Worker Lifecycle

The maintenance commands integrate with the worker system documented in Worker System:

Workers check for the restart signal during their daemon loop between jobs, ensuring they complete in-progress work before terminating. The clear command operates independently and can be executed while workers are running, though cleared jobs will not be processed.

Sources: src/Worker.php (referenced), src/Console/RestartCommand.php (inferred), src/Console/ClearCommand.php (inferred)