База и .env в Laravel: что настроить до первого запроса

К концу этого разбора у вас будет рабочее подключение Laravel к базе данных: команда php artisan migrate отработает без ошибок и создаст таблицы. На чистом проекте это занимает 10–15 минут, если СУБД уже установлена. Если базу тоже придётся ставить — заложите час. Проверено на Laravel 11.x и 12.x; для 10.x всё то же самое, отличий в конфиге подключения нет.

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

Прежде чем трогать .env, убедитесь, что на месте четыре вещи. Без любой из них подключение не заработает, и вы потеряете время на угадывание.

• PHP 8.2+ — минимальная версия для Laravel 11 и 12. Проверьте: php -v.
• Установленная СУБД — MySQL 8.x, MariaDB 10.x или PostgreSQL 16.x, запущенная и принимающая подключения.
• Драйвер PHP для вашей базы — pdo_mysql для MySQL/MariaDB либо pdo_pgsql для PostgreSQL. Проверьте: php -m | grep pdo. Если нужного модуля нет, никакой .env не поможет.
• Созданная база и пользователь с правами на неё — Laravel не создаёт базу сам, он подключается к существующей.

Последний пункт — источник половины ошибок у новичков. Laravel применяет миграции внутри базы, но саму базу (schema) вы создаёте руками заранее.

Создать базу заранее

Для MySQL/MariaDB через клиент:

CREATE DATABASE shop CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'shop_user'@'localhost' IDENTIFIED BY 'YOUR_PASSWORD';
GRANT ALL PRIVILEGES ON shop.* TO 'shop_user'@'localhost';
FLUSH PRIVILEGES;

Для PostgreSQL:

CREATE DATABASE shop;
CREATE USER shop_user WITH PASSWORD 'YOUR_PASSWORD';
GRANT ALL PRIVILEGES ON DATABASE shop TO shop_user;

Проверка: подключитесь к базе тем же пользователем и паролем через mysql -u shop_user -p shop или psql -U shop_user -d shop -h 127.0.0.1. Если пускает — половина дела сделана, дальше только конфиг.

Откуда берётся .env и как он устроен

В свежем проекте после composer create-project файла .env нет — есть только шаблон .env.example. Laravel при установке обычно копирует его сам, но если вы клонировали чужой репозиторий, сделайте это вручную:

cp .env.example .env
php artisan key:generate

Команда key:generate заполняет APP_KEY — без него приложение упадёт с ошибкой про отсутствующий ключ шифрования ещё до всякой базы. Файл .env добавлен в .gitignore и в репозиторий не попадает: это ваши локальные секреты. В git коммитится только .env.example с заглушками.

Правило простое: .env.example — карта того, какие переменные нужны, без реальных значений. .env — ваши реальные значения, которые не должны покинуть машину.

Блок подключения к базе

За подключение отвечают строки, начинающиеся с DB_. Вот они для MySQL:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shop
DB_USERNAME=shop_user
DB_PASSWORD=YOUR_PASSWORD

Что вписывать в каждую строку:

Про пароль отдельно: если в нём есть пробелы, знак # или другие спецсимволы, оберните значение в двойные кавычки — DB_PASSWORD="my pass#1". Символ # без кавычек Laravel посчитает началом комментария и отрежет часть пароля. Диагностировать это тяжело: пароль вроде на месте, а подключение отбивает.

SQLite для быстрого старта

Если СУБД ставить не хочется, для локальной разработки подойдёт SQLite. Laravel 11+ по умолчанию идёт именно на нём. Достаточно создать пустой файл и указать путь:

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

Затем создайте файл базы: touch database/database.sqlite. Laravel ищет его по этому пути по умолчанию. Это удобно для прототипа, но для продакшена с параллельной записью SQLite не подходит — переходите на MySQL или PostgreSQL.

Первая миграция и проверка

После правки .env сбросьте кеш конфигурации — Laravel может держать старые значения в кеше, и новый пароль просто не подхватится:

php artisan config:clear

Затем запустите миграции:

php artisan migrate

Как понять, что получилось: в консоли пойдёт список миграций со статусом DONE, а в базе появятся таблицы (users, migrations и другие). Проверьте их наличие в клиенте базы — если таблицы есть, подключение полностью рабочее.

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

Вот ошибки, которые вы реально увидите в консоли, и что делать с каждой.

• SQLSTATE[HY000] [2002] Connection refused — СУБД не запущена, либо неверный DB_HOST/DB_PORT. Проверьте, что сервер базы работает и слушает указанный порт.
• SQLSTATE[HY000] [1045] Access denied for user — неверный пользователь или пароль, либо у пользователя нет прав на базу. Проверьте вход тем же логином через клиент напрямую.
• SQLSTATE[HY000] [1049] Unknown database 'shop' — базы с таким именем нет. Вернитесь к созданию базы: Laravel её не создаёт.
• could not find driver — не установлен PHP-драйвер (pdo_mysql или pdo_pgsql). Установите модуль и перезапустите PHP-FPM или веб-сервер.
• Изменил пароль, а всё равно Access denied — почти всегда закешированный конфиг. Выполните php artisan config:clear. Если проект деплоили с config:cache, старые значения живут в bootstrap/cache/config.php.

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

Когда подключение работает, настройте под задачу остальное. На локальной машине держите APP_DEBUG=true, чтобы видеть подробные ошибки, но на проде переключите в false — иначе стектрейсы с деталями подключения увидят посетители. На сервере после деплоя запускайте php artisan config:cache для скорости, но помните: после этого любое изменение .env требует повторного config:cache, иначе оно не применится. Дальше стоит разобраться с пулом подключений и отдельным пользователем базы с урезанными правами для приложения — но это уже отдельная тема.