Skip to main content

​
title: Installation description: Install and configure Eloquent ORM JS in your Node.js project.

​
Installation and Quick Start

Version: 1.1.4

​
Install

npm install @alpha.consultings/eloquent-orm.js express
npm install -D typescript ts-node @types/express @types/node
This package is a TypeScript Eloquent ORM. If your app uses HTTP routes, install Express.js up front because the runtime examples and generated controllers are Express-oriented. dotenv and @faker-js/faker stay in the package runtime dependencies because the published runtime uses them:
  • dotenv is used by the default database config bootstrap.
  • @faker-js/faker is used by the factory runtime surface and generated factory flow.
You do not need to install them separately unless your own app imports them directly. If your app bootstrap calls dotenv.config() or your own code imports faker directly, add them in your app too: 
npm install dotenv @faker-js/faker

​
ESM and NodeNext imports

NodeNext and ESM apps can import the public runtime directly from the package root: 
import { SqlModel, column, Factory } from "@alpha.consultings/eloquent-orm.js";
The published package now routes import consumers through an ESM-safe entry while keeping CommonJS require() usage safe for plain root imports that do not need the factory runtime.

​
npm package discovery

These npm metadata commands now resolve directly to the hosted docs, GitHub repository, and issue tracker: 
npm docs @alpha.consultings/eloquent-orm.js
npm repo @alpha.consultings/eloquent-orm.js
npm bugs @alpha.consultings/eloquent-orm.js

​
Prerequisites

The following versions are the current supported and CI-tested prerequisites.
ComponentSupported / tested version
Node.js`^20^22^24`
TypeScript^5.9.3
MySQL8.0
PostgreSQL16
MongoDB7
SQLiteSQLite 3.x via better-sqlite3 12.2.0
Memcached1.6+ server, client package ^2.2.2

​
Full .env setup

Use one active value in DB_CONNECTION and one active value in DB_TEST_CONNECTION. Do not put multiple connection names in the same env variable. 
# Active runtime selectors
DB_CONNECTION=sqlite
DB_TEST_CONNECTION=sqlite_test
ELOQUENT_DB_ROLE=runtime

# MySQL
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=
DB_NAME=eloquent_app
DB_TEST_HOST=127.0.0.1
DB_TEST_PORT=3306
DB_TEST_USER=root
DB_TEST_PASSWORD=
DB_TEST_NAME=eloquent_app_test

# PostgreSQL
PG_HOST=127.0.0.1
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=postgres
PG_NAME=eloquent_app_pg
PG_TEST_HOST=127.0.0.1
PG_TEST_PORT=5432
PG_TEST_USER=postgres
PG_TEST_PASSWORD=postgres
PG_TEST_NAME=eloquent_app_pg_test

# SQLite
SQLITE_PATH=./storage/app.sqlite
SQLITE_TEST_PATH=./storage/app.test.sqlite

# MongoDB
MONGO_URI=mongodb://127.0.0.1:27017
MONGO_DB=eloquent_app
MONGO_TEST_URI=mongodb://127.0.0.1:27017
MONGO_TEST_DB=eloquent_app_test

# Cache / Memcached
MEMCACHED_HOST=127.0.0.1
MEMCACHED_PORT=11211
CACHE_DIR=.cache

​
Quick .env key list

  • DB_CONNECTION: active app connection name such as mysql, pg, sqlite, or mongo
  • DB_TEST_CONNECTION: active test connection name such as mysql_test, pg_test, sqlite_test, or mongo_test
  • ELOQUENT_DB_ROLE: choose runtime for the app process and migration only for migration or reset jobs
  • APP_ENV: use development for local work and production only for real production processes
  • DB_* and DB_TEST_*: MySQL runtime and test credentials
  • PG_* and PG_TEST_*: PostgreSQL runtime and test credentials
  • SQLITE_PATH and SQLITE_TEST_PATH: SQLite database files
  • MONGO_URI, MONGO_DB, MONGO_TEST_URI, and MONGO_TEST_DB: Mongo runtime and test targets
  • MEMCACHED_HOST and MEMCACHED_PORT: Memcached endpoint for production cache mode
  • CACHE_DIR: file-cache fallback directory used in staging and in the production fallback chain

​
.env constant reference

​
Connection selectors

  • DB_CONNECTION: default application connection. Use one value such as mysql, pg, sqlite, or mongo.
  • DB_TEST_CONNECTION: default isolated test connection. Use one value such as mysql_test, pg_test, sqlite_test, or mongo_test.
  • ELOQUENT_DB_ROLE: credential role selector. Use runtime for normal app traffic and migration for migration or reset jobs.
  • APP_ENV: deployment mode. Use development for local work and production only for real production processes.

​
MySQL constants

  • DB_HOST: MySQL host or IP for runtime traffic.
  • DB_PORT: MySQL port for runtime traffic. Usually 3306.
  • DB_USER: MySQL username for runtime traffic.
  • DB_PASSWORD: MySQL password for runtime traffic.
  • DB_NAME: MySQL database name for runtime traffic.
  • DB_TEST_HOST: MySQL host or IP for isolated test traffic.
  • DB_TEST_PORT: MySQL port for isolated test traffic.
  • DB_TEST_USER: MySQL username for isolated test traffic.
  • DB_TEST_PASSWORD: MySQL password for isolated test traffic.
  • DB_TEST_NAME: MySQL database name for isolated test traffic.

