Привет, друзья!

В этой серии из 2 статей я хочу поделиться с вами своими заметками о Prisma.

Prisma — это современное (продвинутое) объектно-реляционное отображение (Object-Relational Mapping, ORM) для Node.js и TypeScript. Проще говоря, Prisma — это инструмент, позволяющий работать с реляционными (PostgreSQL, MySQL, SQL Server, SQLite) и нереляционной (MongoDB) базами данных с помощью JavaScript или TypeScript без использования SQL (хотя такая возможность имеется).

Содержание этой части

• Инициализация проекта
• CLI
• Схема
  
  • Типы данных
  • Атрибуты
  • Функции атрибутов
  • Отношения
• Клиент
  
  • Запросы
  • findUnique
  • findFirst
  • findMany
  • create
  • update
  • upsert
  • delete
  • createMany
  • updateMany
  • deleteMany
  • count
  • aggregate
  • groupBy

Вторая часть.

Если вам это интересно, прошу под кат.

Инициализация проекта

Создаем директорию, переходим в нее и инициализируем Node.js-проект:

mkdir prisma-test
cd prisma-test

yarn init -yp
# or
npm init -y

Устанавливаем Prisma в качестве зависимости для разработки:

yarn add -D prisma

# or
npm i -D prisma

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

npx prisma init

Это приводит к генерации файлов prisma/schema.prisma и .env.

В файле .env содержится переменная DATABASE_URL, значением которой является путь к (адрес) БД. Файл schema.prisma мы рассмотрим позже.

CLI

Интерфейс командной строки (Command line interface, CLI) Prisma предоставляет следующие основные возможности (команды):

• init — создает шаблон Prisma-проекта:
  
  • --datasource-provider — провайдер для работы с БД: sqlite, postgresql, mysql, sqlserver или mongodb (перезаписывает datasource из schema.prisma);
  • --url — адрес БД (перезаписывает DATABASE_URL)

npx prisma init --datasource-provider mysql --url mysql://user:password@localhost:3306/mydb

• generate — генерирует клиента Prisma на основе схемы (schema.prisma). Клиент Prisma предоставляет программный интерфейс приложения (Application Programming Interface, API) для работы с моделями и типы для TypeScript

npx prisma generate

• db pull — генерирует модели на основе существующей схемы БД

npx prisma db pull

• db push — синхронизирует состояние схемы Prisma с БД без выполнения миграций. БД создается при отсутствии. Используется для прототипировании БД и в локальной разработке. Также может быть полезной в случае ограниченного доступа к БД, например, при использовании БД, предоставляемой облачными провайдерами, такими как ElephantSQL или Heroku

npx prisma db push

• seed — выполняет скрипт для наполнения БД начальными (фиктивными) данными. Путь к соответствующему файлу определяется в package.json

"prisma": {
  "seed": "node prisma/seed.js"
}

npx prisma seed

• migrate
  
  • dev — выполняет миграцию для разработки:
  • --name — название миграции

npx prisma migrate dev --name init

Это приводит к созданию БД при ее отсутствии, генерации файла prisma/migrations/migration_name.sql, выполнению инструкции из этого файла (синхронизации БД со схемой) и генерации (регенерации) клиента (prisma generate).

Данная команда должна выполняться после каждого изменения схемы.

• reset — удаляет и заново создает БД или выполняет "мягкий сброс", удаляя все данные, таблицы, индексы и другие артефакты

npx prisma migrate reset

• deploy — выполняет производственную миграцию

npx prisma migrate deploy

• studio — позволяет просматривать и управлять данными, хранящимися в БД, в интерактивном режиме:
  
  • --browser, -b — название браузера (по умолчанию используется дефолтный браузер);
  • --port, -p — номер порта (по умолчанию — 5555)

npx prisma studio

# без автоматического открытия вкладки браузера
npx prisma studio -b none

Подробнее о CLI можно почитать здесь.

Схема

В файле schema.prisma мы видим такие строки:

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

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

