Skip to content

Models and fields

A model is the single source of truth about a piece of data: its fields, their types and validation, and its behaviour. Each model maps to one database table. Ghuri’s models work like Django’s, with a syntax adapted so TypeScript can infer every field type.

src/blog/models.ts
import {
Model, CharField, SlugField, TextField, BooleanField, DateTimeField, PositiveIntegerField,
ForeignKey, ManyToManyField, CASCADE, Manager, MinLengthValidator,
} from '@ghuri/orm'
import { User } from '@ghuri/auth'
export class Post extends Model({
title: new CharField({ maxLength: 200, validators: [new MinLengthValidator(3)] }),
slug: new SlugField({ unique: true }),
body: new TextField({ blank: true }),
status: new CharField({
maxLength: 10,
choices: [['draft', 'Draft'], ['review', 'In review'], ['live', 'Published']],
default: 'draft',
}),
views: new PositiveIntegerField({ default: 0 }),
author: new ForeignKey(() => User, { onDelete: CASCADE, relatedName: 'posts' }),
tags: new ManyToManyField(() => Tag, { blank: true, relatedName: 'posts' }), // Tag is defined elsewhere in this file
createdAt: new DateTimeField({ autoNowAdd: true }),
updatedAt: new DateTimeField({ autoNow: true }),
}) {
static Meta = {
ordering: ['-createdAt'],
verboseNamePlural: 'posts',
indexes: [{ fields: ['status', 'createdAt'] }],
}
declare static objects: Manager<Post>
toString() {
return this.title
}
get isLive() {
return this.status === 'live'
}
}

Model(fields) returns a base class built from the field definitions. You extend it to add Meta, methods, getters and custom managers. Because the fields are a value rather than a set of class property declarations, TypeScript can infer the instance type:

Field Instance property type
CharField, TextField, SlugField, EmailField, URLField, UUIDField string
IntegerField and friends, FloatField, DurationField (ms) number
DecimalField string (exact; never a float)
BooleanField boolean
DateTimeField Date
DateField, TimeField string ('YYYY-MM-DD', 'HH:MM:SS')
JSONField any (or the type parameter: new JSONField<Settings>())
any field with null: true T | null
ForeignKey named author authorId: number plus author (User | PromiseLike<User>: await it, or read it directly once loaded)
ManyToManyField a related manager

Every model gets an implicit id: new BigAutoField({ primaryKey: true }) unless a field sets primaryKey: true. instance.pk is an alias for whichever field is the primary key.

declare static objects: Manager<Post> is what makes Post.objects.get() return a Post (with your methods and getters). Without it, results are typed from the fields only. Reverse relations are created at runtime when the other model is registered, so declare them for TypeScript too. Always use declare (not a class field with an initializer) for these extra typings:

import { type Manager, type RelatedManager } from '@ghuri/orm'
export class Post extends Model({ /* ... */ }) {
declare static objects: Manager<Post>
declare comments: RelatedManager<Comment> // from Comment.post's relatedName: 'comments'
}

BaseModel is the real root class. Use it for instanceof checks and in generic code: function describe(obj: BaseModel) { return obj._meta.label }.

These options work on every field type. The full list per field is in the field reference.

Option Meaning
null Store empty values as NULL. Default false.
blank Allow empty values in validation (forms, serializers, admin). Default false.
default A value, or a function called for each new instance (default: () => crypto.randomUUID()).
dbDefault A default computed by the database (DEFAULT clause).
choices [value, label][], or an enum-like object. Validated, and shown as a select in the admin.
primaryKey Make this the primary key.
unique Add a unique constraint.
dbIndex Add an index.
dbColumn Override the column name.
editable false hides the field from the admin and from ModelSerializer writes.
verboseName, helpText Labels and help text for the admin and OpenAPI schema.
validators Extra validators run by fullClean().
errorMessages Override messages by code, e.g. { unique: 'That slug is taken.' }.

As in Django, null is about the database and blank is about validation. For text fields, prefer blank: true, default: '' to null: true, so there is only one “empty” value.

