The Zuri Standard Library Zuri

Databases

sql.model.record

import sql.model.record
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.record.* needs import sql.model.record.

The class that every model extends, and what a record can do: save itself, delete itself, validate itself, and reach the records it's associated with.

A record never holds a connection. Every method that uses the database takes the connection or transaction to use, so a record loaded on one connection is saved on whichever connection the code saving it is using, including a transaction. A record kept after its connection was closed or returned to a pool can't write through it by accident.

Classes

Model

class sql.model.Model
Zuri

The class that a model extends.

class Post < Model {
  var id
  var title
  var published = false
  var created_at
  var updated_at

  static define(model: Definition) {
    model.timestamps()
    model.validate('title', validate.required().string().max_length(200))
  }

  before_save(db) {
    self.title = self.title.trim()
  }
}
Zuri

Calling the class creates a new record. If a dictionary of attributes is passed, they're assigned in the same way as fill() assigns them. Records loaded from the database are created in the same way, without arguments, so a model's own @new mustn't have required parameters, and it should call parent(attributes) if it takes attributes.

Hooks

A model can override any of these methods to run code at that point in a record's life. Each one is passed the connection or transaction the record is using. If a model has any hooks, saving and deleting run in a transaction, or in a savepoint inside one that's already open, so anything a hook writes is undone along with everything else if something fails. A hook can raise an error to stop the save or the delete.

Hook Runs
before_validate(db) before the record is validated
validate(errors) while it's validated, to add the model's own failures
after_validate(db) after it's validated, whatever the result
before_save(db) before it's written, whether it's new or not
before_create(db) before a new record is inserted
after_create(db) after it's inserted, when it has its key
before_update(db) before a saved record's changes are written
after_update(db) after the changes are written
after_save(db) after it's written, whether it's new or not
before_delete(db) before it's deleted
after_delete(db) after it's deleted
after_load() when a record is created from a row

A model's methods share a namespace with these hooks and with the methods below, so a model mustn't declare a method with the same name as one of them for any other purpose. A field can have the same name as any of them.

  • printable — has a @to_string(), so echo and print() show something useful

Constructor

sql.model.Model(attributes)
Zuri

Parameters

  • attributes (dict|nil) — Assigned as fill() assigns them.

Model.before_validate()

sql.model.Model.before_validate(db)
Zuri

Called before the record is checked.

Parameters

  • db (Connection|Transaction)

Model.validate()

sql.model.Model.validate(errors)
Zuri

Called as the record is checked, after its declared rules, to add failures of the model's own.

Parameters

  • errors (Errors)

Model.after_validate()

sql.model.Model.after_validate(db)
Zuri

Called after the record is checked.

Parameters

  • db (Connection|Transaction)

Model.before_save()

sql.model.Model.before_save(db)
Zuri

Called before the record is written.

Parameters

  • db (Connection|Transaction)

Model.after_save()

sql.model.Model.after_save(db)
Zuri

Called after the record is written.

Parameters

  • db (Connection|Transaction)

Model.before_create()

sql.model.Model.before_create(db)
Zuri

Called before a new record is inserted.

Parameters

  • db (Connection|Transaction)

Model.after_create()

sql.model.Model.after_create(db)
Zuri

Called after a new record is inserted, when it has its key.

Parameters

  • db (Connection|Transaction)

Model.before_update()

sql.model.Model.before_update(db)
Zuri

Called before a saved record's changes are written.

Parameters

  • db (Connection|Transaction)

Model.after_update()

sql.model.Model.after_update(db)
Zuri

Called after a saved record's changes are written.

Parameters

  • db (Connection|Transaction)

Model.before_delete()

sql.model.Model.before_delete(db)
Zuri

Called before the record is deleted.

Parameters

  • db (Connection|Transaction)

Model.after_delete()

sql.model.Model.after_delete(db)
Zuri

Called after the record is deleted.

Parameters

  • db (Connection|Transaction)

Model.after_load()

sql.model.Model.after_load()
Zuri

Called as a record is built from a row, once its fields hold the row's values.

Model.is_persisted()

sql.model.Model.is_persisted() -> bool
Zuri

Whether the record is in the database: loaded from it, or saved and not deleted since.

Returns bool

Model.key()

sql.model.Model.key() -> any
Zuri

The value of the record's primary key.

Returns any

Model.changes()

sql.model.Model.changes() -> dict
Zuri

The columns whose values differ from what the database last held, with their values now. For a record not yet saved, every column holding a value.

Returns dict

Model.is_dirty()

