Pausar todas las colas durante un deploy en Laravel 13.25

En casi todos los deploys hay una ventana en la que el código en disco ya ha cambiado pero los workers que corren contra él todavía no se han reiniciado. Un worker que reserva un job en esa ventana deserializa un payload escrito por el código viejo y lo ejecuta con el código nuevo. La mayoría de las veces no pasa nada. De vez en cuando, una clase de job renombrada o la firma de un constructor que ha cambiado lo convierten en un job fallido que hay que relanzar a mano.

Lo que se hacía hasta ahora era o bien modo mantenimiento, que corta mucho más que la cola, o bien queue:restart, que es una petición y no una garantía: el worker solo la ve entre job y job. Laravel 13.25 añade una tercera opción, un interruptor que impide a todos los workers de todas las conexiones reservar trabajo nuevo, sin tocar el tráfico HTTP.

Requisitos

• Laravel 13.25 o superior, publicada el 11 de agosto de 2026.

• Una caché compartida entre la aplicación y todos los workers, porque el interruptor se guarda ahí. Si tienes una instancia de Redis por servidor, la pausa no se propaga.

El comando

php artisan queue:pause --all

Y para deshacerlo:

php artisan queue:resume --all

El argumento de la cola es ahora opcional en ambos comandos, así que --all es lo único que se pasa. Sin el flag se comportan como antes y esperan un par conexión:cola.

El mismo interruptor está en la facade Queue, para scripts de deploy escritos en PHP o para un controlador detrás de un panel de administración:

<?php

use Illuminate\Support\Facades\Queue;

Queue::pauseAll();

// ...

Queue::resumeAll();

Qué hace exactamente una pausa

Una cola pausada impide a los workers reservar jobs nuevos. El proceso del worker sigue vivo y sigue en su bucle, simplemente duerme en lugar de sacar trabajo. Un job que ya se estaba procesando cuando pausas termina, así que un queue:pause --all en un script de deploy no interrumpe nada a medias.

Los productores tampoco se ven afectados: SomeJob::dispatch() sigue escribiendo en Redis o en la base de datos, y esos jobs se quedan ahí esperando a que reanudes.

Por dentro es una sola clave de caché, illuminate:queues:paused, escrita con forever(). Los workers ya leen la caché una vez por vuelta de bucle para comprobar la señal de reinicio y las pausas por cola, y la clave global se recupera en esa misma llamada a many(), así que no añade ninguna ida y vuelta extra. QueueManager::isPaused() y getPausedQueues() informan de una cola como pausada tanto si está puesta la clave global como si lo está la suya propia.

Los dos interruptores son independientes

pause() y pauseAll() escriben claves distintas y, a propósito, no se conocen entre ellos. Si una cola se pausó de forma individual, resumeAll() la deja pausada:

<?php

Queue::pause('redis', 'imports');   // aparcada mientras investigamos un job

Queue::pauseAll();                  // empieza el deploy
Queue::resumeAll();                 // termina el deploy

Queue::isPaused('redis', 'imports'); // true

Este es el comportamiento que quieres en un script de deploy. Si alguien aparcó la cola imports a propósito hace una hora, un deploy que ejecuta resumeAll() no debería deshacer esa decisión sin avisar. Para quitar una pausa individual sigue haciendo falta queue:resume redis:imports.

Eventos

Se disparan dos eventos nuevos, junto a los ya existentes QueuePaused y QueueResumed por cola:

<?php

use Illuminate\Queue\Events\QueuesPaused;
use Illuminate\Queue\Events\QueuesResumed;

Event::listen(function (QueuesPaused $event) {
    Log::warning('Todas las colas pausadas');
});

Vale la pena engancharlos a lo que uses para monitorizar. Una pausa global que se queda puesta porque un deploy falló a mitad es un incidente silencioso: la aplicación responde con normalidad, los jobs se acumulan y nadie se entera hasta que alguien pregunta por qué no llegan los correos.

Dónde ponerlo en el deploy

El sitio natural es pausar antes de sustituir el código y reanudar después de reiniciar los workers, con queue:restart de por medio. Con eso, la ventana en la que un payload viejo se ejecuta con código nuevo desaparece, y no hay que sacar la aplicación de servicio para conseguirlo.