• datasource — источник данных:
  
  • provider — название провайдера для доступа к БД: sqlite, postgresql, mysql, sqlserver или mongodb (по умолчанию — postgresql);
  • url — адрес БД (по умолчанию — значение переменной DATABASE_URL);
  • shadowDatabaseUrl — адрес "теневой" БД (для БД, предоставляемых облачными провайдерами): используется для миграций для разработки (prisma migrate dev);
• generator — генератор клиента на основе схемы:
  
  • provider — провайдер генератора (единственным доступным на сегодняшний день провайдером является prisma-client-js);
  • binaryTargets — определяет операционную систему для клиента Prisma. Значением по умолчанию является native, но иногда это приходится указывать явно, например, при использовании клиента в Docker-контейнере (в этом случае также приходится явно выполнять prisma generate)

generator client {
  provider      = "prisma-client-js"
  binaryTargets = ["native"]
}

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

Для работы со схемой удобно пользоваться расширением Prisma для VSCode. Соответствующий раздел в файле settings.json должен выглядеть так:

"[prisma]": {
  "editor.defaultFormatter": "Prisma.prisma"
}

Определим в схеме модели для пользователя (User) и поста (Post):

model User {
  id         String   @id @default(uuid()) @db.Uuid
  email      String   @unique
  hash       String   @map("password_hash")
  first_name String?
  last_name  String?
  age        Int?
  role       Role     @default(USER)
  posts      Post[]
  created_at DateTime @default(now())
  updated_at DateTime @updatedAt

  @@map("users")
}

model Post {
  id         String   @id @default(uuid())
  title      String
  content    String
  published  Boolean
  author_id  String
  author     User     @relation(fields: [author_id], references: [id])
  created_at DateTime @default(now())
  updated_at DateTime @updatedAt

  @@map("posts")
}

enum Role {
  USER
  ADMIN
}

Вот что мы здесь видим:

• id, email, hash etc. — названия полей (колонок таблицы);
• @map привязывает поле схемы (hash) к указанной колонке таблицы (password_hash). @map не меняет название колонки в БД и поля в генерируемом клиенте. Для MongoDB использование @map для @id является обязательным: id String @default(auto()) @map("_id") @db.ObjectId;
• String, Int, DateTime etc. — типы данных (см. ниже);
• @db.Uuid — тип данных, специфичный для одной или нескольких БД (в данном случае PostgreSQL);
• модификатор ? после названия типа означает, что данное поле является опциональным (необязательным, может иметь значение NULL);
• модификатор [] после названия типа означает, что значением данного поля является список (массив). Такое поле не может быть опциональным;
• префикс @ означает атрибут поля, а префикс @@ — атрибут блока (модели, таблицы). Некоторые атрибуты принимают параметры;
• атрибут @id означает, что данное поле является первичным (основным) ключом таблицы (PRIMARY KEY) (идентификатор модели). Такое поле не может быть опциональным;
• атрибут @default присваивает полю указанное значение по умолчанию (при отсутствии значения поля) (DEFAULT). Дефолтными могут быть статические значения (42, hi) или значения, генерируемые функциями autoincrement, dbgenerated, cuid, uuid и now (функции атрибутов; см. ниже);
• атрибут @unique означает, что значение поля должно быть уникальным в пределах таблицы (UNIQUE). Таблица должна иметь хотя бы одно поле @id или @unique;
• атрибут @relation указывает на существование отношений между таблицами. В данном случае между таблицами users и posts существуют отношения один-ко-многим (one-to-many, 1-n) — у одного пользователя может быть несколько постов (FOREIGN KEY / REFERENCES) (об отношениях мы поговорим отдельно);
• атрибут @updatedAt обновляет поле текущими датой и временем при любой модификации записи;
• у нас имеется перечисление (enum), значения которого используются в качестве значений поля role модели User (значением по умолчанию является USER);
• атрибут @@map привязывает название модели к названию таблицы в БД. @@map не меняет название таблицы в БД и модели в генерируемом клиенте.

Типы данных

Допустимыми в названиях полей являются следующие символы: [A-Za-z][A-Za-z0-9_]*.

