D1 ORM

A lightweight and powerful ORM designed specifically for Cloudflare D1, inspired by Laravel's Eloquent.

Features

• 🚀 Lightweight & Fast: Optimized for Cloudflare Workers environment.
• 🛠 Eloquent-based: Familiar syntax for Laravel developers.
• 📦 TypeScript: Full static typing for enhanced security.
• 🔗 Relationships: Built-in support for hasOne, hasMany, and belongsTo.
• ⌨️ Integrated CLI: Tools for migrations, model generation, and seeding.

Installation

npm install @3lineas/d1-orm
# Or using pnpm
pnpm add @3lineas/d1-orm

Initial Setup

By default, the ORM attempts to auto-initialize itself if your D1 binding is named DB.

For zero-configuration setup in Cloudflare Workers or Next.js:

// No manual setup required if binding name is 'DB'!
const users = await User.all();

If you use a custom binding name or want manual control:

import { Database } from "@3lineas/d1-orm";

export default {
  async fetch(request, env, ctx) {
    Database.setup(env.MY_CUSTOM_DB);
    // ...
  },
};

Directory Structure

When you run init, the ORM creates a unified structure in src/database (if src exists) or database/:

• database/models/: Your Eloquent-style models.
• database/migrations/: SQL migration files.
• database/seeders/: Data seeders.
• database/config.ts: Central configuration.

Configuration (database/config.ts)

export default {
  binding: "DB", // The name of your D1 binding
};

Defining Models

Define your models by extending the Model class. Models are typically placed in database/models/.

import { Model } from "@3lineas/d1-orm";

export class User extends Model {
  declare id: number;
  declare name: string;
}

CLI & Migrations

The ORM includes a modern, Astro-style CLI for database management.

Initialization

pnpm d1-orm init

This command is non-interactive and automatically detects your project structure.

Available Commands

Manage Models & Schema

The ORM provides interactive tools to manage your database schema and models.

# Create a new model interactively
# It will prompt you for attributes and relationships
pnpm orm make:model User

# Add more attributes or relations to an existing model
pnpm orm model:add

Supported attribute types:

• string, text: For text data.
• integer, float: For numeric data.
• boolean: For true/false values.
• json: Stored as text, parsed automatically.
• enum: Includes database-level CHECK constraints.
• date, datetime: For temporal data.
• blob: For binary data.
• relation: Interactive menu for HasOne, HasMany, and BelongsTo.

Relationship Automation: When you define a relationship through the CLI:

1. The Model file is updated with the correct method (e.g., posts() { return this.hasMany(Post); }).
2. The Migration file automatically includes the foreign key column if you choose BelongsTo.

Run Migrations

# Local
pnpm orm migrate

# Remote
pnpm orm migrate --remote

# Migrate and then seed
pnpm orm migrate --seed

Reset Database

Drop all tables and re-run all migrations.

pnpm orm migrate:fresh

# Reset and seed
pnpm orm migrate:fresh --seed

Seed Database

Run seeders defined in database/seeders.

pnpm orm db:seed

Note: The CLI automatically detects your wrangler.jsonc, wrangler.json or wrangler.toml to find your D1 binding.

Crafted with ❤️ by 3Lineas.