Ви виправляєте дублікати в даних, знову запускаєте 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.