feat(logging): log DB connection-establishment errors on a database channel

Add the `database` Monolog channel and a DBAL driver middleware that logs
connection failures so operators without database access get a signal
(ADR 011). Logging-only — no reconnect/retry.

- ConnectionErrorDriver wraps connect() and reads the raw driver error code
  (a middleware sits below DBAL's exception conversion, which does not
  classify 1040/1203/2003 as ConnectionException). Connection-pressure /
  unreachability codes log at critical, other connect failures at error.
  The original exception is rethrown unchanged; only the host is logged,
  never the password or DSN.
- Register the middleware with the explicit doctrine.middleware tag (the
  bundle collects tagged services; implementing the interface is not enough)
  and bind the database channel.
- Add a prod per-channel handler for `database` (LOG_LEVEL_DATABASE with the
  LOG_LEVEL fallback) and document the event=db.connection_error shape.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: turegjorup

.env

@@ -145,6 +145,9 @@ LOG_LEVEL_FEED=
 LOG_LEVEL_INTERACTIVE=
 # Per-channel override; empty or unset inherits LOG_LEVEL.
 LOG_LEVEL_CACHE=
+# Per-channel override; empty or unset inherits LOG_LEVEL. Connection errors
+# are logged at error/critical, so they emit regardless of this threshold.
+LOG_LEVEL_DATABASE=
 ###< Logging ###
 
 ###> App ###

config/packages/monolog.yaml

@@ -1,3 +1,12 @@
 monolog:
     channels:
-        ['app_http', 'auth', 'screen', 'media', 'feed', 'interactive', 'cache']
+        [
+            'app_http',
+            'auth',
+            'screen',
+            'media',
+            'feed',
+            'interactive',
+            'cache',
+            'database',
+        ]

config/packages/prod/monolog.yaml

@@ -57,6 +57,12 @@ monolog:
             level: '%env(default:app.log_level:LOG_LEVEL_CACHE)%'
             channels: ['cache']
             formatter: monolog.formatter.json
+        database:
+            type: stream
+            path: '%env(resolve:LOG_PATH)%'
+            level: '%env(default:app.log_level:LOG_LEVEL_DATABASE)%'
+            channels: ['database']
+            formatter: monolog.formatter.json
         console:
             type: console
             process_psr_3_messages: false

config/services.yaml

@@ -101,6 +101,15 @@ services:
         arguments:
             $logger: '@monolog.logger.feed'
 
+    # Logs DB connection-establishment failures on the `database` channel.
+    # The explicit doctrine.middleware tag is required: doctrine-bundle collects
+    # tagged services in MiddlewaresPass; implementing the interface is not enough.
+    App\Doctrine\Middleware\ConnectionErrorMiddleware:
+        arguments:
+            $logger: '@monolog.logger.database'
+        tags:
+            - { name: doctrine.middleware }
+
     Symfony\Component\Security\Http\Authentication\AuthenticationFailureHandlerInterface: '@Lexik\Bundle\JWTAuthenticationBundle\Security\Http\Authentication\AuthenticationFailureHandler'
     Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface: '@Lexik\Bundle\JWTAuthenticationBundle\Security\Http\Authentication\AuthenticationSuccessHandler'
 

docs/logging.md

@@ -113,3 +113,27 @@ emits:
   in `context`/`extra`.
 
 Still: do not put credentials or token strings into log context in the first place.
+
+## Database connection errors
+
+A DBAL driver middleware (`App\Doctrine\Middleware\ConnectionErrorMiddleware`) logs
+connection-**establishment** failures on the `database` channel so operators without
+database access get a failure signal (ADR 011). It reads the raw driver error code (a
+middleware sits below DBAL's exception conversion, which does not classify
+`1040`/`1203`/`2003` as `ConnectionException`), fires for every SAPI (web, CLI, Messenger),
+and rethrows the original exception unchanged — it is logging-only, with no reconnect.
+
+The record uses the static message `Database connection failed` with:
+
+| Key | Meaning |
+|---|---|
+| `event` | Always `db.connection_error`. |
+| `db.error_code` | Numeric MySQL/MariaDB error number (e.g. `1040`, `1045`, `2003`). |
+| `db.sqlstate` | The SQLSTATE, when available. |
+| `db.host` | Connection host only — never the password or full DSN. |
+| `exception` | The structured `\Throwable` (via `ExceptionContextProcessor`). |
+
+Connection **pressure / unreachability** codes (`1040`, `1203`, `1226`, `2002`, `2003`,
+`2005`) are logged at `critical`; other connect failures (e.g. a `1045` credential error)
+at `error`. Both levels emit regardless of `LOG_LEVEL_DATABASE`, which only gates
+lower-severity `database`-channel records. Mid-query drops (`2006`/`2013`) are out of scope.

