База дадзэных Prisma’s Shadow і несувязка ў назвах: Кярты эксплуатацыі

Калі команды выбіраюць Prisma з PostgreSQL, паўтараючыся супакошанні выступаюць два: інструмент міграцыі постаўляе можлівасць вычысцэння базы дадзеных для розрабоцтва, а табелі, якія ён стварае, не нагадваюць нічога з таго, што мог бы выбраць адміністратар Postgres. І тое, і другое ўскладненыя, задокументаваныя, а не знакі таго, што Prisma непаспрацоўны для працы ў продакшэне. У гідзе пояснюецца, што вядзецься ў кожным з этых случаў, і даўаецца кароткі набор правілаў, якія дапамагаюць захаваць вашы даны і стандарты схемы.

Чаму prisma migrate dev прапанавае скасаваць базу дадзеных

Тыповы случай выглядае так: хтось запускае npx prisma migrate dev, команда зупіняецца з адказам пра памылку, што табелі чы ўзмацнення "вже існуюць", і найшырэйшы спосаб знікнення гэтага адказу — це prisma migrate reset. Гэтая команда усунець усі табелі і перзапускае весь ход міграцыі з самага пачатку.

Для чаго падае тэневы база даных

У періяд разработкі Prisma Migrate выкарыстоўвае другую, тымчасовую базу даных, якая называецца тэневай базой даных. Яе ўзгалі едынавае заведамства — выяўленне змян. Кожны раз, калі запускаецца команда migrate dev, Prisma стварае чыстую тэневую базу даных, застосоўвае да яе всі вашы файлы міграцый, аналізуе створаную схему і парабяляе яе з рэальной базай даных для разработкі.

Калі гэтыя две базы даных не збігаюцца, значыць, ў базе даных для разработкі з’явіліся змяны, якія не былі задокументаваны ў історыі міграцый. Частыя прычыны:

• prisma db push, які змяніў табліцы без стварэння файлу міграцый
• Ручная змена, адбылася через кліент SQL
• Файл міграцый, які створыў колега, але так і не падаў у базу даных

Prisma не можа з’ясаваць, якую версію даных вы хочаце заставіць, таму ён пропануе едын стаўкавы автаматычны варыянт, які ёсць у яго для базы даных пад час розрабоцтва: ёе трэба адмахнуць і перзапісаць на базе міграцый.

Форма абякання, якая паслаба дакументавана

Команды застаюцца без захоплення з-за іншай проблемы, якая дае падобныя сімптамы. У адарожваных службах Postgres, такіх як Neon або Supabase, корыстувач базы даных у вашай стрэнге з’яносу часта не мае права ствараць і адмахнуць базы даных за патрэбам. У такім случае Prisma не можа стварыць свою тымчасовую базу даных і выдае памятку пра абяканне прав.

Разработчыкі частаўна спрыягаюць гэтую памылку як „міграцыі зламаныя“ і, следуючы парадам з тэадзавароў спяльнай адументнасі, запускаюць migrate reset, каб яе усунуць. Гэта небяпечна, адтолькі ўскладненне — гэта той самы каманд, який надзеяна знішчае даны, якщо стрынг з’яносу вядзе да рэальнага месца. У публічных дыскусіях на GitHub ёсць самэ гэтае апісанне: памылка у тэневай базе дадзеных, непланаванае ускладненне як „вырашэнне“ проблемы, і табелі, якія згубляюцца ў середзіне проекту.

Правілы, якія захоўваюць міграцыі безпечнымі

• З’явіце Prisma адыякраваную базу дадзеных “шэдау”. Установіце shadowDatabaseUrl на адзінокую базу дадзеных, дзе вашы корыстнік можа вольна ствараць і знишчаць табліцы. Ніколі не налаштоввайце яго на базу дадзеных для працы ў рэальных умовах чы на спільную базу для тэставання. Залежна ад версіі Prisma, гэта налаштаванне знаходзіцца ў конфігурацыі джэрела дадзеных у файле схемы чы ў самам файле конфігураціі Prisma, таму пераканайцеся ў актуальных інструкціях, дзе яго чакае ваша версія.
• Завжды спрыяйце migrate reset як даэструктивнам кроку. Якщо яго пропануюць як першы крок у разв’язванні проблем, зупініцеся і спачатку пераканайцеся ў правільнасці пароляў, прывілеях і стане системы.
• Розумейце, што умовы працы ў рэальных умовах адрозненыя. Команда prisma migrate deploy застосоўвае толькі чакаючыя на адбыцьце міграцыі. Яна ніколі не стварае базу дадзеных “шэдау” і ніколі не прасіць пра скасаванне налаштаванняў. Функцыя скасавання налаштавань є частью процесу розработы за прыродным падзеўнікам.

