#Симптомы и условия возникновения
Приложение Node.js не подключается к PostgreSQL или MySQL: ECONNREFUSED, ETIMEDOUT, ENOTFOUND и «authentication failed» имеют разные причины. Проверять следует адрес, доступность TCP и учётные данные отдельно. Для начала проверьте используемую версию среды и точный текст ошибки на копии проекта, не меняя рабочий сервер.
#Причины и как их отличить
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Неправильный host в DockerВ этой ситуации наблюдается конкретный диагностический признак. Сопоставьте его с журналом ошибки и результатом соответствующей проверки, прежде чем выбирать исправление. | localhost указан внутри отдельного контейнера приложения | Использовать имя сервиса сети Docker. |
| Сервер не слушает или путь закрытВ этой ситуации наблюдается конкретный диагностический признак. Сопоставьте его с журналом ошибки и результатом соответствующей проверки, прежде чем выбирать исправление. | ECONNREFUSED либо тайм-аут | Проверить слушающий адрес, порт и правила сети. |
| Неверные учетные данныеВ этой ситуации наблюдается конкретный диагностический признак. Сопоставьте его с журналом ошибки и результатом соответствующей проверки, прежде чем выбирать исправление. | При доступном сервере возвращается ошибка аутентификации | Проверить отдельного пользователя и права подключения. |
#Пошаговая диагностика и решение
- 1. Сначала зафиксируйте точную ошибку драйвераВ логах найдите error.code и адрес назначения; не сохраняйте строку подключения с паролем. Разделите ENOTFOUND (имя), ECONNREFUSED (отказ порта), ETIMEDOUT (нет ответа) и ошибки авторизации.
- 2. Проверьте контекст запускаЕсли Node работает в Docker,
localhostозначает сам контейнер. Откройте docker-compose.yml и сравните имя сервиса БД, порт контейнера и общую сеть. С хоста используется опубликованный порт, между сервисами — внутренний.
- 3. Проверьте DNS и порт без раскрытия секретаИз того же окружения, что и Node, попробуйте разрешить имя базы
node -e "require('node:dns').lookup('db', console.log)"(в контейнере db замените на реальное имя). Убедитесь, что возвращается IP; при ошибке проверьте сеть/имя сервиса.Linux · Терминал (Bash)КомандаВыполните внутри контейнера приложения или на сервере Node; db замените действительным именем. Не требует пароля.node -e "require('node:dns').lookup('db', console.log)"
- 4. Проверьте доступность портаДля PostgreSQL обычно 5432, MySQL обычно 3306, но фактический порт определяется вашей настройкой. В том же окружении выполните TCP-пробу с тайм-аутом, чтобы отличить сетевую проблему от отказа в доступе.
- 5. Сверьте права и способ TLSПри успешном TCP, но ошибке логина, попросите администратора БД проверить пользователя, базу и разрешённый источник. Для удалённой БД проверьте настройки TLS драйвера; не отключайте проверку сертификата для устранения ошибки.
- 6. Проверьте пул подключенийУбедитесь, что используется один управляемый пул, а не новое соединение на каждый запрос без закрытия. Сравните
maxи предел подключений БД; при переполнении запросы могут ожидать даже при исправной сети.
- 7. Запустите минимальный проверочный запросОт имени отдельного тестового пользователя выполните через свою библиотеку SELECT 1. Не используйте административную учётную запись в приложении. Если запрос выполнен, сравните настройки с рабочим сервисом, перезапустите в окно обслуживания.
#Как проверить результат и что делать, если не помогло
Из окружения Node проходит авторизация и запрос SELECT 1, ошибки кодов сети не повторяются, пул выдерживает контрольную нагрузку.
Если неисправность повторилась, выпишите первый код ошибки и действие, на котором она возвращается. Сравните версию Node.js/npm, рабочий каталог, настройки процесса и журнал тестового запуска. Откатите только внесённые изменения из предварительно сохранённой копии, затем разберите причину на отдельной среде.