# Миграции LARAVEL 12

## Гайд по миграциям в **Laravel 12**

> Laravel 12 вышел 6 февраля 2025 г. и привнёс несколько аккуратных улучшений к системе миграций ― от обработчика `shouldRun()` до опции `--isolated` для безопасного выката. Ниже — выжимка шаг-за-шагом, с примерами кода и советами из практики.

---

### 1. Концепция и подготовка окружения

*Миграции — это контроль версий для вашей БД* ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans")).

1. **Требования**: PHP ≥ 8.3, Composer ≥ 2.8, любая из поддерживаемых СУБД (MySQL 8, MariaDB 10.6, PostgreSQL 13, SQLite 3, SQL Server 2019).
2. **Настройка `.env`**: заполняем `DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`.
3. **Запуск проекта**:
    
    ```bash
    composer create-project laravel/laravel:^12 myapp
    cd myapp && php artisan serve
    
    ```

---

### 2. Создаём миграции

<table id="bkmrk-%D0%97%D0%B0%D0%B4%D0%B0%D1%87%D0%B0-%D0%9A%D0%BE%D0%BC%D0%B0%D0%BD%D0%B4%D0%B0-%D0%A7%D1%82%D0%BE-%D0%B4"><thead><tr><th>Задача</th><th>Команда</th><th>Что делает</th></tr></thead><tbody><tr><td>**Новая таблица**</td><td>`php artisan make:migration create_posts_table`</td><td>Laravel сам подставит `Schema::create()` в файле ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td></tr><tr><td>**Изменить таблицу**</td><td>`php artisan make:migration add_status_to_posts_table --table=posts`</td><td>Сгенерирует `Schema::table()`</td></tr><tr><td>**Указать путь**</td><td>`--path=database/migrations/admin`</td><td>Полезно при модулярной архитектуре</td></tr><tr><td>**Создать, но не запускать пока**</td><td>добавить в файл метод `shouldRun()`</td><td>Вернёт `false`, миграция пропустится ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td></tr></tbody></table>

#### Минимальный пример

```php
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->string('title')->index();
            $table->text('body');
            $table->boolean('published')->default(false);
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

```

---

### 3. Запуск миграций

<table id="bkmrk-%D0%9A%D0%BE%D0%BC%D0%B0%D0%BD%D0%B4%D0%B0-%D0%94%D0%BB%D1%8F-%D1%87%D0%B5%D0%B3%D0%BE-%D0%BD%D1%83%D0%B6"><thead><tr><th>Команда</th><th>Для чего нужна</th><th>Где пригодится</th></tr></thead><tbody><tr><td>`php artisan migrate`</td><td>Применить все «висящие» миграции ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td><td>Локальная разработка</td></tr><tr><td>`php artisan migrate --pretend`</td><td>Показать SQL без выполнения ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td><td>Code-review, CI</td></tr><tr><td>`php artisan migrate --isolated`</td><td>Заблокирует одновременный запуск на нескольких нодах ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td><td>Blue-/green deploy</td></tr><tr><td>`php artisan migrate --force`</td><td>Подавить подтверждение в prod ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td><td>CI/CD pipeline</td></tr><tr><td>`php artisan migrate:status`</td><td>Таблица применённых/неприменённых ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td><td>Аудит</td></tr></tbody></table>

---

### 4. Откат и перезапуск

<table id="bkmrk-%D0%9A%D0%BE%D0%BC%D0%B0%D0%BD%D0%B4%D0%B0-%D0%A7%D1%82%D0%BE-%D0%B4%D0%B5%D0%BB%D0%B0%D0%B5%D1%82-p"><thead><tr><th>Команда</th><th>Что делает</th></tr></thead><tbody><tr><td>`php artisan migrate:rollback`</td><td>Откатить последний *batch* ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td></tr><tr><td>`php artisan migrate:rollback --step=2`</td><td>Откатить ровно 2 файла</td></tr><tr><td>`php artisan migrate:reset`</td><td>Откатить **всё** ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td></tr><tr><td>`php artisan migrate:refresh --seed`</td><td>Полный откат → заново → сиды ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td></tr><tr><td>`php artisan migrate:fresh`</td><td>Drop all tables → заново ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td></tr></tbody></table>

