Как подключить 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-БД.