Databases
sql.model
import sql.model
Zuri
sqldoes not re-export this module, so it is reached only by importing it directly.
Rows as objects: a class for each table, records that save and validate themselves, and the associations between them.
A model is a class that extends Model. Its fields are its table's
columns, read and written by name, and a static define() method
describes the rest: the table, how values are cast and checked, and the
model's associations.
import sql
import sql.model { Definition, Model }
import validate
class Author < Model {
var id
var name
var posts
static define(model: Definition) {
model.has_many('posts', Post)
model.validate('name', validate.required().string().max_length(80))
}
}
class Post < Model {
var id
var author_id
var title
var published = false
var created_at
var updated_at
var author
static define(model: Definition) {
model.timestamps()
model.cast('published', 'bool')
model.belongs_to('author', Author)
}
}
var db = sql.open('app.db')
var ada = db.model(Author).create({ name: 'Ada' })
var post = Post({ title: 'On Engines', author_id: ada.id })
post.save(db)
for recent in db.model(Post).where({ published: false }).include('author').all() {
echo '${recent.title}, by ${recent.author.name}'
}
ZuriRecords and connections
db.model(Post) starts a Query on a connection or a transaction.
Every record method that uses the database takes the connection or
transaction to use, as in post.save(db) or post.delete(tx). A record
never holds a connection of its own, so it's saved inside whichever
transaction the code saving it opened, and a record kept after its
connection has gone back to a pool can't write through a connection that
now belongs to someone else.
Loading associations
Associations are only loaded when you ask for them, either with
include() on a query, which runs one query per association however
many records there are, or with load() on a record. Until then, a
field that holds an association is nil. Each query builds its own
records, so two queries that read the same row build two records for it,
and the two are == to each other.
Tables
A model maps a table that already exists. Use sql.migrate and
db.schema to create and change tables.
Submodules
| Module | Reached as | Summary |
|---|---|---|
sql.model.casts |
sql.model.casts.* |
Converts the values that an engine returns into the types that a model's fields hold. |
sql.model.definition |
sql.model.definition.* |
Describes a model: its table, its columns, how its values are cast and checked, what it's associated with,... |
sql.model.errors |
sql.model.errors.* |
The errors that the model layer raises, and the list of errors that a model's own checks add to. |
sql.model.naming |
sql.model.naming.* |
The names that a model uses when it doesn't specify its own. |
sql.model.query |
sql.model.query.* |
Reads and writes a model's rows as records, by conditions. |
sql.model.record |
sql.model.record.* |
The class that every model extends, and what a record can do: save itself, delete itself, validate itself,... |
Functions
query()
sql.model.query(db, model) -> Query
ZuriA query over model's rows on db. What db.model() returns.
Parameters
db(Connection|Transaction)model(class) — A class extendingModel.
Returns Query
Raises ModelError if model is not one, or its definition cannot
work.
2026, Richard Ore and Zuri contributors