Defining Models
A MasterRecord entity is an ES class whose fields are methods. Each method receives the schema builder db and chains a type plus modifiers. MasterRecord reads these definitions to create tables, generate migrations, and track changes.
A basic entity#
// app/models/User.js
export default class User {
id(db) { db.integer().primary().auto(); }
name(db) { db.string().notNullable(); }
email(db) { db.string().notNullable().unique(); }
age(db) { db.integer(); } // nullable by default
is_active(db) { db.boolean().default(true); }
created_at(db) { db.datetime(); }
}name(db) { db.string(); }. A constructor assignment like this.name = { type: 'string' } is ignored— the builder reads the class prototype’s methods, so object-literal properties never reach the schema.Field types#
Every type below maps to a real column on all three engines. Call it as a builder method, e.g. db.datetime().
| Builder | PostgreSQL | MySQL | SQLite |
|---|---|---|---|
db.integer() | INTEGER | INT | INTEGER |
db.bigint() | BIGINT | BIGINT | INTEGER |
db.string() | VARCHAR(255) | VARCHAR(255) | TEXT |
db.text() | TEXT | TEXT | TEXT |
db.mediumtext() / longtext() | TEXT | MEDIUMTEXT / LONGTEXT | TEXT |
db.float() | REAL | FLOAT | REAL |
db.decimal() | DECIMAL | DECIMAL | REAL |
db.boolean() | BOOLEAN | TINYINT | INTEGER |
db.date() | DATE | DATE | TEXT |
db.time() | TIME | TIME | TEXT |
db.datetime() / timestamp() | TIMESTAMP | DATETIME / TIMESTAMP | TEXT |
db.json() | JSON | JSON | TEXT |
db.uuid() | UUID | VARCHAR(36) | TEXT |
db.binary() | BYTEA | BLOB | BLOB |
datetime, date, timestamp, float, decimal, bigint, json, uuid and binary arrived in MasterRecord 1.3.0.Modifiers#
Chain modifiers after the type to shape the column:
| Modifier | Effect |
|---|---|
.primary() | Marks the primary key (implies not-null + unique). |
.auto() | Auto-increment; the DB assigns the value on insert. |
.notNullable() | NOT NULL. (Columns are nullable by default.) |
.nullable() | Explicitly allow NULL. |
.unique() | Adds a UNIQUE constraint. |
.default(value) | Sets a default value. |
.index(name?) | Adds an index on the column. |
.set(fn) / .get(fn) | Transform values in / out of the database. See Transformers. |
Registering models in a context#
Models become queryable by registering them in a context with this.dbset(Model). Name the file after the class (AppContext.js) so the migration CLI can resolve it.
// app/models/AppContext.js
import context from 'masterrecord/context';
import User from './User.js';
import Post from './Post.js';
class AppContext extends context {
constructor() {
super();
this.env('config/environments'); // env.<NODE_ENV>.json
this.dbset(User);
this.dbset(Post);
}
}
export default AppContext;master generate model Comment body:text creates the entity and registers the dbset.Relationships & transformers#
Navigation properties like Posts(db) { db.hasMany('Post'); } and User(db) { db.belongsTo('User'); } declare associations — covered in Relationships. To (de)serialize complex values, use .set() / .get().