Services · Package

MariaDB

winter-service-mariadb is a ready-made MariaDB service. The application starts the database before everything else, waits until it answers, keeps checking it while it runs, restarts it after a crash or a hang, and stops it last — with a normal shutdown.

Package flytachi/winter-service-mariadbClass MariaDbVersion 11.8 (Alpine 3.24)

What it is and why

What it is. The MariaDb class, implementing Service: it knows how to start MariaDB in the application’s container, how to tell it is ready, how to stop it, and what it needs in the image.

The problem. A MariaDB of your own in a container means mariadb-install-db on the first start, an account for the application with its password and database, a root that must not be reachable over the network, Alpine’s own configuration that turns networking off, the server’s time zone and the right stop signal. Every project puts this together again.

The solution. All of it is in the package, tested against a real server. One line is left in the project.

The package runs the server. You connect to it as usual — through PDO or winter-ppa, see Connecting.

Installation

bash
composer require flytachi/winter-service-mariadb

It needs PHP 8.4+, flytachi/winter-kernel 4.5+ and the flytachi/winter image (Alpine): the server itself comes from apk, and call service docker adds it to the image. Alpine 3.24 has MariaDB 11.8, one version — so the service has no version parameter.

Quick start

1. Declare it:

bootstrap.php
use Flytachi\Winter\Service\MariaDb\MariaDb;

protected static function components(Components $components): void
{
  $components->service(new MariaDb(database: 'app', password: env('DB_PASSWORD')));
}

2. Add it to the image:

bash
php call service docker

The Dockerfile gets apk add mariadb mariadb-client tzdata and the directories owned by winter. The command does not touch compose — it prints what to add:

docker-compose.yml
services:
server:
  stop_grace_period: 70s
  volumes:
    - mariadb-data:/var/lib/mysql
volumes:
mariadb-data:
  • stop_grace_period — always needed: HTTP 30 s + MariaDB 30 s + 5 + 5. Docker’s default is 10 seconds, after which it kills the container mid-shutdown.
  • The volume — if the database must outlive a recreated container.
bash
docker compose up -d --build

3. Start it. On the first start the log says:

text
[2026-11-15 16:12:37] [INFO ] -sys- [1]: Application starting High: mariadb
[2026-11-15 16:12:38] [INFO ] -mariadb- [10]: initialised MariaDB 11.8.9 data in /var/lib/mysql.
[2026-11-15 16:12:38] [INFO ] -mariadb- [10]: created database app for winter.
[2026-11-15 16:12:39] [INFO ] -mariadb- [10]: mariadbd: ready for connections.
[2026-11-15 16:12:39] [INFO ] -sys- [1]: mariadb is up.
[2026-11-15 16:12:39] [INFO ] -sys- [1]: Application starting Normal: Http

MariaDB is up before HTTP: the first request comes with the database already answering.

Parameters

The server

Parameter Default What it sets
data /var/lib/mysql The data directory — keep it in a volume
socket /run/mysqld The directory of the Unix socket (mysqld.sock)
host null null — the socket only, nothing outside the container connects. 127.0.0.1 — TCP inside the container too. 0.0.0.0 — other containers as well. A host needs a password
port 3306 The TCP port
user 'winter' The application’s account: all rights on its database, none past it. Created when it is missing
password null Its password, asked for on every connection — through the socket too. Applied on every start: changed in the code, changed in the server
database null The application’s database, created when it is missing. null — named after the user (winter)
charset 'utf8mb4' The character set of the server and of the database
collation null The collation; null — the character set’s default
timezone null The server’s time zone, set on every start: what NOW() and CURDATE() count by. null — the application’s, TIME_ZONE (UTC without it). An IANA name, Asia/Tashkent
settings [] Server options, each passed as --key=value: ['innodb_buffer_pool_size' => '512M', 'max_connections' => 60]; true/false become ON/OFF
args [] Further mariadbd arguments, as they are
logs true Whether MariaDB’s log goes into the application’s — see Log. false — as MariaDB writes it

The system’s option files (/etc/my.cnf, /etc/my.cnf.d/) are not read: the server is what the parameters say, nothing more. Alpine’s own turns networking off — with it, host would not work.

The component

