re:re:actable
Урок 032 минуты чтения

Как подключить PostgreSQL к Next.js

На этой странице
Кратко

Для PostgreSQL нужен работающий сервер БД и драйвер. Пакет pg отправляет SQL из Node.js; пул соединений позволяет переиспользовать подключения.

Вопрос

Как запустить локальную базу и создать подключение для серверного кода Next.js?

Основная идея

Пример рассчитан на App Router, Node.js runtime и выключенные Cache Components. Нужен Docker с Compose либо уже установленный PostgreSQL. Браузер к базе напрямую не подключается.

Пример: база и общий пул

# compose.yaml — только для локальной учебной базы
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: next_app
      POSTGRES_PASSWORD: local_password
      POSTGRES_DB: next_tasks
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - next_tasks_data:/var/lib/postgresql/data
volumes:
  next_tasks_data:
docker compose up -d
npm install pg server-only better-auth zod dotenv
npm install -D @types/pg

Настрой DATABASE_URL из предыдущего материала. Затем создай:

// lib/db-pool.ts — Node.js-модуль для сервера и CLI миграций
import { Pool } from "pg";
 
const connectionString = process.env.DATABASE_URL;
if (!connectionString) throw new Error("Не задан DATABASE_URL");
 
const shared = globalThis as typeof globalThis & { tasksPool?: Pool };
if (!shared.tasksPool) {
  shared.tasksPool = new Pool({
    connectionString,
    max: 5,
    connectionTimeoutMillis: 5000,
    idleTimeoutMillis: 30000,
  });
  shared.tasksPool.on("error", () => {
    console.error("Ошибка свободного соединения PostgreSQL");
  });
}
export const pool = shared.tasksPool;
// lib/db.ts — импортируй эту обертку из серверной логики Next.js
import "server-only";
export { pool } from "./db-pool";

globalThis помогает не создавать новый пул при каждом обновлении модулей в разработке. Низкоуровневый файл не содержит server-only, поскольку его будет читать CLI авторизации вне React. В клиентском коде ни один из этих файлов не используется.

Что важно помнить

Значение max: 5 — учебная настройка, не универсальная рекомендация. У каждого процесса собственный пул. При двадцати экземплярах приложения возможно до ста соединений.

Не вызывай pool.end() после каждого запроса: это закрывает общий пул. Для production используй параметры TLS, которые требует провайдер БД; не отключай проверку сертификата ради обхода ошибки.

Volume сохраняет данные после остановки контейнера. Удаление volume удаляет и базу; для обычного завершения работы достаточно docker compose stop.

Мини-шпаргалка

  • PostgreSQL хранит данные, pg связывает его с Node.js.
  • Один пул переиспользуется в пределах процесса.
  • Клиентские компоненты обращаются к серверу приложения.
  • Локальная база не заменяет настройки production-БД.

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам