Prisma + Next.js: подключение к PostgreSQL

Стеклянная призма на коричневом песке на закате

Кратко: используйте Prisma как ORM для безопасного и удобного доступа к PostgreSQL из Next.js — инициализируйте проект, настройте DATABASE_URL в .env, опишите модель в schema.prisma, выполните npx prisma db push, сгенерируйте клиента и используйте его на сервере через API-роуты. Обязательно проверяйте методы запроса, валидируйте ввод и защищайте строку подключения.

Зачем использовать Prisma

Прямая работа с базой данных увеличивает объём SQL-кода и риск уязвимостей, например SQL-инъекций. ORM (Object Relational Mapper) вроде Prisma обеспечивает абстракцию поверх базы, делает код читаемым и упрощает миграции и рефакторинг схемы.

В этом руководстве вы научитесь подключать Prisma к PostgreSQL в Next.js, создавать модели, генерировать клиента и выполнять CRUD-операции через API.

Что потребуется

Node.js и npm установлены в системе.
Доступ к PostgreSQL (локально или удалённо).
Базовое понимание JavaScript/React/Next.js.

Важно: для production окружения используйте отдельного пользователя БД с минимальными правами и храните секреты в безопасном хранилище.

Создание приложения Next.js

Откройте терминал и создайте проект с именем prisma-next:

npx create-next-app prisma-next

Перейдите в директорию проекта и запустите локальный сервер разработки:

cd prisma-next
npm run dev

По умолчанию сервер доступен на http://localhost:3000.

Установка Prisma

Установите пакеты prisma (CLI/инструменты) и @prisma/client (автогенерируемый клиент):

npm install prisma @prisma/client

Инициализируйте Prisma в проекте:

npx prisma init

Команда создаст файл schema.prisma и .env.

Добавление URL подключения

Формат строки подключения к PostgreSQL примерно такой:

postgresql://{username}:{password}@{hostname}:{port}/{database-name}

Добавьте эту строку в файл .env:

DATABASE_URL="postgresql://username:password@localhost:5432/mydatabase"

Замените username, password, hostname, port и database-name на ваши реальные значения. В production окружениях используйте менеджер секретов или переменные окружения в платформе деплоя.

В schema.prisma укажите источник данных:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

Определение модели данных

Пример простой модели User в schema.prisma:

model User {
  id    String @id @default(cuid())
  name  String?
  email String @unique
}

Описание: id — первичный ключ типа String с автоматической генерацией; name необязательное поле; email уникален.

После изменений в схеме примените их к базе:

npx prisma db push

npx prisma db push создаёт таблицы без полноценной миграционной истории. Если хотите историю миграций — используйте prisma migrate.

Генерация Prisma Client

Сгенерируйте клиент, чтобы работать с моделями из кода:

npx prisma generate

После генерации появится доступ к клиенту через импорт @prisma/client.

Создание экземпляра Prisma Client в Next.js

Создайте папку lib и файл lib/prisma.js с кодом, который безопасно создаёт один экземпляр Prisma Client (важно для dev-сервера с hot reload):

import { PrismaClient } from "@prisma/client";

let prisma;

if (typeof window === "undefined") {
  if (process.env.NODE_ENV === "production") {
    prisma = new PrismaClient();
  } else {
    if (!globalThis.prisma) {
      globalThis.prisma = new PrismaClient();
    }
    prisma = globalThis.prisma;
  }
}

export default prisma;

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

Пример API-роута для создания пользователя

Prisma обычно используется на серверной стороне. В Next.js создайте API-роут pages/api/db/createuser.js:

import prisma from "@/lib/prisma";

export default async function handler(req, res) {
  if (req.method !== "POST") {
    return res.status(405).json({ error: "Method not allowed", user: null });
  }

  const { name, email } = req.body;

  // Простая валидация
  if (!email) {
    return res.status(400).json({ error: "Email is required", user: null });
  }

  try {
    const newUser = await prisma.user.create({
      data: {
        name,
        email,
      },
    });
    res.status(201).json({ user: newUser, error: null });
  } catch (error) {
    res.status(400).json({ error: error.message, user: null });
  }
}

Ключевые моменты: проверка метода запроса, использование req.body для POST и обработка ошибок.

Форма в клиентской части (app/profile/page.js)

Пример простого клиентского компонента с формой, который отправляет POST-запрос на API-роут:

"use client";
import React, { useState } from "react";

export default function Page() {
  const [name, setName] = useState("");
  const [email, setEmail] = useState("");
  const [status, setStatus] = useState(null);

  const handleSubmit = async (e) => {
    e.preventDefault();
    setStatus("loading");

    try {
      const res = await fetch("/api/db/createuser", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ name, email }),
      });
      const data = await res.json();
      if (res.ok) {
        setStatus("success");
        console.log(data.user);
      } else {
        setStatus(`error: ${data.error}`);
      }
    } catch (err) {
      setStatus(`error: ${err.message}`);
    }
  };

  return (
    
       setName(e.target.value)}
      />
       setEmail(e.target.value)}
      />
      
      {status && {status}}
    
  );
}

