RUEN
CLI · Winter Console

Команда db

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

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

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

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

text
The 'db' command needs the database layer, which is not installed.
Add it with:  composer require flytachi/winter-ppa

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

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=bill
php call db sql --plugin=bill -s

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

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

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

  • Выполняются только #[Migratable]-конфиги, в порядке приоритета High → Normal → Low.
  • Идемпотентно: ошибки «объект уже существует» превращаются в [EXIST], а не [FAILED] (pgsql 42P06/42P07/42710, mysql 42S01/42000).
  • При DEBUG=true в ответе виден текст SQL-ошибки для [FAILED].

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

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

bash
php call db pool
text
MainMainDbConfig
active 12 · idle 3 · total 15 · maximum 20 · workers 2
saturated  1 of 2 workers                    [SATURATED]
per worker
worker#0  MainMainDbConfig  active=2  idle=3 total=5  max=10  age=0s
worker#1  MainMainDbConfig  active=10 idle=0 total=10 max=10  age=3s

Смотреть нужно на строки воркеров, а не на общий итог: запрос ждёт освобождения в пуле своего воркера, поэтому один забитый воркер — это реальные задержки, даже когда суммарно места достаточно.

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

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

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

Дальше