Модэлі у формате PascalCase протыў табелей у формате snake_case

Другы момент, які вызывае проблемы, — цэ это называнне элементаў. Язык схем Prisma рэкамендуе імены модэляў у формате PascalCase і імены полей у формате camelCase, што адпавядае стандартам JavaScript і TypeScript. У свете Postgres зазвычай выкарыстоўваецца працоўны формат: ідэнтыфікаторы у формате snake_case, часта з множынымі іменамі табелей.

За стандартным налашчэнням модэль пад назвай User з полем firstName стае табелю пад назвай User з столбцам пад назвай firstName. Postgres гэта прымае, але ідэнтыфікаторы з разным роўнем верхняй і нижней загулкі павінны быць абрамлены подвойнымі цитаткамі у сыром SQL, і такі формат здаецца чужым для адпаведальных за базу дадзеных, інструментаў аналізу та будзь-якіх сервісаў, якія чытаюць базу дадзеных без викорыстоўвання Prisma.

Спарожненне імен за дапамойкай @map і @@map

Prisma рашае гэтыя проблемы за дапамою двух атрыбутаў: @map перайменоўвае столбець адзінага поля, а @@map — таблицу, якая стоіць за модэлем. У вашам коде на TypeScript застаёцца user.firstName, тады калі база дадзенаў храніць users.first_name. Кардыналізацыя працуе добра, але не застосоўваецца автаматычна. У вас ёсць два варыянты:

• вручную атрыбутаваць кожнае поле і модэль, што ўскладненае, але цалкам яснае і лёгкае для перагляду
• выкорыстаць сторонній інструмент prisma-case-format CLI, які масова перапісвае формат назв у файлах схемы і можа быць запусканы знову, каб новыя поля не вернуліся да стандартных значэнняў

Які бы варыянт вы не выбралі, прымкніце рашэнне ўжо да першай міграцыі. Перейменаванне таблиц і столбцаў пазней значыць неабходнасць стварэння міграцый, якія будуць вплываць на існуючыя даны, а кожны прымітны SQL-запит у кодбазе таксама павінен быць змěнены.

Як Drizzle рашырае тую ж проблему

Drizzle, самы выдатны альтэрнатыўны инструмент, які прывязваецца да TypeScript, адказвае за настройку casing, якая перакладае імены у формате camelCase ў кодзе на імены у формате snake_case ў базе дадзеных для всіх схем. эта рэдкі случай, калі звычная схема працы перакручваецца. Prisma зазвычай апісваецца як болей абстрактны інструмент, а Drizzle — як той, який болей прыбліжаны да SQL; пры тым схема Drizzle, створаная на основе коду, спрыяе простам кераванню форматам імен, тады як окрыжная схема Prisma залічваецца як давняе запрасанне да дадзення глобальнай настройкі.

Ключовыя выводы

• Прапыт пра перазначэнне, які выдаецца праз migrate dev, сигналізуе пра адхыленні аб проблемы з правамі на шэда-базу дадзеных, а не пра паспаленыя міграцыі.
• Настроўкай неабходна стварыць яшчэ адну, ізольаваную шэда-базу дадзеных для будь-якага хоставанага прадаўца Postgres.

Ніколы не выкарыстоўваце migrate reset як універсальны спосаб рашэння проблемы; выконанне запускаў у працоўным режыме завісіць ад migrate deploy, які не можа нічаго скасаваць.

Перад першай міграцыяй выберыце стратэгію называння з @map і @@map (вручную або за дапамой prisma-case-format), а не пасля ёй.

Якщо вы розглядаеце Prisma і Drizzle болей шырока, наша параболіка raw SQL, Prisma і Drizzle раскрывае болей шырыя аспекты выбору.

Спадні матэрыялы

• MovieVault Walkthrough: A Watchlist API With Express 5, Prisma 7 і JWT — Указаны таймінгі для выканання завдання на всіх роўнах аплікацыі, а таксама інструкцыі ўжоцьве пра Express, Prisma і JWT; паказваны прыміткі ўжоцьве па перакананню ў правах на адчыненне дадзеныня, обробцы каскадных ситуацый і адхэранні да правіл адчынення кеша.
• Setting Up Prisma 7 with PostgreSQL в проекте на TypeScript і Node.js — Указаны способы выліквавання частых проблем падчас налаштоввання Prisma 7 у проектах на TypeScript, включаючы проблемы з URL-адрэсамі і значэнням undefined, а таксама способы падключэння PostgreSQL за дапамою адаптара pg driver.