MariaDB
winter-service-mariadb — готовый сервис MariaDB. Приложение поднимает базу раньше всего
остального, ждёт, пока она ответит, проверяет её, пока она работает, перезапускает после
падения или зависания и останавливает последней — обычной остановкой.
Что это и зачем
Что это. Класс MariaDb, реализующий Service:
он знает, как запустить MariaDB в контейнере приложения, как понять, что она готова, как
её остановить и что ей нужно в образе.
Проблема. Своя MariaDB в контейнере — это mariadb-install-db при первом старте,
учётная запись приложения с паролем и базой, root, который не должен быть доступен по
сети, системный конфиг Alpine, который выключает сеть, часовой пояс сервера и верный
сигнал остановки. Каждый проект собирает это заново.
Решение. Всё это — в пакете и проверено на настоящем сервере. В проекте остаётся одна строка.
Пакет запускает сервер. Подключаются к нему как обычно — через PDO или
winter-ppa, см. Подключение.
Установка
composer require flytachi/winter-service-mariadbНужны PHP 8.4+, flytachi/winter-kernel 4.5+ и образ flytachi/winter (Alpine): сам
сервер ставится из apk, и call service docker добавляет его в образ. В Alpine 3.24 —
MariaDB 11.8, одна версия, поэтому параметра версии у сервиса нет.
Быстрый старт
1. Объявить:
use Flytachi\Winter\Service\MariaDb\MariaDb;
protected static function components(Components $components): void
{
$components->service(new MariaDb(database: 'app', password: env('DB_PASSWORD')));
}2. Добавить в образ:
php call service dockerВ Dockerfile появится apk add mariadb mariadb-client tzdata и каталоги с владельцем
winter. Compose команда не трогает — она печатает, что в него добавить:
services:
server:
stop_grace_period: 70s
volumes:
- mariadb-data:/var/lib/mysql
volumes:
mariadb-data:stop_grace_period— нужен всегда: HTTP 30 с + MariaDB 30 с + 5 + 5. У Docker по умолчанию 10 секунд, потом он убивает контейнер посреди остановки.- Том — если база должна пережить пересоздание контейнера.
docker compose up -d --build3. Запустить. При первом старте в логе:
[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 поднимается раньше HTTP: первый запрос приходит, когда база уже отвечает.
Параметры
Сервер
| Параметр | По умолчанию | Что задаёт |
|---|---|---|
data |
/var/lib/mysql |
Каталог данных — его держат в томе |
socket |
/run/mysqld |
Каталог Unix-сокета (mysqld.sock) |
host |
null |
null — только сокет, снаружи контейнера не подключиться. 127.0.0.1 — ещё и TCP внутри контейнера. 0.0.0.0 — и для других контейнеров. С host нужен пароль |
port |
3306 |
Порт TCP |
user |
'winter' |
Учётная запись приложения: все права на свою базу, за её пределами — никаких. Создаётся, если её нет |
password |
null |
Её пароль. Спрашивается при каждом подключении — и через сокет тоже. Применяется на каждом старте: сменили в коде — сменился в базе |
database |
null |
База приложения; создаётся, если её нет. null — база с именем пользователя (winter) |
charset |
'utf8mb4' |
Кодировка сервера и базы |
collation |
null |
Сравнение; null — по умолчанию для кодировки |
timezone |
null |
Часовой пояс сервера, ставится на каждом старте: по нему считают NOW() и CURDATE(). null — как у приложения, TIME_ZONE (без него — UTC). Имя IANA, Asia/Tashkent |
settings |
[] |
Опции сервера, каждая уходит как --ключ=значение: ['innodb_buffer_pool_size' => '512M', 'max_connections' => 60]; true/false становятся ON/OFF |
args |
[] |
Другие аргументы mariadbd как есть |
logs |
true |
Писать ли лог MariaDB в лог приложения — см. Лог. false — как пишет сама MariaDB |
Системные файлы настроек (/etc/my.cnf, /etc/my.cnf.d/) не читаются: сервер такой, как
говорят параметры, и ничего сверх. Конфиг самого Alpine выключает сеть — с ним host не
заработал бы.
Компонент
| Параметр | По умолчанию | Что задаёт |
|---|---|---|
name |
'mariadb' |
Имя в логах и app status; том в подсказке compose — {name}-data |
priority |
Priority::High |
Стартует раньше остальных, останавливается после них |
critical |
true |
Не может работать — приложение останавливается |
retries |
3 |
Перезапуски после падения за 30 минут |
grace |
30.0 |
Секунды на остановку до SIGKILL |
startTimeout |
60 |
Секунды, чтобы стать готовой; первый старт создаёт данные |
alive |
true |
true — mariadb-admin ping от healthcheck раз в 10 с, 5 с на ответ, 6 неудач подряд значат «зависла». Свой Probe. null или false — не проверять |
Всё проверяется при создании объекта: относительный путь, порт вне диапазона, host без
пароля, имя пользователя или базы не из букв, цифр и _, user: 'root',
database: 'mysql', неизвестный часовой пояс, настройка, которую сервис ставит сам
(bind_address, port, character_set_server…), значение в две строки — каждое даёт
InvalidArgumentException с объяснением.
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,
],
);Что происходит при старте
Перед сервером работает скрипт пакета, который затем сам становится сервером
(exec), поэтому сигнал остановки приходит прямо MariaDB:
mariadbdнет в образе → старт останавливается: «Add it to the image: call service docker».- Данных нет →
mariadb-install-db. Каталог, в котором лежат файлы, но не данные MariaDB, не инициализируется поверх — старт останавливается. - До того, как сервер начнёт принимать подключения — в режиме bootstrap, без единого
подключения:
rootостаётся только на сокете и только для системногоroot(unix_socket):mariadb-install-dbсоздаётrootбез пароля ещё и для127.0.0.1,::1и имени хоста, и по TCP это был бы вход для любого — эти записи удаляются;- есть
healthcheck— запись для проверки готовности, без прав; - базы нет → она создаётся, и это видно в логе;
- учётной записи приложения нет → она создаётся; пароль ставится тот, что в коде, права
— на свою базу. С
host— то же для TCP ('user'@'%'); безhostэта запись удаляется.
- Запуск сервера:
mariadbd --no-defaults --datadir=… --socket=… --skip-name-resolve …
Пароль попадает в скрипт через переменную окружения, а в сервер — через трубу: его нет ни в командной строке, которую видит любой процесс контейнера, ни на диске.
Учётные записи
| Запись | Откуда | Как входит | Права |
|---|---|---|---|
root |
только сокет | как системный root (unix_socket) |
все: администратор |
healthcheck |
только сокет | без пароля | никаких: проверка готовности |
user (winter) |
сокет; с host — и TCP |
с password |
все на свою базу, за её пределами — никаких |
Учётная запись приложения не может создавать базы и пользователей, читать mysql.user,
выдавать права и менять глобальные настройки. SQL-инъекция через соединение приложения
остаётся в пределах его базы — это вторая линия обороны; первая — запросы с параметрами,
как их строит winter-ppa.
Администратору — root через сокет, от системного root:
docker compose exec -u root server mariadb --socket=/run/mysqld/mysqld.sock -u rootЗабытый пользователь — отказ, а не root
Приложение работает от системного winter, поэтому root в базе ему недоступен. Конфиг,
который забыл указать пользователя (у MySqlDbConfig по умолчанию — root), получит
Access denied, а не все права.
Подключение
Объект MariaDb знает, где его сервер:
$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Через 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());
}Через winter-ppa
Естественное место — класс конфигурации базы winter-ppa:
один и тот же класс и запускает сервер, и подключается к нему. Драйвер MySQL в PDO
принимает сокет как unix_socket, а не как host, поэтому конфигурация отдаёт 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());
}Репозитории ссылаются на неё, как на любую конфигурацию:
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();Если база открыта по TCP (задан host, подключаются другие контейнеры), getDns() не
переопределяют, а в setUp() задают host — 127.0.0.1 или имя контейнера — и port.
Сколько соединений
У MariaDB по умолчанию max_connections = 151. Пул winter-ppa держит соединения в
каждом процессе, а не на всё приложение, поэтому посчитайте, сколько их может открыться
сразу:
(воркеры HTTP + процессы, демоны, планировщик, WebSocket — те, что ходят в базу)
× $poolMaxConnections
+ ~5 — клиент, миграции, проверкиПо умолчанию это 1 воркер × 5 = 5 соединений. Упирается обычно, когда растят воркеры:
8 воркеров (SERVER_WORKERS=8) × пул 20 — уже 160, и под пиком нагрузки сервер начнёт
отвечать Too many connections. Тогда либо уменьшите пул, либо поднимите предел —
settings: ['max_connections' => 300] — с оглядкой на память контейнера.
Лог
Лог MariaDB идёт в лог приложения: в том же формате, канал -mariadb- (в цвете — синий,
чтобы не путать со строками приложения).
[2026-11-15 16:20:11] [WARN ] -mariadb- [10]: Access denied for user 'winter'@'localhost' (using password: YES) {"thread":7}| MariaDB | Лог |
|---|---|
Note |
INFO |
Warning |
WARN |
ERROR |
ERROR |
- Строка соединения несёт в контексте номер его потока:
{"thread":7}. Строки самого сервера (поток 0) — без него. LOG_LEVELдействует и на базу.LOG_LEVEL=warningоставляет предупреждения и ошибки.- Ошибочный запрос клиента MariaDB в свой лог не пишет: эта ошибка приходит клиенту.
- Строки скрипта старта (
created database app for winter.) — тоже в канале-mariadb-; его ошибки — с уровнемERROR.
Лог выключен — база тоже молчит
Строки MariaDB идут через логгер приложения, поэтому без LOG_LEVEL (лог выключен) не
видно и их — в том числе причины, по которой база не стартовала. Чтобы увидеть её,
задайте LOG_LEVEL=error или logs: false: тогда MariaDB пишет свой вывод напрямую.
Остановка
SIGTERM — обычная остановка: соединения закрываются, InnoDB дописывает, что держит в
памяти, сервер выходит с кодом 0. В логе:
[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 останавливается последней, после HTTP, поэтому контейнеру нужен
stop_grace_period: 70s: 30 секунд на HTTP, 30 на MariaDB и по 5 запаса приложению и
контейнеру. Зависшая база — проверка alive не прошла 6 раз подряд — останавливается по
ступеням и перезапускается, как описано в alive.
Обновление
Минорные версии (11.8.8 → 11.8.9) приходят с очередной сборкой образа и ничего не
требуют. Новая мажорная версия приходит с новым выпуском Alpine: MariaDB читает данные
прежней версии, а mariadb-upgrade, запущенный один раз вручную после первого старта,
обновляет её системные таблицы. Выгрузку перед этим всё равно сделайте
(mariadb-dump --all-databases).
Дальше
- Сервисы — что это и как устроено.
- PostgreSQL и Redis — другие готовые сервисы.
- Конфигурация базы —
MySqlDbConfigи пул соединений.