Parameter Default What it sets
name 'mariadb' Its name in logs and app status; the volume in the compose hint is {name}-data
priority Priority::High Starts before the rest, stops after them
critical true When it cannot run, the application stops
retries 3 Restarts after a crash within 30 minutes
grace 30.0 Seconds to stop before SIGKILL
startTimeout 60 Seconds to become ready; a first start creates the data
alive true true — mariadb-admin ping as healthcheck every 10 s, 5 s for an answer, 6 misses in a row mean it hangs. A Probe of your own. null or false — not checked

Everything is checked when the object is made: a relative path, a port out of range, a host without a password, a user or database name not of letters, digits and _, user: 'root', database: 'mysql', an unknown time zone, a setting the service sets itself (bind_address, port, character_set_server…), a value on two lines — each is an InvalidArgumentException explaining what is wrong.

php
new MariaDb(
  database: 'app',
  password: env('DB_PASSWORD'),
  collation: 'utf8mb4_unicode_ci',
  settings: [
      'innodb-buffer-pool-size' => '512M',
      'innodb-log-file-size' => '128M',
      'tmp-table-size' => '32M',
      'max-heap-table-size' => '32M',
      'performance-schema' => false,
      'max-connections' => 60,
      'wait-timeout' => 900,
  ],
);

What a start does

Before the server, the package’s script runs, and then becomes the server itself (exec), so the stop signal reaches MariaDB directly:

  1. No mariadbd in the image → the start stops: “Add it to the image: call service docker”.
  2. No data yet → mariadb-install-db. A directory that holds files but no MariaDB data is not initialised over — the start stops.
  3. Before the server takes connections — in bootstrap mode, without a single connection:
    • root keeps the socket, for the system’s root only (unix_socket): mariadb-install-db makes a passwordless root for 127.0.0.1, ::1 and the host name too, and over TCP that would be anyone’s way in — those accounts go;
    • healthcheck is there — the readiness check’s account, with no rights;
    • no database → it is created, and the log says so;
    • no application account → it is created; its password is the code’s, its rights its database’s. With host, the same for TCP ('user'@'%'); without host that account goes.
  4. The server starts: mariadbd --no-defaults --datadir=… --socket=… --skip-name-resolve …

The password reaches the script through an environment variable and the server through a pipe: it is neither on the command line, which every process in the container can read, nor on disk.

Accounts

Account Where from How it signs in Rights
root the socket only as the system’s root (unix_socket) all: an administrator
healthcheck the socket only without a password none: the readiness check
user (winter) the socket; with host, TCP too with password all on its database, none past it

The application’s account cannot create databases or accounts, read mysql.user, grant rights or change global settings. An SQL injection through the application’s connection stays within its database — the second line of defence; the first is parameterised queries, as winter-ppa builds them.

An administrator — root through the socket, as the system’s root:

bash
docker compose exec -u root server mariadb --socket=/run/mysqld/mysqld.sock -u root

A forgotten user is refused, not root

The application runs as the system’s winter, so the database’s root is out of its reach. A configuration that forgot its user (MySqlDbConfig’s default is root) gets Access denied, not every right.

Connecting

The MariaDb object knows where its server is:

php
$db->dsn();          // mysql:unix_socket=/run/mysqld/mysqld.sock;dbname=app;charset=utf8mb4
$db->socketPath();   // /run/mysqld/mysqld.sock
$db->user;           // winter
$db->database;       // app — without database: winter, the user's name

With PDO

main/Db.php
namespace Main;

use Flytachi\Winter\Service\MariaDb\MariaDb;

final class Db
{
  public static function service(): MariaDb
  {
      return new MariaDb(database: 'app', password: env('DB_PASSWORD'));
  }

  public static function connect(): \PDO
  {
      $db = self::service();
      return new \PDO($db->dsn(), $db->user, $db->password, [
          \PDO::ATTR_ERRMODE => \PDO::ERRMODE_EXCEPTION,
      ]);
  }
}
bootstrap.php
protected static function components(Components $components): void
{
  $components->service(Db::service());
}

With winter-ppa

The natural place is winter-ppa’s database configuration class: one and the same class runs the server and connects to it. PDO’s MySQL driver takes a socket as unix_socket, not as a host, so the configuration gives the service’s DSN:

