🥮 mooncakes.io

    moonbitstack/moonorm/session does not have a README file

    LostUpdate

    source
    pub(all) suberror LostUpdate {
      LostUpdate(String)
    }

    A lost update was detected: an optimistic-lock UPDATE matched no row because the row's version had already moved on since it was read. Raised by Session::modify_versioned.
    impl Show for LostUpdate

    LostUpdate::output

    source
    fn LostUpdate::output(self : LostUpdate, logger : &Logger) -> Unit

    LostUpdate::to_string

    source
    fn LostUpdate::to_string(self : LostUpdate) -> String

    HookContext

    source
    pub struct HookContext {
      event : HookEvent
      table : String
      columns : Array[(String, 
    Value    )]
      sql : String
      params : Array[
    Value    ]
    }

    What a listener is told. columns is the row the unit of work is about to write, as the model's to_columns projected it — and it is mutable, so a Before* hook can stamp a timestamp, normalise a value, or drop a column, and the flush renders what the hook left behind. For a delete it holds the primary key that addresses the row. sql and params carry the statement that ran, filled in for After* hooks and empty before it.

    HookContext::column

    source
    fn HookContext::column(self : HookContext, name : String) -> 
    Value    ?

    The value the row carries for name, or None.

    HookContext::new

    source
    fn HookContext::new(event : HookEvent, table? : String, columns? : Array[(String, 
    Value    )]) -> HookContext

    The context handed to one listener. Hooks outside a row-level statement — a flush or a transaction boundary — carry no table and no columns.

    HookContext::set_column

    source
    fn HookContext::set_column(self : HookContext, name : String, value : 
    Value    ) -> Unit

    Replace a column's value in the row being written, or append it when the row does not carry the column yet. This is how a BeforeInsert hook fills a column in — SQLAlchemy's idiom of setting an attribute on the instance in before_insert.

    HookContext::set_columns

    source
    fn HookContext::set_columns(self : HookContext, columns : Array[(String, 
    Value    )]) -> Unit

    Replace the whole row being written. A hook that wants to drop or reorder columns assigns a new array; set_column is the common case and edits in place.

    HookEvent

    source
    pub(all) enum HookEvent {
      BeforeInsert
      AfterInsert
      BeforeUpdate
      AfterUpdate
      BeforeDelete
      AfterDelete
      BeforeFlush
      AfterFlush
      BeforeCommit
      AfterCommit
      AfterRollback
    } derive(Eq)

    The point in the unit of work a listener fires at. The Before* write hooks see the row before it is rendered and may rewrite its columns; the After* hooks see the statement that ran. BeforeFlush / AfterFlush bracket the whole flush, and BeforeCommit / AfterCommit / AfterRollback bracket the transaction.

    The names follow SQLAlchemy's before_insert, after_insert and friends, which is why they are read as the phase they fire in rather than as statements.

    HookEvent::equal

    source
    fn HookEvent::equal(HookEvent, HookEvent) -> Bool

    HookEvent::not_equal

    source
    fn HookEvent::not_equal(x : HookEvent, y : HookEvent) -> Bool

    IsolationLevel

    source
    pub(all) enum IsolationLevel {
      ReadUncommitted
      ReadCommitted
      RepeatableRead
      Serializable
    } derive(Eq)

    A SQL transaction isolation level, in the four-rung ANSI ladder from weakest to strongest. Passed via TxOptions to Session::begin_with, which renders the backend's SET TRANSACTION (or SQLite PRAGMA) statement.

    IsolationLevel::equal

    source

    IsolationLevel::keyword

    source
    fn IsolationLevel::keyword(self : IsolationLevel) -> String

    The ANSI keyword for an isolation level ("READ COMMITTED", "SERIALIZABLE", …).

    IsolationLevel::not_equal

    source
    fn IsolationLevel::not_equal(x : IsolationLevel, y : IsolationLevel) -> Bool

    RowStream

    source
    pub struct RowStream[T] {
      cursor : &
    Cursor
      model : 
    Model    [T]
    }

    A typed streaming cursor: each next decodes one row into a record via the model. The record-level counterpart to [Session::stream], the streaming form of [fetch_as] (SQLAlchemy's yield_per).

    RowStream::close

    source
    fn[T] RowStream::close(self : RowStream[T]) -> Unit

    Release the underlying cursor early.

    RowStream::next

    source
    fn[T] RowStream::next(self : RowStream[T]) -> T? raise 
    DbError

    The next decoded record, or None once the result is exhausted.

    Savepoint

    source
    pub struct Savepoint {
      sess : Session
      name : String
      depth : Int
      finished : Bool
    }

    A nested transaction opened by Session::begin_nested, wrapping one SAVEPOINT whose name and depth the session tracks for you. It is the faithful equivalent of the object SQLAlchemy's Session.begin_nested() returns: finish it by release-ing (keep the work, merging it into the enclosing transaction) or rollback-ing (discard the work since the savepoint). Both are terminal and idempotent — calling either a second time is a no-op — and both decrement the session's savepoint depth.

    Savepoint::commit

    source

    The same as [release]: keeps the nested work, under the name a reader coming from COMMIT looks for.

    Savepoint::depth

    source
    fn Savepoint::depth(self : Savepoint) -> Int

    This savepoint's nesting depth (1 for the outermost begin_nested, 2 for one opened inside it, and so on).

    Savepoint::name

    source
    fn Savepoint::name(self : Savepoint) -> String

    The generated SQL name of this savepoint.

    Savepoint::release

    source
    fn Savepoint::release(self : Savepoint) -> Unit raise 
    DbError

    Release this savepoint (RELEASE SAVEPOINT <name>), keeping the work done since it opened and merging it into the enclosing transaction. Terminal and idempotent. The SQLAlchemy nested-transaction commit().

    Savepoint::rollback

    source
    fn Savepoint::rollback(self : Savepoint) -> Unit raise 
    DbError

    Roll back and close this savepoint, discarding everything done since it opened while leaving the enclosing transaction intact. It issues ROLLBACK TO SAVEPOINT followed by RELEASE SAVEPOINT, so — like SQLAlchemy's nested rollback() — the savepoint is terminal afterwards and the depth drops. Terminal and idempotent.

    Session

    source
    pub struct Session {
      driver : &
    Driver
      dialect : 
    Dialect
      sp_depth : Int
      sp_seq : Int
      id : Int
      pending : Array[Work]
      dirty : Array[Work]
      deleted : Array[Work]
      detach : Array[() -> Unit]
      hooks : Array[(HookEvent, (HookContext) -> Unit raise 
    DbError    )]
    }

    An explicit unit-of-work over a @moondb.Driver. Unlike SQLAlchemy's implicit autoflush and attribute-triggered SQL, every statement here is issued explicitly — the faithful MoonBit equivalent given the absence of attribute interception, exactly as Diesel and GORM also require. It holds the backend as a &@moondb.Driver trait object, so one Session type drives every backend.

    Session::add

    source

    Build and run an Insert now, returning the affected-row count and new rowid. This is the statement-level form: it goes to the driver on this call and never touches the unit of work. To queue a record instead and let flush order and emit it, use add_record.

    Rendered for the session's dialect, which is what decides between ON CONFLICT and ON DUPLICATE KEY UPDATE.

    Session::add_record

    source
    fn[T] Session::add_record(self : Session, model : 
    Model    [T], record : T) -> Unit

    Queue record for insertion — SQLAlchemy's Session.add. Nothing reaches the database until flush, or until commit flushes on the caller's behalf; the delay is what lets the flush order parents before children and register the row in the identity map. To insert on this call instead, use insert_record.

    Session::all

    source

    Fetch every row of a model's table, decoded into records (`SELECT FROM

    Session::begin

    source
    fn Session::begin(self : Session) -> Unit raise 
    DbError

    Begin an explicit transaction. Delegates to the driver's transaction bracket (@moondb.Driver::begin) rather than emitting BEGIN as text, so a driver that manages transactions out-of-band (or maps them to savepoints) stays in control.

    Session::begin_nested

    source

    Open a nested transaction — SAVEPOINT <auto-name> — and return a handle that tracks its name and depth, so callers never spell (or risk mis-spelling) a savepoint name. Nesting begin_nested inside another increases the depth; each handle's release/rollback brings it back down. This is the ergonomic, depth-tracked counterpart of the raw savepoint/rollback_to/release trio, mirroring SQLAlchemy's begin_nested().

    The generated name (moonorm_sp_<n>, n strictly increasing per session) is a bare identifier by construction, so it is injection-safe without a runtime check.

    Session::begin_with

    source
    fn Session::begin_with(self : Session, opts : TxOptions) -> Unit raise 
    DbError

    Begin a transaction with explicit isolation / read-only options. It brackets the driver's begin with the SET TRANSACTION (or PRAGMA) statements opts renders for the session's dialect, ordered so each backend accepts them: before BEGIN for MySQL and SQLite, after BEGIN for PostgreSQL (see TxOptions::to_sql). Commit or roll back with the usual commit/rollback.

    Session::close

    source
    fn Session::close(self : Session) -> Unit

    Close the session's underlying connection, dropping anything still queued and every record the identity map holds.

    Session::commit

    source
    fn Session::commit(self : Session) -> Unit raise 
    DbError

    Flush the unit of work, then commit the current transaction. Queued records reach the database here if nothing has flushed them yet, which is why a caller can add and commit without naming flush at all. With an empty queue this is the bare driver commit.

    BeforeCommit runs before the flush, so a listener sees the queue it is about to write; AfterCommit runs once the driver has committed.

    Session::create_table

    source

    Create the table backing model from its declared columns, then its indexes (see Model::create_table_sql and Model::create_indexes_sql). With if_not_exists=true the DDL is idempotent.

    Session::delete_record

    source
    fn[T] Session::delete_record(self : Session, model : 
    Model    [T], record : T) -> Unit raise 
    DbError

    Queue record for deletion — SQLAlchemy's Session.delete. The DELETE is keyed on the record's primary key and runs last, in the reverse dependency order, so a child row goes before the parent it points at. Flushing it also drops the record from the identity map.

    Raises QueryError when the model declares no primary key or the record does not carry one. To delete on this call instead, build a Delete and use remove.

    Session::deleted_count

    source
    fn Session::deleted_count(self : Session) -> Int

    How many records are queued for deletion — SQLAlchemy's Session.deleted.

    Session::dialect

    source

    The dialect this session renders its statements for.

    Session::dirty_count

    source
    fn Session::dirty_count(self : Session) -> Int

    How many records are queued for update — SQLAlchemy's Session.dirty.

    Session::execute

    source

    Execute a raw statement with bound params.

    Session::expunge

    source
    fn[T] Session::expunge(self : Session, model : 
    Model    [T], record : T) -> Unit

    Drop record from the identity map, so the next get reads the row back from the database and returns a fresh instance. SQLAlchemy's Session.expunge. Queued work for the record is left alone.

    Session::expunge_all

    source
    fn Session::expunge_all(self : Session) -> Unit

    Empty the identity map: every model this session has loaded through forgets it. SQLAlchemy's Session.expunge_all.

    Session::fetch

    source

    Build and run a Select, returning the matched rows.

    Session::fetch_as

    source

    Run a Select and decode every row into a T via model. Use it with a Model::select() (optionally refined with where_/order_by) to get records rather than raw Rows back.

    Session::flush

    source
    fn Session::flush(self : Session) -> Unit raise 
    DbError

    Emit every queued statement — SQLAlchemy's Session.flush, the point where the unit of work becomes SQL. Inserts go first in dependency order, so a parent row precedes any child that references it; then the updates; then the deletes in the reverse order, so a child goes before its parent. Nothing here commits.

    BeforeFlush runs once before the first statement and AfterFlush once after the last, which is where a listener that wants to see the whole batch registers.

    A statement that has run leaves the queue even when a later one raises, so the failed flush can be rolled back without replaying what already executed.

    Session::get

    source

    Fetch by primary key, consulting the identity map before the database — SQLAlchemy's Session.get. A row this session has already loaded comes back as the same record instance and costs no query; anything else is a SELECT … WHERE pk = ? LIMIT 1 whose result is decoded once and kept. None means there is no such row.

    Because the instance is shared, a record with mutable fields is shared too: two holders of the same row see each other's writes, which is the point of an identity map. expunge drops one; get_by takes a composite key.

    The map is scoped to this session and to the Model value passed in, so keep the model in a let — one rebuilt on every call is a new descriptor each time and carries no history.

    Session::get_by

    source

    get for a composite primary key: one value per declared key column, in declaration order. Raises QueryError when the model declares no primary key, or when key is not as wide as the one it declares.

    Session::insert_record

    source

    Insert a mapped record through its model now, binding the model's to_columns pairs. Returns the affected-row count and new rowid. Nothing is queued and the identity map is not consulted; add_record is the unit-of-work counterpart that defers to flush.

    A joined-table subclass is written as two statements here as well — the parent row first — because the subclass row's foreign key needs it. The Before*/After* insert hooks fire around the write exactly as they do at flush.

    Session::listener_count

    source
    fn Session::listener_count(self : Session, event : HookEvent) -> Int

    How many listeners are registered for event.

    Session::load

    source

    Eagerly load the related records of a 1:N relationship: given a source parent, run the relationship's query and decode every matching child into a record. This is the explicit stand-in for SQLAlchemy's transparent lazy load (parent.children firing a SELECT on attribute access) — MoonBit has no attribute interception, so the load is a call, exactly as Diesel and GORM require. The match value is bound, so eager loading stays injection-safe.

    Session::load_batch

    source

    Eagerly load a 1:N relationship for many sources in a single query, avoiding the N+1 problem. Naively calling load in a loop fires one SELECT per source; this instead issues one SELECT … WHERE key_column IN (all the source keys), then buckets the fetched children back to their parents in memory. The return is index-aligned with sources: result[i] is the list of children whose foreign key matches sources[i]'s key (empty if none). This is the explicit equivalent of SQLAlchemy's selectinload eager strategy.

    Children are matched to a source by comparing the child row's key_column value against the source's extracted key, so a source with no children yields an empty list and children are shared correctly when two sources happen to hold the same key. An empty sources returns an empty array without touching the database.

    Session::load_many

    source

    Eagerly load the related records of a many-to-many relationship: run the junction JOIN for source and decode every matching target row. The N:M counterpart of Session::load, and like it the source key is bound, so eager loading stays injection-safe.

    Session::load_many_batch

    source

    Eagerly load an N:M relationship for many sources in a single query, bucketing the fetched targets to their sources in memory. The counterpart of load_batch for a junction-table relation; strategy chooses an IN query or a JOIN. Returns an array index-aligned with sources.

    Session::load_one

    source

    Eagerly load the single related record of a N:1 relationship (e.g. a child's parent): the first matching row decoded into a record, or None if there is no match. Like load, the match value is bound.

    Session::load_one_batch

    source

    Eagerly load a N:1 relationship for many sources in a single query — the to-one counterpart of load_batch. One SELECT … WHERE key_column IN (…) fetches every distinct parent; the return is index-aligned with sources, result[i] being sources[i]'s parent (Some) or None when there is no match. Avoids the N+1 that a per-source load_one loop would incur.

    Session::modify

    source

    Build and run an Update, returning the affected-row count.

    Session::modify_versioned

    source
    fn Session::modify_versioned(self : Session, stmt : 
    Update    , what? : String) -> 
    ExecResult     raise

    Run a versioned UPDATE under optimistic concurrency control. stmt must carry the version predicate in its WHERE (e.g. where_(version_col, "=",expected)) and bump the version column in its SET. If the update matches no row the version has moved on since it was read — a lost update — and this raises LostUpdate instead of silently doing nothing, the faithful equivalent of SQLAlchemy's version_id_col StaleDataError. The whole statement is parameterised, so both the version guard and the new values stay bound.

    Session::new

    source

    Wrap a connected driver in a session. dialect is what the session renders its statements for, since a driver only takes SQL; it says SQLite unless told otherwise.

    Session::off_all

    source
    fn Session::off_all(self : Session) -> Unit

    Remove every listener, so a session can be reused with a fresh set of hooks.

    Session::on

    source
    fn Session::on(self : Session, event : HookEvent, handler : (HookContext) -> Unit raise 
    DbError    ) -> Unit

    Register a listener for event on this session. The listener runs for every statement of that kind this session emits; narrowing it to one table is a check on ctx.table, which is what a mapper-level listener in SQLAlchemy does by being registered on that mapper.

    Listeners run in registration order. A Before* listener that raises aborts the flush before the statement is sent; nothing already executed is replayed, so a rollback leaves the session where a failed flush would.

    Session::pending_count

    source
    fn Session::pending_count(self : Session) -> Int

    How many records are queued for insertion — SQLAlchemy's Session.new.

    Session::query

    source

    Run a raw query with bound params and return its rows.

    Session::query_stream

    source

    Stream a raw query's rows through a [@moondb.Cursor] instead of materialising them — the bounded-memory counterpart to [query] (SQLAlchemy's stream_results). This seam is synchronous, so only a synchronous driver with incremental fetch streams lazily here: moonsqlite steps its prepared statement row by row. A wire driver's cursor is async and cannot come through here at all — moonpostgres implements @moondb.AsyncDriver instead, so it never sits behind a Session; MySQL's synchronous adapter falls back to a materialised cursor. For lazy streaming over the wire call PgConn/MysqlConn::query_stream directly under an event loop.

    Session::release

    source

    Release a savepoint (RELEASE SAVEPOINT <name>), merging its work into the enclosing transaction (or savepoint). Rejects a non-identifier name.

    Session::remove

    source

    Build and run a Delete, returning the affected-row count.

    Session::rollback

    source
    fn Session::rollback(self : Session) -> Unit raise 
    DbError

    Roll back the current transaction, abandoning whatever is still queued and emptying the identity map. The records held there describe rows the rollback has just undone, so keeping them would hand out state the database no longer has. AfterRollback runs once the driver has rolled back.

    Session::rollback_to

    source

    Roll back to a savepoint (ROLLBACK TO SAVEPOINT <name>), undoing everything done since it was opened while keeping the savepoint (and the outer transaction) active. Rejects a non-identifier name with QueryError.

    Session::savepoint

    source

    Open a nested transaction with SAVEPOINT <name>. Savepoints nest arbitrarily, so this is the faithful equivalent of SQLAlchemy's Session.begin_nested(): work done after the savepoint can be undone with rollback_to(name) without discarding the enclosing transaction, and finalised with release(name).

    name must be a bare identifier (it is interpolated as an identifier, never a bound value); a non-identifier raises QueryError rather than reaching the database. The statement is issued through execute, so a backend that supports SQL savepoints (SQLite, Postgres) runs it verbatim.

    Session::savepoint_depth

    source
    fn Session::savepoint_depth(self : Session) -> Int

    How many nested savepoints opened via begin_nested are currently active.

    Session::stream

    source

    Build and stream a Select, yielding raw rows through a cursor.

    Session::stream_as

    source

    Build and stream a Select, decoding each row into a T on demand — the streaming counterpart to [fetch_as].

    Session::transaction

    source
    fn Session::transaction(self : Session, body : () -> Unit raise 
    DbError    ) -> Unit raise 
    DbError

    Run body inside one transaction: begin, run, commit; on failure roll back and re-raise what body raised, so the caller sees the real cause rather than the rollback's outcome.

    The driver's own begin/commit/rollback are used — not SQL text — so a driver that manages the transaction out of band stays in control. Nothing queued in the unit of work is flushed here: this brackets statements the caller issues.

    Session::update_record

    source
    fn[T] Session::update_record(self : Session, model : 
    Model    [T], record : T) -> Unit raise 
    DbError

    Queue record's current state as an UPDATE keyed on its primary key — the explicit stand-in for SQLAlchemy's dirty tracking, which notices a change by instrumenting attribute writes. MoonBit intercepts nothing, so a changed record is one the caller says is changed. The statement sets every non-key column, is emitted after the inserts, and refreshes the identity map.

    Raises QueryError when the model declares no primary key, when the record does not carry one, or when every column belongs to the key and there is nothing to set. To update on this call instead, build an Update and use modify.

    Session::with_pool

    source

    Run f with a Session on a connection borrowed from pool, returning the connection to the pool when f finishes or raises. The unit of work owns its transaction: commit or roll back inside f before it returns, since the connection is reused as-is.

    TxOptions

    source
    pub(all) struct TxOptions {
      isolation : IsolationLevel?
      read_only : Bool
    }

    Options for a transaction opened by Session::begin_with: an optional isolation level and a read_only flag. This is the explicit counterpart of SQLAlchemy's connection.execution_options(isolation_level=…) — a plain value the session renders into the backend's transaction-characteristics statement.

    TxOptions::default

    source
    fn TxOptions::default() -> TxOptions

    Transaction options with everything defaulted off (backend default isolation, read-write). Set what you need: { ..TxOptions::default(), isolation:Some(Serializable) }.

    TxOptions::to_sql

    source
    fn TxOptions::to_sql(self : TxOptions, dialect : 
    Dialect    ) -> Array[String]

    Render these options into the statements that impose them for dialect. On PostgreSQL and MySQL that is SET TRANSACTION ISOLATION LEVEL <level> and/or SETTRANSACTION READ ONLY; on SQLite, which has no such statement, it is PRAGMA read_uncommitted = 1 for the one weaker level it supports (every other level is SQLite's default serializable behaviour, so nothing is emitted) and PRAGMA query_only = 1 for read-only. An empty result means the backend's defaults already satisfy the options.

    Work

    source
    type Work

    One queued write: the table it writes, the tables that must be written before it, how to read the row's current columns, how to render the statements for those columns, and the identity bookkeeping to run once they have executed.

    The columns are re-read at flush time rather than captured at queue time, so the row written is the record's state at the flush — and so a Before* hook can rewrite it and have the statement follow.

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io