Databases
sql.model.record
import sql.model.record
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.record.*needsimport 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
ZuriThe 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()
}
}
ZuriCalling 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(), soechoandprint()show something useful
Constructor
sql.model.Model(attributes)
ZuriParameters
attributes(dict|nil) — Assigned asfill()assigns them.
Model.before_validate()
sql.model.Model.before_validate(db)
ZuriCalled before the record is checked.
Parameters
db(Connection|Transaction)
Model.validate()
sql.model.Model.validate(errors)
ZuriCalled 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)
ZuriCalled after the record is checked.
Parameters
db(Connection|Transaction)
Model.before_save()
sql.model.Model.before_save(db)
ZuriCalled before the record is written.
Parameters
db(Connection|Transaction)
Model.after_save()
sql.model.Model.after_save(db)
ZuriCalled after the record is written.
Parameters
db(Connection|Transaction)
Model.before_create()
sql.model.Model.before_create(db)
ZuriCalled before a new record is inserted.
Parameters
db(Connection|Transaction)
Model.after_create()
sql.model.Model.after_create(db)
ZuriCalled after a new record is inserted, when it has its key.
Parameters
db(Connection|Transaction)
Model.before_update()
sql.model.Model.before_update(db)
ZuriCalled before a saved record's changes are written.
Parameters
db(Connection|Transaction)
Model.after_update()
sql.model.Model.after_update(db)
ZuriCalled after a saved record's changes are written.
Parameters
db(Connection|Transaction)
Model.before_delete()
sql.model.Model.before_delete(db)
ZuriCalled before the record is deleted.
Parameters
db(Connection|Transaction)
Model.after_delete()
sql.model.Model.after_delete(db)
ZuriCalled after the record is deleted.
Parameters
db(Connection|Transaction)
Model.after_load()
sql.model.Model.after_load()
ZuriCalled 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
ZuriWhether the record is in the database: loaded from it, or saved and not deleted since.
Returns bool
Model.key()
sql.model.Model.key() -> any
ZuriThe value of the record's primary key.
Returns any
Model.changes()
sql.model.Model.changes() -> dict
ZuriThe 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
ZuriWhether 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
ZuriA 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
ZuriAssigns 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'])
ZuriParameters
attributes(dict)only(list[string]|nil) — The keys to take fromattributes, 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
ZuriChecks 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]
ZuriWhat 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
ZuriSaves 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
ZuriDeletes 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
ZuriReads 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
ZuriLoads 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, ascomments.author.
Returns Model|list|nil
Model.related()
sql.model.Model.related(db, name: string) -> Query
ZuriA 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()
ZuriParameters
db(Connection|Transaction)name(string)
Returns Query
Model.attach()
sql.model.Model.attach(db, name: string, targets) -> number
ZuriJoins 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
ZuriUnlinks 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
ZuriMakes 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
ZuriThe 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()
Zuri2026, Richard Ore and Zuri contributors