Початок роботи з Prisma у Node.js та PostgreSQL

Вступ

Prisma — це практичний вибір ORM для сервісів на Node та TypeScript, яким потрібен типований доступ до бази даних. Наведений нижче посібник — це швидкий шлях від базового проекту Node до міграцій, генерованого клієнта та кількох запитів для читання/запису даних у PostgreSQL. Prisma знаходиться між TypeScript-кодом додатку та PostgreSQL: файл схеми є контрактом, міграції змінюють структуру бази даних, а генерований клієнт надає типовані методи для кожної моделі. Ігнорування будь-якого з цих трьох елементів зазвичай призводить пізніше або до помилок SQL під час виконання, або до ситуації, коли TypeScript не може бачити поля, які вже існують у базі даних.

Спочатку підготуйте проект на Node — а також TypeScript, якщо це мова проекту.

Давайте налаштуємо Prisma

Крок 1: Встановіть Prisma та Prisma Client

Встановіть обидві пакети у каталозі проекту:

npm install prisma @prisma/client

• prisma — це CLI-інструмент для роботи з схемами, міграцій та створення клієнтського коду.
• @prisma/client — це бібліотека, код якої імпортується в додатках для звернень до бази даних.

Крок 2: Ініціалізація Prisma

Ініціалізуйте проект з використанням PostgreSQL та власного шляху зберігання клієнтського коду:

npx prisma init --datasource-provider postgresql --output ../generated/prisma

Що робить ця команда:

• Створює каталог prisma з файлом schema.prisma, у якому вказані налаштування підключення та моделі.
• Встановлює джерело даних як PostgreSQL.
• Створює кореневий файл .env для зберігання конфіденційної інформації, такої як URL бази даних.
• --output ../generated/prisma перенаправляє результати створення клієнтського коду за межі стандартного місця зберігання.

Примітка: команда prisma init за замовчуванням використовує PostgreSQL. Якщо потрібен інший двигун або було пропущено параметр --datasource-provider, змініть блок datasource у файлі schema.prisma.

Приклад для PostgreSQL:

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

Розмістіть рядок підключення у файлі .env:

DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA"

Перед створенням моделей чи міграціями замініть USER, PASSWORD, HOST, PORT, DATABASE та SCHEMA на реальні значення.

Крок 3: Додайте схему Prisma та запустіть міграції

Використовуйте Prisma Migrate для створення таблиць. Додайте початкову модель у файл prisma/schema.prisma:

model Post {
  id        Int      @id @default(autoincrement())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  title     String   @db.VarChar(255)
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  Int
}

model Profile {
  id     Int     @id @default(autoincrement())
  bio    String?
  user   User    @relation(fields: [userId], references: [id])
  userId Int     @unique
}

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

Для більш детальних інструкцій щодо створення моделей перегляньте офіційну документацію до моделей даних. Для цього способу налаштування достатньо зразкової моделі для запуску першої міграції.

Створіть та застосуйте міграцію:

npx prisma migrate dev --name init

Це зробить:

• створить SQL-запит на основі схеми
• застосує його до бази даних
• оновить клієнт, щоб моделі можна було використовувати у коді

--name init — це лише позначка. Корисними назвами у майбутньому можуть бути add-post-model або add-user-profile.

Крок 4: Створення клієнта Prisma

Створіть клієнта після встановлення:

npx prisma generate

Процес створення читає файл schema.prisma та записує типи TypeScript та методи запитів у директорію generated/prisma (або в іншу налаштовану директорію). Імпортуйте конструктор та створіть екземпляр:

import { PrismaClient } from './generated/prisma'

const prisma = new PrismaClient()

Цей екземпляр може читати та записувати дані через такі моделі, як User, Post та Profile.

Цікаво знати:

Коли виконується команда prisma generate, вона генерує код, адаптований під поточну схему. Після змін у схемі необхідно її перегенерувати. Для підтримки синхронності бази даних зазвичай використовуються команди prisma migrate dev або prisma db push; ці команди також під час роботи перегенерують клієнтський код.

Крок 5: Запити до бази даних за допомогою TypeScript та PostgreSQL

З вже створеним клієнтом почніть з невеликого скрипту.

1. Створіть новий файл під назвою index.ts:

import { PrismaClient } from './generated/prisma'

const prisma = new PrismaClient()

async function main() {
  // ... you will write your Prisma Client queries here
}

main()
  .then(async () => {
    await prisma.$disconnect()
  })
  .catch(async (e) => {
    console.error(e)
    await prisma.$disconnect()
    process.exit(1)
  })

2. Читання даних — перелік користувачів у функції main:

async function main() {
  // ... you will write your Prisma Client queries here
  const allUsers = await prisma.user.findMany()
  console.log(allUsers)
}

3. Запис даних — створення пов’язаних записів:

async function main() {
  await prisma.user.create({
    data: {
      name: 'Alice',
      email: 'alice@prisma.io',
      posts: {
        create: { title: 'Hello World' },
      },
      profile: {
        create: { bio: 'I like turtles' },
      },
    },
  })

  const allUsers = await prisma.user.findMany({
    include: {
      posts: true,
      profile: true,
    },
  })
  console.dir(allUsers, { depth: null })
}

• prisma.user.create додає користувача разом із пов’язаними даними про пости та профіль.
• findMany з параметром include завантажує пов’язані пости та профіль.

console.dir із повною глибиною відображає вкладені об’єкти чітко.

Вважайте генерацію частиною циклу редагування, а не одноразовим процесом запуску. Зміни схеми без повторної генерації змушують код додатку працювати зі старими типами. Міграції без відповідного клієнта призводять до несинхронності даних бази даних у часі виконання та під час компіляції. Проста звичка — виконати міграцію (або оновлення), а потім перевірити, чи оновився вихід клієнта — допомагає уникнути багатьох ситуацій на кшталт «Чому TypeScript не знає про це поле?».

Для локальної розробки тримайте файл .env поза системою контролю версій та описайте очікуваний формат змінної DATABASE_URL у документації README. Для CI вставляйте ту саму змінну з розділу секретів та виконуйте команди migrate deploy (або еквівалентний крок) перед інтеграційними тестами, які працюють з базою даних. Вищенаведена налаштування достатні для ознайомлення з клієнтом; покращення для продакшну включають пулінг з’єднань, єдиний екземпляр клієнта та автоматичне роз’єднання під час завершення роботи процесу.

Що далі?

Це охоплює налаштування TypeScript Node з Prisma: встановлення, ініціалізацію, міграції, генерацію коду та виконання базових операцій читання та запису. Наступним етапом є моделювання даних — визначення зв’язків, обмежень та складніших функцій схеми, які забезпечують високу ефективність роботи шару бази даних у міру зростання додатку.