main/Configs/MainDbConfig.php
namespace Main\Configs;

use Flytachi\Winter\Cdo\Config\MySqlDbConfig;
use Flytachi\Winter\Ppa\Pool\PpaPoolConfigInterface;
use Flytachi\Winter\Ppa\Pool\PpaPoolTrait;
use Flytachi\Winter\Service\MariaDb\MariaDb;

class MainDbConfig extends MySqlDbConfig implements PpaPoolConfigInterface
{
  use PpaPoolTrait;

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

  /** What the application runs. */
  public static function service(): MariaDb
  {
      return new MariaDb(database: 'app', password: env('DB_PASSWORD'));
  }

  /** How winter-ppa connects to it. */
  public function setUp(): void
  {
      $db = self::service();
      $this->database = $db->database;
      $this->username = $db->user;
      $this->password = $db->password ?? '';
  }

  /** Through the socket: PDO's MySQL driver takes it as unix_socket. */
  public function getDns(): string
  {
      return self::service()->dsn();
  }
}
bootstrap.php
protected static function components(Components $components): void
{
  $components->service(MainDbConfig::service());
}

Repositories point at it as at any configuration:

php
class RecordRepository extends Repository
{
  protected string $dbConfigClassName = MainDbConfig::class;
  protected string $entityClassName = Record::class;
  public static string $table = 'records';
}

$records = RecordRepository::instance()->orderBy('id')->findAll();

Over TCP (host set, other containers connecting) getDns() is not overridden, and setUp() sets host — 127.0.0.1 or the container’s name — and port.

How many connections

MariaDB’s default is max_connections = 151. winter-ppa’s pool holds its connections in every process, not for the whole application, so count how many can be open at once:

text
(HTTP workers + the processes, daemons, scheduler, WebSockets that use the database)
× $poolMaxConnections
+ ~5 — the client, migrations, checks

By default that is 1 worker × 5 = 5 connections. It is usually hit when the workers grow: 8 workers (SERVER_WORKERS=8) × a pool of 20 is 160 already, and at a peak the server starts answering Too many connections. Then make the pool smaller, or raise the limit — settings: ['max_connections' => 300] — with the container’s memory in mind.

Log

MariaDB’s log goes into the application’s: in the same format, under the -mariadb- channel (blue in colour, not to be taken for the application’s lines).

text
[2026-11-15 16:20:11] [WARN ] -mariadb- [10]: Access denied for user 'winter'@'localhost' (using password: YES) {"thread":7}
MariaDB Log
Note INFO
Warning WARN
ERROR ERROR
  • A connection’s line carries its thread in the context: {"thread":7}. The server’s own lines (thread 0) do not.
  • LOG_LEVEL applies to the database too. LOG_LEVEL=warning keeps the warnings and errors.
  • A client’s failed query is not in MariaDB’s log: that error goes to the client.
  • The start script’s lines (created database app for winter.) are in the -mariadb- channel too; its errors at ERROR.

Log off — the database is silent too

MariaDB’s lines go through the application’s logger, so without LOG_LEVEL (the log off) they are not seen either — the reason the database did not start among them. To see it, set LOG_LEVEL=error, or logs: false: MariaDB then writes its output directly.

Stopping

SIGTERM — a normal shutdown: the connections close, InnoDB writes what it holds in memory, the server exits 0. The log says:

text
[2026-11-15 16:13:05] [INFO ] -mariadb- [10]: mariadbd (initiated by: unknown): Normal shutdown
[2026-11-15 16:13:05] [INFO ] -mariadb- [10]: mariadbd: Shutdown complete

MariaDB stops last, after HTTP, so the container needs stop_grace_period: 70s: 30 seconds for HTTP, 30 for MariaDB and 5 each of margin for the application and the container. A hung database — its alive check failed 6 times in a row — is stopped by steps and restarted, as alive describes.

Upgrading

Minor versions (11.8.8 → 11.8.9) come with the image’s next build and need nothing. A new major version comes with a new Alpine release: MariaDB reads the previous version’s data, and mariadb-upgrade, run once by hand after the first start, brings its system tables up to date. Take a dump before all the same (mariadb-dump --all-databases).

Next