---
title: "Одна міграція на MySQL, PostgreSQL і SQLite: що змінює подія MigrationFailed у Laravel 13.42"
url: https://laravelukraine.com/blog/odna-migraciia-na-mysql-postgresql-i-sqlite-shho-zminiuje-podiia-migrationfailed-u-laravel-1342
date: 2026-11-17
source: https://dev.to/hafiz619/i-broke-one-laravel-migration-on-mysql-postgresql-and-sqlite-what-migrationfailed-in-1342-changes-3p61
---

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

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

Laravel 13.42 додав подію `MigrationFailed` якраз для цього моменту ([PR #62342](https://github.com/laravel/framework/pull/62342) від Джека Бейліса). Вона спрацьовує, коли міграція кидає виняток, і несе цей виняток із собою. В [огляді випуску на Laravel News](https://laravel-news.com/laravel-13-42-0) пропонують використовувати її, щоб попередити команду, перш ніж користувачі наткнуться на напівзастосовану схему.

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

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

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

```php
  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 лишає стовпець, і повторний запуск падає

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

```text
   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`:

```php
  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();
```

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

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

```text
   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 відкочує все

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

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

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

```text
   2026_11_14_000002_add_slug_to_products_table .. 12.95ms DONE
```

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

### А SQLite?

Нові Laravel-застосунки використовують SQLite як базу даних за замовчуванням ще з [Laravel 11](https://laravel.com/docs/11.x/releases), тож чимало локальних середовищ проходять саме цим шляхом.

```text
  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:

```php
  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` викликає неявний коміт](https://dev.mysql.com/doc/refman/8.4/en/implicit-commit.html), тож транзакція навколо міграції однаково нічого б не втримала. MariaDB отримує ту саму поведінку, бо `MariaDbGrammar` розширює `MySqlGrammar`.

SQLite - інша історія. Загортання в транзакцію з'явилося в Laravel 5.3 у [PR #15780](https://github.com/laravel/framework/pull/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 саме друге й потрібне, щоб відновитися.

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

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

```php
  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` спрацьовує лише для успішних інструкцій, тож невдала до списку ніколи не потрапляє. Ось що слухач залогував на кожній базі (повідомлення про помилку обрізано):

```text
  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 - винести кожну інструкцію, яка може впасти, в окрему міграцію:

```text
  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:

```text
   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` виконав тільки індекс:

```text
   2026_11_14_000004_add_unique_index_to_product_slugs .. 32.57ms DONE
```

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

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

```php
  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 не виконує всередині блоку транзакції](https://www.postgresql.org/docs/17/sql-createindex.html). З тієї ж причини тримайте такі міграції в одну інструкцію.

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

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

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

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

Читайте також: [Міграції бази даних без простою в Laravel: expand-contract і lock_timeout](/blog/migraciyi-bazi-danix-bez-prostoiu-v-laravel-expand-contract-i-lock-timeout).
