The Zuri Standard Library Zuri

Databases

sql.model

import sql.model
Zuri

sql does 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}'
}
Zuri

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

A query over model's rows on db. What db.model() returns.

Parameters

  • db (Connection|Transaction)
  • model (class) — A class extending Model.

Returns Query

Raises ModelError if model is not one, or its definition cannot work.


2026, Richard Ore and Zuri contributors