src/Doctrine/Middleware/ConnectionErrorDriver.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Doctrine\Middleware;
+
+use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Driver\Connection as DriverConnection;
+use Doctrine\DBAL\Driver\Exception as DriverException;
+use Doctrine\DBAL\Driver\Middleware\AbstractDriverMiddleware;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Logs MariaDB/MySQL connection-establishment failures on the `database`
+ * channel, reading the raw driver error code (a middleware sits below DBAL's
+ * exception conversion, which does not classify 1040/1203/2003/2013 as
+ * ConnectionException). Fires for every SAPI and regardless of whether
+ * application code later swallows the exception. The original exception is
+ * rethrown unchanged.
+ */
+final class ConnectionErrorDriver extends AbstractDriverMiddleware
+{
+    /**
+     * MySQL/MariaDB error numbers that indicate connection PRESSURE or
+     * unreachability (as opposed to e.g. a bad credential typo). Logged at
+     * `critical`; other connect failures at `error`.
+     *
+     * @var list<int>
+     */
+    private const CONNECTION_PRESSURE = [
+        1040, // ER_CON_COUNT_ERROR  — too many connections
+        1203, // ER_TOO_MANY_USER_CONNECTIONS
+        1226, // ER_USER_LIMIT_REACHED
+        2002, // CR_CONNECTION_ERROR — can't connect via socket
+        2003, // CR_CONN_HOST_ERROR  — can't connect via TCP (refused / host down)
+        2005, // CR_UNKNOWN_HOST
+    ];
+
+    public function __construct(
+        Driver $driver,
+        private readonly LoggerInterface $logger,
+    ) {
+        parent::__construct($driver);
+    }
+
+    public function connect(array $params): DriverConnection
+    {
+        try {
+            return parent::connect($params);
+        } catch (DriverException $e) {
+            $code = $e->getCode();
+            $level = in_array($code, self::CONNECTION_PRESSURE, true) ? 'critical' : 'error';
+
+            $this->logger->log($level, 'Database connection failed', [
+                'event' => 'db.connection_error',
+                'db.error_code' => $code,
+                'db.sqlstate' => $e->getSQLState(),
+                'db.host' => $params['host'] ?? null,   // host only — never password/DSN
+                'exception' => $e,
+            ]);
+
+            throw $e;
+        }
+    }
+}

src/Doctrine/Middleware/ConnectionErrorMiddleware.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Doctrine\Middleware;
+
+use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Driver\Middleware;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Wraps the DBAL driver so connection-establishment failures are logged on the
+ * `database` channel before they propagate (ADR 011). Logging only — there is
+ * no reconnect/retry.
+ */
+final class ConnectionErrorMiddleware implements Middleware
+{
+    public function __construct(
+        private readonly LoggerInterface $logger,
+    ) {}
+
+    public function wrap(Driver $driver): Driver
+    {
+        return new ConnectionErrorDriver($driver, $this->logger);
+    }
+}

tests/Doctrine/Middleware/ConnectionErrorDriverTest.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Doctrine\Middleware;
+
+use App\Doctrine\Middleware\ConnectionErrorDriver;
+use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Driver\Exception as DriverException;
+use Monolog\Handler\TestHandler;
+use Monolog\Level;
+use Monolog\Logger;
+use PHPUnit\Framework\TestCase;
+
+class ConnectionErrorDriverTest extends TestCase
+{
+    public function testConnectionPressureCodeIsLoggedAsCriticalWithoutSecrets(): void
+    {
+        $handler = new TestHandler();
+        $driver = $this->driverThrowing(2003, 'HY000'); // CR_CONN_HOST_ERROR
+
+        $this->expectException(DriverException::class);
+
+        try {
+            (new ConnectionErrorDriver($driver, new Logger('database', [$handler])))
+                ->connect(['host' => 'db.internal', 'password' => 's3cr3t', 'user' => 'app']);
+        } finally {
+            $records = $handler->getRecords();
+            $this->assertCount(1, $records);
+            $record = $records[0];
+
+            $this->assertSame(Level::Critical, $record->level);
+            $this->assertSame('database', $record->channel);
+            $this->assertSame('Database connection failed', $record->message);
+            $this->assertSame('db.connection_error', $record->context['event']);
+            $this->assertSame(2003, $record->context['db.error_code']);
+            $this->assertSame('HY000', $record->context['db.sqlstate']);
+            $this->assertSame('db.internal', $record->context['db.host']);
+
+            // The middleware logs the host only — never the password or DSN.
+            $serialised = json_encode($record->toArray(), JSON_THROW_ON_ERROR | JSON_PARTIAL_OUTPUT_ON_ERROR);
+            $this->assertStringNotContainsString('s3cr3t', $serialised);
+            $this->assertArrayNotHasKey('password', $record->context);
+        }
+    }
+
+    public function testCredentialErrorIsLoggedAsError(): void
+    {
+        $handler = new TestHandler();
+        $driver = $this->driverThrowing(1045, '28000'); // ER_ACCESS_DENIED_ERROR
+
+        try {
+            (new ConnectionErrorDriver($driver, new Logger('database', [$handler])))
+                ->connect(['host' => 'db.internal']);
+            $this->fail('Expected the driver exception to be rethrown.');
+        } catch (DriverException) {
+            $record = $handler->getRecords()[0];
+            $this->assertSame(Level::Error, $record->level);
+            $this->assertSame(1045, $record->context['db.error_code']);
+        }
+    }
+
+    private function driverThrowing(int $code, string $sqlState): Driver
+    {
+        $exception = new class($code, $sqlState) extends \RuntimeException implements DriverException {
+            public function __construct(
+                int $code,
+                private readonly string $sqlState,
+            ) {
+                parent::__construct('driver failure', $code);
+            }
+
+            public function getSQLState(): ?string
+            {
+                return $this->sqlState;
+            }
+        };
+
+        $driver = $this->createMock(Driver::class);
+        $driver->method('connect')->willThrowException($exception);
+
+        return $driver;
+    }
+}