Laravel: SQLSTATE[HY000] [2002] — Laravel не подключается к базе данных
Laravel берёт адрес базы данных, её имя, пользователя и пароль из файла .env. Ошибка со словом SQLSTATE значит, что подключиться не получилось: база не запущена, адрес или пароль неверные, базы нет или в ней нет таблиц. Номер в квадратных скобках подсказывает, что именно не так.
Содержание 13
Что сделать прямо сейчас
- Найдите в тексте ошибки номер в квадратных скобках после
SQLSTATE[…]и откройте его разбор в таблице. - Посмотрите настройки базы в файле .env:
grep '^DB_' .env— в папке проекта. - Проверьте, что база работает:
sudo systemctl status mysqlилиsudo systemctl status postgresql. - После правки .env выполните
php artisan config:clear.
Команды вводятся на сервере: подключитесь к нему по SSH (как подключиться). В папке проекта лежат файл artisan и папки public и storage, например /var/www/example.com.
Как выглядит ошибка
SQLSTATE[HY000] [2002] … (Connection: mysql, Host: 127.0.0.1, Port: 3306, Database: laravel, SQL: select * from `sessions` where `id` = … limit 1)| Часть | Что значит |
|---|---|
SQLSTATE[HY000] | код ошибки по стандарту SQL; HY000 — «общая ошибка» |
[2002] | номер ошибки от MySQL — по нему ищут причину |
… после номера | причина от системы или от базы данных |
Connection: mysql | какое подключение из настроек Laravel использовалось |
Host, Port, Database | куда Laravel подключался — сверьте с .env |
SQL: … | какой запрос Laravel хотел выполнить |
Запрос к таблице sessions в примере — не причина. В новом проекте Laravel сессии посетителей хранятся в базе, поэтому до базы Laravel обращается на любой странице, даже на главной.
Если в настройках задан сокет, вместо Host и Port в тексте стоит Socket: ….
Что значит номер в ошибке
| Начало ошибки | Что случилось | Что делать |
|---|---|---|
SQLSTATE[HY000] [2002] | до MySQL не достучаться: база не запущена или адрес неверный | проверьте DB_HOST и базу |
[2002] php_network_getaddresses: getaddrinfo for … failed | имя из DB_HOST не находится | поправьте DB_HOST |
SQLSTATE[HY000] [1045] Access denied for user | неверный пользователь или пароль | Разбор 1045 |
SQLSTATE[HY000] [1049] Unknown database | базы с таким именем нет | Разбор 1049 |
SQLSTATE[42S02]: Base table or view not found: 1146 | база есть, таблиц нет | выполните миграции |
SQLSTATE[08006] [7] connection to server at | PostgreSQL не отвечает или не пускает | PostgreSQL |
Database file at path [...] does not exist. | нет файла базы SQLite | SQLite |
could not find driver | в PHP нет модуля для базы | Разбор |
Какие строки .env проверить
grep '^DB_' .envОтвет для MySQL выглядит так:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=пароль| Строка | Что в ней |
|---|---|
DB_CONNECTION | какая база: mysql, mariadb, pgsql или sqlite |
DB_HOST | адрес сервера базы; если база на этом же сервере — 127.0.0.1 |
DB_PORT | порт: 3306 у MySQL и MariaDB, 5432 у PostgreSQL |
DB_DATABASE | имя базы; у SQLite — путь к файлу |
DB_USERNAME, DB_PASSWORD | пользователь базы и его пароль |
Если в пароле есть пробел или знак #, возьмите его в двойные кавычки: DB_PASSWORD="па#роль".
В новом проекте строки DB_HOST, DB_PORT и другие закомментированы — перед ними стоит #. Уберите #, иначе Laravel возьмёт значения по умолчанию: адрес 127.0.0.1 и базу с именем laravel.
Если правка .env не помогла
Если настройки закешированы командой php artisan config:cache или php artisan optimize, Laravel не читает .env. Обновите кеш:
php artisan config:clearЕсли кеш настроек нужен, снова выполните php artisan config:cache — после правки .env каждый раз.
Если номер 2002
Laravel не достучался до MySQL. После [2002] стоит причина от системы: нет файла сокета или в подключении отказано.
- Проверьте, что MySQL работает:
sudo systemctl status mysql. Если служба не работает —Active: failedилиinactive, — запустите:sudo systemctl start mysql. Если не запускается, причину покажетsudo journalctl -u mysql -n 30. - Сверьте
DB_HOSTиDB_PORTс тем, где MySQL принимает подключения:sudo ss -tlnp | grep 3306.
Чем отличаются localhost и 127.0.0.1 в DB_HOST:
| DB_HOST | Как PHP подключается | Разбор ошибки |
|---|---|---|
localhost | через файл сокета на этом сервере | MySQL 2002: Can't connect through socket |
127.0.0.1 | по сети, на порт из DB_PORT | MySQL 2003: Can't connect to MySQL server |
Если сомневаетесь, поставьте DB_HOST=127.0.0.1.
Если в DB_HOST имя, а не адрес
SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo for mysql failed: …В DB_HOST стоит имя, которого сервер не знает, — в примере mysql. Такое имя бывает в .env, скопированном с компьютера разработчика, где база работала в отдельном контейнере. На сервере укажите настоящий адрес базы: 127.0.0.1, если база на этом же сервере.
Если пишет Base table or view not found
SQLSTATE[42S02]: Base table or view not found: 1146 Table 'laravel.sessions' doesn't existК базе Laravel подключился, но таблиц в ней нет. Создайте их миграциями:
php artisan migrate --force--force нужен, если в .env стоит APP_ENV=production: без него команда переспросит. Перед миграциями на рабочем сайте сделайте копию базы. Подробнее о самой ошибке — MySQL 1146: Table doesn't exist.
Если база PostgreSQL
Ошибка подключения к PostgreSQL начинается так:
SQLSTATE[08006] [7] connection to server at "127.0.0.1", port 5432 failed: …Причина — после слова failed:.
| После failed | Разбор |
|---|---|
| в подключении отказано | PostgreSQL: Connection refused |
password authentication failed for user | PostgreSQL: password authentication failed |
database "…" does not exist | PostgreSQL: database does not exist |
Для PostgreSQL в .env стоит DB_CONNECTION=pgsql и DB_PORT=5432.
Если база SQLite
Database file at path [/var/www/example.com/database/database.sqlite] does not exist. Ensure this is an absolute path to the database.Файла базы SQLite нет по указанному пути. В новом проекте Laravel база по умолчанию — SQLite, файл — database/database.sqlite. Создайте файл и таблицы:
touch database/database.sqlite
php artisan migrate --force
sudo chown -R www-data:www-data databaseПоследняя команда отдаёт папку database пользователю сайта: SQLite пишет служебные файлы рядом с базой, поэтому писать нужно и в саму папку. Если папку не отдать, SQLite ответит attempt to write a readonly database.
Если в DB_DATABASE путь указан вручную, он должен начинаться с / — от корня диска.
Ошибки и как их исправить
| Что видите | Причина | Что делать |
|---|---|---|
SQLSTATE[HY000] [2002] | MySQL не запущен или неверный DB_HOST | проверьте базу и адрес |
getaddrinfo for … failed | в DB_HOST имя, которого нет | поставьте адрес |
[1045] Access denied for user | неверный пароль | Разбор |
[1049] Unknown database | нет базы | Разбор |
Base table or view not found | не выполнены миграции | php artisan migrate |
SQLSTATE[08006] [7] | PostgreSQL не пускает | PostgreSQL |
Database file at path [...] does not exist. | нет файла SQLite | создайте файл |
attempt to write a readonly database | у www-data нет записи в папку database | отдайте папку www-data |
| поправили .env, ошибка та же | настройки закешированы | php artisan config:clear |
could not find driver | нет модуля PHP для базы | Разбор |
Тексты сообщений сверены по исходному коду Laravel 13.42.0 и PHP 8.3.6.
Источники
- Документация Laravel: Database — на английском: настройки подключения, SQLite и строки DB_ в .env.
- Документация Laravel: Migrations — на английском: php artisan migrate и --force.
- Шаблон config/database.php в Laravel — на английском: значения по умолчанию 127.0.0.1 и laravel.
- Исходный код QueryException в Laravel — на английском: Connection, Host, Port, Socket и SQL в тексте ошибки.
- Исходный код SQLiteConnector в Laravel — на английском: проверка файла базы.
- Исходный код PDO в PHP 8.3.6 — на английском: как собирается текст SQLSTATE.
Сверено 13 ноября 2026 года.
Что почитать дальше
- Ошибки Laravelвсе ошибки Laravel на одной странице.
- Сервер для базы данныхкогда базу держать на отдельном сервере.
- MySQL 1045: Access deniedесли не подходит пароль.