Installation

This guide covers everything you need to get d1-eloquent installed and wired up in a Cloudflare Workers project.

Prerequisites

Before you start, make sure you have:

• A Cloudflare Workers project (created with wrangler init or create-cloudflare)
• A D1 database created in your Cloudflare account (wrangler d1 create my-database)
• Node.js 18+ or Bun installed

New to Cloudflare D1?

The D1 getting started guide walks through creating a Workers project and provisioning a D1 database.

Install the Package

npm

npm install @orphnet/d1-eloquent

bun

bun add @orphnet/d1-eloquent

pnpm

pnpm add @orphnet/d1-eloquent

yarn

yarn add @orphnet/d1-eloquent

Configure Wrangler

Add your D1 database binding to wrangler.toml. If you have not created a D1 database yet, run wrangler d1 create my-database first — it will print the database_id you need here.

# wrangler.toml

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "your-database-id-here"

Binding name matters

The binding value (DB in the example above) is how you access the D1 database inside your Worker. Every d1-eloquent call receives this binding as its first argument: User.create(env.DB, attrs). Use any name you like, but keep it consistent.

Access the Binding in Your Worker

Once the binding is configured, Cloudflare injects it into env at runtime. Pass env.DB directly to any d1-eloquent method:

import { User } from './models/User'

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const users = await User.query().limit(10).get(env.DB)
    return Response.json(users.map(u => u.attrs))
  },
}

interface Env {
  DB: D1Database
}

Type-safe bindings

Define an Env interface (as shown above) and type your handler with it. TypeScript will enforce that env.DB is a D1Database — no silent any types slipping through.

Run Migrations

d1-eloquent includes a CLI for managing migrations. Run your first migration against a local D1 database:

# Run all pending migrations locally
npx @orphnet/d1-eloquent migrate --db DB --local

To run against your remote Cloudflare D1 database:

npx @orphnet/d1-eloquent migrate --db DB --remote

The --db flag must match the binding value in your wrangler.toml. Pass --local during development (uses Wrangler's local D1 emulation) and --remote when deploying changes to production.

Check Migration Status

npx @orphnet/d1-eloquent status --db DB --local

This lists every migration file, whether it has been applied, and when it ran.

Next Steps

You are ready to define your first model and run migrations. Continue to the Quick Start guide for a complete end-to-end walkthrough.