sql.model.Model.is_dirty(column) -> bool
Zuri

Whether a column, or any column, has changed since the database last held the record.

Parameters

  • column (string|nil) — Any column when nil.

Returns bool

Model.original()

sql.model.Model.original(column: string) -> any
Zuri

A column's value as the database last held it, or nil for a record not yet saved.

Parameters

  • column (string)

Returns any

Model.fill()

sql.model.Model.fill(attributes: dict, only) -> Model
Zuri

Assigns attributes from a dictionary, as a form or a request body supplies them.

Only fillable columns are assigned: those the model lists with fillable(), or every column but the primary key and the timestamps when it lists none. That is what keeps a request from setting a record's key, or a column it was never meant to reach.

post.fill(request.form(), ['title', 'body'])
Zuri

Parameters

  • attributes (dict)
  • only (list[string]|nil) — The keys to take from attributes, leaving the rest. Every key when nil.

Returns Model — The record, for chaining.

Raises ModelError for a key taken that is not fillable.

Model.is_valid()

sql.model.Model.is_valid(db) -> bool
Zuri

Checks the record: its declared rules, its unique columns, and its own validate().

Parameters

  • db (Connection|Transaction) — For the unique checks.

Returns bool — Whether it passed. errors() has what it found.

Model.errors()

sql.model.Model.errors() -> list[dict]
Zuri

What the last check found, each { field, message }. Empty before the record was ever checked.

Returns list[dict]

Model.save()

sql.model.Model.save(db) -> Model
Zuri

Saves the record: inserts it when it is new, writes its changes when it is not.

It is checked first, and not written when it fails. A new record leaves out every column still nil, so the database's default fills it, then reads those columns back, so the record holds what was stored. A record already saved writes only the columns that changed, and nothing at all when none did. A record held in a belongs_to association sets the column referring to it.

Parameters

  • db (Connection|Transaction)

Returns Model — The record.

Raises RecordInvalid if it fails its checks.

Raises ModelError if a record it belongs to has not been saved.

Model.delete()

sql.model.Model.delete(db) -> Model
Zuri

Deletes the record's row. The record keeps its values, and saving it again inserts it anew.

Parameters

  • db (Connection|Transaction)

Returns Model — The record.

Raises ModelError if the record was never saved.

Model.reload()

sql.model.Model.reload(db) -> Model
Zuri

Reads the record again from the database, discarding changes not saved and any associations loaded.

Parameters

  • db (Connection|Transaction)

Returns Model — The record.

Raises RecordNotFound if its row is gone.

Model.load()

sql.model.Model.load(db, name: string) -> Model|list|nil
Zuri

Loads an association into its field and returns what it loaded: a record or nil for belongs_to and has_one, a list for the rest.

Parameters

  • db (Connection|Transaction)
  • name (string) — Dotted to load what it loads, as comments.author.

Returns Model|list|nil

Model.related()

sql.model.Model.related(db, name: string) -> Query
Zuri

A query over the records that an association reaches, for narrowing them further instead of loading them all.

var drafts = author.related(db, 'posts').where({ published: false }).count()
Zuri

Parameters

  • db (Connection|Transaction)
  • name (string)

Returns Query

Model.attach()

sql.model.Model.attach(db, name: string, targets) -> number
Zuri

Joins records to this one through a belongs_to_many association's table. One already joined is left as it is.

Parameters

  • db (Connection|Transaction)
  • name (string)
  • targets (Model|any|list) — Records, keys, or a list of either.

Returns number — How many were joined.

Model.detach()

sql.model.Model.detach(db, name: string, targets) -> number
Zuri

Unlinks records from this one in a belongs_to_many association's join table.

Parameters

  • db (Connection|Transaction)
  • name (string)
  • targets (Model|any|list|nil) — Records, keys, or a list of either. If it's nil, every linked record is unlinked.

Returns number — The number of records unlinked.

Model.sync()

sql.model.Model.sync(db, name: string, targets: list) -> dict
Zuri

Makes the records joined to this one in a belongs_to_many association exactly targets, joining and separating as needed.

Parameters

  • db (Connection|Transaction)
  • name (string)
  • targets (list) — Records or keys.

Returns dict — { attached, detached }, the keys of each.

Model.to_dict()

sql.model.Model.to_dict() -> dict
Zuri

The record as a dictionary: every column but the hidden ones, and every association that has been loaded, as dictionaries in turn.

Returns dict

Model.to_string()

sql.model.Model.to_string()
Zuri

2026, Richard Ore and Zuri contributors