Utiliser Prisma sur Cloudflare Workers

Prisma ORM fournit des outils modernes et robustes pour interagir avec les bases de données. Associé à Hono et Cloudflare Workers, il permet de déployer des applications sans serveur performantes en périphérie du réseau.

Ce guide présente deux approches distinctes pour utiliser Prisma ORM dans Hono :

• Prisma Postgres: Une base PostgreSQL gérée, sans serveur, intégrée à Prisma. Cette approche convient à la production : Prisma Postgres propose un pool de connexions intégré, sans démarrage à froid, qui atténue les problèmes de montée en charge dans les environnements sans serveur et en périphérie.

• Adaptateurs de pilotes : Une alternative qui utilise les adaptateurs de pilotes flexibles de Prisma pour se connecter à toute base de données prise en charge par Prisma ORM.

Les deux approches ont leurs avantages ; choisissez celle qui correspond le mieux aux besoins de votre projet.

Utiliser Prisma Postgres

Prisma Postgres est une base PostgreSQL gérée et sans serveur, fondée sur des unikernels. Elle propose notamment le pooling de connexions, la mise en cache et des recommandations d’optimisation des requêtes. Une offre gratuite généreuse est disponible pour le développement initial, les tests et les projets personnels.

1. Installer Prisma et les dépendances nécessaires

Installez Prisma dans votre projet Hono :

npm i prisma --save-dev

Installez l’extension Prisma Client nécessaire à Prisma Postgres :

npm i @prisma/extension-accelerate

Initialisez Prisma avec une instance Prisma Postgres :

npx prisma@latest init --db

Si vous n’avez pas encore de compte Prisma Data Platform ou n’êtes pas connecté, la commande vous invite à vous connecter avec l’un des fournisseurs d’authentification disponibles. Une fenêtre de navigateur s’ouvre pour vous permettre de vous connecter ou de créer un compte. Revenez à la CLI après cette étape.

Une fois connecté (ou si vous l’étiez déjà), la CLI vous invite à choisir un nom de projet et une région pour la base de données.

À la fin de son exécution, la commande a créé :

• Un projet dans votre console de plateforme contenant une instance Prisma Postgres.
• Un dossier prisma contenant schema.prisma, où vous définirez le schéma de votre base de données.
• Un fichier .env à la racine du projet, contenant l’URL de la base Prisma Postgres : DATABASE_URL=<your-prisma-postgres-database-url>.

Créez un fichier .dev.vars et placez-y DATABASE_URL :

.dev.vars

DATABASE_URL="your_prisma_postgres_url"

Conservez le fichier .env pour que la CLI Prisma puisse y accéder ensuite lors des migrations, de la génération de Prisma Client ou de l’ouverture de Prisma Studio.

2. Configurer Prisma dans votre projet

Ouvrez maintenant votre fichier schema.prisma et définissez les modèles du schéma de votre base de données. Par exemple, vous pouvez ajouter un modèle User :

schema.prisma

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

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

model User {
  id  Int @id @default(autoincrement())
  email String
  name 	String
}

Utilisez Prisma Migrate pour appliquer les modifications à la base de données :

npx prisma migrate dev

Créez une fonction comme celle-ci, que vous pourrez utiliser ensuite dans votre projet :

prismaFunction.ts

import { PrismaClient } from '@prisma/client/edge'
import { withAccelerate } from '@prisma/extension-accelerate'

export const getPrisma = (database_url: string) => {
  const prisma = new PrismaClient({
    datasourceUrl: database_url,
  }).$extends(withAccelerate())
  return prisma
}

Voici un exemple d’utilisation de cette fonction dans votre projet :

index.ts

import { Hono } from 'hono'
import { sign, verify } from 'hono/jwt'
import { getPrisma } from '../usefulFun/prismaFun'

// Create the main Hono app
const app = new Hono<{
  Bindings: {
    DATABASE_URL: string
    JWT_SECRET: string
  }
  Variables: {
    userId: string
  }
}>()

app.post('/', async (c) => {
  // Now you can use it wherever you want
  const prisma = getPrisma(c.env.DATABASE_URL)
})

