Skip to content
Cloudflare Docs

Drizzle ORM

Drizzle ORM ↗ is a lightweight TypeScript ORM with a focus on type safety. This example demonstrates how to use Drizzle ORM with PostgreSQL via Cloudflare Hyperdrive in a Workers application.

Prerequisites

1. Install Drizzle

Install the Drizzle ORM and its dependencies such as the postgres ↗ driver:

Terminal window
# postgres 3.4.5 or later is recommended
npm i drizzle-orm postgres dotenv
npm i -D drizzle-kit tsx @types/node

Add the required Node.js compatibility flags and Hyperdrive binding to your wrangler.jsonc file:

{
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "compatibility_date": "2024-09-23",
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<your-hyperdrive-id-here>"
    }
  ]
}

2. Configure Drizzle

2.1. Define a schema

With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL.

  1. Create a folder /db/ in /src/.

  2. Create a schema.ts file.

  3. In schema.ts, define a users table as shown below.

    src/db/schema.ts
    // src/db/schema.ts
    import { pgTable, serial, varchar, timestamp } from "drizzle-orm/pg-core";
    

    export const users = pgTable("users", {
      id: serial("id").primaryKey(),
      name: varchar("name", { length: 255 }).notNull(),
      email: varchar("email", { length: 255 }).notNull().unique(),
      createdAt: timestamp("created_at").defaultNow(),
    });

2.2. Connect Drizzle ORM to the database with Hyperdrive

Use your Hyperdrive configuration for your database when using the Drizzle ORM.

Populate your index.ts file as shown below.

src/index.ts
// src/index.ts
import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";
import { users } from "./db/schema";


export interface Env {
  HYPERDRIVE: Hyperdrive;
}


export default {
  async fetch(request, env, ctx): Promise<Response> {
    // Create a database client with postgres.js driver connected via Hyperdrive
    const sql = postgres(env.HYPERDRIVE.connectionString, {
      // Limit the connections for the Worker request to 5 due to Workers' limits on concurrent external connections
      max: 5,
      // If you are not using array types in your Postgres schema, disable `fetch_types` to avoid an additional round-trip (unnecessary latency)
      fetch_types: false,
    });


    // Create the Drizzle client with the postgres.js connection
    const db = drizzle(sql);


    // Sample query to get all users
    const allUsers = await db.select().from(users);


    return Response.json(allUsers);
  },
} satisfies ExportedHandler<Env>;

2.3. Configure Drizzle-Kit for migrations (optional)

You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to Drizzle ORM docs ↗ for additional guidance.

  1. Create a .env file the root folder of your project, and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations.

    .env
    # .env
    # Replace with your direct database connection string
    DATABASE_URL='postgres://user:password@db-host.cloud/database-name'

  2. Create a drizzle.config.ts file in the root folder of your project to configure Drizzle Kit and add the following content:

    drizzle.config.ts
    // drizzle.config.ts
    import "dotenv/config";
    import { defineConfig } from "drizzle-kit";
    export default defineConfig({
      out: "./drizzle",
      schema: "./src/db/schema.ts",
      dialect: "postgresql",
      dbCredentials: {
        url: process.env.DATABASE_URL!,
      },
    });

  3. Generate the migration file for your database according to your schema files and apply the migrations to your database.

    Run the following two commands:

    Terminal window
    npx drizzle-kit generate
    No config path provided, using default 'drizzle.config.ts'
    Reading config file 'drizzle.config.ts'
    1 tables
    users 4 columns 0 indexes 0 fks
    

    [✓] Your SQL migration file ➜ drizzle/0000_mysterious_queen_noir.sql 🚀
    Terminal window
    npx drizzle-kit migrate
    No config path provided, using default 'drizzle.config.ts'
    Reading config file 'drizzle.config.ts'
    Using 'postgres' driver for database querying

3. Deploy your Worker

Deploy your Worker.

Terminal window
npx wrangler deploy

Next steps