Databases
sql.model.definition
import sql.model.definition
Zuri
sqllifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelledsql.model.definition.*needsimport sql.model.definition.
Describes a model: its table, its columns, how its values are cast and checked, what it's associated with, and which hooks it has.
Most of this comes from the model's class. Every field the class
declares that doesn't start with _ is a column with the same name,
which is read and written as that field. The rest is described in a
static define() method, which is passed a Definition to describe the
model with:
class Post < Model {
var id
var title
var author_id
var author
static define(model: Definition) {
model.belongs_to('author', Author)
model.validate('title', validate.required().string().max_length(200))
}
}
Zuridefine() runs once, the first time the model is used, not when its
class is declared, so it can refer to a model that's declared later in
the same file. The definition is checked against the class at that
point. A definition that can't work, such as an association with no
field to hold it or a cast on a field that isn't a column, raises a
ModelError on that first use, instead of failing somewhere later.
Constants
BELONGS_TO
sql.model.BELONGS_TO = 'belongs_to'
ZuriA record holding the key of another, which it belongs to.
HAS_ONE
sql.model.HAS_ONE = 'has_one'
ZuriA record that another holds the key of, one of at most.
HAS_MANY
sql.model.HAS_MANY = 'has_many'
ZuriA record that others hold the key of, any number of them.
BELONGS_TO_MANY
sql.model.BELONGS_TO_MANY = 'belongs_to_many'
ZuriRecords joined to others through a table holding both keys.
HOOKS
sql.model.HOOKS = [...]
ZuriThe methods a model overrides to run code around its own life. Each is
called with the connection or transaction the record is being saved or
deleted through, except after_load(), called as a record is built from
a row.
Functions
definition_of()
sql.model.definition_of(model) -> Definition
ZuriThe definition of model, made the first time it is asked for and kept
from then on.
Making it builds one record of the class, with no arguments, to be sure
it is a model, then runs its define() when it has one.
Parameters
model(class)
Returns Definition
Raises ModelError if model is not a class extending Model, or
its definition cannot work.
Classes
Association
class sql.model.Association
ZuriOne association of a model.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
name |
string |
The association's name, which is also the field its records are loaded into. |
kind |
string |
One of BELONGS_TO, HAS_ONE, HAS_MANY and BELONGS_TO_MANY. |
model |
class |
The model on the other side. |
foreign_key |
string |
The column that holds the other side's key. |
key |
string|nil |
The column whose value the foreign key holds. |
through |
string|nil |
For BELONGS_TO_MANY, the join table. |
other_key |
string|nil |
For BELONGS_TO_MANY, the join table's column for the other model. |
Constructor
sql.model.Association(name, kind, model)
ZuriParameters
name(string)kind(string)model(class)
Association.is_many()
sql.model.Association.is_many() -> bool
ZuriWhether the association holds a list of records, as opposed to a single one.
Returns bool
Association.to_string()
sql.model.Association.to_string()
ZuriDefinition
class sql.model.Definition
ZuriA model's description: what define() is handed to write it on, and
what everything else reads once it is finished.
The methods a model calls in define() each return the definition, so
they can be chained, and each is checked against the class when the
definition is finished.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
model |
class |
The model's class. |
name |
string |
The model's class name. |
table_name |
string |
The table. |
primary |
The primary key's column. | |
columns |
list[string] |
The columns, in the order the class declares their fields. |
created_column |
The column stamped when a record is created, or nil. | |
updated_column |
The column stamped whenever a record is saved with a change, or nil. | |
casts |
dict |
The cast of each column that has one. |
validators |
dict |
The validate.Validator of each column that has one. |
uniques |
list[dict] |
The checks for values no other row may share, each { columns, message }. |
fillable_columns |
list[string] |
The columns fill() assigns. |
hidden_columns |
list[string] |
The columns left out of to_dict() and @to_json(). |
transient_fields |
list[string] |
The fields that are not columns. |
scopes |
dict |
The scopes, by name. |
associations |
dict |
The associations, by name. |
hooks |
dict |
Which hooks the model overrides, by name. |
schema |
The validators as one validate.Schema, or nil when there are none. |
|
transactional |
Whether saving and deleting run in a transaction of their own: when the model has hooks or unique checks,... |
Constructor
sql.model.Definition(model, name)
ZuriParameters
model(class)name(string)
Definition.table()
sql.model.Definition.table(name: string) -> Definition
ZuriNames the model's table, in place of the plural of its class name.
Parameters
name(string)
Returns Definition
Definition.primary_key()
sql.model.Definition.primary_key(column: string) -> Definition
ZuriNames the primary key's column, in place of id.
A model's key is one column. A table keyed by several, such as a join
table, is reached through belongs_to_many() or with SQL.
Parameters
column(string)
Returns Definition
Definition.timestamps()
sql.model.Definition.timestamps(created, updated) -> Definition
ZuriHas the model stamp a column with the time a record is created, and
another with the time it is saved with a change. Both are set as
date.Dates in UTC.
Parameters
created(string|nil) —created_atwhen nil.updated(string|nil) —updated_atwhen nil.
Returns Definition
Definition.cast()
sql.model.Definition.cast(column: string, kind: string) -> Definition
ZuriCasts a column's value as it is read, so the field holds the same type
on every engine. See the casts module for each cast.
model.cast('published', 'bool')
model.cast('settings', 'json')
ZuriParameters
column(string)kind(string) — One ofbool,integer,number,decimal,string,jsonanddate.
Returns Definition
Raises ModelError for any other kind.
Definition.validate()
sql.model.Definition.validate(column: string, rules) -> Definition
ZuriChecks a column's value with a validate chain before a record is
saved.
model.validate('email', validate.required().string().email())
ZuriParameters
column(string)rules(validate.Validator)
Returns Definition
Raises ModelError if the column already has rules.
Definition.unique()
sql.model.Definition.unique(columns, message) -> Definition
ZuriChecks, before a record is saved, that no other row has the same values
in columns. A record with nil in any of them isn't checked, because a
unique index allows any number of nulls.
A value that's already taken is reported as a validation failure, along with any others. Only a unique index in the database can stop two records saved at the same moment from taking the same value, so keep one there as well.
Parameters
columns(string|list[string])message(string|nil) — The message for people to read. If it's nil, the message isThe <column> field has already been taken.
Returns Definition
Definition.fillable()
sql.model.Definition.fillable(columns: list) -> Definition
ZuriThe columns fill() and building a record from a dictionary assign.
Every column but the primary key and the timestamps when this is not
called.
Parameters
columns(list[string])
Returns Definition
Definition.hidden()
sql.model.Definition.hidden(columns: list) -> Definition
ZuriColumns left out of to_dict() and @to_json(), such as a password's
hash, so a record handed to a response does not carry them.
Parameters
columns(list[string])
Returns Definition
Definition.transient()
sql.model.Definition.transient(fields: list) -> Definition
ZuriFields of the class that are not columns: values a record works with that the table does not hold.
Parameters
fields(list[string])
Returns Definition
Definition.scope()
sql.model.Definition.scope(name: string, body: function) -> Definition
ZuriA reusable piece of a query, applied with Query.scope().
model.scope('published', (query, _) => query.where({ published: true }))
model.scope('by', (query, author) => query.where({ author_id: author.id }))
ZuriParameters
name(string)body(function) — Called with the query and the argument given toscope(), and returns the query to use.
Returns Definition
Definition.belongs_to()
sql.model.Definition.belongs_to(name: string, model, options) -> Definition
ZuriThis model holds the key of another model that it belongs to. For example, a post belongs to its author.
model.belongs_to('author', Author)
ZuriParameters
name(string) — The name of the association, and of the field it's loaded into.model(class)options(dict|nil) —foreign_key, the column of this model that holds the key, which defaults to<name>_id, andowner_key, the column of the other model whose value it holds, which defaults to that model's primary key.
Returns Definition
Definition.has_one()
sql.model.Definition.has_one(name: string, model, options) -> Definition
ZuriAnother model holds this model's key, and there's at most one of it. For example, a user has one profile.
Parameters
name(string)model(class)options(dict|nil) —foreign_key, the column of the other model that holds this model's key, which defaults to this class's name in snake case followed by_id, andlocal_key, the column of this model whose value it holds, which defaults to the primary key.
Returns Definition
Definition.has_many()
sql.model.Definition.has_many(name: string, model, options) -> Definition
ZuriOther models hold this one's key, any number of them: an author has many posts.
Parameters
name(string)model(class)options(dict|nil) — Ashas_one()takes.
Returns Definition
Definition.belongs_to_many()
sql.model.Definition.belongs_to_many(name: string, model, options) -> Definition
ZuriRecords of this model and another model are joined through a table that holds both keys. For example, a post belongs to many tags, and a tag belongs to many posts.
Parameters
name(string)model(class)options(dict|nil) —through, the join table, which defaults to the two class names in snake case, in alphabetical order, joined by an underscore, as inpost_tag.foreign_key, the join table's column for this model's key, andother_key, its column for the other model's key, each default to the class name in snake case followed by_id.
Returns Definition
Definition.association()
sql.model.Definition.association(name: string) -> Association
ZuriThe association called name.
Parameters
name(string)
Returns Association
Raises ModelError if there is none.
Definition.has_hook()
sql.model.Definition.has_hook(name: string) -> bool
ZuriWhether the model overrides hook name.
Parameters
name(string)
Returns bool
Definition.finish()
sql.model.Definition.finish(info: dict, base: string)
ZuriChecks what define() described against the class, and works out the
rest. Called once, by definition_of().
Parameters
info(dict) —zuri.reflect.class_info()of the model.base(string) — The name of the class models extend.
Raises ModelError for a definition that cannot work.
Definition.build()
sql.model.Definition.build(row: dict) -> Model
ZuriBuilds a record from a row, as it would be after being loaded.
Parameters
row(dict) — Column to value.
Returns Model
Definition.load()
sql.model.Definition.load(record, row: dict)
ZuriGives record the values of row, cast, and marks it as holding what
the database holds.
Parameters
record(Model)row(dict)
Definition.saved()
sql.model.Definition.saved(record)
ZuriMarks record as holding what the database holds.
Parameters
record(Model)
Definition.values_of()
sql.model.Definition.values_of(record) -> dict
ZuriThe value of each column of record.
Parameters
record(Model)
Returns dict
Definition.snapshot()
sql.model.Definition.snapshot(record) -> dict
ZuriThe values of record, copied deep enough that changing a list or
dictionary in place still shows as a change against it.
Parameters
record(Model)
Returns dict
Definition.to_string()
sql.model.Definition.to_string()
Zuri2026, Richard Ore and Zuri contributors