Database connection

A configuration describes one connection endpoint: driver, address, credentials, schema. The pool builds all of its connections from it, so everything that must be identical across connections lives here — and this is also where migrations are enabled.

Why a class, not an array

An array in config/database.php is the familiar shape, but it knows nothing about itself: a typo in a key shows up at runtime, and “which databases does this project even have” is answered by eye.

A class solves three problems at once: the class name becomes the identifier a repository points at; the scanner finds every configuration on its own, so migrations and health checks need no registry; and properties are typed, so $port will not quietly be a string.

Declaring one

<?php

namespace Main\Configurations;

use Flytachi\Winter\Cdo\Config\PgDbConfig;

class MainDbConfig extends PgDbConfig
{
  public function setUp(): void
  {
      $this->host     = env('DB_HOST', 'localhost');
      $this->port     = (int) env('DB_PORT', 5432);
      $this->database = env('DB_NAME', 'app');
      $this->username = env('DB_USER', 'postgres');
      $this->password = env('DB_PASS', '');
  }
}

setUp() runs once per instance created — that is, once per connection in the pool. Reading the environment here is fine; going to the network or to the database is not.

Reference

Base classes

Choosing a base class is choosing a driver. Their property sets differ because different databases accept different things.

PgDbConfig

pgsql:host=db;port=5432;dbname=app;sslmode=disable;

$sslmode defaults to disable — convenient locally and wrong in production: traffic to the database goes in the clear. Managed databases normally want at least require.

MySqlDbConfig

mysql:host=db;port=3306;dbname=app;charset=utf8mb4;

MySQL has no schemas: there the database is the namespace, so getSchema() returns null.

SqliteDbConfig

sqlite:/var/app.sqlite

No server and no credentials — which is exactly why it is handy in tests. :memory: lives as long as the connection does.

DbConfig

The common base: the same properties plus a $driver you set yourself. Use it for a driver that has no dedicated class.

Shared properties

Traits

PpaPoolTrait

Lets a configuration set its own pool size. Without it the defaults apply.

use Flytachi\Winter\Ppa\Pool\{PpaPoolConfigInterface, PpaPoolTrait};

class MainDbConfig extends PgDbConfig implements PpaPoolConfigInterface
{
  use PpaPoolTrait;

  public int   $poolMaxConnections = 10;
  public float $poolWaitTimeout    = 5.0;

  public function setUp(): void { … }
}

The trait declares methods only, no properties — so the class declares them itself and nothing breaks when the interface gains one. How to pick the numbers is covered in Connection pool.

PpaCallTrait

Flytachi\\Winter\\Ppa\\PpaCallTrait — short access to a pooled connection straight from the configuration class:

$cdo = MainDbConfig::instance();   // the current unit of work's connection
$cte = MainDbConfig::cte();        // a CTE repository on the same database

Application code normally goes through a repository; this is the door for infrastructure code — migrations, one-off maintenance queries, CTEs spanning several tables.

Configuration methods

Environment variables

A configuration reads .env through env(), with the fallback as the second argument:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=app
DB_USER=postgres
DB_PASS=secret

The names are yours; the layer does not dictate them. Keep the fallbacks safe for local development: the application should boot on an empty .env rather than die with “no such variable”.

Binding a repository

A repository points at a configuration by class, not by string:

class UserRepository extends Repository
{
  public static string $table         = 'users';
  protected string $dbConfigClassName = MainDbConfig::class;
}

That is what decides which database the query goes to. A rename is handled by the IDE, and a typo becomes a parse-time error instead of a runtime one.

Schema

The schema comes from the configuration ($schema on PostgreSQL) and, when needed, from the repository:

class AuditRepository extends Repository
{
  public static string $table = 'events';
  protected ?string $schema   = 'audit';      // → audit.events
}

A repository’s schema overrides the configuration’s. This is what you want when one database holds several logical spaces: public for the application, audit for journals.

Several databases

One class per connection endpoint:

class MainDbConfig extends PgDbConfig    { /* the main database */ }
class AuditDbConfig extends PgDbConfig   { /* journals, another server */ }
class LegacyDbConfig extends MySqlDbConfig { /* the old system */ }

Each gets its own pool with its own ceiling, and call db pool lists them separately. Repositories are routed between databases by $dbConfigClassName.

Checking connectivity

php call db ping

The command finds every configuration in the project, connects to each and prints the latency. /actuator/health reports the same numbers — there it is pingDetail() doing the work:

{ "status": true, "latency": 1.24, "error": null }

ping() never throws: an unreachable database is false, not an exception. That is why it can be called from a health endpoint without a try.

Opting into migrations

A configuration takes part in migrations only when it says so:

use Flytachi\Winter\Ppa\Mapping\Attributes\Config\{Extension, Migratable};
use Flytachi\Winter\Ppa\Mapping\Constants\MigratablePriority;

#[Migratable(priority: MigratablePriority::High)]
#[Extension('uuid-ossp')]
class MainDbConfig extends PgDbConfig { … }

Without #[Migratable] the command says plainly what is missing:

No migratable configs — add #[Migratable] to a DbConfig to opt in.

The opt-in is not a formality: it keeps the schema tool away from a database somebody else owns — a legacy system the application only reads from, for instance.

Next

• Entities — what describes this database’s tables
• Migrations — how the description reaches the server
• Connection pool — how many connections open, and when