Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

ORM: Getting Started

View as Markdownllms.txt

The ORM (object-relational mapper) is the part of Strutvane that turns database rows into TypeScript objects and back. Each table gets a model: a small class in app/models that knows how to find, create, update and delete rows of that table. You never write SQL for everyday work, and you never repeat your columns: the model reads them from your migrations.

Use the ORM whenever your own code (a controller, a seeder, a job) needs to read or change data. The generated CRUD API uses exactly the same models, so what you learn here also explains what the API does.

Say a migration created a posts table with title, slug, body, status, published_on, meta, author_id, timestamps and soft deletes (see Your First CRUD). This is a complete model for it:

app/models/post.ts
import { Model } from '@strutvane/framework'
export class Post extends Model('posts', {
fillable: ['title', 'body', 'status'],
}) {}

That’s all. The name 'posts' tells Strutvane which table this is, and from the generated types it knows every column, its type and whether it can be empty. fillable lists the columns people may set when creating or filling a post (see Mass Assignment).

Now use it. A post needs an author, so the smallest real example creates it through the author’s posts() relationship, which fills in author_id for you:

app/http/controllers/post.controller.ts (excerpt)
import { User } from '../../models/user.ts'
const ada = await User.findOrFail(1)
const post = await ada.posts().create({ title: 'Hello world', status: 'draft' })
console.log(post.id) // a number: the new row's key
console.log(post.slug) // filled in from the title
console.log(post.author_id) // set by the relationship
console.log(post.created_at) // a Date, set for you

What you’ll see:

1
hello-world
1
2026-11-14T09:30:00.000Z

The row is in the database, the slug was generated, the author was linked and both timestamps were set.

You never configure these; they follow from your migrations.

Thing Convention Where it comes from
Table the first argument of Model('posts') must be a table some migration created
Columns every column of that table, typed the generated .strutvane/types/models.d.ts
Primary key the column named id t.id() or t.uuid('id').primary() in the migration
Timestamps created_at and updated_at are filled in when both exist t.timestamps()
Soft deletes on when deleted_at exists t.softDeletes() (see Soft Deletes)
Slugs filled in on create t.slug('slug').from('title') (see Slugs)
Casts picked from each column’s type the migration (see Casts)
Migration The key is Who makes it
t.id() a growing whole number (1, 2, 3…) the database
t.uuid('id').primary() a UUIDv7 string like '019a8b2c-6a7f-7b12-9d6f-2f8a4e0c9c11' the ORM, before the insert

A UUIDv7 is a random-looking id that still sorts by creation time, so new rows land at the end of the index (fast inserts) and orderBy('id') is creation order. It’s also hard to guess, which makes it a good choice for ids in URLs. Laravel 13 uses the same kind by default.

A table without an id column can’t have a model (pivot tables like post_tag don’t need one). And the key of a saved row never changes; see Common mistakes.

Columns live only in migrations. When you add, rename or drop one, run node strut migrate: it regenerates the types, and every line of code that still uses an old name becomes a compile error. With Docker, the command runs inside the app container; the result is the same.

error TS2339: Property 'body' does not exist on type 'Post'.
You want Write You get
Every row await Post.all() Post[]
One row by its key await Post.find(1) Post or undefined
One row, or a 404 await Post.findOrFail(1) Post, or throws ModelNotFoundError
Rows that match await Post.where('status', 'published').get() Post[]
The first match await Post.query().where('status', 'draft').first() Post or undefined
The first match, or a 404 await Post.query().where('slug', slug).firstOrFail() Post
How many await Post.query().count() number
Whether any exist await Post.query().where('status', 'draft').exists() boolean
app/http/controllers/post.controller.ts (excerpt)
const post = await Post.findOrFail(1)
console.log(post.title, post.status)
// → Hello world draft
const drafts = await Post.where('status', 'draft').orderBy('created_at', 'desc').get()
console.log(drafts.map((p) => p.title))
// → [ 'Hello world' ]

Every column is a typed property: post.status is 'draft' | 'published', so if (post.status === 'archived') doesn’t compile. Lists are plain JavaScript arrays (see Collections). All the ways to filter, order and limit are in Querying.

To walk through thousands of rows without loading them all at once, page through them with a cursor:

app/jobs/send-digest.ts (excerpt)
let cursor: string | undefined
do {
const page = await Post.query().published().orderBy('id').cursorPaginate(100, cursor)
for (const post of page.data) {
// work on one post
}
cursor = page.nextCursor ?? undefined
} while (cursor !== undefined)

Memory stays flat, because only 100 posts are loaded at a time. See Pagination for how cursors work.

There are three ways, and all of them run the same checks.

