-
Notifications
You must be signed in to change notification settings - Fork 784
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add Guides section to documentation (#6537)
* Add Guides section to documentation * Update content/800-guides/1000-using-prisma-orm-with-turborepo.mdx * ignore word Turborepo * fix link * fix localhost links * update turborepo og image * add og images to all current guides * Optimised images with calibre/image-actions * make formatting changes to guides * re-format typeorm and sequelize guides * update Mongoose * format Drizzle and D1 * remove cruft * add meta guide * cspell * temp remove files + update formatting of D1 doc --------- Co-authored-by: Ankur Datta <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
- Loading branch information
3 people
authored
Jan 8, 2025
1 parent
a721bc7
commit cfa887b
Showing
54 changed files
with
2,529 additions
and
4,243 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -23,7 +23,7 @@ The edge-compatible drivers for Cloudflare Workers and Pages are: | |
| - [PlanetScale Serverless](https://planetscale.com/docs/tutorials/planetscale-serverless-driver) uses HTTP to access the database | ||
| - [`node-postgres`](https://node-postgres.com/) (`pg`) uses Cloudflare's `connect()` (TCP) to access the database | ||
| - [`@libsql/client`](https://github.com/tursodatabase/libsql-client-ts) is used to access Turso databases via HTTP | ||
| - [Cloudflare D1](/orm/prisma-client/deployment/edge/deploy-to-cloudflare#cloudflare-d1) is used to access D1 databases | ||
| - [Cloudflare D1](/orm/prisma-client/deployment/edge/deploy-to-cloudflare) is used to access D1 databases | ||
|
|
||
| There's [also work being done](https://github.com/sidorares/node-mysql2/pull/2289) on the `node-mysql2` driver which will enable access to traditional MySQL databases from Cloudflare Workers and Pages in the future as well. | ||
|
|
||
|
|
@@ -538,201 +538,4 @@ Then you can go ahead then deploy the Worker: | |
| npx wrangler deploy | ||
| ``` | ||
|
|
||
| The command will output the URL where you can access the deployed Worker. | ||
|
|
||
| ### Cloudflare D1 | ||
|
|
||
| If you are using a D1 database, you need to: | ||
|
|
||
| - use the `@prisma/adapter-d1` database adapter (via the `driverAdapters` Preview feature) | ||
| - set `sqlite` as the `datasource` provider in your Prisma schema | ||
| - manually generate SQL statements for schema changes using `prisma migrate diff` but execute them using [D1's migration system](https://developers.cloudflare.com/d1/reference/migrations/) | ||
|
|
||
| You can find a [deployment-ready example on GitHub](https://github.com/prisma/prisma-examples/blob/latest/deployment-platforms/edge/cloudflare-workers/with-d1). | ||
|
|
||
| #### 1. Configure Prisma schema | ||
|
|
||
| > **Note**: If you don't have a project to deploy, follow the instructions in the [Prerequisites](#prerequisites) to bootstrap a basic Cloudflare Worker with Prisma ORM in it. | ||
| In your Prisma schema, add the `driverAdapters` Preview feature to the `generator` block and set the `provider` of the `datasource` to `sqlite`. If you just bootstrapped the Prisma schema with `prisma init`, also be sure to add the following `User` model to it: | ||
|
|
||
| ```prisma file=schema.prisma | ||
| generator client { | ||
| provider = "prisma-client-js" | ||
| previewFeatures = ["driverAdapters"] | ||
| } | ||
| datasource db { | ||
| provider = "sqlite" | ||
| url = env("DATABASE_URL") | ||
| } | ||
| model User { | ||
| id Int @id @default(autoincrement()) | ||
| email String @unique | ||
| name String? | ||
| } | ||
| ``` | ||
|
|
||
| Note that in this tutorial, you won't need the `.env` file since the connection between Prisma ORM and D1 will happen through a [binding](https://developers.cloudflare.com/workers/configuration/bindings/). | ||
|
|
||
| #### 2. Install dependencies | ||
|
|
||
| Next, install the required packages: | ||
|
|
||
| ```terminal | ||
| npm install @prisma/adapter-d1 | ||
| ``` | ||
|
|
||
| Also, be sure to use a version of the Wrangler CLI that's above [`wrangler@^3.39.0`](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%403.39.0), otherwise the `--remote` flag that's used in the next sections won't be available. | ||
|
|
||
| #### 3. Set the D1 database connection via a binding | ||
|
|
||
| To connect your Workers with the D1 instance, add the following binding to your `wrangler.toml` (if you don't have a D1 instance yet, you can create one using the [Cloudflare Dashboard](https://dash.cloudflare.com/) or with the [`wrangler d1 create`](https://developers.cloudflare.com/workers/wrangler/commands/#create) command): | ||
|
|
||
| ```toml file=wrangler.toml | ||
| name = "prisma-cloudflare-worker-example" | ||
| main = "src/index.ts" | ||
| compatibility_date = "2024-03-20" | ||
| compatibility_flags = ["nodejs_compat"] | ||
|
|
||
| [[d1_databases]] | ||
| binding = "DB" # i.e. available in your Worker on env.DB | ||
| database_name = "__YOUR_D1_DATABASE_NAME__" # to be replaced | ||
| database_id = "__YOUR_D1_DATABASE_ID__" # to be replaced | ||
| ``` | ||
|
|
||
| Note that `__YOUR_D1_DATABASE_NAME__` and `__YOUR_D1_DATABASE_ID__` in the snippet above are placeholders that should be replaced with the database name and ID of your own D1 instance. | ||
|
|
||
| If you weren't able to grab this ID from the terminal output, you can also find it in the Cloudflare Dashboard or by running `npx wrangler d1 list` and `npx wrangler d1 info __YOUR_D1_DATABASE_NAME__` in your terminal. | ||
|
|
||
| #### 4. Migrate your database schema (if applicable) | ||
|
|
||
| If your Prisma schema only contains the `User` model but your D1 database is still empty, you need to make sure that there is a table in D1 that mirrors the structure of the `User` model. | ||
|
|
||
| D1 comes with its own [migration system](https://developers.cloudflare.com/d1/reference/migrations/) that lets you manage migration files in your file system. While this is convenient for creating and applying migration files, it doesn't help you identifying the actual SQL statements that you need to put into these migration files. That's where Prisma Migrate comes into play, because you can generate SQL statements for schema changes using the [`prisma migrate diff`](/orm/reference/prisma-cli-reference#migrate-diff) command. | ||
|
|
||
| First, create the `migrations` directory and initial migration file using the [`wrangler d1 migrations`](https://developers.cloudflare.com/workers/wrangler/commands/#migrations-create) command as follows: | ||
|
|
||
| ```terminal | ||
| npx wrangler d1 migrations create __YOUR_D1_DATABASE_NAME__ create_user_table | ||
| ``` | ||
|
|
||
| Replace `__YOUR_D1_DATABASE_NAME__` with the name of your database again and, when prompted, confirm that you want to create the `migrations` directory. After having run this command, there should be a new folder called `migrations` with a file called `0001_create_user_table.sql` inside of it. | ||
|
|
||
| You can now generate the required SQL statement for creating a `User` table that can be mapped to the `User` model in your the Prisma schema as follows: | ||
|
|
||
| ```terminal | ||
| npx prisma migrate diff --from-empty --to-schema-datamodel ./prisma/schema.prisma --script --output migrations/0001_create_user_table.sql | ||
| ``` | ||
|
|
||
| Note that the resulting SQL statement is stored in a file in the `migrations` directory called `0001_create_user_table.sql` which looks as follows: | ||
|
|
||
| ```sql file=migrations/0001_create_user_table.sql no-copy | ||
| -- CreateTable | ||
| CREATE TABLE "User" ( | ||
| "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, | ||
| "email" TEXT NOT NULL, | ||
| "name" TEXT | ||
| ); | ||
|
|
||
| -- CreateIndex | ||
| CREATE UNIQUE INDEX "User_email_key" ON "User"("email"); | ||
| ``` | ||
|
|
||
| You now need to use the [`wrangler d1 migrations apply`](https://developers.cloudflare.com/workers/wrangler/commands/#migrations-apply) command to send this SQL statement to D1. Note that this command accepts two options: | ||
|
|
||
| - `--local`: Executes the statement against a _local_ version of D1. This local version of D1 is a SQLite database file that'll be located in your project. This approach is useful, when you want to develop and test your Worker on your local machine. Learn more in the [Cloudflare docs](https://developers.cloudflare.com/d1/build-with-d1/local-development/). | ||
| - `--remote`: Executes the statement against your _remote_ version of D1. This version is used by your _deployed_ Cloudflare Workers. Learn more in the [Cloudflare docs](https://developers.cloudflare.com/d1/build-with-d1/remote-development/). | ||
|
|
||
| In this tutorial, you'll do both: test the Worker locally _and_ deploy it afterwards. So, you need to run both commands. Open your terminal and paste the following commands: | ||
|
|
||
| ```terminal | ||
| # For the local database | ||
| npx wrangler d1 migrations apply __YOUR_D1_DATABASE_NAME__ --local | ||
| # For the remote database | ||
| npx wrangler d1 migrations apply __YOUR_D1_DATABASE_NAME__ --remote | ||
| ``` | ||
|
|
||
| As before, you need to replace `__YOUR_D1_DATABASE_NAME__` with the name of your D1 database. | ||
|
|
||
| Let's also create some dummy data that we can query once the Worker is running. This time, you'll run the SQL statement without storing it in a file: | ||
|
|
||
| ```terminal | ||
| # For the local database | ||
| npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO \"User\" (\"email\", \"name\") VALUES | ||
| ('[email protected]', 'Jane Doe (Local)');" --local | ||
| # For the remote database | ||
| npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO \"User\" (\"email\", \"name\") VALUES | ||
| ('[email protected]', 'Jane Doe (Remote)');" --remote | ||
| ``` | ||
|
|
||
| #### 5. Use Prisma Client in your Worker to send a query to the database | ||
|
|
||
| Before adding a Prisma Client query to your Worker, you need to generate Prisma Client with the following command: | ||
|
|
||
| ``` | ||
| npx prisma generate | ||
| ``` | ||
|
|
||
| In order to query your database from the Worker using Prisma ORM, you need to: | ||
|
|
||
| 1. Add the `DB` binding to the `Env` interface. (Alternatively, you can run [`npx wrangler types`](https://developers.cloudflare.com/workers/wrangler/commands/#types) to generate the `Env` type from the binding in a separate file called `worker-configuration.d.ts`.) | ||
| 2. Instantiate `PrismaClient` using the `PrismaD1` driver adapter. | ||
| 3. Send a query using Prisma Client and return the result. | ||
|
|
||
| Open `src/index.ts` and replace the entire content with the following: | ||
|
|
||
| ```typescript file=src/index.ts | ||
| import { PrismaClient } from '@prisma/client' | ||
| import { PrismaD1 } from '@prisma/adapter-d1' | ||
|
|
||
| export interface Env { | ||
| DB: D1Database | ||
| } | ||
|
|
||
| export default { | ||
| async fetch( | ||
| request: Request, | ||
| env: Env, | ||
| ctx: ExecutionContext | ||
| ): Promise<Response> { | ||
| const adapter = new PrismaD1(env.DB) | ||
| const prisma = new PrismaClient({ adapter }) | ||
|
|
||
| const users = await prisma.user.findMany() | ||
| const result = JSON.stringify(users) | ||
| return new Response(result) | ||
| }, | ||
| } | ||
| ``` | ||
|
|
||
| #### 6. Run the Worker locally | ||
|
|
||
| With the database query in place and Prisma Client generated, you can go ahead and run the Worker locally: | ||
|
|
||
| ``` | ||
| npm run dev | ||
| ``` | ||
|
|
||
| Now you can open your browser at [`http://localhost:8787`](http://localhost:8787/) to see the result of the database query: | ||
|
|
||
| ```js no-copy | ||
| ;[{ id: 1, email: '[email protected]', name: 'Jane Doe (Local)' }] | ||
| ``` | ||
|
|
||
| #### 7. Set the `DATABASE_URL` environment variable and deploy the Worker | ||
|
|
||
| To deploy the Worker, run the the following command: | ||
|
|
||
| ``` | ||
| npm run deploy | ||
| ``` | ||
|
|
||
| Your deployed Worker is accessible via `https://prisma-d1-example.USERNAME.workers.dev`. If you navigate your browser to that URL, you should see the following data that's queried from your remote D1 database: | ||
|
|
||
| ```js no-copy | ||
| ;[{ id: 1, email: '[email protected]', name: 'Jane Doe (Remote)' }] | ||
| ``` | ||
| The command will output the URL where you can access the deployed Worker. | ||
Oops, something went wrong.