Англійська для розробників Prisma ORM

Prisma змінила те, як розробники TypeScript взаємодіють з базами даних, і вона принесла з собою свій власний точний словник. Слова, такі як «інтроспекція», «підвищення» і «сівання» мають певні значення в екосистемі Prisma, які відрізняються від загальної термінології бази даних. Якщо ви працюєте у команді, яка використовує Prisma, а англійська мова не є вашою першою мовою, розуміння того, як використовувати ці терміни, допоможе вам з впевненістю брати участь у перегляді коду, спринтах і документації щодо впровадження. Цей посібник містить найважливіші слова Prisma і показує вам, як англомовні користувачі використовують ці терміни на практиці.

Ключовий словник

** Схема (схема Prisma) ** Єдине джерело правди для проекту Prisma, написане в schema.prisma. У ньому визначено з’ єднання з базою даних, генератор (наприклад, Prisma Client) і всі моделі даних. Зміни у схемі впливають як на структуру бази даних, так і на створений клієнт. Приклад: “Ми оновили схему Prisma, щоб додати поле publishedAt до моделі Post, а потім запустили міграцію, щоб застосувати зміну.”

** Модель даних ** Блок model всередині схеми Prisma, який представляє таблицю бази даних (у базах даних SQL) або збірку (у MongoDB). Кожне поле у моделі відповідає одному з полів стовпчика або документа. Приклад: “Модель даних User має відношення один-до-багатьох з Post, що означає, що один користувач може створити декілька постів.”

Миграція Скрипт SQL з версіями, створений Prisma під час зміни схеми. Запуск prisma migrate dev створює новий файл міграції і застосовує його до бази даних розробки. Міграції утворюють історію всіх змін схеми.

• Приклад: « Під час міграції до таблиці User було додано стовпчик stripeCustomerId — переконайтеся, що ви застосували його до стадії тестування перед об’ єднанням ». *

Семя Процес заповнення бази даних початковими або тестовими даними за допомогою скрипту (зазвичай prisma/seed.ts ). Сіювання виконується з prisma db seed і відрізняється від міграцій.

• Приклад: « Скрипт- сіяч вставляє типового користувача адміністратора і п’ ять прикладних продуктів, щоб розробники мали реалістичні дані з самого початку. » *

** Призма клієнт ** Автоматично створений, безпечний клієнт бази даних, створений prisma generate. Вона надає такі методи, як findMany, create, update, і delete, які відображаються безпосередньо на моделі даних у схемі. Приклад: “Ми створюємо один клієнт Prisma в lib/db.ts і імпортуємо його туди, де нам потрібно запитати базу даних.”

Связь З’ єднання між двома моделями даних, визначене за допомогою атрибутів @relation і полів зв’ язку. Prisma підтримує відносини один-до-одного, один-до-багатьох і багато-до-багатьох. Приклад: “Модель Order має відношення багато-до-багатьох з Product через явну таблицю з’єднання під назвою OrderItem.”

Внутрішня роздумка Процес створення схеми Prisma з існуючої бази даних за допомогою запуску команди prisma db pull. Корисно, якщо ви використовуєте Prisma у проекті, у якому вже є база даних з власною структурою.

• Приклад: « Ми скористалися інтроспекцією для створення початкової схеми зі застарілої бази даних MySQL, а не писали її вручну. » *

• Вперед Одна операція з базою даних, яка створює запис, якщо його не існує, або оновлює його, якщо він існує — об’ єднання INSERT і UPDATE у один атомарний крок. У Prisma це prisma.model.upsert().

• Приклад: « Ми додаємо запис підписки користувача на кожній події webhook, щоб обробляти як нових підписників, так і відновлення за допомогою того ж шляху коду. » *

Звичайні фрази

** В обзорах коду: **

• «Ця реляція не має атрибуту @relation з явними іменами полів і посилань — Prisma іноді може вивести його, але явність уникає неоднозначності в створеному клієнті»
• Ви викликаєте prisma.user.findMany() всередині петлі — розгляньте використання одного findMany з фільтром in, щоб уникнути проблеми N+1 запиту
• « Ця міграція перейменовує колонку руйнівним чином; у виробництві це призведе до скидання старої колонки і її даних. Розглянемо замість цього двох кроків міграції»

В стоячих позах:

• «Я оновив схему, щоб додати tags реляцію і запустив prisma migrate dev локально — міграція готова для перегляду»
• «Я зараз запускаю базу даних з реалістичними даними про продукт, щоб команда QA могла правильно перевірити поток оплати»
• «Я отримав помилку типу в Prisma Client після зміни схеми; я забув запустити prisma generate після оновлення моделі — тепер це виправлено»

** У документації: **