1. Through a relationship, which also sets the foreign key (the safest way to set an owner):

const post = await ada.posts().create({ title: 'Second post', body: 'More words.', status: 'draft' })

2. In one step, with create(), when every required column is fillable or has a default:

const tag = await Tag.create({ name: 'news' })

3. In steps, with make(), then fill() or plain assignment, then save():

const post = Post.make() // a new, unsaved post
post.fill({ title: 'Third post' }) // from a request: only fillable columns
post.author_id = ada.id // your own code may set any column directly
await post.save() // INSERT
console.log(post.isPersisted()) // → true

When a row is inserted, Strutvane:

  1. stamps the active tenant on tenant tables (see Tenancy);
  2. generates the key when it’s a UUID;
  3. sets created_at and updated_at when the table has them;
  4. converts and checks every value (see Casts);
  5. fills empty slug columns from their source;
  6. reads the row back, so database defaults appear: post.status is 'draft' even when you didn’t send it.

For trusted data (seeders, imports, your own services), Post.forceCreate({...}) accepts every real column except the ones Strutvane manages. See Mass Assignment.

Change properties, then save(). Only the columns you changed are written, plus updated_at:

const post = await Post.findOrFail(1)
post.title = 'Hello again'
console.log(post.getDirty()) // → { title: 'Hello again' }
console.log(post.isDirty()) // → true
console.log(post.isDirty('status')) // → false
await post.save() // UPDATE posts SET title = ?, updated_at = ? WHERE id = ?
console.log(post.isDirty()) // → false

A dirty column is one you changed since the row was loaded or last saved. Calling save() with nothing dirty sends no query at all.

fill() works for updates too, with the same fillable rules as create():

post.fill({ status: 'published' })
await post.save()

To throw away unsaved changes and reload the row from the database, use await post.refresh().

const post = await Post.findOrFail(1)
await post.delete()

If the table has a deleted_at column (t.softDeletes() in the migration), delete() only hides the row so it can be restored; forceDelete() removes it for good. See Soft Deletes.

Pruning means deleting rows you no longer need on a schedule, like posts soft-deleted more than 30 days ago.

toJSON() gives you a plain object, ready to send; JSON.stringify(post) and ctx.json(post) call it for you. Dates become ISO strings, decimals stay exact strings, loaded relations and counts are nested in, and columns listed in hidden never appear (their keys are missing from the TypeScript type too):

app/models/user.ts
import { Model } from '@strutvane/framework'
export class User extends Model('users', {
fillable: ['name', 'email'],
hidden: ['password'],
}) {}
const json = (await User.findOrFail(1)).toJSON()
console.log(json)
// → { id: 1, name: 'Ada', email: 'ada@example.com', created_at: '2026-11-14T09:30:00.000Z', updated_at: '2026-11-14T09:30:00.000Z' }
json.password // compile error: Property 'password' does not exist

Everything about the output (each value type, relations, the JsonOf and generated PostJson types, and the coming visible and appends) is on Serialization.

The class body is yours. Add methods, getters (computed values), relations and scopes:

app/models/post.ts
import { Model, type Scopes } from '@strutvane/framework'
import { User } from './user.ts'
export class Post extends Model('posts', {
fillable: ['title', 'body', 'status', 'published_on'],
}) {
static readonly scopes = {
published: (query) => query.where('status', 'published'),
} satisfies Scopes<'posts'>
author() {
return this.belongsTo(User, 'author_id')
}
get isPublished(): boolean {
return this.status === 'published'
}
}
const posts = await Post.query().published().with('author').get()
console.log(posts[0]?.author?.name, posts[0]?.isPublished)
// → Ada true

A method or getter must not have the same name as a column (see Common mistakes).

A model event is a hook that runs when a model is created, updated, deleted or restored, like “send a welcome mail after a user is created”. An observer is a class that groups those hooks for one model. They follow Laravel’s names (creating, created, updating, updated, saving, saved, deleting, deleted, restoring, restored), and “after” events inside a transaction wait for the commit.

A few switches apply to the whole app. The framework sets them at boot; change them in a service provider:

app/providers/app.provider.ts (excerpt)
import { configureOrm } from '@strutvane/framework'
configureOrm({
maxPerPage: 200,
onUnsafeTenancy: (event) => console.warn('tenancy bypass', event), // send this to your audit log
})
Setting Default What it does
preventLazyLoading true, except when NODE_ENV=production refuses loading a relation one row at a time inside a list (the N+1 problem)
maxPerPage 100 the largest page paginate() and cursorPaginate() accept
tenancy from config/tenancy.ts: { column: 'tenant_id' } with teams, false without the one tenant column of the app, or false for a single-tenant app; set it in config/tenancy.ts, not here
onUnsafeTenancy does nothing called for every audited tenancy bypass; wire it to your audit log

