The Zuri Standard Library Zuri

Databases

sql.model.definition

import sql.model.definition
Zuri

sql lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled sql.model.definition.* needs import 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))
  }
}
Zuri

define() 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'
Zuri

A record holding the key of another, which it belongs to.

HAS_ONE

sql.model.HAS_ONE = 'has_one'
Zuri

A record that another holds the key of, one of at most.

HAS_MANY

sql.model.HAS_MANY = 'has_many'
Zuri

A record that others hold the key of, any number of them.

BELONGS_TO_MANY

sql.model.BELONGS_TO_MANY = 'belongs_to_many'
Zuri

Records joined to others through a table holding both keys.

HOOKS

sql.model.HOOKS = [...]
Zuri

The 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
Zuri

The 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
Zuri

One association of a model.

  • printable — has a @to_string(), so echo and print() 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)
Zuri

Parameters

  • name (string)
  • kind (string)
  • model (class)

Association.is_many()

sql.model.Association.is_many() -> bool
Zuri

Whether the association holds a list of records, as opposed to a single one.

Returns bool

Association.to_string()

sql.model.Association.to_string()
Zuri

Definition

class sql.model.Definition
Zuri

A 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(), so echo and print() 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)
Zuri

Parameters

  • model (class)
  • name (string)

Definition.table()

sql.model.Definition.table(name: string) -> Definition
Zuri

Names 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
Zuri

Names 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
Zuri

Has 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_at when nil.
  • updated (string|nil) — updated_at when nil.

Returns Definition

Definition.cast()

sql.model.Definition.cast(column: string, kind: string) -> Definition
Zuri

Casts 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')
Zuri

Parameters

  • column (string)
  • kind (string) — One of bool, integer, number, decimal, string, json and date.

Returns Definition

Raises ModelError for any other kind.

Definition.validate()

sql.model.Definition.validate(column: string, rules) -> Definition
Zuri

Checks a column's value with a validate chain before a record is saved.

model.validate('email', validate.required().string().email())
Zuri

Parameters

  • column (string)
  • rules (validate.Validator)

Returns Definition

Raises ModelError if the column already has rules.

Definition.unique()

sql.model.Definition.unique(columns, message) -> Definition
Zuri

Checks, 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 is The <column> field has already been taken.

Returns Definition

Definition.fillable()

sql.model.Definition.fillable(columns: list) -> Definition
Zuri

The 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
Zuri

Columns 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
Zuri

Fields 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
Zuri

A 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 }))
Zuri

Parameters

  • name (string)
  • body (function) — Called with the query and the argument given to scope(), and returns the query to use.

Returns Definition

Definition.belongs_to()

sql.model.Definition.belongs_to(name: string, model, options) -> Definition
Zuri

This model holds the key of another model that it belongs to. For example, a post belongs to its author.

model.belongs_to('author', Author)
Zuri

Parameters

  • 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, and owner_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
Zuri

Another 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, and local_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
Zuri

Other models hold this one's key, any number of them: an author has many posts.

Parameters

  • name (string)
  • model (class)
  • options (dict|nil) — As has_one() takes.

Returns Definition

Definition.belongs_to_many()

sql.model.Definition.belongs_to_many(name: string, model, options) -> Definition
Zuri

Records 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 in post_tag. foreign_key, the join table's column for this model's key, and other_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
Zuri

The 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
Zuri

Whether the model overrides hook name.

Parameters

  • name (string)

Returns bool

Definition.finish()

sql.model.Definition.finish(info: dict, base: string)
Zuri

Checks 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
Zuri

Builds 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)
Zuri

Gives 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)
Zuri

Marks record as holding what the database holds.

Parameters

  • record (Model)

Definition.values_of()

sql.model.Definition.values_of(record) -> dict
Zuri

The value of each column of record.

Parameters

  • record (Model)

Returns dict

Definition.snapshot()

sql.model.Definition.snapshot(record) -> dict
Zuri

The 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()
Zuri

2026, Richard Ore and Zuri contributors