Skip to main content

How to use Prisma ORM with Cloudflare D1

10 min

Introduction​

This guide shows you how to use Prisma ORM with Cloudflare D1, a serverless SQL database that runs on Cloudflare's edge network. You'll learn how to set up Prisma ORM with D1, handle migrations, and deploy your application to Cloudflare Workers. You can find a deployment-ready example on GitHub.

Prerequisites​

Before starting this guide, make sure you have:

  • A Cloudflare account
  • Node.js installed (version 18 or higher)
  • Wrangler CLI installed (version 3.39.0 or higher)
  • Basic familiarity with Cloudflare Workers and D1

1. Create a new Cloudflare Worker and initialize Prisma ORM​

Run the following command to create a new Cloudflare Worker project:

npm create cloudflare@latest d1-tutorial -- --type=hello-world --ts=true --git=true --deploy=false

Then navigate into the newly created directory:

cd d1-tutorial

And initialize Prisma ORM in the project:

npx prisma init --datasource-provider sqlite

And install the Prisma ORM CLI as a development dependency:

npm install --save-dev prisma

2. Configure Prisma schema​

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/schema.prisma
generator client {
  provider = "prisma-client-js"
  output   = "../src/generated/prisma"
  previewFeatures = ["driverAdapters"]
}

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

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

3. Install dependencies​

Next, install the required packages:

npm install @prisma/adapter-d1 dotenv

Also, be sure to use a version of the Wrangler CLI that's above wrangler@^3.39.0, otherwise the --remote flag that's used in the next sections won't be available.

4. Create a D1 database​

Run the following command to create a new D1 database:

npx wrangler@latest d1 create __YOUR_D1_DATABASE_NAME__
note

The __YOUR_D1_DATABASE_NAME__ is a placeholder that should be replaced with the name you want to give your D1 database. For example, you can use prisma-d1-example.

This command will authenticate you with Cloudflare and ask you to select a Cloudflare account. After that, it will create a new D1 database and output the database ID and name:

✅ Successfully created DB '__YOUR_D1_DATABASE_NAME__' in region __REGION__
Created your new D1 database.

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "__YOUR_D1_DATABASE_NAME__",
      "database_id": "<unique-ID-for-your-database>"
    }
  ]
}

Copy the terminal output and add the content to your wrangler.jsonc file. This file is used to configure your Cloudflare Worker and its bindings.

To connect your Workers with the D1 instance, add the following binding to your wrangler.jsonc:

wrangler.jsonc
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "d1-tutorial",
	"main": "src/index.ts",
	"compatibility_date": "2025-08-05",
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "__YOUR_D1_DATABASE_NAME__", // to be replaced
			"database_id":  "__YOUR_D1_DATABASE_ID__" // to be replaced
		}
	]
}

note

The __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 the database 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.

5. Set up database migrations​

note

We recommend using prisma migrate in order to keep your data in D1 migrated. However, if you would prefer to use Cloudflare's migration system, that workflow is also available

5.1 Add needed environment variables​

In order to use the Prisma D1 adapter, you'll need to add a few secrets to a .env file:

  • DATABASE_URL: A path to your local D1 instance. Usually "file:./prisma/db.sqlite".
  • CLOUDFLARE_ACCOUNT_ID: Your Cloudflare account ID, fetched via npx wrangler whoami
  • CLOUDFLARE_DATABASE_ID: The ID of your database, retrieved during D1 database creation.
  • CLOUDFLARE_D1_TOKEN: This API token is used by Prisma ORM to communicate with your D1 instance directly. To create this, follow these steps:
    1. Visit https://dash.cloudflare.com/profile/api-tokens
    2. Click "Create Token"
    3. On the Custom token section click on "Get started".
    4. Fill out the template: Make sure you use a recognizable name
    5. For the Permissions, add the Account / D1 / Edit permission.
    6. Click "Continue to summary" and then "Create Token".
    7. Click on "Copy" and store the token in a safe place.

You can now store these secrets to be used by Prisma ORM. We recommend a .env file for local development, but any secret store will work.

.env
DATABASE_URL="file:./prisma/db.sqlite"

CLOUDFLARE_ACCOUNT_ID="0773..."
CLOUDFLARE_DATABASE_ID="01f30366-..."
CLOUDFLARE_D1_TOKEN="F8Cg..."

5.2 Configure Prisma Config​

Ensure that you have a prisma.config.ts file set up in the root of your project with a driver adapter defined.

import type { PrismaConfig } from 'prisma';
import { PrismaD1 } from '@prisma/adapter-d1';

// import your .env file
import 'dotenv/config';

export default {
	experimental: {
		adapter: true,
	},
	schema: 'prisma/schema.prisma',
	async adapter() {
		return new PrismaD1({
			CLOUDFLARE_D1_TOKEN: process.env.CLOUDFLARE_D1_TOKEN!,
			CLOUDFLARE_ACCOUNT_ID: process.env.CLOUDFLARE_ACCOUNT_ID!,
			CLOUDFLARE_DATABASE_ID: process.env.CLOUDFLARE_DATABASE_ID!,
		});
	},
} satisfies PrismaConfig;
note

As of Prisma ORM v6.11.0, the D1 adapter has been renamed from PrismaD1HTTP to PrismaD1.

This will allow prisma migrate to interact with your D1 database.

4.3 Run your first migration​

You can now run prisma migrate dev to migrate your database to match your local schema:

npx prisma migrate dev --name init

Let's also create some dummy data that we can query once the Worker is running. This time, we'll use wrangler to run a SQL statement without storing it in a file:

# For the local database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Local)');" --local

# For the remote database
npx wrangler d1 execute __YOUR_D1_DATABASE_NAME__ --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Remote)');" --remote

5. Implement the Worker​

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

src/index.ts
import { PrismaClient } from './generated/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​

First copy the contents of your .env file to a new file called .dev.vars in the root of your project. This file will be used to set environment variables when running the Worker locally.

cp .env .dev.vars

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 to see the result of the database query:

;[{ id: 1, email: 'jane@prisma.io', 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
note

Make sure to upload the .dev.vars file to your Cloudflare Worker environment. This file contains the DATABASE_URL and other environment variables needed for the Worker to connect to the D1 database.

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:

;[{ id: 1, email: 'jane@prisma.io', name: 'Jane Doe (Remote)' }]

Next steps​

Now that you've set up Prisma ORM with Cloudflare D1, you can:

  • Add more complex queries using Prisma's powerful query API
  • Set up Prisma Studio for database management
  • Implement database monitoring
  • Add automated tests

For more information:


Stay connected with Prisma

Continue your Prisma journey by connecting with our active community. Stay informed, get involved, and collaborate with other developers:

We genuinely value your involvement and look forward to having you as part of our community!

Open in
Copy as Markdown
Open in Claude
Open in ChatGPT
Open in T3.chat
Edit in GitHub