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

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

`typescript
// 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:

`typescript
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.

$3

`typescript
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/.

`typescript
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.

$3

`bash
pnpm d1-orm init
`

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

$3

#### Manage Models & Schema

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

`bash


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

`bash


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.

`bash
pnpm orm migrate:fresh

Reset and seed


pnpm orm migrate:fresh --seed
`

#### Seed Database

Run seeders defined in database/seeders.

`bash
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.