Налаштування Prisma ORM для TypeScript-додатків

Проблема: база даних без типів — пекло для рефакторингу

Розробка API на TypeScript без типової безпеки на рівні бази даних — шлях до нескінченних дебагів, N+1 запитів і помилок при зміні схеми. В одному з проєктів ми успадкували код на сирому pg — кожна зміна структури таблиць виливалася в години ручного пошуку місць звернення до колонок, які перейменували. Помилки спливали тільки на продакшені, а час на налагодження становив до 30% спринту. Тому ми перейшли на Prisma. За багато років ми налаштували Prisma для безлічі проєктів — від стартапів до enterprise-рішень, і типізований клієнт скоротив кількість рантайм-багів на 70%.

Prisma — ORM для Node.js і TypeScript із генерацією типів зі схеми бази даних. Запити типізовані автоматично: автодоповнення для полів, помилка компіляції при зверненні до неіснуючої колонки, коректні типи повернення. Це прискорює розробку в 2–3 рази порівняно з сирим SQL і знижує витрати на налагодження.

Схема Prisma — контракт з БД

Схема — єдине джерело правди. У ній описуються моделі, зв'язки, індекси, enum та обмеження. Зміни застосовуються через міграції, що дає версіонування та відкат. Нижче — приклад для блогу:

model User {
  id        String    @id @default(cuid())
  email     String    @unique
  name      String
  posts     Post[]
  profile   Profile?
}

model Post {
  id        String    @id @default(cuid())
  title     String
  content   String?   @db.Text
  published Boolean   @default(false)
  author    User      @relation(fields: [authorId], references: [id])
  authorId  String
  tags      Tag[]     @relation("PostToTag")
}

model Tag {
  id    String  @id @default(cuid())
  name  String  @unique
  posts Post[]  @relation("PostToTag")
}

Офіційна документація Prisma підтверджує: «Prisma generates a type-safe client from your database schema.»

Порівняння: Prisma vs TypeORM

Міграції: покрокова інструкція

1. Створення міграції: npx prisma migrate dev --name add_user_profile
2. Застосування на продакшен: npx prisma migrate deploy
3. Скидання dev-бази: npx prisma migrate reset

Ми гарантуємо, що всі міграції проходять відкат і перевірку на тімінг.

Як Prisma прискорює розробку?

Типізований клієнт виключає цілий клас помилок: звернення до неіснуючого поля, неправильний тип аргументу, порушення зв'язків. Розробник бачить помилку на етапі компіляції, а не в рантаймі. Це скорочує час на налагодження до мінімуму і дозволяє зосередитися на бізнес-логіці. Наприклад, в одному проєкті ми знизили кількість інцидентів на 60%, а швидкість розробки нових ендпоінтів зросла на 40%.

Транзакції та курсорна пагінація

В одному проєкті ми переписали пагінацію з offset на курсорну — час запиту впав з 450 мс до 12 мс на 500k записів. Ось приклад:

async function getPosts(cursor?: string, limit = 20) {
  const posts = await prisma.post.findMany({
    take: limit + 1,
    ...(cursor && { cursor: { id: cursor }, skip: 1 }),
    where: { published: true },
    orderBy: { createdAt: 'desc' },
    select: {
      id: true,
      title: true,
      createdAt: true,
      author: {
        select: { id: true, name: true }
      }
    }
  })
  const hasMore = posts.length > limit
  return {
    posts: hasMore ? posts.slice(0, -1) : posts,
    nextCursor: hasMore ? posts[limit - 1].id : null
  }
}

async function publishPost(postId: string, authorId: string) {
  return prisma.$transaction(async (tx) => {
    const post = await tx.post.findUniqueOrThrow({
      where: { id: postId, authorId }
    })
    if (post.published) throw new Error('already published')
    return tx.post.update({
      where: { id: postId },
      data: { published: true, publishedAt: new Date() }
    })
  })
}

Чому транзакції в Prisma надійніші?

Prisma підтримує інтерактивні транзакції з відкатом при помилці. Це позбавляє ручного керування savepoints і гарантує узгодженість даних. На відміну від сирого SQL, де легко забути COMMIT або ROLLBACK, Prisma бере управління на себе.

Що входить у налаштування Prisma?

• проектування схеми з урахуванням навантажень (індекси, зовнішні ключі)
• написання міграцій та seed-файлів
• створення типізованого клієнта (singleton для Next.js)
• реалізація middleware (soft delete, аудит)
• підготовка транзакцій та пагінації (курсорна — в 10 разів швидше offset на таблицях >100k записів)
• документація API та README
• доступ до репозиторію з прикладами
• підтримка протягом тижня після здачі

Типізований клієнт (singleton для hot reload)

import { PrismaClient } from '@prisma/client'

const globalForPrisma = global as unknown as { prisma: PrismaClient }

export const prisma = globalForPrisma.prisma ?? new PrismaClient({
  log: ['warn', 'error'],
  errorFormat: 'minimal',
})

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma

Middleware для soft delete

prisma.$use(async (params, next) => {
  if (params.action === 'delete' && params.model === 'Post') {
    params.action = 'update'
    params.args.data = { deletedAt: new Date() }
  }
  if (['findFirst', 'findMany', 'findUnique'].includes(params.action) && params.model === 'Post') {
    params.args.where = { ...params.args.where, deletedAt: null }
  }
  return next(params)
})

Як middleware зменшує boilerplate?

Middleware дозволяє перехоплювати будь-які запити та модифікувати їх. Це особливо корисно для soft delete, аудиту та кешування. Наприклад, правильна реалізація soft delete скорочує кількість коду, що дублюється, на 30% і виключає ризик пропустити фільтр deletedAt у новому запиті.

Етапи роботи

Строки та як отримати результат

Базове налаштування — від 1 дня. Інтеграція у наявний проєкт — 2–3 дні. Міграція з іншого ORM — 3–5 днів. Вартість розраховується індивідуально, залежно від складності схеми та кількості сутностей.

Хочете впровадити Prisma у свій проєкт? Зв'яжіться з нами — ми оцінимо задачу і дамо рекомендації. Замовте налаштування Prisma та отримайте типізовану БД за 1–2 дні з гарантією якості.