• String — строка переменной длины (для PostgreSQL — это тип text);
• Boolean — логическое значение: true или false (boolean);
• Int — целое число (integer);
• BigInt — BigInt (integer);
• Float — число с плавающей точкой (запятой) (double precision);
• Decimal (decimal(65,30));
• DateTime — дата и время в формате ISO 8601;
• Json — объект в формате JSON (jsonb);
• Bytes (bytea).

Атрибут @db позволяет использовать типы данных, специфичные для одной или нескольких БД.

Атрибуты

Кроме упомянутых выше, в схеме можно использовать следующие атрибуты:

• @@id — определяет составной (composite) первичный ключ таблицы, например, @@id[title, author] (в данном случае соответствующее поле будет называться title_author — это можно изменить);
• @@unique — определяет составное ограничение уникальности (unique constraint) для указанных полей (такие поля не могут быть опциональными), например, @@unique([title, author]);
• @@index — определяет индекс в БД (INDEX), например, @@index([title, author]);
• @ignore, @@ignore — используется для обозначения невалидных полей и моделей, соответственно.

Функции атрибутов

• auto — представляет дефолтные значения, генерируемые БД (только для MongoDB);
• autoincrement — генерирует последовательные целые числа (SERIAL в PostgreSQL, не поддерживается MongoDB);
• cuid — генерирует глобальный уникальный идентификатор на основе спецификации cuid;
• uuid — генерирует глобальный уникальный идентификатор на основе спецификации UUID;
• now — возвращает текущую отметку времени (timestamp) (CURRENT_TIMESTAMP в PostgreSQL);
• dbgenerated — представляет дефолтные значения, которые не могут быть выражены в схеме (например, random()).

Подробнее о схеме можно почитать здесь.

Отношения

Атрибут @relation указывает на существование отношений между моделями (таблицами). Он принимает следующие параметры:

• name?: string — название отношения;
• fields?: [field1, field2, ...fieldN] — список полей текущей модели (в нашем случае это [author_id] модели Post); обратите внимание: само поле определяется отдельно);
• references: [field1, field2, ...fieldN] — список полей другой модели (стороны отношений) (в нашем случае это [id] модели User).

В приведенной выше схеме полями, указывающими на существование отношений между моделями User и Post, являются поля posts и author. Эти поля существуют только на уровне Prisma, в БД они не создаются. Скалярное поле author_id также существует только на уровне Prisma — это внешний ключ (FOREIGN KEY), соединяющий Post с User.

Как известно, существует 3 вида отношений:

• один-к-одному (one-to-one, 1-1);
• один-ко-многим (one-to-many, 1-n);
• многие-ко-многим (many-to-many, m-n).

Атрибут @relation является обязательным только для отношений 1-1 и 1-n.

Предположим, что в нашей схеме имеются такие модели:

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

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

model Post {
  id         Int        @id @default(autoincrement())
  author     User       @relation(fields: [authorId], references: [id])
  authorId   Int
  categories Category[]
}

model Category {
  id    Int    @id @default(autoincrement())
  posts Post[]
}

Вот что мы здесь видим:

• между моделями User и Profile существуют отношения 1-1 — у одного пользователя может быть только один профиль;
• между моделями User и Post существуют отношения 1-n — у одного пользователя может быть несколько постов;
• между моделями Post и Category существуют отношения m-n — один пост может принадлежать к нескольким категориям, в одну категорию может входить несколько постов.

Подробнее об отношениях можно почитать здесь.

Клиент

Импортируем и создаем экземпляр клиента Prisma:

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

export default prisma

Иногда может потребоваться делать так:

const Prisma = require('prisma')

const prisma = new Prisma.PrismaClient()

module.exports = prisma

Запросы

findUnique

findUnique позволяет извлекать единичные записи по идентификатору или уникальному полю.

Сигнатура

findUnique({
  where: condition,
  select?: fields,
  include?: relations,
  rejectOnNotFound?: boolean
})

Модификатор ? означает, что поле является опциональным.

