Skip to content
mxMigrations
mxMigrations
Расширяемый раннер и генератор миграций для MODX Revolution 2 и 3 — журнал, контрольные суммы, защита порядка и готовые шаблоны.
  • MODX 2
  • MODX 3
  • PHP 7.4
  • PHP 8.1
  1. Компоненты
  2. mxMigrations
  3. Расширение и поддержка
  4. Диагностика

Диагностика ​

status --strict вернул 2 ​

Это означает, что хотя бы одна группа pending, drifted, missing или outOfOrder не пуста. Запустите обычный status, затем разберите соответствующий раздел ниже. Сам код 2 не означает ошибку PHP или подключения MODX.

pending больше нуля ​

Файл ещё не применён либо его последняя попытка имеет статус failed.

  1. Посмотрите очередь через up --dry-run.
  2. Если это failed-файл, прочитайте output его строки в таблице журнала.
  3. Исправьте причину так, чтобы миграция безопасно пережила уже выполненную часть.
  4. Повторите up.

Не меняйте успешно применённые старые файлы вместе с исправлением — это создаст drift. Для дополнительного изменения создайте новую миграцию.

drifted больше нуля ​

SHA-256 файла отличается от значения, записанного при применении.

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

up --ignore-checksum допустим только когда:

  • изменение не требует выполнения на базе, например исправлен комментарий;
  • либо база уже вручную приведена к состоянию изменённого файла;
  • причина и проверка состояния зафиксированы в рабочей задаче.

Dry-run с флагом показывает строки [ACCEPTED], но журнал меняет только обычный up --ignore-checksum.

missing больше нуля ​

Журнал знает миграцию, которой нет в каталоге. Обычно файл удалили, переименовали или не доставили на эту среду.

Верните тот же файл с тем же именем и содержимым. Раннер намеренно не удаляет историю автоматически и не предоставляет команду «забыть миграцию».

outOfOrder больше нуля ​

Новая датированная миграция сортируется раньше последней уже применённой. Причины: метку написали вручную, ветки Git создали файлы независимо или часы машин различались.

При order = allow (по умолчанию) файл выполнится с предупреждением, переименовывать его не нужно. Если порядок важен, добавьте в файл // @depends <имя>. При order = strict прогон блокируется: задайте @depends, переключите order на allow или разово запустите up --allow-out-of-order.

В журнале остались записи переименованных файлов ​

Переименованный файл с тем же содержимым распознаётся автоматически и повторно не выполняется. Если содержимое менялось, укажите в нём // @renamed-from <старое_имя>. Остатки чистит journal:clean (сухой прогон) и journal:clean --apply.

Миграции уже выполняет другой процесс ​

MySQL не выдал проектную блокировку без ожидания. Проверьте deploy, cron и ручные SSH-сессии, работающие с той же базой.

Не пытайтесь обходить блокировку вторым конфигом: два процесса смогут одновременно менять схему. Если процесс аварийно завершён, MySQL освобождает advisory lock при закрытии его соединения.

Каталог миграций не найден ​

Проверьте migrations_path и правило разрешения путей: относительное значение считается от каталога PHP-конфига. Для status и up каталог должен существовать.

Команда new --apply создаёт отсутствующий каталог с режимом 0775, но родительский каталог должен быть доступен на запись текущему пользователю.

Не найден bootstrap MODX ​

Неверен modx_root. Он должен указывать на корень конкретной установки MODX, а не на core/ или каталог компонента.

  • линия MODX 2 ищет <modx_root>/index.php;
  • линия MODX 3 ищет <modx_root>/config.core.php, а затем Composer autoload в корне сайта или core/.

Для конфига core/config/mxmigrations.php типовое значение:

php
'modx_root' => dirname(__DIR__, 2),

Project autoload или класс провайдера не найден ​

Проверьте по порядку:

  1. каждый путь из autoload существует относительно каталога конфига;
  2. Composer autoload содержит namespace проекта;
  3. класс из recipe_providers загружается этим autoload;
  4. класс имеет публичный конструктор без обязательных аргументов;
  5. объект реализует MigrationRecipeProviderInterface.

Ошибки провайдеров возникают при создании приложения, до чтения и выполнения проектных миграций.

model:build требует сначала применить миграцию ​

В реестре изменений модели есть миграция, которая ещё не отмечена применённой. Выполните up --dry-run, затем up. Модель разрешено записывать только после успешного изменения базы, иначе xPDO начнёт использовать поля, которых ещё нет.

Таблица найдена в нескольких моделях ​

Одна таблица описана в нескольких XML-схемах из раздела models. Повторите new с явным --model=имя. Пакет не выбирает владельца произвольно, потому что это изменило бы не ту схему и каталог модели.

После обновления miniShop исчезли проектные поля модели ​

Убедитесь, что для сторонней модели включён overlay => true, а файл migrations/.mxmigrations/model-changes.php доставлен из репозитория. Затем повторите model:build --model=minishop2 --apply: проектные изменения будут наложены на обновлённую штатную схему.

PHP-миграция ничего не вернула ​

Новый файл обязан завершаться callable. Для MODX 2:

php
return function (modX $modx): void {
    // Изменение.
};

Для MODX 3 тип аргумента — \MODX\Revolution\modX.

Если файл сам выполняет bootstrap ядра, он относится к legacy-формату и должен завершаться как самостоятельный CLI-скрипт с кодом 0. Не смешивайте два формата в одном файле.

baseline отметил лишние файлы ​

baseline помечает все текущие pending одним вызовом и не имеет фильтра по имени. До команды обязательно проверяйте status и содержимое каталога.

Если файл отмечен ошибочно, не правьте таблицу журнала без расследования: сначала определите фактическое состояние базы и создайте корректирующую миграцию. Ручное удаление строки может повторно запустить потенциально неидемпотентный код.

Безопасная последовательность в CI ​

bash
php core/components/mxmigrations/bin/mxmigrations.php status --strict
php core/components/mxmigrations/bin/mxmigrations.php up --dry-run
php core/components/mxmigrations/bin/mxmigrations.php up --by=deploy
php core/components/mxmigrations/bin/mxmigrations.php status --strict

Во всех командах выше подразумевается --config=... или MXMIGRATIONS_CONFIG. Перед up добавьте резервную копию средствами проекта: mxMigrations отвечает за историю изменений, но не создаёт бэкап.