Увійти Реєстрація
Вакансії
Вакансії Laravel Компанії Статистика
Підготовка
Як підготуватися < href="https://laravelukraine.com/interviews" wire:navigate.hover class="flex items-center gap-3 rounded-md px-3 py-2 text-base font-medium text-gray-600 hover:bg-gray-50 hover:text-gray-900 dark:text-gray-400 dark:hover:bg-gray-900 dark:hover:text-white" >Співбесіди Тестування Документація
Блог
Всі статті Серії
Екосистема
Пакети Ресурси Проєкти Інструменти Події Відео
Інше
Про нас Реклама
Переклади 17 листопада 2026

Одна міграція на MySQL, PostgreSQL і SQLite: що змінює подія MigrationFailed у Laravel 13.42

Ви виправляєте дублікати в даних, знову запускаєте php artisan migrate, а Laravel відповідає Duplicate column name 'slug'. Першого разу міграція впала, тож Laravel її не записав. Але половина її все одно виконалася - і тепер саме ця половина блокує повторний запуск.

Laravel 13.42 додав подію MigrationFailed якраз для цього моменту (PR #62342 від Джека Бейліса). Вона спрацьовує, коли міграція кидає виняток, і несе цей виняток із собою. В огляді випуску на Laravel News пропонують використовувати її, щоб попередити команду, перш ніж користувачі наткнуться на напівзастосовану схему.

То які ж бази справді лишають таку схему? Я запустив ту саму невдалу міграцію на MySQL 8.4.13, PostgreSQL 17.12 і SQLite 3.53.4 (версії, що йде з PHP 8.4 на моєму Mac), усе на Laravel 13.42.0. Безлад після них виявився не однаковим.

Міграція, яка падає на півдорозі

Класична міграція зі slug. Додати nullable-стовпець, заповнити його, потім додати унікальний індекс:

  public function up(): void
  {
      Schema::table('products', function (Blueprint $table) {
          $table->string('slug')->nullable()->after('name');
      });

      DB::table('products')->orderBy('id')->each(function ($product) {
          DB::table('products')
              ->where('id', $product->id)
              ->update(['slug' => Str::slug($product->name)]);
      });

      Schema::table('products', function (Blueprint $table) {
          $table->unique('slug');
      });
  }

У таблиці products три рядки: Blue Mug, Red Kettle і ще один Blue Mug (два розміри, однакова назва). Заповнення двічі записує blue-mug, тож індекс не будується. Це і є збій, навмисний. І водночас реалістичний: такий дублікат з'являється в продакшн-даних і майже ніколи - в локальній базі, заповненій сідерами.

MySQL лишає стовпець, і повторний запуск падає

Перший запуск, зі скороченим стек-трейсом:

   2026_11_14_000002_add_slug_to_products_table .. 32.09ms FAIL

     Illuminate\Database\UniqueConstraintViolationException

    SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry 'blue-mug'
    for key 'products.products_slug_unique' (Connection: mysql, ... SQL: alter table
    `products` add unique `products_slug_unique`(`slug`))

Потім я перевірив саму таблицю і таблицю migrations:

  Schema::hasColumn('products', 'slug');
  DB::table('products')->orderBy('id')->pluck('slug');
  collect(Schema::getIndexes('products'))->pluck('name');
  DB::table('migrations')->where('migration', 'like', '%add_slug%')->exists();
  slug column: true
  slugs: ["blue-mug","red-kettle","blue-mug"]
  indexes: ["primary"]
  recorded: false

Стовпець є. Заповнені slug є. Індексу немає, і Laravel не має жодного запису про те, що все це відбулося. Тож я перейменував другий товар на Blue Mug Large і знову запустив migrate:

   2026_11_14_000002_add_slug_to_products_table .. 7.97ms FAIL

     Illuminate\Database\QueryException

    SQLSTATE[42S21]: Column already exists: 1060 Duplicate column name 'slug'
    (Connection: mysql, ... SQL: alter table `products` add `slug` varchar(255) null after `name`)

Дані виправлено. А міграція все одно не може виконатися, бо її перша інструкція тепер натикається на її ж власні залишки. Далі лишається видалити стовпець руками, відредагувати міграцію або вставити фальшивий рядок у migrations. Жодному з цих варіантів не місце в розгортанні.

PostgreSQL відкочує все

Та сама міграція, ті самі три рядки, той самий збій на унікальному індексі. Стан після нього:

  slug column: false
  indexes: ["products_pkey"]
  recorded: false

Ні стовпця, ні slug, ні запису. Після того самого перейменування повторний запуск просто спрацював:

   2026_11_14_000002_add_slug_to_products_table .. 12.95ms DONE

Саме такої поведінки я й очікував усюди.

А SQLite?

Нові Laravel-застосунки використовують SQLite як базу даних за замовчуванням ще з Laravel 11, тож чимало локальних середовищ проходять саме цим шляхом.

  slug column: true
  slugs: ["blue-mug","red-kettle","blue-mug"]
  indexes: ["primary"]
  recorded: false

SQLite зберіг усе те саме, що й MySQL. І повторний запуск упав так само, з duplicate column name: slug. Причому не тому, що SQLite не вміє краще. Загорнута в транзакцію, ця сама міграція на SQLite відкотилася повністю (цей тест - нижче). Просто Laravel ніколи цієї транзакції не відкриває.

Звідки береться різниця

Відповідь - у кількох рядках Illuminate\Database\Migrations\Migrator::runMigration() станом на 13.42:

  try {
      $this->getSchemaGrammar($connection)->supportsSchemaTransactions()
          && $migration->withinTransaction
              ? $connection->transaction($callback)
              : $callback();
  } catch (Throwable $e) {
      $this->fireMigrationEvent(new MigrationFailed($migration, $method, $name, $e));

      throw $e;
  }

supportsSchemaTransactions() читає властивість $transactions граматики схеми. Вона дорівнює true у PostgresGrammar і SqlServerGrammar. Усі інші граматики лишають значення базового класу за замовчуванням, тобто false.

Для MySQL це чесна відповідь. Кожен ALTER TABLE викликає неявний коміт, тож транзакція навколо міграції однаково нічого б не втримала. MariaDB отримує ту саму поведінку, бо MariaDbGrammar розширює MySqlGrammar.

SQLite - інша історія. Загортання в транзакцію з'явилося в Laravel 5.3 у PR #15780, і той PR вмикав його тільки для PostgreSQL. Автор писав, що не може протестувати SQL Server і не певен, чи SQLite повністю підтримує alter table всередині транзакції. SQL Server отримав прапорець пізніше. SQLite - так ніколи.

Тож на MySQL і SQLite кожна інструкція виконується сама по собі й комітиться одразу. ALTER TABLE комітиться. Кожен UPDATE комітиться. Невдалий індекс нічого не забирає з собою назад.

Що насправді дає MigrationFailed

Подія спрацьовує в тому самому блоці catch, і саме це місце пояснює її поведінку:

  • На PostgreSQL вона спрацьовує після відкату. На момент виконання catch метод $connection->transaction() уже відкотив транзакцію і повторно кинув виняток. Слухач, який я туди додав, не побачив на PostgreSQL жодного стовпця slug.
  • Виняток повторно кидається після того, як відпрацюють слухачі. Тож migrate однаково завершується з кодом 1, і скрипт розгортання з set -e однаково зупиняється.
  • Вона спрацьовує і для down. migrate:rollback проходить через той самий runMigration(), а $event->method тоді дорівнює down.

Подія несе екземпляр міграції, метод, ім'я файлу і виняток. Як і сповіщення про повільні завдання з 13.40, вона повідомляє про момент збою, а діагностику лишає вам. Вона не каже, чи щось було відкочено і які інструкції вже виконалися. А на MySQL саме друге й потрібне, щоб відновитися.

Слухач, який каже, що лишилося

Цей слухач записує інструкції зміни схеми, поки виконується міграція, і логує їх, лише якщо вони пережили збій:

  use Illuminate\Database\Events\MigrationFailed;
  use Illuminate\Database\Events\MigrationStarted;
  use Illuminate\Database\Events\QueryExecuted;
  use Illuminate\Support\Facades\DB;
  use Illuminate\Support\Facades\Event;
  use Illuminate\Support\Facades\Log;

  public function boot(): void
  {
      if (! $this->app->runningInConsole()) {
          return;
      }

      $statements = [];

      Event::listen(function (MigrationStarted $event) use (&$statements) {
          $statements = [];
      });

      DB::listen(function (QueryExecuted $query) use (&$statements) {
          if (preg_match('/^\s*(alter|create|drop|rename)\b/i', $query->sql)) {
              $statements[] = $query->sql;
          }
      });

      Event::listen(function (MigrationFailed $event) use (&$statements) {
          $connection = DB::connection($event->migration->getConnection());

          $rolledBack = $event->migration->withinTransaction
              && $connection->getSchemaGrammar()->supportsSchemaTransactions();

          Log::critical("Migration [{$event->name}] failed", [
              'connection' => $connection->getName(),
              'rolled_back' => $rolledBack,
              'already_applied' => $rolledBack ? [] : $statements,
              'error' => $event->exception->getMessage(),
          ]);
      });
  }

Перевірка rolled_back повторює власну умову Migrator, тож покриває й міграцію, яка встановлює $withinTransaction = false. QueryExecuted спрацьовує лише для успішних інструкцій, тож невдала до списку ніколи не потрапляє. Ось що слухач залогував на кожній базі (повідомлення про помилку обрізано):

  mysql   {"connection":"mysql","rolled_back":false,"already_applied":["alter table `products` add `slug` varchar(255) null after `name`"]}
  pgsql   {"connection":"pgsql","rolled_back":true,"already_applied":[]}
  sqlite  {"connection":"sqlite","rolled_back":false,"already_applied":["alter table \"products\" add column \"slug\" varchar"]}

UPDATE із заповнення я навмисно не включив. Вони теж закомітилися, але рядок на кожен запис - це шум у сповіщенні, а стовпець, у який вони писали, у списку вже є. Надсилайте той самий контекст у Slack або куди ви зазвичай шлете сповіщення. Канал логів - просто те, на чому я тестував.

Чи варто слухачу класти застосунок?

У прикладі з Laravel News слухач викликає Artisan::call('down'). За замовчуванням я б так не робив.

На PostgreSQL нічого напівзастосованого немає, тож режим обслуговування нікого не захищає. На MySQL погляньте, що тут насправді лишилося: один зайвий nullable-стовпець. Код, який досі працює, про нього не знає і далі працюватиме. Вимкнення сайту перетворює тиху проблему на простій - посеред розгортання, у якому й так вистачає рухомих частин (у те саме вікно ваші воркери черг отримують SIGTERM).

Аргумент на користь down - міграція, яка видаляє або перейменовує щось до того, як упасти. Працюючий код читає цей стовпець і почне кидати винятки. Список already_applied показує, який із двох випадків у вас, і це кращий привід, ніж «якась міграція впала».

Як змусити MySQL падати на чистій межі

Міграція отримує рядок у migrations лише після того, як up() поверне керування. Тож рішення на MySQL - винести кожну інструкцію, яка може впасти, в окрему міграцію:

  2026_11_14_000002_add_slug_column_to_products_table.php
  2026_11_14_000003_backfill_product_slugs.php
  2026_11_14_000004_add_unique_index_to_product_slugs.php

Той самий код, що й раніше, розділений на три частини. Ті самі три рядки на MySQL:

   2026_11_14_000002_add_slug_column_to_products_table .. 16.21ms DONE
   2026_11_14_000003_backfill_product_slugs .. 7.91ms DONE
   2026_11_14_000004_add_unique_index_to_product_slugs .. 13.32ms FAIL

Тепер збій припадає на записану межу. Заповнення вже виконалося, тож виправлення має оновити не лише назву, а й slug. Після цього migrate виконав тільки індекс:

   2026_11_14_000004_add_unique_index_to_product_slugs .. 32.57ms DONE

Жодних стовпців, видалених руками, жодних фальшивих рядків у migrations. Лише виправлення даних і повторний запуск.

На SQLite є й другий варіант, бо SQLite вміє відкочувати DDL. Я сам загорнув початкову єдину міграцію в транзакцію:

  public function up(): void
  {
      DB::transaction(function () {
          // the same three steps as before
      });
  }

На SQLite вона впала на індексі й не лишила по собі стовпця slug. На MySQL ця сама обгортка нічого не змінила, і стовпець лишився на місці. Я перевірив лише цю міграцію, тож перш ніж на це покладатися, спробуйте так само свої ризикованіші міграції на SQLite.

Для таких випадків часто радять ще й перевірки Schema::hasColumn(). Вони дають повторному запуску пройти, але й приховують, що схема розійшлася з очікуваною, тож я тримав би їх як крайній захід, а не як план.

Часті питання

Чи записується невдала міграція в таблицю migrations?

Ні. Laravel записує рядок лише після того, як up() поверне керування. У моїх тестах невдала міграція не мала рядка в жодній із трьох баз - саме тому MySQL і SQLite й застрягають: схема змінилася, а запис каже, що ні.

Чи спрацьовує MigrationFailed під час migrate:rollback?

Так. Відкат іде через той самий метод runMigration(), тож down(), що кидає виняток, запускає подію з $event->method, рівним down.

Чи MariaDB тут поводиться так само, як MySQL?

У Laravel - так. MariaDbGrammar розширює MySqlGrammar і успадковує $transactions = false, тож міграції на MariaDB виконуються без обгортальної транзакції.

Що робить $withinTransaction = false на PostgreSQL?

Вимикає загортання в транзакцію для цієї однієї міграції, тож вона поводиться як на MySQL. Це потрібно для CREATE INDEX CONCURRENTLY, який PostgreSQL не виконує всередині блоку транзакції. З тієї ж причини тримайте такі міграції в одну інструкцію.

Чи можна побачити, яка інструкція впала, без слухача?

Так. QueryException містить SQL, що впав, як у виводах вище. Чого він не скаже - які інструкції перед нею виконалися успішно. Цю прогалину й закриває слухач.

Одна інструкція, що може впасти, на одну міграцію

На MySQL і SQLite Laravel-міграція - не єдине ціле. Це список інструкцій, які комітяться по одній, і перший збій лишає попередні на місці. Тож давайте кожній міграції щонайбільше одну інструкцію, яка може впасти. Тоді повторний запуск після збою - це виправлення даних і нічого більше.

Читайте також: Міграції бази даних без простою в Laravel: expand-contract і lock_timeout.

Переклад оригіналу: dev.to
8

Читати в документації

Коментарі

Увійдіть, щоб залишити коментар

Будьте першим, хто залишить коментар!

Читайте також

Тести як дані
Переклади 17 листопада 2026

Тести як дані: як переконатися, що код від AI-агента робить те, що потрібно

Коли код і тести пише AI-агент, розробник стає замовником, а головним контрактом стають читабельні приймальні тести, винесені в дані. Переказ статті Маттео Ваккарі з martinfowler.com про таблиці, сценарії, захист тестового каркаса і перевірку самих тестів.

9
Laravel Shift
Переклади 17 листопада 2026

Як одне питання на конференції стало бізнесом однієї людини на $50K на місяць

Jason McCreary розповів Tiny Empires, як Laravel Shift виріс із питання до Taylor Otwell у сервіс із доходом близько $50K на місяць: занизькі ціни на старті, п'ять років до нинішніх тарифів, робота наодинці й перший рік падіння.

12

Вакансії за темою

SoftWars Нова
Сьогодні

Middle PHP Developer

Розробка та підтримка backend-частини вебзастосунків на PHP 8+ і Laravel, створення та інтеграція REST API, оптимізація продуктивності та SQL-запитів. Кандидат має мати від 2 років комерційного досвіду з PHP, знання ООП, SOLID, MySQL, Git і Composer, а також вміння самостійно вирішувати технічні завдання та брати участь у code review.

N-iX
11 днів тому

Senior / Lead PHP Engineer with AI skills (#5887)

Розробка та підтримка backend-сервісів і API на PHP та Laravel для нового великого релізу європейського онлайн-маркетплейсу автомобілів. Завдання включають інтеграцію агентних AI-потоків (LLM-агенти, tool-calling), менторство інженерів і відповідальність за фічі від дизайну до моніторингу. Вимоги: 6+ років PHP, 4+ роки з Laravel, практичний досвід GenAI, сильні знання MySQL/PostgreSQL, Docker та хмарних платформ, англійська Upper-Intermediate.

Vodworks
13 днів тому

Full Stack (JavaScript / PHP / AI)

Senior-розробник на позиції індивідуального контриб'ютора без керування людьми: архітектура та розробка масштабованих застосунків, мікросервісів і API, переважно на PHP з Laravel, а також JavaScript і сучасний фронтенд. Завдання включають обробку даних у реальному часі, кешування, черги повідомлень і розподілені системи. Вимоги: 7+ років досвіду, практичне використання AI-інструментів у розробці, англійська C1 і вище, менторство молодших розробників.

Пакети за темою

Kalimera

welldigit/kalimera

Interactive installer that scaffolds Laravel applications the Well Digit way.

v1.0.0 17

Bagisto

bagisto/bagisto

Bagisto — це платформа для електронної комерції, побудована на Laravel. Вона надає готове рішення для створення та управління інтернет-магазинами з підтримкою каталогу товарів, замовлень, платежів та клієнтів.

28,380 v2.5.1 13 28