• condition — условие для выборки;
• fields — поля для выборки;
• relations — отношения (связанные поля) для выборки;
• rejectOnNotFound — если имеет значение true, при отсутствии записи выбрасывается исключение NotFoundError. Если имеет значение false, при отсутствии записи возвращается null.

Пример

async function getUserById(id) {
  try {
    const user = await prisma.user.findUnique({
      where: {
        id
      }
    })
    return user
  } catch(e) {
    onError(e)
  }
}

findFirst

findFirst возвращает первую запись, соответствующую заданному критерию.

Сигнатура

findFirst({
  where?: condition,
  select?: fields,
  include?: relations,
  rejectOnNotFound?: boolean,
  distinct?: field,
  orderBy?: order,
  cursor?: position,
  skip?: number,
  take?: number
})

• distinct — фильтрация по определенному полю;
• orderBy — сортировка по определенному полю и в определенном порядке;
• cursor — позиция начала списка (как правило, id или другое уникальное значение);
• skip — количество пропускаемых записей;
• take — количество возвращаемых записей (в данном случае может иметь значение 1 или -1: во втором случае возвращается последняя запись.

Пример

async function getLastPostByAuthorId(author_id) {
  try {
    const post = await prisma.post.findFirst({
      where: {
        author_id
      },
      orderBy: {
        created_at: 'asc'
      },
      take: -1
    })
    return post
  } catch(e) {
    onError(e)
  }
}

findMany

findMany возвращает все записи, соответствующие заданному критерию.

Сигнатура

findMany({
  where?: condition,
  select?: fields,
  include?: relations,
  rejectOnNotFound?: boolean,
  distinct?: field,
  orderBy?: order,
  cursor?: position,
  skip?: number,
  take?: number
})

Пример

async function getAllPostsByAuthorId(author_id) {
  try {
    const posts = await prisma.post.findMany({
      where: {
        author_id
      },
      orderBy: {
        updated_at: 'desc'
      }
    })
    return posts
  } catch(e) {
    onError(e)
  }
}

create

create создает новую запись.

Сигнатура

create({
  data: _data,
  select?: fields,
  include?: relations
})

• _data — данные создаваемой записи.

Пример

async function createUserWithProfile(data) {
  const { email, password, firstName, lastName, age } = data
  try {
    const hash = await argon2.hash(password)
    const user = await prisma.user.create({
      data: {
        email,
        hash,
        profile: {
          create: {
            first_name: firstName,
            last_name: lastName,
            age
          }
        }
      },
      select: {
        email: true
      },
      include: {
        profile: true
      }
    })
    return user
  } catch(e) {
    onError(e)
  }
}

update

update обновляет существующую запись.

Сигнатура

update({
  data: _data,
  where: condition,
  select?: fields,
  include?: relations
})

Пример

async function updateUserById(id, changes) {
  const { email, age } = changes
  try {
    const user = await prisma.user.update({
      where: {
        id
      },
      data: {
        email,
        profile: {
          update: {
            age
          }
        }
      },
      select: {
        email: true
      },
      include: {
        profile: true
      }
    })
    return user
  } catch(e) {
    onError(e)
  }
}

upsert

upsert обновляет существующую или создает новую запись.

Сигнатура

upsert({
  create: _data,
  update: _data,
  where: condition,
  select?: fields,
  include?: relations
})

Пример

async function updateOrCreateUser(data) {
  const { userName, email, password } = data
  try {
    const hash = await argon2.hash(password)
    const user = await prisma.user.create({
      where: { user_name: userName },
      update: {
        email,
        hash
      },
      create: {
        email,
        hash,
        user_name: userName
      },
      select: { user_name: true, email: true }
    })
    return user
  } catch(e) {
    onError(e)
  }
}

delete

delete удаляет существующую запись по идентификатору или уникальному полю.

Сигнатура

delete({
  where: condition,
  select?: fields,
  include?: relations
})

Пример

async function removeUserById(id) {
  try {
    await prisma.user.delete({
      where: {
        id
      }
    })
  } catch(e) {
    onError(e)
  }
}

createMany

createMany создает несколько записей с помощью одной транзакции (о транзакциях мы поговорим отдельно).

Пример

createMany({
  data: _data[],
  skipDuplicates?: boolean
})

• _data[] — данные для создаваемых записей в виде массива;
• skipDuplicates — при значении true создаются только уникальные записи.

Пример

// предположим, что `users` - это массив объектов
async function createUsers(users) {
  try {
    const users = await prisma.user.createMany({
      data: users
    })
    return users
  } catch(e) {
    onError(e)
  }
}

updateMany

updateMany обновляет несколько существующих записей за один раз и возвращает количество (sic) обновленных записей.

Сигнатура

updateMany({
  data: _data[],
  where?: condition
})

Пример

async function updateProductsByCategory(category, newDiscount) {
  try {
    const count = await prisma.product.updateMany({
      where: {
        category
      },
      data: {
        discount: newDiscount
      }
    })
    return count
  } catch(e) {
    onError(e)
  }
}

deleteMany

deleteMany удаляет несколько записей с помощью одной транзакции и возвращает количество удаленных записей.

Сигнатура

deleteMany({
  where?: condition
})

Пример

async function removeAllPostsByUserId(author_id) {
  try {
    const count = await prisma.post.deleteMany({
      where: {
        author_id
      }
    })
    return count
  } catch(e) {
    onError(e)
  }
}

count

count возвращает количество записей, соответствующих заданному критерию.

Сигнатура

count({
  where?: condition,
  select?: fields,
  cursor?: position,
  orderBy?: order,
  skip?: number,
  take?: number
})

Пример

async function countUsersWithPublishedPosts() {
  try {
    const count = await prisma.user.count({
      where: {
        post: {
          some: {
            published: true
          }
        }
      }
    })
    return count
  } catch(e) {
    onError(e)
  }
}

aggregate

aggregate выполняет агрегирование полей.

Сигнатура

aggregate({
  where?: condition,
  select?: fields,
  cursor?: position,
  orderBy?: order,
  skip?: number,
  take?: number,

  _count: count,
  _avg: avg,
  _sum: sum,
  _min: min,
  _max: max
})

• _count — возвращает количество совпадающих записей или не null-полей;
• _avg — возвращает среднее значение определенного поля;
• _sum — возвращает сумму значений определенного поля;
• _min — возвращает наименьшее значение определенного поля;
• _max — возвращает наибольшее значение определенного поля.

Пример

async function getAllUsersCountAndMinMaxProfileViews() {
  try {
    const result = await prisma.user.aggregate({
      _count: {
        _all: true
      },
      _max: {
        profileViews: true
      },
      _min: {
        profileViews: true
      }
    })
    return result
  } catch(e) {
    onError(e)
  }
}

groupBy

groupBy выполняет группировку полей.

Сигнатура

groupBy({
  by?: by,
  having?: having,

  where?: condition,
  orderBy?: order,
  skip?: number,
  take?: number,

  _count: count,
  _avg: avg,
  _sum: sum,
  _min: min,
  _max: max
})

• by — определяет поле или комбинацию полей для группировки записей;
• having — позволяет фильтровать группы по агрегируемому значению.

Пример

В следующем примере мы выполняем группировку по country / city, где среднее значение profileViews превышает 100, и возвращаем общее количество (_sum) profileViews для каждой группы. Запрос также возвращает количество всех (_all) записей в каждой группе и все записи с не null значениями поля city в каждой группе:

async function getUsers() {
  try {
    const result = await prisma.user.groupBy({
      by: ['country', 'city'],
      _count: {
        _all: true,
        city: true
      },
      _sum: {
        profileViews: true
      },
      orderBy: {
        country: 'desc'
      },
      having: {
        profileViews: {
          _avg: {
            gt: 100
          }
        }
      }
    })
    return result
  } catch(e) {
    onError(e)
  }
}

Пожалуй, это все, о чем я хотел рассказать вам в первой части.

Благодарю за внимание и happy coding!

---