> ## Documentation Index
> Fetch the complete documentation index at: https://alphaconsultings.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

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

# Installation and Quick Start

Version: `1.3.0`

## Install

```bash theme={null}
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:

```bash theme={null}
npm install dotenv @faker-js/faker
```

## ESM and NodeNext imports

NodeNext and ESM apps can import the public runtime directly from the package root:

```ts theme={null}
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:

```bash theme={null}
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.

| Component  | Supported / tested version             |   |     |   |       |
| ---------- | -------------------------------------- | - | --- | - | ----- |
| Node.js    | \`^20                                  |   | ^22 |   | ^24\` |
| TypeScript | `^5.9.3`                               |   |     |   |       |
| MySQL      | `8.0`                                  |   |     |   |       |
| PostgreSQL | `16`                                   |   |     |   |       |
| MongoDB    | `7`                                    |   |     |   |       |
| SQLite     | `SQLite 3.x via better-sqlite3 12.2.0` |   |     |   |       |
| Memcached  | `1.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.

```env theme={null}
# 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:

```env theme={null}
# 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:

```env theme={null}
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

```env theme={null}
DB_CONNECTION=sqlite
SQLITE_PATH=./database.sqlite
DB_TEST_CONNECTION=sqlite_test
SQLITE_TEST_PATH=./database.test.sqlite
```

## Mongo example environment

```env theme={null}
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.

```bash theme={null}
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:

```env theme={null}
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.

```ts theme={null}
import { registerModels } from "@alpha.consultings/eloquent-orm.js";
import { User } from "./app/models/User";

registerModels([User]);
```

For explicit model base classes:

```ts theme={null}
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:

```ts theme={null}
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

```ts theme={null}
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

```bash theme={null}
npm run build
npx eloquent --help
```

## Where to go next

* [Quick start](./quick-start)
* [Usage guides](./usage-guides)
* [API reference](../api/reference)
* [NoSQL usage](../orm/nosql)