Laravel 13.17: Route-Metadata und Postgres-Pooling im Detail

Am 2. Juli erschien Laravel 13.17.0. Zwei Features darin sind für Agenturen mit API-Projekten unmittelbar relevant. Route-Metadata löst ein Problem, das viele Teams über Jahre mit Workarounds im Action-Array gelöst haben. Der native Postgres-Pooler-Support macht Connection-Pooling in Serverless- und Cloud-Deployments zu einer Konfigurationszeile statt zu einem Custom-Package.

Als PHP-Freelancer mit Fokus auf Symfony bekomme ich regelmäßig Anfragen zu Laravel-Projekten, wenn Agenturen einen zweiten Blick auf ihre Architektur brauchen. Beide Frameworks lösen ähnliche Probleme, manchmal mit unterschiedlichen Prioritäten. Route-Metadata und Postgres-Pooling in 13.17 sind ein gutes Beispiel dafür, wie Laravel aktuell auf reale Produktionsprobleme reagiert, nicht auf Feature-Wünsche.

Laravel 13.17: Die vier Kern-Neuerungen

Was Route-Metadata konkret ändert

Vor 13.17 gab es keinen unterstützten Weg, strukturierte Zusatzdaten an eine Route zu hängen. Teams haben sich mit dem Action-Array beholfen, was funktionierte, aber nicht über die Pipeline hinweg konsistent war. Route-Metadata macht das jetzt zu einem First-Class-Attribut, inklusive Unterstützung für route:cache-Serialisierung und Group-Vererbung.

// Metadata direkt an einer Route setzen
Route::get('/users', [UserController::class, 'index'])
    ->metadata(['version' => 'v2', 'public' => true]);

// Group-Cascading: Metadata vererbt sich an alle Routen der Gruppe
Route::middleware('api')
    ->metadata(['version' => 'v2'])
    ->group(function () {
        Route::get('/users', [UserController::class, 'index']);
        Route::get('/orders', [OrderController::class, 'index']);
        // beide erben version: v2, sofern nicht überschrieben
    });

// Dot-Notation für gezielten Zugriff:
$route->metadata('version');  // 'v2'

Für API-Versionierung ist das der naheliegende Einsatz. Statt Versions-Logik über URL-Präfixe oder separate Route-Dateien zu lösen, kann die Version als Metadata mitlaufen und in Middleware, Dokumentations-Generatoren oder OpenAPI-Exportern konsistent ausgelesen werden.

Warum der Postgres-Pooler-Support mehr ist als ein Nischen-Feature

Transaction-Mode-Pooling bei Postgres-Proxies wie PgBouncer hält eine Serververbindung nur für die Dauer einer einzelnen Transaktion offen. Das Problem dabei: Prepared Statements sind mit diesem Modus grundsätzlich inkompatibel, weil sie eine Verbindung über mehrere Transaktionen hinweg voraussetzen. Bisher mussten Laravel-Teams das über Community-Packages lösen, die eigene Connection-Klassen bereitstellten.

// config/database.php: Pooled Connection aktivieren
'pgsql' => [
    'driver' => 'pgsql',
    'host' => env('DB_HOST'),
    'pooled' => true,  // aktiviert emulated prepares automatisch
    // ...
],

// Migrationen und Schema-Befehle brauchen eine direkte Verbindung.
// Laravel routet automatisch, wenn ::direct angehängt wird:
php artisan migrate --database=pgsql::direct

Wenn pooled auf true steht, wechselt die Verbindung automatisch zu emulierten Prepares, die mit Transaction-Mode-Poolern kompatibel sind. Befehle, die eine direkte Verbindung benötigen, etwa Migrationen, schema:dump oder db:wipe, routen automatisch zum direkten Endpunkt. Verbindungen ohne pooled => true behalten das bisherige Verhalten bei, die Änderung ist vollständig rückwärtskompatibel.

