Postgres в Next.js
База только на сервере, Neon и пулинг, кэш по видам данных, seed и миграции.
Обновлено
Что значит подключить Next.js к базе данных
В Next.js к базе обращаются только на сервере: в Server Components, Server Actions и Route Handlers. Компонент в браузере никогда не общается с базой напрямую — всегда через ваш серверный код, который проверяет, кто и что запрашивает.
Это приложение — ровно такой проект: Next.js 16 + Postgres на Neon.
«Серверлесс» Postgres — почему Neon, Supabase, Vercel Postgres
Классическая база постоянно держит открытые соединения. Серверлесс-функции (Vercel) часто запускаются и останавливаются — каждая открывала бы новые соединения и исчерпала бы лимит.
| Решение | Как решает |
|---|---|
HTTP-драйвер (@neondatabase/serverless) |
каждый запрос — HTTP-запрос, соединение держать не нужно |
пул соединений (PgBouncer, URL с -pooler) |
посредник переиспользует несколько настоящих соединений |
| scale to zero | база останавливается, когда не используется (дёшево для личных проектов) |
| ветвление (Neon) | мгновенная копия базы для каждого preview / PR |
Структура в проекте
.env.localDATABASE_URL — никогда в Gitsrc/shared/api/db.tsклиент с import 'server-only'
entities/lesson/api/lesson-api.tsзапросы с 'use cache' + cacheTag
progress/api/progress-api.tsчтение по пользователю (динамика)save-progress.tsServer Action для записи
db/schema.sqlструктура таблиц
scripts/seed.tsначальные данные
// shared/api/db.ts
import 'server-only'
import { neon } from '@neondatabase/serverless'
export const sql = neon(process.env.DATABASE_URL!)server-only заставит сборку упасть, если модуль когда-нибудь попадёт в Client Component.
Чтение, запись, кэш — полный шаблон
| Операция | Где | Кэш |
|---|---|---|
| публичные данные (уроки, товары) | функция в entities/*/api |
'use cache' + cacheLife + cacheTag |
| данные пользователя (прогресс, корзина) | функция, читающая cookies() / сессию |
динамика, внутри <Suspense> |
| запись | Server Action: авторизация → валидация Zod → запрос → updateTag / refresh() |
инвалидация |
Все три реализованы в этом приложении — см. Кэш и Server Actions.
Seed и тестовые данные
Seed наполняет базу начальными данными (контент уроков здесь приходит из npm run seed). Правила: seed идемпотентен (два запуска дают один результат — INSERT ... ON CONFLICT DO UPDATE) и не запускается на продакшене с тестовыми данными.
Чек-лист продакшена
DATABASE_URLзадан в Vercel отдельно для Production и Preview (в идеале — отдельная ветка Neon для preview).- URL с pooler для серверлесс-функций.
- Миграции выполнены до деплоя кода, который от них зависит.
- Индексы на колонках из
WHEREиJOIN. - Включены бэкапы / point-in-time restore.
Коротко
- База — только на сервере; клиент БД с
server-only. - Серверлесс → HTTP-драйвер или пулинг; Neon даёт ещё и ветвление для preview.
- Публичное →
'use cache'; по пользователю → динамика в Suspense; запись → Server Action + инвалидация.