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.
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
composer require flytachi/winter-service-mariadbIt 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:
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:
php call service dockerThe 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:
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.
docker compose up -d --build3. Start it. On the first start the log says:
[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: HttpMariaDB 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.
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:
- No
mariadbdin the image → the start stops: “Add it to the image: call service docker”. - No data yet →
mariadb-install-db. A directory that holds files but no MariaDB data is not initialised over — the start stops. - Before the server takes connections — in bootstrap mode, without a single
connection:
rootkeeps the socket, for the system’srootonly (unix_socket):mariadb-install-dbmakes a passwordlessrootfor127.0.0.1,::1and the host name too, and over TCP that would be anyone’s way in — those accounts go;healthcheckis 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'@'%'); withouthostthat account goes.
- 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:
docker compose exec -u root server mariadb --socket=/run/mysqld/mysqld.sock -u rootA 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:
$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 nameWith PDO
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,
]);
}
}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:
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();
}
}protected static function components(Components $components): void
{
$components->service(MainDbConfig::service());
}Repositories point at it as at any configuration:
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:
(HTTP workers + the processes, daemons, scheduler, WebSockets that use the database)
× $poolMaxConnections
+ ~5 — the client, migrations, checksBy 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).
[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_LEVELapplies to the database too.LOG_LEVEL=warningkeeps 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 atERROR.
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:
[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 completeMariaDB 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
- Services — what they are and how they work.
- PostgreSQL and Redis — the other ready-made services.
- Database configuration —
MySqlDbConfigand the connection pool.