Si vous souhaitez utiliser votre propre base de données avec Prisma ORM tout en bénéficiant du pooling de connexions et de la mise en cache en périphérie, vous pouvez activer Prisma Accelerate. Découvrez comment configurer Prisma Accelerate pour votre projet.

Utiliser les adaptateurs de pilotes Prisma

Prisma peut être utilisé avec la base D1 via driverAdapters. Vous devez au préalable installer Prisma et intégrer Wrangler pour le lier à votre projet Hono. Cet exemple rassemble les étapes, car les documentations de Hono, Prisma et Cloudflare D1 sont séparées et ne donnent pas de procédure commune précise.

Configurer Prisma

Prisma et D1 utilisent un binding dans Wrangler pour établir la connexion avec un adaptateur.

npm install prisma --save-dev
npx prisma init
npm install @prisma/client
npm install @prisma/adapter-d1

Prisma génère ensuite le schéma de votre base de données ; définissez un modèle simple dans prisma/schema.prisma. N’oubliez pas de changer l’adaptateur.

prisma/schema.prisma

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"] // change from default
}

datasource db {
  provider = "sqlite" // d1 is sql base database
  url      = env("DATABASE_URL")
}

// Create a simple model database
model User {
  id    String @id  @default(uuid())
  email String  @unique
  name  String?
}

Base de données D1

Si vous disposez déjà d’une base D1, passez cette étape. Sinon, créez-en une en suivant les instructions ici.

npx wrangler d1 create __DATABASE_NAME__ // change it with yours

Assurez-vous que votre base de données est liée dans wrangler.toml.

wrangler.toml

[[d1_databases]]
binding = "DB" # i.e. available in your Worker on env.DB
database_name = "__DATABASE_NAME__"
database_id = "DATABASE ID"

Prisma Migrate

Cette commande permet d’effectuer une migration Prisma et de modifier la base D1, locale ou distante.

npx wrangler d1 migrations create __DATABASE_NAME__ create_user_table # will generate migration folder and sql file

// for generate sql statement

npx prisma migrate diff \
  --from-empty \
  --to-schema-datamodel ./prisma/schema.prisma \
  --script \
  --output migrations/0001_create_user_table.sql

Migrez le modèle de base de données vers D1.

npx wrangler d1 migrations apply __DATABASE_NAME__ --local
npx wrangler d1 migrations apply __DATABASE_NAME__ --remote
npx prisma generate

Configurer Prisma Client

Pour interroger la base D1 avec Prisma, ajoutez les types avec :

npx wrangler types

Cela génère un fichier worker-configuration.d.ts.

Clients Prisma

Pour utiliser Prisma globalement, créez un fichier lib/prismaClient.ts avec un code comme celui-ci.

lib/prisma.ts

import { PrismaClient } from '@prisma/client'
import { PrismaD1 } from '@prisma/adapter-d1'

const prismaClients = {
  async fetch(db: D1Database) {
    const adapter = new PrismaD1(db)
    const prisma = new PrismaClient({ adapter })
    return prisma
  },
}

export default prismaClients

Liez Hono aux valeurs de l’environnement Wrangler :

src/index.ts

import { Hono } from 'hono'
import prismaClients from '../lib/prismaClient'

type Bindings = {
  MY_KV: KVNamespace
  DB: D1Database
}

const app = new Hono<{ Bindings: Bindings }>() // binding env value

Exemple d’utilisation dans une route Hono :

src/index.ts

import { Hono } from 'hono'
import prismaClients from '../lib/prismaClient'

type Bindings = {
  MY_KV: KVNamespace
  DB: D1Database
}
const app = new Hono<{ Bindings: Bindings }>()

app.get('/', async (c) => {
  const prisma = await prismaClients.fetch(c.env.DB)
  const users = await prisma.user.findMany()
  console.log('users', users)
  return c.json(users)
})

export default app

Cela renvoie tous les utilisateurs sur la route /. Utilisez Postman ou Thunder Client pour consulter le résultat.

Ressources

Vous pouvez utiliser les ressources suivantes pour enrichir votre application :

• Ajoutez de la mise en cache à vos requêtes.
• Consultez la documentation Prisma Postgres.