Démarrer avec Prisma sur Node.js et PostgreSQL

Introduction

Prisma est un ORM pratique pour les services Node et TypeScript qui nécessitent un accès à la base de données typé. La démarche présentée ci-dessous constitue un chemin rapide allant d’un projet Node de base vers des migrations, un client généré, ainsi que quelques requêtes de lecture/écriture vers PostgreSQL. Prisma se situe entre le code TypeScript de l’application et PostgreSQL : le fichier de schéma représente le contrat, les migrations modifient la base de données, et le client généré fournit des méthodes typées pour chaque modèle. Omettre l’un de ces trois éléments entraîne généralement plus tard soit des erreurs SQL en temps de exécution, soit un code TypeScript incapable de reconnaître les champs déjà présents dans la base de données.

Avoir d’abord un projet Node prêt — ainsi que du TypeScript si c’est le langage utilisé dans le projet.

Mettons en place Prisma

Étape 1 : Installer Prisma et le Prisma Client

Installez les deux paquets dans le répertoire du projet :

npm install prisma @prisma/client

• prisma est l’outil en ligne de commande pour la création de schémas, les migrations et la génération du client.
• @prisma/client est la bibliothèque que l’on importe dans le code de l’application pour interroger la base de données.

Étape 2 : Initialiser Prisma

Initialisez avec PostgreSQL et un chemin de sortie personnalisé pour le client :

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

Fonction de cette commande :

• Crée un répertoire prisma contenant schema.prisma pour les paramètres de connexion et les modèles.
• Définit la source de données sur PostgreSQL.
• Crée un fichier .env de base pour stocker des informations secrètes telles que l’URL de la base de données.
• --output ../generated/prisma redirige le contenu généré par le client vers un emplacement différent de la valeur par défaut.

Remarque : prisma init utilise par défaut PostgreSQL. Pour un autre moteur — ou lorsque l’option --datasource-provider a été omise — modifiez le bloc datasource dans schema.prisma.

Exemple avec PostgreSQL :

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

Placez la chaîne de connexion dans .env :

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

Remplacez USER, PASSWORD, HOST, PORT, DATABASE et SCHEMA par des valeurs réelles avant de modéliser ou de migrer.

Étape 3 : Ajouter le schéma Prisma et exécuter les migrations

Utilisez Prisma Migrate pour créer des tables. Ajoutez un modèle de base à 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?
}

Pour des directives plus détaillées sur le modélisation, consultez la documentation officielle du modèle de données. Pour cette configuration, le modèle d’exemple suffit pour exécuter une première migration.

Créez et appliquez la migration :

npx prisma migrate dev --name init

Cela permettra :

• de générer du SQL à partir du schéma
• d’appliquer ce SQL à la base de données
• de mettre à jour le client afin que les modèles soient utilisables dans le code

--name init n’est qu’une étiquette. Des noms plus utiles pourraient être add-post-model ou add-user-profile.

Étape 4 : Générer le client Prisma

Générez le client après l’installation :

npx prisma generate

La génération lit schema.prisma et écrit des types TypeScript ainsi que des méthodes de requête dans le répertoire generated/prisma (ou dans le répertoire de sortie configuré). Importez le constructeur et créez une instance :

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

const prisma = new PrismaClient()

Cette instance peut lire et écrire à l’aide de modèles tels que User, Post et Profile.

À savoir :

Lorsque prisma generate est exécuté, il génère du code adapté au schéma actuel. Après avoir modifié le schéma, il faut le regénérer. Pour maintenir la base de données en synchronisation, on utilise généralement prisma migrate dev ou prisma db push ; ces commandes regénèrent également le client en arrière-plan.

Étape 5 : Interroger la base de données à l’aide de TypeScript et PostgreSQL

Avec un client généré, commencez par un petit script.

1. Créez un nouveau fichier nommé 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. Lire des données — afficher la liste des utilisateurs dans main:

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

3. Écrire des données — créer des enregistrements associés :

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 insère un utilisateur accompagné des données correspondantes concernant les articles et le profil.
• findMany avec include charge les articles et le profil associés.

console.dir, lorsqu’utilisé à pleine profondeur, affiche clairement les objets imbriqués.

Considérez la génération comme faisant partie du cycle d’édition, et non comme une opération initiale unique. Les modifications de schéma sans régénération font en sorte que le code de l’application interagit avec des types obsolètes. Les migrations sans version correspondante du client entraînent un décalage entre les vues en temps de exécution et en temps de compilation de la base de données. Une habitude simple — migrer (ou pousser les modifications), puis vérifier que la sortie du client est mise à jour — permet d’éviter de nombreux problèmes du type « pourquoi TypeScript ne connaît-il pas ce champ ? ».

Pour le développement local, gardez .env en dehors du contrôle de version et documentez la structure attendue de DATABASE_URL dans le README. Pour les tests d’intégration continue, injectez la même variable provenant des secrets et exécutez migrate deploy (ou une étape équivalente) avant les tests d’intégration qui interagissent avec la base de données. La configuration ci-dessus suffit pour apprendre à utiliser le client ; le renforcement en environnement de production ajoute un pooling de connexions, un singleton de client partagé, ainsi qu’une déconnexion explicite en cas d’arrêt du processus.

Que faire ensuite ?

Cela couvre une configuration TypeScript Node avec Prisma : installation, initialisation, migration, génération, ainsi que l’exécution de lectures et d’écritures de base. Le niveau suivant consiste en la modélisation des données — relations, contraintes et fonctionnalités avancées de schéma qui permettent au niveau de la base de données de rester expressif à mesure que l’application se développe.