​
PostgreSQL constants

  • PG_HOST: PostgreSQL host or IP for runtime traffic.
  • PG_PORT: PostgreSQL port for runtime traffic. Usually 5432.
  • PG_USER: PostgreSQL username for runtime traffic.
  • PG_PASSWORD: PostgreSQL password for runtime traffic.
  • PG_NAME: PostgreSQL database name for runtime traffic.
  • PG_TEST_HOST: PostgreSQL host or IP for isolated test traffic.
  • PG_TEST_PORT: PostgreSQL port for isolated test traffic.
  • PG_TEST_USER: PostgreSQL username for isolated test traffic.
  • PG_TEST_PASSWORD: PostgreSQL password for isolated test traffic.
  • PG_TEST_NAME: PostgreSQL database name for isolated test traffic.

​
SQLite constants

  • SQLITE_PATH: file path for the runtime SQLite database.
  • SQLITE_TEST_PATH: file path for the isolated test SQLite database.

​
MongoDB constants

  • MONGO_URI: MongoDB connection string for the runtime database.
  • MONGO_DB: runtime MongoDB database name.
  • MONGO_TEST_URI: MongoDB connection string for the isolated test database.
  • MONGO_TEST_DB: isolated test MongoDB database name.

​
Cache constants

  • MEMCACHED_HOST: Memcached host or IP used in production cache mode.
  • MEMCACHED_PORT: Memcached port used in production cache mode. Usually 11211.
  • CACHE_DIR: file-cache directory used in staging and as a fallback in production.

​
Runtime role and environment mode

Use these two variables together:
  • ELOQUENT_DB_ROLE=runtime
    • normal app runtime
    • Express requests
    • controllers, services, and standard CRUD traffic
  • ELOQUENT_DB_ROLE=migration
    • migration commands
    • reset or fresh flows
    • controlled schema-change jobs
  • APP_ENV=development
    • your local machine
    • normal development and testing
  • APP_ENV=production
    • real production deploys
    • production migration jobs
Recommended combinations: 
# Local app runtime
APP_ENV=development
ELOQUENT_DB_ROLE=runtime

# Local migration command
APP_ENV=development
ELOQUENT_DB_ROLE=migration

# Production app runtime
APP_ENV=production
ELOQUENT_DB_ROLE=runtime

# Production migration job
APP_ENV=production
ELOQUENT_DB_ROLE=migration

​
Cache environment keys

When APP_ENV=production, cache setup uses this fallback chain:
  1. Memcached
  2. file cache
  3. memory cache
Use these env keys: 
MEMCACHED_HOST=127.0.0.1
MEMCACHED_PORT=11211
CACHE_DIR=.cache
Defaults:
  • MEMCACHED_HOST defaults to 127.0.0.1
  • MEMCACHED_PORT defaults to 11211
  • CACHE_DIR defaults to .cache

​
Example SQL-first environment

DB_CONNECTION=sqlite
SQLITE_PATH=./database.sqlite
DB_TEST_CONNECTION=sqlite_test
SQLITE_TEST_PATH=./database.test.sqlite

​
Mongo example environment

DB_CONNECTION=mongo
MONGO_URI=mongodb://127.0.0.1:27017
MONGO_DB=eloquent_app
DB_TEST_CONNECTION=mongo_test
MONGO_TEST_URI=mongodb://127.0.0.1:27017
MONGO_TEST_DB=eloquent_app_test

​
Quick start

  1. Install the package and Express.js.
  2. Add the .env keys for your active driver.
  3. Register models at app startup.
  4. Generate and run migrations.
  5. Seed data and run a scenario check.
npm install @alpha.consultings/eloquent-orm.js express dotenv
eloquent make:model User --with-migration
eloquent make:service User
eloquent make:controller User
eloquent migrate:run --all-migrations
eloquent db:seed --class UserSeeder
Quick .env minimum for a SQLite start: 
DB_CONNECTION=sqlite
DB_TEST_CONNECTION=sqlite_test
SQLITE_PATH=./storage/app.sqlite
SQLITE_TEST_PATH=./storage/app.test.sqlite

​
Runtime bootstrap example

This ORM runtime is designed to work smoothly with Express.js in HTTP applications. If your app exposes routes, keep Express.js at runtime; examples assume this setup. 
import { registerModels } from "@alpha.consultings/eloquent-orm.js";
import { User } from "./app/models/User";

registerModels([User]);
For explicit model base classes: 
import { registerModels, column } from "@alpha.consultings/eloquent-orm.js";
import { SqlModel, MongoModel, type ModelInstance } from "@alpha.consultings/eloquent-orm.js/Model";
Use SqlModel for SQL-backed models and MongoModel for Mongo-backed models. Example SQL model: 
import { registerModels, column } from "@alpha.consultings/eloquent-orm.js";
import { SqlModel, type ModelInstance } from "@alpha.consultings/eloquent-orm.js/Model";

type UserAttrs = {
  id?: number;
  name?: string;
};

export class User extends SqlModel<UserAttrs> {
  static tableName = "users";
  static connectionName = process.env.DB_CONNECTION ?? "sqlite";
  static schema = {
    id: column("increments", undefined, { primary: true }),
    name: column("string", 255),
  };

  constructor() {
    super("users", process.env.DB_CONNECTION ?? "sqlite");
  }
}

export interface User extends ModelInstance<UserAttrs> {}

registerModels([User]);

​
First runtime test

const user = new User();
user.fill({ name: "Alice", email: "alice@example.com" });
await user.save();
const stored = await User.findOneBy("email", "alice@example.com");
console.log(stored?.toJSON());

​
Verify your installation

npm run build
npx eloquent --help

​
Where to go next