🚀 EF-Core for Node.js

A lightweight Node.js implementation of .NET EF Core — combining DbContext + DbSet + Migrations + Drift Detection in one provider‑agnostic engine.

✨ Features

• 🧠 DbContext + DbSet for entity/session management
• 🔄 Deterministic migrations via snapshot system
• ⚙️ Provider‑agnostic (SQLite, Postgres, MySQL, SqlServer)
• 🧱 Fluent ModelBuilder DSL
• 🔍 Drift detection for production safety
• 🔒 Migration locking (concurrency‑safe)
• 🖥️ CLI + Library parity with .NET EF Core

📊 Feature Comparison

See how EF‑Core for Node.js compares with .NET EF Core:

Feature Comparison Table

📦 Installation

# pnpm
pnpm install @dreamz-it/ef-core

# npm
npm install @dreamz-it/ef-core

# yarn
yarn add @dreamz-it/ef-core

⚡ Quick Start

🌐 Community & Repository

Explore the source code, report issues, and contribute via our public GitHub repository:

👉 EF-Core for Node.js on GitHub

Join discussions, share feedback, and help shape the roadmap!

Track 1: CLI‑Only (Migrations & Drift)

If just want migrations without writing DbContext code:

# Create a migration
ef add Init

# Apply migrations
ef apply

# Check migration status
ef status

# Generate SQL script
ef script

# Detect drift (production safety)
ef drift

# Rollback last migration
ef rollback

👉 This track is ideal if only need schema evolution and drift detection.

Track 2: Full DbContext (EF Core‑style ORM)

If want the full EF Core experience in Node.js:

1. Define DbContext (app.db.ts)

import { DbContext } from "@dreamz-it/ef-core/core/db.context.js";
import { Column } from "@dreamz-it/ef-core/core/db.decorator.js";
import { BaseEntity, PrimaryKey } from "@dreamz-it/ef-core/core/db.entity.js";
import { ModelBuilder } from "@dreamz-it/ef-core/core/db.model.builder.js";
import { DbSet } from "@dreamz-it/ef-core/core/db.set.js";

export class User extends BaseEntity {
  id!: string;
  @Column({ typeName: "string", maxLength: 200 })
  name: string = "";
  email: string = "";
}

export class AppDbContext extends DbContext {
  public Users!: DbSet<User>;

  protected override onModelCreating(builder: ModelBuilder): void {
    builder.entity(User, "users")
      .hasKey(new PrimaryKey<User>({ id: "string" }, { auto: true }));
  }
}

2. Configure EF Core (app-db.config.ts)

import { AppDbContext } from "./app.db.js";
import { defineConfig } from "@dreamz-it/ef-core/cli/index.js";
import { getEnv } from "@dreamz-it/ef-core/system/environment.js";
import { ProviderType } from "@dreamz-it/ef-core/providers/types.js";

export default defineConfig({
  context: AppDbContext as new () => AppDbContext,
  migrationsDir: "./migrations",
  environment: getEnv(),
  contextOptions: {
    provider: (process.env.DATABASE_PROVIDER || "sqlite") as ProviderType,
    connectionString: process.env.DATABASE_URL || "app.db",
    poolSize: Number(process.env.DB_POOL_SIZE) || 10,
    logging: process.env.DB_LOGGING === "true",
  },
});

3. Run migrations with the DbContext

ef add Init
ef apply

🧱 Migration Example

import { MigrationBuilder } from "@dreamz-it/ef-core";

export default class Init {

  up(mb: MigrationBuilder) {
    mb.createTable("Users", t => {
      t.column("id", "string", c => c.primary());
      t.column("email", "string", c => c.notNull().unique());
    });
  }

  down(mb: MigrationBuilder) {
    mb.dropTable("Users");
  }
}

🧠 How It Works

Model Schema
     ↓
Snapshot (_snapshot.json)
     ↓
Diff Engine
     ↓
Migration Operations
     ↓
SQL Generator (provider-specific)
     ↓
Execution Engine
     ↓
Database

🔍 Drift Detection

Detect when the database has been modified outside migrations:

ef drift

Example output:

⚠️ Drift detected:

missing_table  | table=Users
extra_column   | table=Orders | column=tempField
changed_column | table=Users  | column=email

🔒 Safety Features

• Migration Locking → prevents concurrent execution
• Snapshot Versioning → future-proof schema evolution
• Deterministic Hashing → consistent comparisons
• Strict Diff Engine → no silent changes

📁 Project Structure