Option Meaning
dbTable Table name. Default ${appLabel}_${modelname}, e.g. blog_post.
ordering Default ordering for QuerySets: ['-createdAt', 'title'].
verboseName, verboseNamePlural Human-readable names.
uniqueTogether [['author', 'slug']].
indexes [{ fields: ['status', 'createdAt'], name?: 'post_status_idx' }].
constraints Check and unique constraints.
abstract Make an abstract base model (no table).
permissions Extra permissions: [['publish_post', 'Can publish posts']].
defaultPermissions Default ['add', 'change', 'delete', 'view'].
getLatestBy Field used by latest() / earliest().
appLabel Override the app the model belongs to.
managed false means Ghuri never creates, alters or flushes the table (migrations still track the model’s state). Default true.
defaultManagerName Manager used by related lookups and internals. Default objects.
swappable Name of the setting that can replace this model, like auth.User’s 'AUTH_USER_MODEL'. See Swappable models.

Indexes are { fields, name?, unique?, condition? }, where condition is a raw SQL WHERE clause for a partial index and a leading - in fields makes that column descending. Constraints are { type: 'unique', fields, name, condition? } or { type: 'check', check: 'price >= 0', name }:

static Meta = {
indexes: [{ fields: ['-createdAt', 'status'], name: 'post_recent_idx' }],
constraints: [
{ type: 'unique', fields: ['author', 'slug'], name: 'post_author_slug_uniq' },
{ type: 'check', check: 'views >= 0', name: 'post_views_gte_0' },
],
}

A model gets its app label (and so its table name, blog_post) from the app that lists it:

src/blog/app.ts
import { AppConfig } from '@ghuri/core'
import * as models from './models'
export class BlogConfig extends AppConfig {
name = 'blog'
models = models
}

Outside INSTALLED_APPS (scripts, tests), set Meta.appLabel or call registerModels('blog', models). Reverse relations only exist once the model declaring the foreign key is registered. To build a model class at runtime, use createModelClass('Post', fields, { meta, registry }); this is what migrations use for historical models, with an isolated new ModelRegistry({ isolated: true }).

Post._meta exposes the model’s structure. It is a stable, public API that the admin, the REST framework, the agents package and the CLI are built on, and you can use it for generic code:

Post._meta.label // 'blog.Post'
Post._meta.dbTable // 'blog_post'
Post._meta.pk.name // 'id'
Post._meta.getField('title').maxLength // 200
Post._meta.fields.map((f) => f.name)
Post._meta.relatedObjects // reverse relations, e.g. comments

Share fields between models with an abstract model:

export class Timestamped extends Model({
createdAt: new DateTimeField({ autoNowAdd: true }),
updatedAt: new DateTimeField({ autoNow: true }),
}) {
static Meta = { abstract: true }
}
export class Page extends Model(
{ title: new CharField({ maxLength: 200 }), body: new TextField() },
{ extends: Timestamped },
) {}

Page gets createdAt and updatedAt and its own table; Timestamped has no table. You can also spread fields: Model({ ...Timestamped.fields, title: ... }). Multi-table inheritance and proxy models are not supported in 0.1.

A reusable app can let projects replace one of its models, the way AUTH_USER_MODEL replaces auth.User. The model names a setting in Meta.swappable; a dotted name reads a nested setting:

export class Conversation extends Model({ ...conversationFields }) {
static Meta = { appLabel: 'agents', swappable: 'AGENTS.CONVERSATION_MODEL' }
}

While the setting is unset (or names the model itself), nothing changes. When it names another model (AGENTS: { CONVERSATION_MODEL: 'shop.Conversation' }), the built-in model is swapped:

  • Conversation._meta.swapped is 'shop.Conversation' (otherwise undefined).
  • It is not installed: apps.getModels() and the migration autodetector skip it, and it gets no table. Its migration operations are skipped too (see Swappable models in migrations).
  • Its managers throw Manager isn't available; 'agents.Conversation' has been swapped for 'shop.Conversation', and its relations are not reverse relations of their targets.

Code that should follow the setting asks for the model instead of importing it:

import { getSwappableModel } from '@ghuri/orm'
const Conversation = getSwappableModel('AGENTS.CONVERSATION_MODEL', 'agents.Conversation')
new ForeignKey(() => getSwappableModel('AGENTS.CONVERSATION_MODEL', 'agents.Conversation'), { … })

