Миграции и первая таблица в Laravel: без граблей новичка

За 20 минут вы создадите таблицу posts в базе данных через миграцию Laravel, откатите её и убедитесь, что схема легла правильно. Не через phpMyAdmin руками, а так, как это делают в команде: файл миграции лежит в репозитории, и любой коллега поднимает у себя ту же структуру одной командой. Инструкция для Laravel 11.x, но всё сказанное работает и в 10.x — различия отмечу отдельно.

Что нужно иметь до начала

Проверьте это до первой команды, иначе застрянете на середине.

• PHP 8.2 или выше — Laravel 11 не запустится на 8.1.
• Composer и уже созданный проект (composer create-project laravel/laravel my-app).
• Работающая база данных: MySQL 8, MariaDB, PostgreSQL 16 или SQLite. Если ничего не настраивали — по умолчанию в Laravel 11 стоит SQLite, и это самый простой старт.
• Терминал открыт в корне проекта — там, где лежит файл artisan.

Термин: миграция

Миграция — это PHP-файл, который описывает изменение структуры базы: создать таблицу, добавить колонку, повесить индекс. Laravel хранит список применённых миграций в служебной таблице migrations и по нему понимает, что уже накатано, а что нет. Это система контроля версий для схемы базы данных.

Шаг 1. Настройте подключение в .env

Откройте файл .env в корне проекта. За подключение к базе отвечают строки с префиксом DB_. Для SQLite достаточно двух строк:

DB_CONNECTION=sqlite
# остальные DB_-строки можно закомментировать или удалить

Файл базы Laravel создаст сам в database/database.sqlite — если его нет, создайте пустой: touch database/database.sqlite.

Для MySQL строки выглядят так:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=my_app
DB_USERNAME=root
DB_PASSWORD=YOUR_DB_PASSWORD

Проверка: сама база данных my_app для MySQL должна уже существовать — Laravel создаёт таблицы, но не саму базу. Создайте её через клиент базы или командой CREATE DATABASE my_app;.

Шаг 2. Сгенерируйте файл миграции

Выполните в терминале:

php artisan make:migration create_posts_table

Laravel по имени create_posts_table сам поймёт, что вы создаёте таблицу posts, и подставит заготовку с методами up() и down().

Проверка: в папке database/migrations появился файл с датой в имени, например 2024_06_01_120000_create_posts_table.php. Дата в начале имени задаёт порядок применения — не переименовывайте её вручную.

Шаг 3. Опишите структуру таблицы

Откройте созданный файл. Внутри метода up() опишите колонки:

<?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();                    // BIGINT автоинкремент, первичный ключ
            $table->string('title');          // VARCHAR(255)
            $table->text('body')->nullable(); // может быть пустым
            $table->boolean('is_published')->default(false);
            $table->timestamps();             // created_at и updated_at
        });
    }

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

Метод up() накатывает изменение, down() — откатывает. Заполняйте down() честно: пустой откат сломает вам migrate:rollback в самый неудобный момент.

Шаг 4. Примените миграцию

php artisan migrate

В консоли появится строка вида 2024_06_01_120000_create_posts_table ... DONE. Laravel применит все ещё не накатанные миграции, включая свои служебные (users, cache, jobs).

Проверка: откройте базу в любом клиенте — таблица posts с вашими колонками на месте. Или спросите у самого Laravel:

php artisan db:table posts

Команда выведет список колонок и их типы прямо в терминал.

Шаг 5. Научитесь откатывать

Ошиблись в структуре — откатите последнюю пачку миграций:

php artisan migrate:rollback

Отменит последнюю применённую группу и вызовет её down(). На боевой базе так делать нельзя — но об этом ниже.

Правило, которое экономит часы: применённую миграцию не редактируют. Если таблица уже в базе — не меняйте старый файл, создавайте новую миграцию add_column_to_posts_table. Отредактированный старый файл не перечитается, а у коллег структура разъедется с вашей.

Если не получилось

Пять ошибок, на которые новичок натыкается чаще всего.

• SQLSTATE[HY000] [1045] Access denied for user — неверный логин или пароль в .env. Проверьте DB_USERNAME и DB_PASSWORD. После правки .env выполните php artisan config:clear — Laravel мог закешировать старый конфиг.
• SQLSTATE[HY000] [1049] Unknown database 'my_app' — вы не создали саму базу. Laravel таблицы создаёт, а базу — нет. Создайте её вручную.
• Database file at path [...] does not exist (SQLite) — нет файла базы. Создайте пустой: touch database/database.sqlite.
• Nothing to migrate — файл уже накатан или Laravel его не видит. Проверьте, что файл лежит именно в database/migrations и имя начинается с даты.
• Изменили колонку, а в базе по-старому — вы отредактировали уже применённый файл. Laravel его повторно не читает. Либо создайте новую миграцию, либо на локальной базе выполните php artisan migrate:fresh (сотрёт все таблицы и накатит заново — только локально).

migrate:fresh против migrate:rollback

Две команды, которые путают. rollback вызывает down() последней группы и возвращает базу на шаг назад. fresh дропает вообще все таблицы и накатывает всё с нуля — данные исчезают полностью. На локальной базе fresh удобен, на боевой — это потеря данных.

Что делать дальше

Таблица создана — дальше два шага. Первый: создайте Eloquent-модель, чтобы работать с записями из PHP: php artisan make:model Post. Второй: посмотрите, как наполнять таблицу тестовыми данными через сидеры (make:seeder) и фабрики — это ускорит разработку, когда таблиц станет много. Про внешние ключи и связи между таблицами (foreignId, constrained) — отдельная тема, здесь мы разобрали только первую таблицу. Точный список методов Blueprint для колонок и индексов сверяйте в разделе Migrations официальной документации вашей версии Laravel.