Подключение Node.js к PostgreSQL через node-postgres

Крупный план звеньев металлической цепи крупным планом

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

Большинство языков программирования предоставляют средства для подключения приложений к таким СУБД, как PostgreSQL. Ниже — подробная инструкция, как с помощью пакета node-postgres (pg) подключить Node.js-приложение к PostgreSQL.

Как начать

Чтобы подключиться к локальной базе данных, сначала убедитесь, что сервер PostgreSQL установлен и запущен.

PostgreSQL является одной из наиболее популярных реляционных СУБД благодаря гибкости и функциональности. Его часто выбирают вместо MySQL для более сложных проектов или когда важна открытость и расширяемость.

Создание Node-приложения

Первым шагом создайте каталог для тестового приложения.

        `mkdir postgres-node  
`

Перейдите в созданную папку и инициализируйте npm.

        `cd postgres-node  
npm init -y  
`

Эта команда должна создать файл package.json.

Создайте файл index.js — в нём вы будете писать код подключения к PostgreSQL.

Модуль node-postgres

node-postgres (пакет pg) — npm-пакет, который позволяет подключаться и взаимодействовать с PostgreSQL из Node.js. Есть два основных варианта использования:

одиночный Client — если нужен один статический соединение;
Pool (пул соединений) — если требуется обрабатывать несколько одновременных запросов.

Выбирайте Client для простых задач и скриптов; Pool — для серверных приложений с конкурентными запросами.

Установка node-postgres

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

        `npm install pg  
`

Если вы используете Node.js версии >= 14.x, рекомендуется установить совместимую ветку pg (например, 8.x). Можно указать версию при установке:

        `npm install pg=8.7.3  
`

Параметры подключения

Для подключения node-postgres требует набор параметров:

PGUSER — имя пользователя PostgreSQL.
PGHOST — адрес сервера (например, localhost).
PGPASSWORD — пароль пользователя.
PGDATABASE — имя базы данных.
PGPORT — порт сервера (обычно 5432).

Создайте файл .env и добавьте эти переменные, подставив значения вашей БД:

        `PGUSER=  
PGHOST=  
PGPASSWORD=  
PGDATABASE=  
PGPORT=  
`

Установите пакет dotenv, чтобы читать .env из Node:

        `npm install dotenv  
`

В index.js импортируйте и сконфигурируйте dotenv:

        `const dotenv = require("dotenv")  
dotenv.config()  
`

Подключение с помощью одиночного Client

Ниже — пример подключения с одним Client. Этот подход удобен для простых скриптов или задач, где нужен единственный последовательный запрос.

        `const { Client } = require("pg")  
const dotenv = require("dotenv")  
dotenv.config()  
  
const connectDb = async () => {  
    try {  
        const client = new Client({  
            user: process.env.PGUSER,  
            host: process.env.PGHOST,  
            database: process.env.PGDATABASE,  
            password: process.env.PGPASSWORD,  
            port: process.env.PGPORT  
        })  
  
        await client.connect()  
        const res = await client.query('SELECT * FROM some_table')  
        console.log(res)  
        await client.end()  
    } catch (error) {  
        console.log(error)  
    }  
}  
  
connectDb()  
`

Пул соединений (Pool)

Пул соединений позволяет обслуживать несколько параллельных запросов и эффективнее использовать ресурсы сервера баз данных.

        `const { Pool } = require("pg");  
const dotenv = require("dotenv");  
dotenv.config();  
  
const connectDb = async () => {  
    try {  
        const pool = new Pool({  
            user: process.env.PGUSER,  
            host: process.env.PGHOST,  
            database: process.env.PGDATABASE,  
            password: process.env.PGPASSWORD,  
            port: process.env.PGPORT,  
        });  
  
        await pool.connect()  
        const res = await pool.query('SELECT * FROM clients')  
        console.log(res)  
        await pool.end()  
    } catch (error) {  
        console.log(error)  
    }  
}  
  
connectDb()  
  
`

