Issue Feature Resolved

#110227Maintain database connections in long-running Messenger workers (ping/close middlewares)

Stefan Bürk 07/19/26, 15:27 updated 10/08/26, 12:25

Description

Problem

Long-running Symfony Messenger workers started via typo3 messenger:consume keep
a PHP process – and its database connections – alive across many messages. A
database connection that stays idle between two messages can be dropped by the
server (for example MySQL’s wait_timeout), so the next message handled by the
worker fails with errors such as “MySQL server has gone away”.

Symfony ships DoctrinePingConnectionMiddleware and
@DoctrineCloseConnectionMiddleware@ for exactly this, but they live in the
*non-vendored* symfony/doctrine-bridge package and are built around
@ManagerRegistry@ / EntityManagerInterface (Doctrine ORM). TYPO3 has no ORM
manager and routes connections through its own
@TYPO3\CMS\Core\Database\ConnectionPool@, so the Symfony middlewares cannot be
reused as-is.

Proposed solution

Provide two TYPO3-native messenger middlewares operating on ConnectionPool:

  • TYPO3\CMS\Core\Messenger\Middleware\DoctrinePingConnectionMiddleware -
    before handling a message, pings each open connection with a lightweight
    dummy select and transparently closes+reconnects a connection that turned out
    to be stale.
  • TYPO3\CMS\Core\Messenger\Middleware\DoctrineCloseConnectionMiddleware -
    after handling a message, closes the open connections so the next message
    starts with a fresh connection. Closing happens even when the handler throws.

Both middlewares are registered by default and wrap the message handling
(close outermost, ping innermost, around HandleMessageMiddleware).

Behaviour

  • They act only on asynchronous consumption: a message is processed only when
    it carries a ConsumedByWorkerStamp (added by the worker). A synchronous
    dispatch – including the SyncTransport – is passed through untouched, so
    regular request handling never pings or closes connections.
  • They operate on currently open connections only (a new
    ConnectionPool::getOpenConnectionNames() accessor), so no connection is
    opened just to ping or close it.
  • Staleness detection uses the platform dummy select
    (AbstractPlatform::getDummySelectSQL()); on failure the connection is closed
    and the check is retried, which reconnects lazily. This is DBAL 4 compatible
    (Connection::ping() was removed in DBAL 4).

Extensibility

Two cancellable PSR-14 events allow listeners to exclude individual connections:

  • TYPO3\CMS\Core\Messenger\Event\BeforeMessengerDoctrinePingEvent
  • TYPO3\CMS\Core\Messenger\Event\BeforeMessengerDoctrineCloseEvent

Each exposes getConnectionName() and skip() / shouldSkip() and stops
propagation once skipped. A typical use is keeping a dedicated connection open
across messages (skip its close) while still validating it before the next
message (ping).

Example

Enabling is not required – the maintenance is active for every worker. To keep a
specific connection open across messages, register a listener:

use TYPO3\CMS\Core\Attribute\AsEventListener;
use TYPO3\CMS\Core\Messenger\Event\BeforeMessengerDoctrineCloseEvent;

final class KeepReportingConnectionOpen
{
    #[AsEventListener]
    public function __invoke(BeforeMessengerDoctrineCloseEvent $event): void
    {
        if ($event->getConnectionName() === 'Reporting') {
            $event->skip();
        }
    }
}

Notes

  • No new configuration option is introduced; the middlewares are always active
    for worker (async) message handling and inert for synchronous dispatch.
  • Complements the transport routing / async separation work
    (#101699, #110223, #107032).

Reviews 4

History 211

  1. Stefan Bürk commented and changed status Under Review Resolved done 0 % 100 % <span data-processor="relativetime" data-value="2026-10-08T12:25:13+00:00" > 10/08/26, 12:25 </span>

    Applied in changeset commit:1b416fa15221a6ef4e386c3bb2e39a387d393789.