Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cloud: support edge in prisma #16966

Merged
merged 1 commit into from
Apr 7, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 59 additions & 10 deletions tidb-cloud/serverless-driver-prisma-example.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -125,16 +171,16 @@ 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:

```
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

Expand Down Expand Up @@ -178,7 +224,7 @@ To complete this tutorial, you need the following:
},
})
```

3. Execute some transaction operations with Prisma Client. For example:

```js
Expand Down Expand Up @@ -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).
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)
Loading