API: DB Facade

API: DB Facade#

Class: Infocyph\DBLayer\DB

The facade is the orchestration layer. It resolves named connections, exposes raw SQL helpers, and proxies advanced runtime controls (pooling, telemetry, timeouts, and retry policy wrappers).

Role in the 3-Layer API#

  • DB: orchestration and infrastructure controls.

  • QueryBuilder: SQL composition surface.

  • Repository: reusable table policy surface.

DB is not a replacement for repository policies. It is the shared gateway that creates builder/repository instances and owns connection/runtime behavior.

Most applications use a mix of:

  • TableRepository subclasses for static class-based repository workflows

  • DB::table() for query builder flows

  • DB::repository() for table-oriented app services

  • DB::transaction() for write consistency boundaries

Connection Methods#

  • addConnection(), connection(), freshConnection(), reconnect(), disconnect()

  • setDefaultConnection(), getDefaultConnection(), hasConnection(), getConnections(), purge()

  • setSecurityDefaults(), hardenProduction()

Raw SQL Methods#

  • select(), selectOne(), selectResultSets(), scalar()

  • insert(), update(), delete(), statement(), unprepared(), batch()

  • stream(), yieldRows()

Builder and Repository#

  • table()

  • repository()

  • raw()

Transactions#

  • beginTransaction(), commit(), rollBack()

  • transaction(), readOnlyTransaction(), transactionLevel(), transactionStats()

Execution Controls#

  • withQueryTimeout()

  • withQueryDeadline()

  • withQueryCancellation()

  • withQueryRetryPolicy()

Observability and Utility#

  • enableLogger(), disableLogger(), logger(), setPsrLogger()

  • enableProfiler(), disableProfiler(), profiler()

  • enableTelemetry(), disableTelemetry(), telemetry(), telemetryOtel()

  • flushTelemetry(), flushTelemetryOtel(), slowQueryReport()

  • setMaxQueryLogEntries(), setProfilerMaxProfiles(), setTelemetryBufferLimits()

  • listen(), whenQueryingForLongerThan()

  • stats(), health(), capabilities(), supportsReturning(), supportsJson(), supportsWindowFunctions()

  • pool(), poolManager(), withPooledConnection()

  • cache(), useFileCache()

  • resetRuntimeState() (useful for long-running workers between requests/jobs)

Long-Running Worker Note#

For worker runtimes (RoadRunner/Swoole/Octane-style loops), call DB::resetRuntimeState() between logical requests/jobs to clear query logs, telemetry/profiler buffers, listeners, and threshold monitors while preserving registered connection configurations.