Как проверить миграции, очереди и тесты перед обновлением Laravel
Обновление Laravel редко ограничивается заменой версий в composer.json. Основные сюрпризы появляются позже: миграция не проходит на боевой базе, воркер очереди не может разобрать задачу, созданную до деплоя, а тесты, которые «всегда были зелёными», проверяют не то, что действительно ломается.
Проверка перед обновлением Laravel — это последовательность шагов, а не один прогон. Сначала фиксируется исходное состояние, затем миграции прогоняются на копии базы, отдельно проверяются очереди и фоновые задачи, и только после этого имеет смысл смотреть на набор тестов и план отката. Такой порядок удобно проходить на копии проекта и тестовом окружении, чтобы на рабочий сервер попал предсказуемый результат.
С чего начать: зафиксируйте исходное состояние
Обновление фреймворка затрагивает не только PHP-код: на результат влияют версия интерпретатора, расширения, СУБД, драйвер очередей и порядок сборки кешей. Если эти параметры на локальной машине, в CI и на сервере расходятся, проверка теряет смысл — вы тестируете другую систему.
- версия PHP и набор расширений на рабочем сервере, в CI и на машине разработчика;
- тип и версия СУБД, а также версия Redis или другого брокера, если он используется для очередей и кеша;
- зафиксированный
composer.lockи список пакетов, которые зависят от версии фреймворка; - драйвер очередей, параметры воркеров и список запланированных задач;
- способ деплоя: как собираются конфиги и маршруты, есть ли режим обслуживания и как он включается.
Дальше посмотрите на зависимости: composer outdated покажет, какие пакеты отстали, а composer update --dry-run — что именно изменится без фактической установки. Если проект должен собираться на конкретной версии PHP, проверьте настройку config.platform в composer.json и команду composer check-platform-reqs: они помогают заметить расхождение между тем, что требует composer, и тем, что реально установлено на сервере.
Отдельно проверьте переменные окружения. Если на сервере включено кеширование конфигов, обращение к env() вне файлов config/*.php после php artisan config:cache может вернуть пустое значение. Прогон config:cache и route:cache на тестовом окружении до деплоя показывает такие ошибки заранее — вместе с проблемами вроде замыканий в маршрутах, которые кеширование не поддерживает.
Обновление удобно делать в отдельной ветке и не смешивать с функциональными изменениями. Тогда при падении тестов видно, что причина в зависимостях, а не в свежем коде, который попал в тот же коммит.
Для проверки миграций и очередей нужна копия боевой базы. Если в ней есть персональные данные, перенос в тестовое окружение может требовать отдельной оценки с точки зрения защиты данных — такую ситуацию лучше согласовать с компетентным специалистом и сверить с официальными разъяснениями, а не решать по привычке. Практичный компромисс — обезличенная копия, но и она требует аккуратного обращения.
Миграции: проверять на копии базы, а не на продакшене
Миграции — самая необратимая часть обновления. Код можно откатить к предыдущему коммиту за минуты, а вот столбец, который уже удалён или переименован, сам не вернётся. Поэтому все прогоны делаются на копии базы, объём которой сопоставим с боевым: на пустой схеме миграция пройдёт мгновенно и ничего не расскажет о блокировках и времени выполнения.
Сухой прогон и просмотр SQL
Начните с php artisan migrate:status на копии: команда покажет, какие миграции уже применены, а какие ждут выполнения. Затем имеет смысл выполнить php artisan migrate --pretend — в большинстве случаев команда выводит SQL-запросы, которые будут отправлены в базу, не выполняя их. Это удобно, чтобы заметить DROP COLUMN, смену типа, добавление NOT NULL без значения по умолчанию или переименование таблицы.
Но --pretend не заменяет реальный прогон: он не покажет, сколько времени займёт операция на таблице с миллионами строк, не поймает ошибку, зависящую от данных, и не расскажет о блокировках. Следующий шаг — выполнить php artisan migrate на копии и замерить время. Если миграция идёт минутами, стоит заранее решить, как она будет применяться на боевой базе: отдельным шагом, в окно низкой нагрузки или через промежуточную стратегию.
Отдельно проверьте миграции, которые создают индексы, меняют внешние ключи или тип поля на большой таблице. Такие операции удобнее выносить в самостоятельный шаг, чтобы не смешивать их с изменениями, которые можно применить быстро. Точное поведение зависит от СУБД и её версии, поэтому замер на копии важнее любых общих рекомендаций. На копии видно и то, укладывается ли операция в окно обслуживания, и нужен ли режим обслуживания вообще.
Обратимость, данные и стратегия expand–contract
Метод down() есть не у всех миграций, а если он есть, он отменяет изменения схемы, но не возвращает данные. Откат удалённого столбца восстановит пустую колонку, а не её содержимое. Это лучше проговорить с командой до деплоя, чтобы никто не рассчитывал на «магический rollback».
Перед обновлением сделайте резервную копию базы и проверьте, что из неё действительно можно восстановиться. Откат миграции через migrate:rollback возвращает структуру, но не данные, поэтому бэкап остаётся единственной реальной страховкой при деструктивных изменениях.
Для изменений, которые нельзя применить за один шаг, используют схему expand–contract: сначала добавляется новый столбец или таблица (совместимо со старым кодом), затем деплоится код, который пишет в оба места, потом данные переносятся, чтение переключается на новое поле, и только после этого старое удаляется отдельной миграцией. Такой порядок позволяет откатить код, не откатывая схему, — а это часто важнее, чем формальная обратимость миграции.
Если миграция не только меняет схему, но и переносит данные (заполняет новый столбец, пересчитывает значения), прогоняйте её на копии с реальным объёмом. На сотне строк такая операция пройдёт мгновенно и не покажет ни времени, ни влияния на блокировки. Перенос данных часто разумно отделять от изменения схемы и делать идемпотентным, чтобы повторный запуск не портил уже обработанные записи.
Проверьте сиды и фабрики: если тесты и наполнение тестовой базы зависят от структуры таблиц, после миграций они могут перестать работать. Прогон php artisan migrate:fresh --seed на локальной базе — быстрый способ поймать такие расхождения, но на копии боевых данных его применять не нужно: команда удаляет все таблицы.
Очереди и фоновые задачи: что ломается при обновлении
Задачи в очереди хранятся в сериализованном виде: в payload записаны имя класса, его конструктор и параметры. Если при обновлении класс переименован, перенесён в другой namespace или изменилась сигнатура конструктора, задача, созданная до деплоя, может не восстановиться и упадёт при обработке. Это одна из частых причин «странных» ошибок сразу после обновления.
Отсюда практическое правило: перед деплоем дайте текущим задачам догореть или временно остановите постановку новых, а после деплоя перезапустите воркеры. Воркер держит код в памяти и не увидит изменения, пока его не перезапустить. Для стандартных очередей это php artisan queue:restart — команда просит воркеры корректно завершиться после текущей задачи; для Redis-очередей под управлением Horizon аналогичную роль играет php artisan horizon:terminate.
Проверьте конфигурацию обработки: параметр retry_after и таймаут задачи должны быть согласованы, иначе задачу может забрать второй воркер, пока первый ещё её выполняет. Точные значения зависят от версии фреймворка и драйвера, поэтому сверяйтесь с документацией своей версии и с настройками в config/queue.php. Заодно посмотрите на количество попыток, паузу между ними и на то, что происходит с задачей после исчерпания ретраев.
Если задачи не идемпотентны, повторная обработка после сбоя может привести к дублям: двум письмам, двум списаниям, двум записям в журнале. Перед обновлением полезно проверить, какие задачи защищены WithoutOverlapping или ShouldBeUnique, а где защита держится только на дисциплине. Если описание фоновых задач в проекте размыто, помогает отдельный документ — например, материал о том, как подготовить ТЗ на Laravel: роли, фоновые задачи и интеграции.
Отдельная категория — цепочки и пакеты задач. Если задача ставится в цепочку, при падении одного звена остальные могут не выполниться, и после обновления важно понимать, что делать с такими «полувыполненными» цепочками: повторять целиком, добивать по шагам или разбирать вручную. Для пакетов задач проверьте, что обработчик завершения совместим с новым кодом и не зависит от структуры, которая изменилась.
Не забудьте про планировщик. Проверьте, что запись cron для schedule:run на сервере существует и что задачи не задваиваются, если cron добавлен и в другом месте. Команда schedule:list, если она доступна в вашей версии, показывает список зарегистрированных задач — по нему удобно сверить расписание до и после обновления. Отдельно проверьте часовой пояс планировщика: если задачи запускаются по местному времени, смена таймзоны или переход на летнее время может сместить запуск.
Решите заранее, что делать с записями в таблице упавших задач. Массовый queue:retry all после обновления может запустить старые задачи с несовместимыми данными. Разумнее сначала разобрать причины падений, а повторять — выборочно. Полезно также свериться с показателями очереди до и после деплоя: длина очереди, число упавших задач, время ожидания. Если после обновления очередь начинает расти, а число обработанных задач падает, это заметно раньше, чем жалобы пользователей.
Тесты: какой набор реально что-то проверяет
Зелёный прогон тестов важен, но сам по себе ничего не гарантирует. Если тесты выполняются на SQLite, а продакшен работает на другой СУБД, часть различий в поведении останется незамеченной. Если очереди и внешние вызовы подменены фейками, интеграционные проблемы тоже не проявятся. Поэтому смотреть нужно не на факт прохождения, а на состав набора.
- модульные тесты доменной логики — бизнес-правила, расчёты, значения по умолчанию;
- feature-тесты HTTP-маршрутов, middleware, политик и прав доступа;
- тесты миграций и сидов на чистой базе — они ловят расхождения между схемой и кодом;
- тесты задач очереди, событий и слушателей, включая проверку повторной обработки;
- тесты консольных команд и запланированных задач;
- дымовые проверки ключевых сценариев на тестовом окружении после деплоя.
Фейки (Queue::fake(), Bus::fake(), Http::fake(), Notification::fake()) нужны, чтобы тесты были быстрыми и предсказуемыми, но хотя бы один сценарий стоит прогнать без подмены — с реальным воркером и тестовой очередью. Так проверяется то, что фейки скрывают: сериализация задачи, поведение при ошибке, повторные попытки.
Запускайте тесты на той же СУБД, что и в продакшене, хотя бы в CI. SQLite удобен для быстрых прогонов, но различия в типах, ограничениях и обработке транзакций проявляются именно на боевой СУБД.
Если в проекте включён параллельный прогон тестов, убедитесь, что тесты не мешают друг другу на общей базе: изоляция через транзакции при параллельном запуске работает иначе, и часть конфликтов проявляется только в CI. Проверьте и то, как тесты готовят данные: RefreshDatabase и фабрики должны работать после изменения схемы, иначе падения будут выглядеть как ошибки приложения.
Полезно включить в прогон отчёт о deprecation-предупреждениях: они не роняют тесты, но показывают места, которые перестанут работать в следующих версиях. Статический анализ (например, PHPStan с расширением для Laravel) и проверка стиля не заменяют тесты, но помогают найти вызовы изменившихся методов. Если тестов мало, начинать стоит не с погони за покрытием, а с самых дорогих сценариев: оплата, авторизация, запись данных, отправка уведомлений.
В CI имеет смысл зафиксировать матрицу: версия PHP, версия СУБД, драйвер очередей. Тогда обновление проверяется в условиях, близких к боевым, а не только на одной конфигурации разработчика. Для небольших проектов достаточно одного прогона на боевой конфигурации — это лучше, чем десять прогонов на SQLite.
Проверка перед обновлением Laravel: порядок действий
Последовательность важнее отдельных команд. Разумный каркас выглядит так:
- Зафиксировать исходное состояние: версии, lock-файл, настройки окружения, список задач и расписание.
- Сделать резервную копию базы и проверить восстановление на копии.
- Прогнать тесты до обновления — чтобы знать, какие падения были и раньше.
- Обновить зависимости в отдельной ветке и повторить прогон.
- Прогнать миграции на копии боевой базы и замерить время выполнения.
- Проверить задачи очереди: сериализацию, ретраи, поведение после перезапуска воркеров.
- Подготовить план отката: к какому коммиту, с какой схемой, что делать с уже обработанными задачами.
- Задеплоить, пересобрать кеши конфигов и маршрутов, перезапустить воркеры и планировщик.
- Проверить логи, очередь упавших задач и ключевые пользовательские сценарии.
Если приложение работает с пользователями в Эстонии, время деплоя удобно выбирать вне местных рабочих часов — но это вопрос удобства, а не технической необходимости. Важнее, чтобы в момент обновления рядом был человек, который может принять решение об откате и знает, где лежит резервная копия.
| Что проверяем | Чем проверить | Тревожный признак |
|---|---|---|
| Порядок миграций | php artisan migrate:status на копии |
неприменённые миграции в неожиданном порядке |
| Содержимое миграции | php artisan migrate --pretend |
DROP COLUMN, смена типа, NOT NULL без значения по умолчанию |
| Откат | migrate:rollback --step=1 на копии |
пустой down() или ошибка при откате |
| Очередь | тестовая задача и queue:work --once |
задача не десериализуется или падает по таймауту |
| Воркеры после деплоя | queue:restart, horizon:terminate |
воркеры продолжают выполнять старый код |
| Тесты | php artisan test |
падения и deprecation-предупреждения |
| Кеши | config:cache, route:cache |
ошибка из-за замыканий в маршрутах или конфигах |
| Зависимости | composer outdated, composer check-platform-reqs |
пакет требует другую версию PHP или фреймворка |
Частые вопросы
Можно ли проверить миграции, не запуская их на реальной базе?
migrate --pretend показывает SQL, который будет выполнен, и помогает заметить опасные операции. Но он не покажет время выполнения, блокировки и ошибки, зависящие от данных, поэтому полноценная проверка — это прогон на копии базы, сопоставимой по объёму с боевой.
Нужно ли останавливать очередь перед обновлением?
Желательно как минимум приостановить постановку новых задач и дать текущим догореть. Если формат задач изменился несовместимо, старые записи лучше обработать до деплоя или предусмотреть в новом коде совместимость со старым payload.
Что делать с упавшими задачами после обновления?
Не запускать массовый повтор сразу. Сначала посмотрите причину падения: если задача создана старым кодом и несовместима с новым, повтор ничего не исправит. Разберите ошибки, при необходимости откатите код и только потом повторяйте выборочно.
Достаточно ли зелёных тестов, чтобы деплоить?
Нет. Тесты могут выполняться на другой СУБД, с фейками очередей и на небольших объёмах данных. Дополнительно нужны прогон миграций на копии, проверка задач с реальным воркером и дымовые проверки на тестовом окружении.
Как откатить обновление, если миграция уже применилась?
Откат кода и откат схемы — разные операции. migrate:rollback вернёт структуру, но не данные, поэтому основа плана — резервная копия и схема expand–contract, при которой старый код продолжает работать с новой схемой. Конкретный порядок зависит от того, какие изменения уже прошли.