---

### 5. Оптимизация: squash-дампы

С ростом проекта сотни файлов замедляют CI.  
Используйте:

```bash
php artisan schema:dump --prune      # создаст dump.sql и удалит старые миграции

```

На чистой базе Laravel сначала прогонит `dump.sql`, а затем только новые миграции ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans")).

---

### 6. Лайфхаки и лучшие практики

1. **Атомарность**: тяжёлые изменения (переименование столбцов, удаление индексов) выполняйте в отдельных мелких миграциях.
2. **Idempotency**: проверяйте `Schema::hasTable()` / `hasColumn()` перед изменениями для совместимости между ветками ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans")).
3. **Транзакции**: `public bool $withinTransaction = true;` в классе миграции гарантирует откат при ошибке (по умолчанию true для поддерживаемых СУБД).
4. **Странициируйте деплой**: для «живых» таблиц используйте «параллельную» стратегию — добавьте новый столбец, заполните его бэкграунд-джобой, переключайтесь, потом удаляйте старый.
5. **CI-тесты**: в PHPUnit подключите трейт `RefreshDatabase` — он вызывает `migrate:fresh` и откатывает после тестов.
6. **Stub publishing**:
    
    ```bash
    php artisan stub:publish --only=migration
    resources/stubs/migration.stub
    
    ```
    
    Настройте свои шаблоны под корпоративные стандарты.

---

### 7. Отладка типичных ошибок

<table id="bkmrk-%D0%A1%D0%B8%D0%BC%D0%BF%D1%82%D0%BE%D0%BC-%D0%9F%D1%80%D0%B8%D1%87%D0%B8%D0%BD%D0%B0-%D0%A0%D0%B5%D1%88%D0%B5"><thead><tr><th>Симптом</th><th>Причина</th><th>Решение</th></tr></thead><tbody><tr><td>`SQLSTATE[42S01]: Table already exists`</td><td>Миграция не в `down()` или путаются имена</td><td>Проверить `down()`, убедиться в правильном порядке launch-batch</td></tr><tr><td>`Class ... not found`</td><td>Переименовали файл/класс</td><td>Очистить кэш `composer dump-autoload`</td></tr><tr><td>Ошибка кодировки/сортировки</td><td>MySQL 8, несовпадение `charset/collation`</td><td>Явно задать `$table->charset('utf8mb4');` ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))</td></tr></tbody></table>

---

### 8. Чек-лист перед продакшен-выкатом

- [ ]  [ ]  Миграции проходят `php artisan migrate --pretend` на staging.
- [ ]  [ ]  Включён `--isolated` или ручная блокировка.
- [ ]  [ ]  Тесты используют ту же версию СУБД, что и prod.
- [ ]  [ ]  Резервная копия БД лежит в безопасном месте.
- [ ]  [ ]  Для разрушительных изменений используется «expand-migrate-contract» паттерн.

---

### 9. Ссылки для углубления

- Официальная документация «Database → Migrations» Laravel 12 ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))
- Ченджлог 12.x (`shouldRun`, `isolated`) GitHub ([laravel.com](https://laravel.com/docs/12.x/migrations "Database: Migrations - Laravel 12.x - The PHP Framework For Web Artisans"))
- Release Notes 12.x для общего понимания цикла релизов ([laravel.com](https://laravel.com/docs/12.x/releases?utm_source=chatgpt.com "Release Notes - Laravel 12.x - The PHP Framework For Web Artisans"))

---

#### Краткий итог

Миграции в Laravel 12 — зрелый инструмент: **генерируем** `make:migration`, **описываем** `up()/down()`, **запускаем** `migrate`, **откатываем** `rollback`. Новинка `shouldRun()` помогает «прятать» эксперименты, а `--isolated` — уберечь прод от гонок. Пользуйтесь «мелкими, атомарными» паттернами, держите *schema dump* в репозитории и внедряйте миграции в CI — тогда база данных будет версионироваться так же уверенно, как и код.