Подключение базы и настройка .env в Laravel: гайд

После composer create-project laravel/laravel myapp вы получаете рабочий каркас, но первая же команда php artisan migrate упрётся в базу данных. По умолчанию Laravel 11 настроен на SQLite, и если вы хотите MySQL или PostgreSQL — придётся править файл .env. Это займёт около 15 минут: создать базу, вписать реквизиты, проверить подключение и прогнать миграции. В конце у вас будут созданные таблицы users, cache, jobs и рабочее соединение.

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

Проверьте, что всё это на месте, иначе застрянете на середине.

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

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

Шаг 1. Создайте базу данных

Laravel не создаёт саму базу — только таблицы внутри неё. Базу создаёте вы вручную.

Для MySQL:

mysql -u root -p

CREATE DATABASE myapp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;

Для PostgreSQL:

psql -U postgres

CREATE DATABASE myapp;
\q

Проверка: команда завершилась без ошибки, а SHOW DATABASES; (MySQL) или \l (PostgreSQL) показывает myapp в списке.

Шаг 2. Откройте .env и найдите блок DB_

В корне проекта лежит .env. Если его нет, скопируйте из шаблона: cp .env.example .env. Найдите строки, начинающиеся с DB_. В Laravel 11 по умолчанию они выглядят так:

DB_CONNECTION=sqlite
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=laravel
# DB_USERNAME=root
# DB_PASSWORD=

Часть строк закомментирована. Их нужно раскомментировать и заполнить.

Шаг 3. Впишите реквизиты подключения

Для MySQL блок должен принять такой вид:

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

Для PostgreSQL меняется драйвер и порт:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=myapp
DB_USERNAME=postgres
DB_PASSWORD=YOUR_DB_PASSWORD

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

Если пароль содержит пробел, # или другой спецсимвол — заключите значение в двойные кавычки: DB_PASSWORD="p@ss #1". Иначе парсер .env обрежет строку на символе #, приняв остаток за комментарий.

Шаг 4. Сбросьте кеш конфигурации

Laravel умеет кешировать конфиг в один файл ради скорости. Если вы когда-то запускали php artisan config:cache, старые значения .env будут висеть в кеше, и новые не подхватятся. Сбросьте его:

php artisan config:clear

Проверка: в ответ вы увидите строку вроде Configuration cache cleared successfully.

Важная деталь: внутри контроллеров и моделей нельзя читать env('DB_HOST') напрямую — при закешированном конфиге env() вернёт null. Обращайтесь только через config('database.connections.mysql.host'). Функция env() допустима лишь в файлах config/*.php.

Шаг 5. Проверьте подключение и прогоните миграции

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

php artisan db:show

Команда выведет таблицу с именем БД, драйвером, хостом и числом таблиц. Если вместо этого прилетела ошибка подключения — переходите в раздел ниже. Если всё в порядке, создавайте таблицы:

php artisan migrate

Проверка: в консоли построчно пройдут миграции со статусом DONE, а в базе появятся таблицы migrations, users, cache, jobs. Открыв базу любым клиентом, вы их увидите.

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

• SQLSTATE[HY000] [1045] Access denied for user — неверный логин или пароль в .env. Проверьте DB_USERNAME/DB_PASSWORD и что не забыли config:clear после правки.
• SQLSTATE[HY000] [2002] Connection refused — сервер БД не запущен или неверный DB_HOST/DB_PORT. Проверьте, что MySQL/PostgreSQL работает, и что порт совпадает.
• SQLSTATE[HY000] [1049] Unknown database 'myapp' — база не создана. Вернитесь к шагу 1.
• could not find driver — не установлено PHP-расширение pdo_mysql или pdo_pgsql. Установите его и перезапустите PHP-процесс (для php-fpm — перезагрузите сервис).
• Изменили .env, а ничего не поменялось — почти всегда виноват закешированный конфиг. Выполните php artisan config:clear.

Docker и отдельный сервер БД

Одна ловушка касается тех, кто запускает приложение и базу в разных контейнерах. Внутри контейнера 127.0.0.1 — это сам контейнер приложения, а не хост с базой. В этом случае в DB_HOST ставят имя сервиса из docker-compose.yml (например mysql или db), а не localhost. Полная настройка Docker — отдельная тема, здесь важно только это соответствие имён.

Что дальше

Подключение работает — теперь стоит настроить остальные хранилища, которые Laravel по умолчанию тоже уводит в базу или файлы: SESSION_DRIVER, CACHE_STORE, QUEUE_CONNECTION. На боевом сервере кеш конфига, наоборот, включают — php artisan config:cache при деплое, — но тогда все значения обязаны быть в .env до кеширования. Следующий шаг после этого — создать первую свою миграцию через php artisan make:migration и описать таблицы под ваш проект.