CLI · Winter Console

Команда db

db управляет подключениями к БД и генерацией схемы: ping проверяет соединения, migrate создаёт таблицы из атрибутов сущностей, sql показывает сгенерированный DDL без выполнения.

Субкоманды ping · migrate · sql · poolСхема из #[Migratable] конфиговТребует flytachi/winter-ppa

Команда живёт на пакете winter-ppa

Слой базы данных в ядро не входит — он ставится отдельно. Без него db не работает целиком, включая ping: любая субкоманда отвечает и не выполняется.

text
 | [=================================== Db ===================================]
| [!] The 'db' command needs the database layer, which is not installed.
| [i] Add it with:  composer require flytachi/winter-ppa
| [=================================== Db ===================================]

Отказ полный, а не частичный, намеренно. Работай половина субкоманд — вывод был бы «команда сломана», и искать причину пошли бы не туда. Не работает ничего и сказано почему — вывод «не хватает пакета», и это правда.

call db --help печатается и без пакета: именно из справки видно, что это за команда и зачем ставить зависимость. Строку Requires она показывает всегда, а когда пакета нет — дополнительно предупреждает.

Что такое db и зачем

db — консольный интерфейс к базе данных проекта.

Проблема. Нужно проверять, что приложение достаёт до БД, и поднимать схему на новой машине. Делать это внешними утилитами и вручную — лишние шаги.

Решение. db даёт проверку связи и генерацию схемы прямо из кода проекта — по всем сконфигурированным подключениям. Об этом и раздел.

Субкоманды

Субкоманда Назначение
ping Подключиться к каждой конфигурации, показать драйвер, DSN, задержку и статус
migrate Выполнить DDL (сгруппированный по типам)
sql Напечатать DDL в stdout без выполнения (предпросмотр)
pool Показать загрузку пула соединений работающего сервера
bash
php call db ping
php call db sql        # предпросмотр
php call db migrate    # выполнить

Флаги фаз (migrate и sql)

Выбирают, какие части схемы генерировать. Без флагов — все пять:

Флаг Фаза Примечание
-e Extensions только pgsql
-s Schemes только pgsql
-t Tables —
-i Indexes —
-c Constraints FK, CHECK
bash
php call db migrate          # все фазы
php call db migrate -t -i     # только таблицы + индексы

Область (плагины)

Опция Область
(нет) Приложение (Project)
--plugin=<name> Один плагин
--plugins Все плагины
bash
php call db migrate --plugin=acme/billing
php call db sql --plugin=acme/billing -s

ping всегда пингует всё

Опции --plugin / --plugins действуют только на migrate и sql. Команда db ping всегда проверяет приложение и все плагины, игнорируя эти опции.

Поведение миграции

  • Выполняются только #[Migratable]-конфиги, в порядке приоритета High → Normal → Low.
  • Повторный запуск: IF NOT EXISTS есть только у расширений; для остального ошибка «объект уже существует» превращается в [EXIST], а не [FAILED] (pgsql 42P06/42P07/42710, mysql 42S01 и код драйвера 1061 для индексов). Существующее ограничение на MySQL и любой повтор на SQLite так не распознаются и дают [FAILED] — подробности в Миграциях.
  • При DEBUG=true в ответе виден текст SQL-ошибки для [FAILED].

Полные правила генерации схемы, опт-ин и ограничения — на странице Миграции.

db pool — загрузка пула

bash
php call db pool
text
 | [==================== Connection pools — web workers ====================]
| [ Main\MainDbConfig ]
|       active       12
|       idle         3
|       total        15
|       maximum      20
|       workers      2
|       saturated    1 of 2 workers
|       Main\MainDbConfig ........................................... [SATURATED]
| [===================== Connection pools — processes =====================]
| [ Main\MainDbConfig ]
|       active       4
|       idle         2
|       total        6
|       maximum      10
|       processes    2
|       Main\MainDbConfig ........................................... [OK]
|       open connections per config
|       Main\MainDbConfig                        21  (web 15 + processes 6)
|       per source
|       worker#0                 Main\MainDbConfig                        active=2 idle=3 total=5 max=10  pid=4101  age=0s
|       worker#1                 Main\MainDbConfig                        active=10 idle=0 total=10 max=10  pid=4102  age=3s
|       process Main\Process\ReportProcess Main\MainDbConfig                        active=1 idle=1 total=2 max=5  pid=4120  age=1s
|       daemon Main\Daemon\Emails.0 Main\MainDbConfig                        active=3 idle=1 total=4 max=5  pid=4131  age=2s

Пул есть у каждого процесса ОС: у каждого веб-воркера, у каждого процесса и у каждого воркера демона. Поэтому вывод разделён на группы — веб-воркеры и процессы, — а в конце идут строки по каждому источнику с его pid. В каждой группе по конфигурации выводятся суммы active, idle, total, maximum и число источников (workers или processes) и бейдж: [OK] или [SATURATED], если хотя бы у одного источника пул занят полностью (строка saturated говорит, у скольких).

Смотреть нужно на строки источников, а не на общий итог: запрос ждёт освобождения в пуле своего процесса, поэтому один забитый воркер или процесс — это реальные задержки, даже когда суммарно места достаточно. Строка «open connections per config» — сколько соединений приложение держит открытыми по каждой конфигурации; её сравнивают с max_connections самой базы (если несколько конфигураций смотрят на один сервер, их числа складываются).

Данные приходят от работающего сервера

Консоль — отдельный процесс и в память сервера заглянуть не может, поэтому воркеры и процессы сами публикуют статистику по таймеру (PPA_POOL_TELEMETRY, по умолчанию 5 секунд). Остановившийся процесс убирает свою запись сразу.

Если сервер не запущен или ещё ни разу не открывал соединение, команда честно скажет, что телеметрии нет. Подробнее — как устроен пул.

Дальше