• Після витягування цього сховища, запустіть prisma migrate dev, щоб застосувати всі очікувані міграції і prisma db seed, щоб заповнити початкові дані
• «Все доступ до бази даних проходить через спільний екземпляр Prisma Client, експортований з lib/db.ts ; не створюйте новий клієнт на запит»
• “При додаванні обов’язкового поля до існуючої моделі, введіть типове значення в міграції або зробіть поле необмеженим, щоб уникнути розриву існуючих рядків.”

Фрази, яких слід уникати

** При вимові « модель Prisma » слід розуміти як модель схеми, так і створений клас клієнта. ** Блок model у вашій схемі є * моделлю даних * або * моделлю схеми *. Створені методами клієнта (наприклад, prisma.user ) називаються * делегатом клієнта Prisma * або просто « клієнтом ». Розрізняйте між ними: « Я оновив * модель даних * у схемі » проти « Я викликав * клієнта Prisma *, щоб отримати запис »

** Використання « запустити міграцію », коли ви маєте на увазі « створити міграцію ». ** У Prisma, prisma migrate dev як генерує новий файл міграції, так і застосовує його. Якщо ви просто хочете застосувати існуючі файли міграції (наприклад, на сервері CI), ви запускаєте prisma migrate deploy. Скажімо: «Я створив і застосував міграцію в розробці» і «CI розгортає міграції до стадії»

** Використання слова « seed the scheme » замість « seed the database ». ** Ви створюєте * базу даних * з даними, а не схему. Схема визначає структуру; база даних містить дані. Скажіть: « Я буду засіяти * базу даних * тестовими записами », а не « Я буду засіяти * схему * »

Краткий справочник

Term	How to use it
schema	”Update the Prisma schema and regenerate the client after every model change.”
migration	”Run prisma migrate dev to generate and apply the migration locally.”
seed	”Run prisma db seed to populate the database with initial data.”
upsert	”Use upsert when a record may or may not already exist.”
introspection	”Use prisma db pull to introspect the existing database and generate the schema.”

Національний інститут стандартів: англійська мова для офіційних осіб

Prisma є потужним ORM, але ефективне спілкування про його можливості - схеми, міграції і запити - вимагає більше, ніж просто знати, як ним користуватися. Для не рідних носіїв англійської мови, оволодіння точним словником і фразуванням, що використовуються в професійних середовищах розвитку, може бути значною перешкодою. Це не просто переклад технічних термінів; це передавання намірів, співпраця з колегами по команді і значний внесок у дискусії навколо дизайну бази даних і логіки застосування. Давайте розглянемо, як удосконалювати комунікацію під час роботи з Prisma.

Однією з поширених проблем є неоднозначність навколо змін схеми. Під час перегляду коду, ви можете отримати коментар на зразок: « Ця міграція вводить нове поле email_verified на моделі User. Чи могли б ви розкрити причини додавання цього параметра і його впливу на існуючі запиту?» Просте « Я додав його, оскільки нам потрібно стежити за станом перевірки користувача » не є достатнім. Замість цього, прагніть до ясності, заявивши * чому * зміна є необхідною - “Ми вводимо новий поток перевірки електронної пошти, що вимагає від нас записувати, чи виконав користувач цей крок. Це поле буде заповнено після успішної перевірки і використано у наших панелях управління звітністю. Використання фраз на кшталт « вплив на існуючі запити » демонструє розуміння потенційних ефектів на нижніх рівнях і заохочує обговорення оптимізації або переробки. Аналогічно, при описі вашої роботи в описі Pull Request (PR), уникайте нечітких тверджень; замість цього, чітко сформулюйте * мету * зміни: «Ця PR вводить нове is_active булеве поле в модель User, що дозволяє нам легко деактивувати облікові записи користувачів без вилучення їх з бази даних»

Іншою областю, де нюанс є критичним, є обговорення продуктивності запиту. У повідомленні Slack може бути написано: « Повільні запиту на сторінці списку продуктів ». Хоча це технічно вірно, у повідомленні відсутня інформація, яку можна використати. Краще відповідь буде: «Я досліджую повільні запити на сторінці списку продуктів. Я визначив складний SELECT інструкцію з декількома з’єднаннями, що, ймовірно, сприяє затримці. Я досліджу оптимізацію цього запиту за допомогою можливостей індексування Prisma і, можливо, переписую запит для поліпшення продуктивності. » Ключовим є перейти від простого опису проблеми до активного демонстрування вашого розуміння потенційних рішень.

Нарешті, пам’ятайте, що “найкраща практика” не завжди чітко зазначена. Розробники часто покладаються на спільні знання і встановлені шаблони. Фрази на кшталт «Давайте переробимо це, щоб використовувати більш декларативний підхід» або «Чи можемо ми використати конструктор запитів Prisma для цього?» сигналізують про бажання поліпшити і запропонувати співпрацю. Не бійтеся задати прояснюючі питання — набагато краще шукати розуміння, ніж робити припущення.

// Example: Adding an index to the User model for faster queries
datasource user migrations {
  provider = "postgresql"

  schema = "my_app"

  preUpdate() {
    createIndex on user(email)
  }
}