MasterRecord

Installation

Add the ORM and a database driver to your project.

MasterRecord is a pure-ESM package and requires Node.js 22.12+ (declared in engines since 1.31.0 — Node 20 is end-of-life). In a Master app it’s already installed in the backend/ workspace — this page is for adding it to any standalone Node project.

Install#

terminal

$ npm install masterrecord

MasterRecord bundles the drivers for all three engines (better-sqlite3, mysql2, and pg), so there is nothing else to install for SQLite, MySQL, or PostgreSQL. 1.31.0 requires better-sqlite3 13.0.3 or newer, which bundles SQLite 3.53.4.

npm lists better-sqlite3's install script

npm 12 (and npm 11.19+) blocks dependency install scripts by default and lists them after an install. better-sqlite3 13 ships prebuilt binaries for macOS, Linux (glibc and musl) and Windows on x64 and arm64, so SQLite loads without its script. Record the decision once with npm install-scripts deny better-sqlite3 — or approve it on a platform without a prebuilt binary, where it has to compile.

ESM only

Your project must be ESM. Add "type": "module" to your package.json and use import / export syntax throughout.

The migration CLI#

MasterRecord ships a masterrecord binary for migrations. Run it with npx, or through the Master CLI’s friendly master db wrapper:

terminal

$ npx masterrecord --help
$ # or, inside a Master app:
$ master db migrate

Verify#

Create a context, register a model, and run a query to confirm everything is wired up:

smoke-test.mjs

import context from 'masterrecord/context';

class Widget { id(db) { db.integer().primary().auto(); } name(db) { db.string(); } }
class AppContext extends context {
  constructor() {
    super();
    this.env({ type: 'better-sqlite3', connection: 'db/' });
    this.dbset(Widget);
  }
}

const db = new AppContext();
console.log('connected:', db.isSQLite); // true

Connecting a Database →

Configure SQLite, MySQL, or Postgres.

Defining Models →

Describe your schema as classes.