getSwappableModel(setting, default) throws ImproperlyConfigured when the setting is not 'app_label.ModelName' or names a model that is not installed. Packages usually wrap it, like getUserModel() in @ghuri/auth and getConversationModel() in @ghuri/agents.

Set a swappable setting before the first migrate. The replacement must not be created in a migration that depends on the app it replaces. Changing it on a database that already has the tables needs a hand-written migration; see the agents example in Your own conversation model.

Post.objects is the default manager, the entry point for queries. Add your own for common filters:

import { Manager } from '@ghuri/orm'
class LiveManager extends Manager<Post> {
getQueryset() {
return super.getQueryset().filter({ status: 'live' })
}
byTag(name: string) {
return this.getQueryset().filter({ tags__name: name })
}
}
export class Post extends Model({ /* ... */ }) {
declare static objects: Manager<Post>
static live = new LiveManager()
}
await Post.live.byTag('typescript').count()

objects always exists, and extra managers are static properties. To change the default manager’s behaviour, assign your own: static objects = new PostManager(). Unlike Django, the default manager (used for related lookups) is always objects unless you set Meta.defaultManagerName.

const post = new Post({ title: 'Hi', slug: 'hi', authorId: 1 })
await post.save() // INSERT
post.title = 'Hello'
await post.save({ updateFields: ['title'] }) // UPDATE only that column
await post.refreshFromDb() // or refreshFromDb({ fields: ['title'] })
await post.delete() // [total, { 'blog.Post': 1, 'blog.Comment': 3 }]

save() also accepts { forceInsert, forceUpdate, using }. delete() runs the onDelete rules of every foreign key pointing at the object, sends delete signals and returns the number of deleted rows, in total and per model.

save() does not validate. Call fullClean() first when data comes from users (the admin and ModelSerializer do this for you). It runs field validation, choices, your clean() method, foreign-key existence checks and uniqueness checks (unique, uniqueTogether, unique constraints) against the database, and throws ValidationError with a messageDict. fullClean({ exclude: ['slug'], validateUnique: false }) narrows it:

import { ValidationError } from '@ghuri/core'
export class Post extends Model({ /* ... */ }) {
clean() {
if (this.status === 'live' && !this.body) {
throw new ValidationError({ body: ['A published post needs a body.'] })
}
}
}
try {
await post.fullClean()
} catch (e) {
if (e instanceof ValidationError) console.log(e.messageDict)
}

Override save() to add behaviour, and call super.save():

async save(opts?: { updateFields?: string[] }) {
if (!this.slug) this.slug = this.title.toLowerCase().replace(/[^a-z0-9]+/g, '-')
await super.save(opts)
}

When the database itself rejects a write, the error is normalised across backends: IntegrityError (unique, foreign key, NOT NULL or check violations), NotSupportedError, or the base DatabaseError, all exported from @ghuri/orm. Deletes refused by onDelete raise ProtectedError or RestrictedError; an unknown field in a query raises FieldError.

For behaviour that should run for every save including bulkCreate, prefer signals or explicit service functions; like Django, bulk operations do not call save().

instance.toJSON() returns a plain object of concrete field values (foreign keys as their ...Id), so JSON.stringify(post) and json(c, post) work. For API output with control over fields and relations, use a serializer.

QuerySets compile to SQL with the ORM’s own builder (qs.toSQL() returns { sql, params }), but each model also has a generated Drizzle table, for queries the ORM cannot express:

import { getDrizzle } from '@ghuri/orm'
import { sql } from 'drizzle-orm'
const db = await getDrizzle()
const posts = Post.table()
const rows = await db.select({ day: sql`date(${posts.createdAt})`, n: sql`count(*)` })
.from(posts).groupBy(sql`1`)

Post.table() uses the dialect of the default database; getTable(Post, 'postgresql') and getSchema([Post, Comment], dialect) (keyed by class name, including auto-created many-to-many tables) build tables for a given dialect, and field.drizzleColumn(dialect) builds a single column. Drizzle columns are keyed by attribute name (posts.createdAt, posts.authorId), and values are converted the same way the ORM converts them.

Code written this way is dialect-specific when it uses raw SQL, so keep it in one place.