RUEN
Package · cdo

Logging & diagnostics

CDO logs every generated query through a PSR-3 logger and exposes light health checks on each config. This guide shows how to wire a logger, read the debug output, probe reachability, and recover a stale connection.

Attach a PSR-3 logger

Every config starts with a NullLogger (silent). Provide your own logger and CDO records each query it builds at debug level.

Attach it when the pool first instantiates the config:

php
use Flytachi\Winter\Cdo\ConnectionPool;
use App\Db\AppDb;

// $logger is any Psr\Log\LoggerInterface
ConnectionPool::getConfigDb(AppDb::class, $logger);

$cdo = ConnectionPool::db(AppDb::class);

Or set it directly on a config instance:

php
$config = ConnectionPool::getConfigDb(AppDb::class);
$config->setLogger($logger);

Attach the logger before connecting

The logger is handed to CDO when the connection is opened. Set it before the first connect() / db() call — ConnectionPool::getConfigDb() ignores the $logger argument on every call after the config is first cached.

What gets logged

Each DML method logs the SQL it generates at debug level, prefixed by operation:

Prefix Method
insert: insert()
insert group: insertGroup() (per chunk)
upsert: upsert()
insert or update group: upsertGroup() (per chunk)
update: update()
delete: delete()

The logged string is the query with its :placeholders, not the bound values — so debug logs never leak the data itself.

Health checks

Every config offers two probes, both running a SELECT 1:

php
$config = ConnectionPool::getConfigDb(AppDb::class);

$config->ping();        // bool — reachable?

$config->pingDetail();  // ['status' => bool, 'latency' => float|null (ms), 'error' => string|null]

Use ping() for a readiness check and pingDetail() when you want latency or the error message for a status endpoint.

Recovering a stale connection

Connections can go stale after a long idle period or a server-side timeout. The config exposes the full lifecycle:

php
$config = ConnectionPool::getConfigDb(AppDb::class);

$config->disconnect(); // release the CDO reference
$config->connect();    // reopen lazily
$config->reconnect();  // disconnect + connect in one call

A common pattern is to retry once on failure:

php
use Flytachi\Winter\Cdo\Connection\CDOException;

try {
  $id = ConnectionPool::db(AppDb::class)->insert('events', $event);
} catch (CDOException $e) {
  ConnectionPool::getConfigDb(AppDb::class)->reconnect();
  $id = ConnectionPool::db(AppDb::class)->insert('events', $event);
}