В примере пул настраивается через .env. Альтернативно можно полагаться на стандартные переменные окружения — тогда Pool возьмёт их автоматически.

        `const connectDb = async () => {  
    try {  
        const pool = new Pool();  
        const res = await pool.query('SELECT * FROM clients')  
        console.log(res)  
        await pool.end()  
    } catch (error) {  
        console.log(error)  
    }  
}  
`

При таком подходе укажите переменные окружения при запуске:

        `PGUSER= \  
PGHOST= \  
PGPASSWORD= \  
PGDATABASE= \  
PGPORT= \  
node\u00A0index.js  
`

Это делает программу более переносимой и удобной для деплоя.

Когда выбирать Client, а когда Pool

Если приложение выполняет редкие последовательные задачи или короткие админские скрипты — Client проще.
Для веб-сервера, API или приложений с параллельными запросами — обязательно используйте Pool.
В серверных окружениях контролируйте максимальное количество клиентов в пуле (max) и таймауты.

Отладка и распространённые ошибки

ECONNREFUSED или connection refused — проверьте, запущен ли PostgreSQL и правильность хоста/порта.
28P01 / authentication failed — неверный пользователь или пароль.
Неправильная переменная окружения — убедитесь, что dotenv вызывается до создания клиента или пула.
Утечки соединений — забытые client.end() или pool.end() приводят к удержанию ресурсов.

Советы для отладки: включите logging в PostgreSQL, проверяйте процессы соединений (pg_stat_activity) и тестируйте локально psql.

Безопасность и секреты

Никогда не храните пароли в репозитории. Используйте .env (в .gitignore) или менеджеры секретов среды (Vault, AWS Secrets Manager).
Ограничьте доступ по сети: настройте pg_hba.conf и firewall, чтобы принимать соединения только с доверенных адресов.
Используйте SSL/TLS для соединений при работе с удалёнными базами.

Важно: в продакшене отдавайте предпочтение управляемым секретам и ротации паролей.

Практические шаблоны и чеклист

Чеклист перед деплоем:

Переменные окружения заданы и не включены в репозиторий.
Пул настроен с ограничением max.
Логи и метрики подключены.
Проверена работа SSL, если требуется.
Произведена нагрузочная проверка на типичном окружении.

Роль-based чеклист:

Разработчик: писать код с try/catch, закрывать соединения, не логировать пароли.
DevOps: настраивать секреты, сеть, мониторинг и резервное копирование БД.
DBA: правильно конфигурировать pg_hba.conf, планировать maintenance и индексы.

Критерии приёмки

Приложение успешно выполняет целевые SQL-запросы в тестовой БД.
Нет утечек соединений при нагрузочном тесте.
Переменные секретов не попали в репозиторий.
Метрики (latency, active connections) находятся в допустимых пределах.

Нюансы и альтернативы

Если вам нужна ORM-абстракция: рассмотрите Sequelize, TypeORM или Objection.js поверх pg.
Для простых ключ-значение задач можно использовать Redis.
Если требуется аналитика и OLAP — подумайте о ClickHouse или специализированных решениях.

Фактические преимущества pg: нативный драйвер, активное сообщество и совместимость с большинством облачных PostgreSQL-провайдеров.

Короткий глоссарий

Client — одиночное соединение к БД.
Pool — пул повторно используемых соединений.
.env — файл с переменными окружения для локальной разработки.

Завершение

В этой статье вы узнали, как быстро настроить подключение Node.js к PostgreSQL с помощью node-postgres, когда использовать Client или Pool, и получили базовый чеклист для деплоя. Начните с локальной разработки, затем перенесите конфигурацию в переменные окружения или системе управления секретами для продакшена.

Важно: выбор СУБД должен соответствовать требованиям данных и нагрузке приложения — PostgreSQL отлично подходит для сложных реляционных задач, но альтернативы (MySQL, NoSQL) тоже уместны в зависимости от случая.