Settings you don’t pass keep their values.

Strict mode means “fail loudly in development instead of quietly doing something slow or wrong”. Part of it is always on:

  • Unknown and non-fillable fields throw (Laravel’s preventSilentlyDiscardingAttributes), in every environment. See Mass Assignment.
  • Lazy loading inside a list throws LazyLoadingError outside production (preventLazyLoading). See Relationships.
  • Unknown column names throw with a “did you mean”, in where(), sort(), filter() and search().

To log or count the SQL your code sends (useful in tests and while debugging), listen on the connection:

tests/feature/post-list.test.ts (excerpt)
import { defaultConnection } from '@strutvane/framework'
let queries = 0
const stop = defaultConnection().onQuery((event) => {
queries += 1
console.log(event.sql, event.params, `${event.durationMs.toFixed(1)} ms`)
})
await Post.query().with('author').get()
stop()
console.log(queries) // → 2

onQuery() returns a function that stops listening. Parameters are included for debugging; never write them to a log without redaction, because they can contain personal data.

The ORM behaves the same on MySQL 8.4+ (the default), PostgreSQL and SQLite: the spike behind it runs every test on all three. Where the engines differ, the ORM smooths it over:

  • Booleans: MySQL and SQLite store 0/1; you always get true/false.
  • Decimals: SQLite stores them as floats; you always get an exact string like '10.50'.
  • Text length: SQLite ignores VARCHAR(200); the ORM enforces the length everywhere.
  • Dates: stored and read in UTC on every engine.
  • Inserts: MySQL has no RETURNING, so the row is read back by key (one extra query).
  • Case and accents: MySQL’s default collation treats 'résumé' and 'resume' as equal. Identifier-like columns (email, slug, uuid, enum, tokens) are designed to use a byte-for-byte collation on MySQL (coming in 0.2: the ORM was tested with it, the migration recorder doesn’t write it yet); normalise emails with a cast meanwhile (see Casts).
ModelNotFoundError: No row in "posts" with key 99. It may not exist, may be soft-deleted, or may belong to another tenant.

Why: findOrFail() (and firstOrFail()) throw when nothing matches. In a controller this becomes a 404 response, which is usually what you want.

Fix: when “not found” is a normal case, use find() and check for undefined:

const post = await Post.find(99)
if (post === undefined) {
// show a friendly message instead
}

“Did you mean …?” when creating a row

Section titled ““Did you mean …?” when creating a row”
MassAssignmentError: "posts" has no column "titel". Did you mean "title"? Columns come from your migrations: add one with a new migration, then run `node strut migrate`.

Why: the column doesn’t exist (here, a typo). Strutvane refuses unknown fields instead of silently dropping them.

Fix: use the real column name. If the column is new, add it in a migration and run node strut migrate, which regenerates the types.

“The table … is not in the schema snapshot”

Section titled ““The table … is not in the schema snapshot””
OrmUsageError: The table "post" is not in the schema snapshot. Did you create it in a migration and run `node strut migrate`?

Why: the name in Model('post') doesn’t match a table (tables are plural), or the migration hasn’t run yet.

Fix: use the table name from the migration (Model('posts')) and run node strut migrate.

OrmUsageError: "post_tag" has no "id" column. Models need t.id() (or t.uuid('id').primary()) in the migration; pivot tables don't need a model.

Fix: add t.id() in the migration, or don’t write a model for a pivot table: use belongsToMany() instead.

A column with the same name as a model method

Section titled “A column with the same name as a model method”
OrmUsageError: "posts.save" has the same name as the model method save(). Rename the column in a new migration.

Why: columns become properties of the model, so a column called save, delete or fill would hide the method.

Fix: rename the column in a new migration (t.renameColumn('save', 'saved_flag')).

OrmUsageError: Can't delete() a "posts" row that was never saved. Call save() first.

Why: Post.make() builds an object that isn’t in the database yet.

Fix: call await post.save() first, or use create(), which saves in one step.

OrmUsageError: The primary key of a saved "posts" row can't change. Create a new row instead.

Why: the key is how every other table points at this row. Changing it would break those links.

Fix: create a new row and delete the old one if you need to.

A database error about author_id when creating a post

Section titled “A database error about author_id when creating a post”

Why: author_id is required but isn’t in fillable (on purpose: users must not pick the author), so Post.create({ title }) leaves it empty and the database refuses the row.

Fix: create the post through the relationship, user.posts().create({...}), or set post.author_id = user.id in your own code before save().