Für Serverless-Deployments ist das ein praktischer Gewinn. Neon zum Beispiel begrenzt die Anzahl gleichzeitiger direkter Verbindungen standardmäßig auf 100. Wer viele kurzlebige Serverless-Funktionen betreibt, die jeweils eigene Datenbankverbindungen aufbauen, läuft ohne Pooling schnell in dieses Limit. PgBouncer reduziert die Anzahl aktiver Backend-Prozesse, aber eben nur, wenn Laravel korrekt mit dem Transaction-Mode umgehen kann.

Was dev:list und ShouldNotRetry im Alltag bringen

Wie hilft dev:list bei mehreren Dev-Prozessen?

Größere Laravel-Projekte starten beim lokalen Entwickeln oft mehrere parallele Prozesse: Vite-Dev-Server, Queue-Worker, Horizon, WebSocket-Server aus verschiedenen Paketen. Der neue dev:list-Befehl zeigt alle registrierten Dev-Prozesse gemeinsam mit der Quelle, die sie registriert hat, sei es die eigene Applikation oder ein Vendor-Package.

Das klingt unspektakulär, spart aber in der Praxis Zeit beim Debuggen von lokalen Umgebungsproblemen. Wer nicht mehr rätseln muss, welches Package einen bestimmten Prozess gestartet hat, kommt schneller zur eigentlichen Fehlerursache.

Wann lohnt sich der ShouldNotRetry-Handler?

Manche Exceptions sollten grundsätzlich keinen Retry auslösen. Ungültige Eingaben, permanente Fehler bei externen Diensten, oder Situationen, in denen ein erneuter Versuch garantiert dasselbe Ergebnis liefert. Bisher musste man das über eigene Job-Logik abfangen. Jetzt kann eine Exception-Klasse selbst über eine retry()-Methode entscheiden, oder die Konfiguration erfolgt zentral in bootstrap/app.php über withExceptions().

// Exception-Klasse entscheidet selbst über Retry-Verhalten
class InvalidApiCredentialsException extends Exception
{
    public function retry(): bool
    {
        return false;  // kein erneuter Versuch, das Ergebnis bleibt gleich
    }
}

Das schont das Retry-Budget von Queue-Jobs. Wie ich in Symfony-Projekten regelmäßig sehe, ist ein ähnliches Muster mit Messenger-Middleware lösbar, aber dort meist mit mehr Konfigurationsaufwand als dieser direkte Ansatz.

Was bedeutet das für die Framework-Wahl?

Route-Metadata und Postgres-Pooling sind keine Gründe, ein bestehendes Symfony-Projekt auf Laravel umzustellen. Beide Frameworks lösen ähnliche Probleme mit unterschiedlichen Prioritäten und Ökosystemen. Was diese Laravel-Version zeigt: Der Trend geht bei beiden Frameworks in Richtung pragmatischer Lösungen für reale Cloud- und Serverless-Deployment-Probleme, nicht in Richtung reiner Syntax-Erweiterungen.

Für Agenturen, die beide Frameworks im Portfolio haben oder Projekte mit gemischtem Stack betreuen, lohnt sich der Blick auf beide Ökosysteme. Wie ich in meiner Arbeit an API-Integrationsprojekten immer wieder sehe, entscheidet am Ende weniger das Framework als die konkrete Architektur-Entscheidung darüber, wie gut ein System skaliert.

Zusammenfassung

Route-Metadata macht strukturierte Zusatzdaten an Routen zu einem First-Class-Attribut mit Cache-Serialisierung und Group-Vererbung. Der naheliegende Einsatz ist API-Versionierung und automatisierte Dokumentation.

Postgres-Pooler-Support macht Connection-Pooling mit PgBouncer, AWS RDS Proxy oder Neon zu einer Konfigurationszeile. Migrationen und Schema-Befehle routen automatisch um den Pooler herum.

dev:list und ShouldNotRetry sind kleinere, aber praxisrelevante Ergänzungen für lokale Entwicklung und Queue-Robustheit.