Сервисы · Пакет

MariaDB

winter-service-mariadb — готовый сервис MariaDB. Приложение поднимает базу раньше всего остального, ждёт, пока она ответит, проверяет её, пока она работает, перезапускает после падения или зависания и останавливает последней — обычной остановкой.

Пакет flytachi/winter-service-mariadbКласс MariaDbВерсия 11.8 (Alpine 3.24)

Что это и зачем

Что это. Класс MariaDb, реализующий Service: он знает, как запустить MariaDB в контейнере приложения, как понять, что она готова, как её остановить и что ей нужно в образе.

Проблема. Своя MariaDB в контейнере — это mariadb-install-db при первом старте, учётная запись приложения с паролем и базой, root, который не должен быть доступен по сети, системный конфиг Alpine, который выключает сеть, часовой пояс сервера и верный сигнал остановки. Каждый проект собирает это заново.

Решение. Всё это — в пакете и проверено на настоящем сервере. В проекте остаётся одна строка.

Пакет запускает сервер. Подключаются к нему как обычно — через PDO или winter-ppa, см. Подключение.

Установка

bash
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. Объявить:

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. Добавить в образ:

bash
php call service docker

В Dockerfile появится apk add mariadb mariadb-client tzdata и каталоги с владельцем winter. Compose команда не трогает — она печатает, что в него добавить:

docker-compose.yml
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 секунд, потом он убивает контейнер посреди остановки.
  • Том — если база должна пережить пересоздание контейнера.
bash
docker compose up -d --build

3. Запустить. При первом старте в логе:

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 поднимается раньше 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 с объяснением.

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,
  ],
);

Что происходит при старте

Перед сервером работает скрипт пакета, который затем сам становится сервером (exec), поэтому сигнал остановки приходит прямо MariaDB:

  1. mariadbd нет в образе → старт останавливается: «Add it to the image: call service docker».
  2. Данных нет → mariadb-install-db. Каталог, в котором лежат файлы, но не данные MariaDB, не инициализируется поверх — старт останавливается.
  3. До того, как сервер начнёт принимать подключения — в режиме bootstrap, без единого подключения:
    • root остаётся только на сокете и только для системного root (unix_socket): mariadb-install-db создаёт root без пароля ещё и для 127.0.0.1, ::1 и имени хоста, и по TCP это был бы вход для любого — эти записи удаляются;
    • есть healthcheck — запись для проверки готовности, без прав;
    • базы нет → она создаётся, и это видно в логе;
    • учётной записи приложения нет → она создаётся; пароль ставится тот, что в коде, права — на свою базу. С host — то же для TCP ('user'@'%'); без host эта запись удаляется.
  4. Запуск сервера: 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:

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

Забытый пользователь — отказ, а не root

Приложение работает от системного winter, поэтому root в базе ему недоступен. Конфиг, который забыл указать пользователя (у MySqlDbConfig по умолчанию — root), получит Access denied, а не все права.

Подключение

Объект MariaDb знает, где его сервер:

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

Через 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());
}

Через winter-ppa

Естественное место — класс конфигурации базы winter-ppa: один и тот же класс и запускает сервер, и подключается к нему. Драйвер MySQL в PDO принимает сокет как unix_socket, а не как host, поэтому конфигурация отдаёт 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());
}

Репозитории ссылаются на неё, как на любую конфигурацию:

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();

Если база открыта по TCP (задан host, подключаются другие контейнеры), getDns() не переопределяют, а в setUp() задают host — 127.0.0.1 или имя контейнера — и port.

Сколько соединений

У MariaDB по умолчанию max_connections = 151. Пул winter-ppa держит соединения в каждом процессе, а не на всё приложение, поэтому посчитайте, сколько их может открыться сразу:

text
(воркеры HTTP + процессы, демоны, планировщик, WebSocket — те, что ходят в базу)
× $poolMaxConnections
+ ~5 — клиент, миграции, проверки

По умолчанию это 1 воркер × 5 = 5 соединений. Упирается обычно, когда растят воркеры: 8 воркеров (SERVER_WORKERS=8) × пул 20 — уже 160, и под пиком нагрузки сервер начнёт отвечать Too many connections. Тогда либо уменьшите пул, либо поднимите предел — settings: ['max_connections' => 300] — с оглядкой на память контейнера.

Лог

Лог MariaDB идёт в лог приложения: в том же формате, канал -mariadb- (в цвете — синий, чтобы не путать со строками приложения).

text
[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. В логе:

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 останавливается последней, после 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).

Дальше