Команды CLI

Общий синтаксис:

php core/components/mxmigrations/bin/mxmigrations.php \
  --config=/path/to/migrations.php <команда> [параметры]

Вместо --config можно задать переменную окружения MXMIGRATIONS_CONFIG. Параметры пишутся только в форме --name или --name=value.

Справочник команд

Команда	Назначение
status [--strict]	Показать количество миграций в каждой группе состояния.
up [--dry-run] [--ignore-checksum] [--allow-out-of-order] [--by=name]	Показать или применить очередь миграций.
baseline [--by=name]	Пометить все ожидающие миграции применёнными без выполнения.
new <slug> [--recipe=name] [параметры шаблона] [--apply]	Сгенерировать новую миграцию.
model:build [--model=name] [--apply]	Показать или записать модель из XML-схемы.
recipe:list	Показать готовые и собственные шаблоны.
recipe:help <name>	Показать описание и параметры одного шаблона.
help	Показать краткую справку.

status

php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/config/mxmigrations.php status --strict

Команда выводит пять счётчиков:

• pending — файл ещё не применён или предыдущая попытка завершилась ошибкой. Сначала выполните up --dry-run; если прошлый запуск упал, исправьте причину ошибки, затем повторите up.
• drifted — SHA-256 применённого файла не совпадает с журналом. Верните файл к применённой версии; если базе действительно нужно новое изменение, создайте следующую миграцию, а не переписывайте старую.
• missing — запись есть в журнале, но файла больше нет в каталоге. Верните файл с прежним именем и содержимым из системы контроля версий.
• outOfOrder — новый файл расположен раньше уже применённых. Если он ещё нигде не выполнялся, пересоздайте или переименуйте его с более поздней меткой.
• applied — файл применён, его контрольная сумма совпадает с журналом. Ничего делать не нужно.

Подробные причины и редкие исключения разобраны в разделе Диагностика.

Без --strict команда возвращает код 0 независимо от счётчиков. С флагом возвращается 2, если хотя бы одна из первых четырёх групп не пуста. Это режим для CI и deploy-скрипта.

up

Предпросмотр очереди:

php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/config/mxmigrations.php up --dry-run

Применение:

php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/config/mxmigrations.php up --by=deploy

Раннер захватывает MySQL-блокировку, повторно строит план под блокировкой и выполняет pending по имени. При ошибке он:

1. записывает текущий файл со статусом failed и текстом исключения;
2. не выполняет оставшуюся очередь;
3. возвращает код 1.

Следующий up снова начнёт с failed-файла. Поэтому каждая миграция должна быть идемпотентной и корректно переживать повторный запуск после частичного выполнения.

--dry-run

Показывает очередь строками [DRY], но не подключает файлы и не меняет журнал. Проверка порядка не блокирует dry-run: команда нужна в том числе для диагностики outOfOrder.

--by=name

Записывает указанное имя в applied_by. Без параметра используется строка <пользователь>@<hostname>.

--ignore-checksum

Принимает текущее содержимое изменённых применённых файлов как новый эталон без повторного выполнения. Статус, исходное время и длительность применения сохраняются, а в output добавляется запись о принятии.

Это не способ доставить исправление

Изменение применённой миграции не меняет уже существующую базу. Используйте --ignore-checksum только когда расхождение осознанно и состояние базы уже проверено. Обычное исправление доставляется новой миграцией.

--allow-out-of-order

Разрешает выполнить новый файл, имя которого расположено раньше уже применённых.

Сначала выясните причину

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

baseline

php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/config/mxmigrations.php baseline --by=deploy

baseline говорит раннеру: «все миграции, которые сейчас лежат в каталоге, уже отражены в этой базе». Команда не выполняет PHP-файлы и не сравнивает их с реальной структурой БД. Она только записывает имена и контрольные суммы всех текущих pending в журнал со статусом baseline.

Типичный случай — старый работающий сайт:

1. нужные таблицы, колонки и настройки уже существуют;
2. исторические миграции добавили в каталог только сейчас;
3. журнал mxMigrations ещё пуст, поэтому status показывает все файлы как pending;
4. после ручной проверки базы выполняют baseline;
5. новые миграции, добавленные позже, снова будут pending и выполнятся через обычный up.

То есть baseline запускают после появления изменений в базе, но до первого up через mxMigrations.

Перед baseline:

1. проверьте каждое ожидающее изменение в целевой базе;
2. сохраните вывод status;
3. убедитесь, что в очереди нет новой миграции, которую действительно надо выполнить.

Не используйте baseline для новой базы

Если изменения ещё не внесены, нужен up. baseline создаст только записи в журнале, после чего раннер будет считать невыполненные изменения применёнными. Команда помечает всю очередь сразу — выбрать отдельные файлы нельзя.

new

php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/config/mxmigrations.php \
  new add_order_status --recipe=add-column \
  --table=site_orders --column=status \
  --type="VARCHAR(20) NOT NULL" --apply

По умолчанию используется пустой шаблон empty. Без --apply команда печатает будущее имя и PHP-код. С флагом файл записывается в migrations_path; уже существующий файл никогда не перезаписывается.

Для шаблонов колонок и индексов команда ищет таблицу во всех записях models. Если таблица найдена в нескольких схемах, укажите --model=имя. Собственная XML-схема обновляется вместе с записью миграции; для сторонней модели создаётся проектное overlay.

Идентификатор приводится к нижнему регистру, пробелы и дефисы заменяются подчёркиваниями. После нормализации допустимы только латинские буквы, цифры и _.

model:build

php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/config/mxmigrations.php model:build

php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/config/mxmigrations.php model:build --apply

Без --apply команда собирает модели во временном каталоге и показывает новые, изменённые и удалённые metadata/map-файлы. С флагом изменения записываются. --model=minishop2 ограничивает запуск одной записью конфига.

Команда откажется собирать модель, пока связанная с её изменением миграция не применена. Существующие основные классы объектов не заменяются; для новых объектов они создаются вместе с платформенными классами.

Шаблоны миграций

php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/config/mxmigrations.php recipe:list

php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/config/mxmigrations.php recipe:help add-index

В список входят и собственные шаблоны проекта.

Коды возврата

Код	Значение
0	Команда выполнена; для status --strict проблем нет.
1	Ошибка аргументов, конфигурации, запуска MODX или применения миграции.
2	Только status --strict: есть pending, drifted, missing или outOfOrder.