src/
├── core/            # Engine (schema, diff, builder)
├── providers/       # SQL + DB introspection
├── infrastructure/  # execution, snapshot, history
├── services/        # orchestration layer
├── cli/             # command-line interface
└── utils/           # helpers

🧩 Supported Providers

• ✅ SQLite (better-sqlite3)
• ✅ SQLite (libsql)
• ✅ Postgres (pg)
• ✅ Postgres (postgres.js)
• ✅ SqlServer (mssql)
• ✅ SqlServer (tedious)
• ✅ MySQL (mysql2)
• ✅ MariaDB (mysql2) (not fully tested on MariaDB context)
• ⚠️ MySQL (planetscale)

📊 Feature Comparison: EF Core (.NET) vs EF‑Core for Node.js

| Feature | .NET EF Core | EF‑Core for Node.js | |-------------|------------------|--------------------------| | DbContext + DbSet | ✅ Fully supported | ✅ Supported | | Fluent ModelBuilder DSL | ✅ Full API | ✅ Supported (parity in progress) | | Migrations | ✅ Deterministic, snapshot‑based | ✅ Deterministic, snapshot‑based | | Drift Detection | ❌ Not built‑in | ✅ Supported | | Migration Locking | ❌ Not built‑in | ✅ Supported (via sp_getapplock / advisory locks) | | CLI + Library Parity | ✅ Rich tooling | ✅ Supported (CLI + programmatic) | | Provider Support | ✅ SQL Server, SQLite, Postgres, MySQL, etc. | ✅ SQLite, Postgres, MySQL, MariaDB, SqlServer (mssql + tedious), ⚠️ Planetscale | | Index + Constraint Diffing | ✅ Advanced | 🚧 Stable | | Rename Detection | ✅ Advanced | 🚧 Stable | | Seed System | ✅ Built‑in | 🚧 Redesign planned | | Migration Graph Visualization | ✅ Limited tooling | 🚧 Planned | | Multi‑environment Support | ✅ Supported | 🚧 Stable | | LINQ Queries | ✅ Full LINQ provider | ❌ Not supported (use SQL/QueryBuilder) | | Change Tracking | ✅ Full | 🚧 Planned (basic tracking only) | | Lazy Loading | ✅ Supported | 🚧 Planned (basic lib only) | | Compiled Queries | ✅ Supported | ❌ Not supported |

🚧 Roadmap

• 🔁 Rename detection (advanced diff)
• 📊 Index + constraint diffing (advanced)
• 🌱 Seed system redesign
• 🧭 Migration graph visualization
• ☁️ Multi-environment support

📈 Roadmap Diagram (ASCII)

Now
 ├── DbContext + DbSet
 ├── Deterministic Migrations
 ├── Drift Detection
 ├── Migration Locking
 └── Provider Support (SQLite, Postgres, MySQL, SqlServer)

   ↓ Next
 ├── Rename Detection (Advanced)
 ├── Index + Constraint Diffing (Advanced)
 ├── Seed System Redesign
 └── Migration Graph Visualization

   ↓ Future
 ├── Multi-environment Support
 ├── Change Tracking (Advanced)
 ├── Lazy Loading (Advanced)
 └── Compiled Queries

📊 Roadmap Diagram (Mermaid)

flowchart TD
    A[Now] --> B[Next] --> C[Future]

    A --> A1[DbContext + DbSet]
    A --> A2[Deterministic Migrations]
    A --> A3[Drift Detection]
    A --> A4[Migration Locking]
    A --> A5[Provider Support]

    B --> B1[Rename Detection] (Advanced)
    B --> B2[Index + Constraint Diffing] (Advanced)
    B --> B3[Seed System Redesign]
    B --> B4[Migration Graph Visualization]

    C --> C1[Multi-environment Support]
    C --> C2[Change Tracking] (Advanced)
    C --> C3[Lazy Loading] (Advanced)
    C --> C4[Compiled Queries]

🧠 Philosophy

EF-Core for Node.js is not just a migration tool. It’s a lightweight EF Core analogue:

• DbContext + DbSet for entity/session management
• Fluent ModelBuilder for schema configuration
• Provider‑agnostic migrations
• Drift detection and snapshot system for production safety

Inspired by:

• .NET EF Core
• Prisma (DX)
• DrizzleORM (lessons learned 😄)
• TypeORM (lessons learned 😄)

📜 License

MIT

🙌 Contributing

PRs are welcome. Keep it clean, typed, and deterministic.