Introduction

Welcome to D1 Migration Mastery! This comprehensive guide will take you from zero to deploying a fully-functional API with Cloudflare D1, Drizzle ORM, and Elysia.

What you’ll build

By the end of this tutorial, you’ll have built a complete blog API with:

A fully deployed REST API on Cloudflare Workers using Elysia
A SQLite database running on Cloudflare D1
Type-safe database access with Drizzle ORM
Auto-generated API documentation with Swagger
Database migrations that work across local, staging, and production environments

Final Architecture

Here’s an overview of what you’ll build:

flowchart TB
  subgraph Client["Client"]
      Browser["Browser / API Client"]
  end

  subgraph CloudflareEdge["Cloudflare Edge"]
      Worker["Cloudflare Worker<br/>(Elysia API)"]
      D1["Cloudflare D1<br/>(SQLite)"]
      Swagger["Swagger UI<br/>(/swagger)"]
  end

  subgraph LocalDev["Local Development"]
      Wrangler["Wrangler Dev Server"]
      LocalD1["Local D1<br/>(SQLite)"]
      DrizzleKit["Drizzle Kit<br/>(Migrations)"]
  end

  Browser --> Worker
  Worker --> D1
  Worker --> Swagger
  Wrangler --> LocalD1
  DrizzleKit --> |"generate"| Wrangler
  DrizzleKit --> |"migrate"| D1

The architecture follows a modern edge-first approach:

Elysia handles routing, validation, and Swagger documentation
Drizzle ORM provides type-safe database queries and schema management
Cloudflare D1 stores your data in SQLite, replicated globally at the edge
Drizzle Kit generates and manages database migrations

Prerequisites

Before you begin, make sure you have:

Node.js 18+ installed (download here)
pnpm package manager (npm install -g pnpm)
A Cloudflare account (free tier works) — sign up here
Basic knowledge of TypeScript
Familiarity with REST APIs (helpful but not required)

How this tutorial works

Each chapter builds on the previous one. You can:

Follow along step-by-step from the beginning
Jump to any chapter using the reset commands
Experiment freely — you can always reset to a clean state

Chapter Reset Commands

The starter project includes reset scripts that let you jump to specific points:

Command	Description
`pnpm reset:ch1`	Reset to empty database (Chapter 1)
`pnpm reset:ch2`	Reset to Users table only (Chapter 2)
`pnpm reset:ch3`	Reset to Users + Posts tables (Chapter 3)
`pnpm reset:all`	Full reset to fresh state

Getting the starter project

The starter project provides everything you need to follow along:

# Clone the starter repository
git clone https://github.com/d1-migration-mastery/starter.git

# Navigate to the project
cd starter

# Install dependencies
pnpm install

Or download directly: Download Starter Project (ZIP)

What’s included

The starter project comes with:

Pre-configured Elysia with Swagger plugin
Drizzle ORM and Drizzle Kit setup
Wrangler configuration for Cloudflare Workers
TypeScript configuration with strict type checking
ESLint for code quality
Chapter reset scripts for easy navigation

Ready to begin? Let’s deploy your first app in the next chapter!