diff --git a/tidb-cloud/serverless-driver-prisma-example.md b/tidb-cloud/serverless-driver-prisma-example.md index 49b3ffd9a7c88..a7f3fbe8aab28 100644 --- a/tidb-cloud/serverless-driver-prisma-example.md +++ b/tidb-cloud/serverless-driver-prisma-example.md @@ -7,13 +7,59 @@ summary: Learn how to use TiDB Cloud serverless driver with Prisma ORM. [Prisma](https://www.prisma.io/docs) is an open source next-generation ORM (Object-Relational Mapping) that helps developers interact with their database in an intuitive, efficient, and safe way. TiDB Cloud offers [@tidbcloud/prisma-adapter](https://github.com/tidbcloud/prisma-adapter), enabling you to use [Prisma Client](https://www.prisma.io/docs/concepts/components/prisma-client) over HTTPS with [TiDB Cloud serverless driver](/tidb-cloud/serverless-driver.md). Compared with the traditional TCP way, [@tidbcloud/prisma-adapter](https://github.com/tidbcloud/prisma-adapter) brings the following benefits: -- Better performance in serverless environments -- Possibility of using Prisma client in the edge environments (see [#21394](https://github.com/prisma/prisma/issues/21394) for more information) +- Better performance of Prisma Client in serverless environments +- Ability to use Prisma Client in edge environments -This tutorial describes how to use TiDB Cloud serverless driver with the Prisma adapter. +This tutorial describes how to use [@tidbcloud/prisma-adapter](https://github.com/tidbcloud/prisma-adapter) in serverless environments and edge environments. + +## Install + +You need to install both [@tidbcloud/prisma-adapter](https://github.com/tidbcloud/prisma-adapter) and [TiDB Cloud serverless driver](/tidb-cloud/serverless-driver.md). You can install them using [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) or your preferred package manager. + +Taking npm as an example, you can run the following commands for installation: + +```shell +npm install @tidbcloud/prisma-adapter +npm install @tidbcloud/serverless +``` + +## Enable `driverAdapters` + +To use the Prisma adapter, you need to enable the `driverAdapters` feature in the `schema.prisma` file. For example: + +```prisma +generator client { + provider = "prisma-client-js" + previewFeatures = ["driverAdapters"] +} + +datasource db { + provider = "mysql" + url = env("DATABASE_URL") +} +``` + +## Initialize Prisma Client + +Before using Prisma Client, you need to initialize it with `@tidbcloud/prisma-adapter`. For example: + +```js +import { connect } from '@tidbcloud/serverless'; +import { PrismaTiDBCloud } from '@tidbcloud/prisma-adapter'; +import { PrismaClient } from '@prisma/client'; + +// Initialize Prisma Client +const connection = connect({ url: ${DATABASE_URL} }); +const adapter = new PrismaTiDBCloud(connection); +const prisma = new PrismaClient({ adapter }); +``` + +Then, queries from Prisma Client can be sent to the TiDB Cloud serverless driver for processing. ## Use the Prisma adapter in Node.js environments +This section provides an example of how to use `@tidbcloud/prisma-adapter` in Node.js environments. + ### Before you begin To complete this tutorial, you need the following: @@ -40,7 +86,7 @@ To complete this tutorial, you need the following: npm install @tidbcloud/serverless npm install prisma --save-dev ``` - + 3. In the `package.json` file, specify the ES module by adding `type: "module"`: ```json @@ -125,8 +171,8 @@ To complete this tutorial, you need the following: ``` npx prisma db push ``` - - This command will create the `user` table in your TiDB Serverless cluster through the traditional TCP connection, rather than through the HTTPS connection using `@tidbcloud/prisma-adapter`. This is because it uses the same engine as Prisma Migrate. For more information about this command, see [Prototype your schema](https://www.prisma.io/docs/concepts/components/prisma-migrate/db-push). + + This command will create the `user` table in your TiDB Serverless cluster through the traditional TCP connection, rather than through the HTTPS connection using `@tidbcloud/prisma-adapter`. This is because it uses the same engine as Prisma Migrate. For more information about this command, see [Prototype your schema](https://www.prisma.io/docs/concepts/components/prisma-migrate/db-push). 4. Generate Prisma Client: @@ -134,7 +180,7 @@ To complete this tutorial, you need the following: npx prisma generate ``` - This command will generate Prisma Client based on the Prisma schema. + This command will generate Prisma Client based on the Prisma schema. ### Step 4. Execute CRUD operations @@ -178,7 +224,7 @@ To complete this tutorial, you need the following: }, }) ``` - + 3. Execute some transaction operations with Prisma Client. For example: ```js @@ -213,7 +259,10 @@ To complete this tutorial, you need the following: console.log(e) } ``` - + ## Use the Prisma adapter in edge environments -Currently, `@tidbcloud/prisma-adapter` is not compatible with edge environments such as Vercel Edge Function and Cloudflare Workers. However, there are plans to support these environments. For more information, see [#21394](https://github.com/prisma/prisma/issues/21394). \ No newline at end of file +You can use `@tidbcloud/prisma-adapter` v5.11.0 or a later version in edge environments such as Vercel Edge Functions and Cloudflare Workers. + +- [Vercel Edge Function example](https://github.com/tidbcloud/serverless-driver-example/tree/main/prisma/prisma-vercel-example) +- [Cloudflare Workers example](https://github.com/tidbcloud/serverless-driver-example/tree/main/prisma/prisma-cloudflare-worker-example)