После отправки формы API-роут создаст запись в таблице User.

Другие операции с Prisma

Prisma предоставляет методы для чтения, обновления и удаления:

// find
const users = await prisma.user.findMany({ where: { name: { contains: 'A' } } });

// update
const updated = await prisma.user.update({ where: { id: '...' }, data: { name: 'New' } });

// delete
const deleted = await prisma.user.delete({ where: { id: '...' } });

Используйте промисы, оборачивайте в try/catch и возвращайте информативные HTTP-статусы.

Безопасность и эксплуатация

Important: защита данных и доступов критически важна.

Храните DATABASE_URL в защищённых переменных окружения, не в репозитории.
Используйте пользователя БД с минимальными правами и отдельную схему для приложений.
Включайте SSL/TLS для удалённых подключений.
Для управления пулом подключений в production используйте PgBouncer или Prisma Data Proxy.
Ограничьте экспозицию API: проверяйте методы, валидируйте и санитизируйте ввод.
Логируйте ошибки, но не записывайте в логи секреты или полные строки подключения.

Когда Prisma может не подойти

Очень сложные SQL-запросы с тонкой оптимизацией (требуются хинты или специфичные конструкции SQL).
Случаи, где нужна максимальная портируемость между множеством разных SQL-диалектов и уже сложная ручная миграция.

В таких случаях рассмотрите raw SQL через pg/pg-promise или query builders.

Альтернативы

pg (node-postgres) — нативный драйвер, даёт полный контроль и лучший контроль производительности.
Knex — query builder с миграциями.
TypeORM, Sequelize — другие ORM с разными соглашениями и уровнем абстракции.

Выбор зависит от требований: удобство разработки vs контроль и производительность.

Быстрая методичка: чек-листы по ролям

Разработчик:

Инициализировать prisma и сгенерировать клиента.
Описать модели в schema.prisma.
Не хранить секреты в коде.

DevOps:

Настроить секреты окружения.
Настроить пул подключений (PgBouncer) для нагрузки.
Настроить бэкапы БД.

DBA:

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

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

API-роут POST /api/db/createuser создаёт пользователя в базе и возвращает 201.
Неправильные данные возвращают 4xx с понятной ошибкой.
Логов с секретами нет.
Тесты покрывают основные сценарии (см. тест-кейсы далее).

Тест-кейсы

Успешное создание пользователя
- Ввод: валидный email и имя
- Ожидаемый результат: HTTP 201 и объект пользователя
Отсутствует email
- Ожидаемый результат: HTTP 400 и сообщение об ошибке
Повтор email (уже существует)
- Ожидаемый результат: HTTP 400 с сообщением уникальности
Метод GET на роуте
- Ожидаемый результат: HTTP 405

Краткая шпаргалка по командам

npx create-next-app prisma-next — создать Next.js проект
npm install prisma @prisma/client — установить Prisma
npx prisma init — инициализация
npx prisma db push — применить schema.prisma в БД
npx prisma generate — сгенерировать Prisma Client

Простая схема принятия решения (Mermaid)

flowchart TD
  A[Нужна быстрая разработка и безопасность?] -->|Да| B[Использовать Prisma]
  A -->|Нет| C[Использовать raw SQL или query builder]
  B --> D{Требуются сложные оптимизации SQL?}
  D -->|Да| C
  D -->|Нет| E[Оставаться на Prisma]

Однострочный глоссарий

ORM — библиотека для работы с базой через объекты/модели.
Prisma Client — автогенерируемый клиент для работы с моделями из JS.
schema.prisma — файл, где описываются модели и источник данных.
npx prisma db push — команда для доставки схемы в базу без миграций.

Итог и рекомендации

Использование Prisma в Next.js ускоряет разработку, упрощает чтение и поддержку кода и обеспечивает защиту от типичных ошибок при работе с SQL. Для production окружений уделите внимание управлению подключениями, правам БД и хранению секретов. Если вам нужна тонкая оптимизация запросов, комбинируйте Prisma с raw SQL в узких местах.

Summary

Prisma делает работу с PostgreSQL в Next.js безопаснее и удобнее.
Всегда валидируйте входные данные и проверяйте метод запроса.
Настройте пул подключений и безопасное хранение переменных окружения.

Notes

Если нужна история миграций и контроль версий схемы, используйте prisma migrate вместо db push.
Для высоконагруженных систем тестируйте поведение пула подключений под нагрузкой.