Einführung in Prisma mit Node.js und PostgreSQL

Einführung

Prisma ist eine praktische ORM-Lösung für Node- und TypeScript-Dienste, die einen typisierten Datenbankzugriff benötigen. Die nachstehende Anleitung führt Sie schnell von einem einfachen Node-Projekt über Migrationsdateien, einen generierten Client bis hin zu einigen Lese-/Schreibabfragen gegen PostgreSQL. Prisma verbindet die TypeScript-Anwendung mit PostgreSQL: Die Schema-Datei dient als Vertrag, Migrationsdateien ändern die Datenbankstruktur und der generierte Client stellt typisierte Methoden für jedes Modell bereit. Wenn einer dieser drei Schritte weggelassen wird, treten in der Regel später entweder Laufzeit-SQL-Fehler auf oder TypeScript kann die bereits vorhandenen Felder der Datenbank nicht erkennen.

Haben Sie zunächst ein Node-Projekt bereit – sowie TypeScript, falls das die Projekt-Sprache ist.

Lassen Sie uns Prisma einrichten

Schritt 1: Prisma und Prisma Client installieren

Installieren Sie beide Pakete im Projektverzeichnis:

npm install prisma @prisma/client

• prisma ist die CLI für Schema-Arbeiten, Migrations und Erstellung von Clients.
• @prisma/client ist die Bibliothek, deren Code importiert wird, um die Datenbank abzufragen.

Schritt 2: Prisma initialisieren

Initialisieren mit PostgreSQL und einem benutzerdefinierten Ausgabepfad für den Client:

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

Was dieser Befehl tut:

• Erstellt ein prisma-Verzeichnis mit schema.prisma für Verbindungs-Einstellungen und Modelle.
• Stellt die Datenquelle auf PostgreSQL ein.
• Erstellt eine root-.env-Datei für Geheimnisse wie die Datenbank-URL.
• --output ../generated/prisma leitet die erzeugten Client-Ausgaben an einen anderen Ort als den Standardort um.

Hinweis: prisma init verwendet standardmäßig PostgreSQL. Für einen anderen Datenbankmotor – oder wenn --datasource-provider weggelassen wurde – bearbeiten Sie den datasource-Block in schema.prisma.

Beispiel für PostgreSQL:

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

Fügen Sie die Verbindungszeichenkette in .env ein:

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

Ersetzen Sie USER, PASSWORD, HOST, PORT, DATABASE und SCHEMA vor dem Modellieren oder Migrieren durch echte Werte.

Schritt 3: Prisma-Schema hinzufügen und Migrations ausführen

Verwenden Sie Prisma Migrate, um Tabellen zu erstellen. Fügen Sie ein Starter-Modell zu prisma/schema.prisma hinzu:

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?
}

Für detailliertere Anleitungen zum Modellieren finden Sie die offiziellen Dokumente zum Datenmodell. Für diesen Einrichtungsweg reicht das Beispiel-Modell aus, um eine erste Migration durchzuführen.

Erstellen und anwenden Sie die Migration:

npx prisma migrate dev --name init

Dies wird:

• SQL aus dem Schema generieren
• diese SQL-Anweisungen auf die Datenbank anwenden
• den Client aktualisieren, damit die Modelle im Code verwendet werden können

--name init ist lediglich eine Bezeichnung. Nützlichere Namen könnten später add-post-model oder add-user-profile sein.

Schritt 4: Prisma Client generieren

Generieren Sie den Client nach der Installation:

npx prisma generate

Die Generierung liest schema.prisma und schreibt TypeScript-Typen sowie Abfragemethoden unter generated/prisma (oder dem konfigurierten Ausgabepfad). Importieren Sie den Konstruktor und erstellen Sie eine Instanz:

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

const prisma = new PrismaClient()

Diese Instanz kann über Modelle wie User, Post und Profile lesen und schreiben.

Wissenswert:

Wenn prisma generate ausgeführt wird, erzeugt es Code, der auf dem aktuellen Schema basiert. Nach Änderungen am Schema sollte man neu generieren. Um die Datenbank im Einklang zu halten, genügt in der Regel prisma migrate dev oder prisma db push; diese Befehle erzeugen im Hintergrund auch den Client neu.

Schritt 5: Abfragen der Datenbank mit TypeScript und PostgreSQL

Mit einem generierten Client sollte man mit einem kleinen Skript beginnen.

1. Erstellen Sie eine neue Datei mit dem Namen 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. Daten lesen – Liste der Benutzer in main:

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

3. Daten schreiben – Erstellen von zusammenhängenden Datensätzen:

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 fügt einen Benutzer zusammen mit den zugehörigen Beitrags- und Profildaten ein.
• findMany mit include lädt die zugehörigen Beiträge und das Profil.

console.dir gibt verschachtelte Objekte bei voller Tiefe klar wieder.

Betrachten Sie die Erneuerung als Teil des Bearbeitungszyklus und nicht als einmalige Initialisierung. Schema-Änderungen ohne Neuerstellung führen dazu, dass der Anwendungscode weiterhin mit den alten Typen arbeitet. Migrations ohne entsprechenden Client sorgen dafür, dass die Laufzeit- und Kompilierungsansichten der Datenbank aus dem Gleichgewicht geraten. Eine einfache Gewohnheit – migrieren (oder pushen) und anschließend überprüfen, ob die Client-Ausgabe aktualisiert wurde – verhindert viele Fälle der Frage „Warum kennt TypeScript dieses Feld nicht?“

Zur lokalen Entwicklung sollte .env außerhalb des Versionskontrollsystems bleiben, und die erwartete Struktur von DATABASE_URL muss im README dokumentiert werden. Für CI sollte dieselbe Variable aus den Geheimnissen eingefügt und vor den Integrationstests, die die Datenbank nutzen, „migrate deploy“ (oder ein äquivalenter Schritt) ausgeführt werden. Die obige Einrichtung reicht aus, um den Client kennenzulernen; zur Erhöhung der Sicherheit in der Produktion kommen Verbindungs-Pooling, ein gemeinsamer Client-Singleton sowie eine explizite Trennung der Verbindung beim Beenden des Prozesses hinzu.

Was kommt als Nächstes?

Das umfasst eine TypeScript-Node-Einrichtung mit Prisma: Installation, Initialisierung, Migrationsausführung, Generierung sowie Ausführung grundlegender Lese- und Schreibvorgänge. Die nächste Ebene der Vertiefung ist das Datenmodellieren – Beziehungen, Einschränkungen sowie fortgeschrittene Schema-Funktionen, die sicherstellen, dass die Datenbankschicht im Laufe des Wachstums der Anwendung weiterhin leistungsfähig bleibt.