🥮 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

    AsyncRowStream

    source

    A typed asynchronous streaming cursor: each next awaits one row off the wire and decodes it via the model. The record-level counterpart to [AsyncSession::stream].

    AsyncRowStream::close

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

    Release the underlying cursor early.

    AsyncRowStream::next

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

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

    AsyncSavepoint

    source
    pub struct AsyncSavepoint {
      sess : AsyncSession
      name : String
      depth : Int
      finished : Bool
    }

    A nested transaction opened by AsyncSession::begin_nested, wrapping one SAVEPOINT whose name and depth the session tracks. Finish it by release-ing (keep the work) or rollback-ing (discard the work since the savepoint, in the database and in the session's own state). Both are terminal and idempotent.

    AsyncSavepoint::commit

    source

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

    AsyncSavepoint::depth

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

    This savepoint's nesting depth (1 for the outermost begin_nested).

    AsyncSavepoint::name

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

    The generated SQL name of this savepoint.

    AsyncSavepoint::release

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

    Release this savepoint, keeping the work done since it opened. Terminal and idempotent.

    AsyncSavepoint::rollback

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

    Roll back and close this savepoint, discarding everything done since it opened — the database rows and the session's queued writes and identity map together — while leaving the enclosing transaction intact. Terminal and idempotent.

    AsyncSession

    source

    An explicit unit of work over an @moondb.AsyncDriver — [Session] with every call awaited.

    One session is one connection, so it runs one statement at a time; concurrency comes from running several sessions at once, which is exactly what with_pool is for. Nothing is shared between two sessions except the models they were built from, and each keeps its own identity map.

    AsyncSession::add

    source

    Build and run an Insert now, returning the affected-row count and new rowid. The statement-level form: it never touches the unit of work.

    AsyncSession::add_all

    source
    fn[T] AsyncSession::add_all(self : AsyncSession, model : 
    Model    [T], records : Array[T]) -> Unit

    Queue every record in records for insertion.

    AsyncSession::add_record

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

    Queue record for insertion — the awaited [Session::add_record]: nothing reaches the database until flush or commit.

    AsyncSession::all

    source

    Fetch every row of a model's table, decoded into records.

    AsyncSession::begin

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

    Begin an explicit transaction through the driver's own bracket, so a backend that tracks transactions out of band stays in control.

    AsyncSession::begin_nested

    source

    Open a nested transaction with an auto-generated name and return its handle — the awaited counterpart of [Session::begin_nested], with the same depth tracking and the same session-state rollback.

    AsyncSession::begin_with

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

    Begin a transaction with explicit isolation / read-only options, ordered for the session's dialect exactly as [Session::begin_with] does. The statements that undo a connection-level option run when commit or rollback ends the transaction.

    AsyncSession::close

    source
    async fn AsyncSession::close(self : AsyncSession) -> Unit noraise

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

    AsyncSession::commit

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

    Flush the unit of work, then commit. BeforeCommit fires before the flush and AfterCommit once the driver has committed and the connection is back to its untransacted state.

    AsyncSession::create_table

    source

    Create the table backing model from its declared columns, then its indexes.

    AsyncSession::delete_all

    source
    fn[T] AsyncSession::delete_all(self : AsyncSession, model : 
    Model    [T], records : Array[T]) -> Unit raise 
    DbError

    Queue every record in records for deletion.

    AsyncSession::delete_record

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

    Queue record for deletion, keyed on its primary key.

    AsyncSession::deleted_count

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

    How many records are queued for deletion.

    AsyncSession::dialect

    source

    The dialect this session renders its statements for.

    AsyncSession::dirty_count

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

    How many records are queued for update.

    AsyncSession::execute

    source

    Execute a raw statement with bound params.

    AsyncSession::expire_all

    source
    fn AsyncSession::expire_all(self : AsyncSession) -> Unit

    Mark every loaded record stale, so the next get reads it back.

    AsyncSession::expunge

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

    Drop record from the identity map, so the next get reads the row back.

    AsyncSession::expunge_all

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

    Empty the identity map.

    AsyncSession::fetch

    source

    Build and run a Select, returning the matched rows.

    AsyncSession::fetch_as

    source

    Run a Select and decode every row into a T via model.

    AsyncSession::flush

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

    Emit every queued statement in dependency order: inserts, then updates, then deletes in reverse. Nothing here commits.

    AsyncSession::get

    source

    Fetch by primary key, consulting the identity map before the database — the awaited [Session::get]. A record this session already holds costs no round trip.

    AsyncSession::get_by

    source

    get for a composite primary key: one value per declared key column, in declaration order.

    AsyncSession::insert_record

    source

    Insert a mapped record now, without queueing it — the awaited counterpart of [Session::insert_record], including the joined-table split and the insert hooks.

    AsyncSession::listener_count

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

    How many listeners are registered for event.

    AsyncSession::load

    source

    Eagerly load a 1:N relationship for one source — the awaited [Session::load], with the same strategy choice and the same bound match value.

    AsyncSession::load_batch

    source

    Eagerly load a 1:N relationship for many sources in one query, index-aligned with sources — the selectinload shape, without the N+1.

    AsyncSession::load_many

    source

    Eagerly load the related records of an N:M relationship through its junction table.

    AsyncSession::load_many_batch

    source

    Eagerly load an N:M relationship for many sources in one query.

    AsyncSession::load_one

    source

    Eagerly load the single related record of a N:1 relationship.

    AsyncSession::load_one_batch

    source

    Eagerly load a N:1 relationship for many sources in one query.

    AsyncSession::merge

    source
    async fn[T] AsyncSession::merge(self : AsyncSession, model : 
    Model    [T], record : T) -> T

    Insert record or update it, whichever its primary key calls for — the awaited [Session::merge]. The lookup is a round trip, so merge is one statement dearer than add_record on a row that may exist.

    AsyncSession::modify

    source

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

    AsyncSession::modify_versioned

    source

    Run a versioned UPDATE under optimistic concurrency control, raising [LostUpdate] when no row matched the expected version — see [Session::modify_versioned].

    AsyncSession::new

    source

    Wrap a connected async 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.

    AsyncSession::off_all

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

    Remove every listener from this asynchronous session.

    AsyncSession::on

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

    Register a listener for event on this asynchronous session — the same eleven points, the same context and the same ordering as [Session::on]. A listener is a plain closure, not an async one: it runs between statements, never instead of one, so there is nothing for it to await.

    AsyncSession::pending_count

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

    How many records are queued for insertion.

    AsyncSession::query

    source

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

    AsyncSession::query_stream

    source

    Stream a raw query's rows through an [@moondb.AsyncCursor], reading each row off the wire when it is asked for — the bounded-memory counterpart to [query], and the part a synchronous Session cannot offer a networked backend at all.

    The cursor must be drained or closed: MoonBit has no finaliser, so an abandoned one leaves the statement open and the connection mid-result.

    AsyncSession::refresh

    source
    async fn[T] AsyncSession::refresh(self : AsyncSession, model : 
    Model    [T], record : T) -> T

    Re-read record's row and replace it in the identity map — the awaited [Session::refresh]. Raises [LostUpdate] when the row is gone.

    AsyncSession::release

    source

    Release a savepoint, merging its work into the enclosing transaction.

    AsyncSession::remove

    source

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

    AsyncSession::rollback

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

    Roll back the current transaction, abandoning whatever is queued and emptying the identity map, then re-raise nothing: the caller keeps going as the synchronous twin does.

    AsyncSession::rollback_to

    source

    Roll back to a savepoint, undoing everything done since it opened in the database and in the session: writes queued after it leave the queues, and the identity map returns to the records it held when the savepoint opened.

    AsyncSession::savepoint

    source

    Open a nested transaction with SAVEPOINT <name>. Rejects a non-identifier name with QueryError before anything reaches the server.

    AsyncSession::savepoint_depth

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

    How many nested savepoints opened via begin_nested are currently active.

    AsyncSession::scalar

    source

    Build and run a Select and return the first column of its first row, or None when it matched nothing.

    AsyncSession::scalars

    source

    Build and run a Select and return the first column of every row.

    AsyncSession::stream

    source

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

    AsyncSession::stream_as

    source

    Build and stream a Select, decoding each row into a T on demand — the streaming counterpart to fetch_as, and the yield_per shape a large read wants.

    AsyncSession::transaction

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

    Run body inside one transaction: begin, run, commit; on failure roll back and re-raise what body raised. body is awaited, so the whole bracket is one task's.

    AsyncSession::update_record

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

    Queue record's current state as an UPDATE keyed on its primary key.

    AsyncSession::with_pool

    source

    Run f with an AsyncSession on a connection borrowed from pool, returning it when f finishes or raises — the awaited counterpart of [Session::with_pool], and the entry that makes concurrency possible: two tasks calling this at once take two connections and run at the same time.

    The unit of work owns its transaction: commit or roll back inside f before it returns, since the connection goes back to the pool as it was left.

    Core

    source
    type Core

    The state both session types carry. id names this session's slot in the identity map of every model it touches.

    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.

    The session is rolled back with the database: writes queued since the savepoint opened leave the queues, and the identity map returns to the records it held then. Otherwise the next flush would write rows the rollback undid, and a get would hand out a record whose row no longer exists.

    Session

    source

    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.

    The state — queues, identity map, savepoints — is Core's; this type adds the one thing a synchronous backend needs, a blocking call per rendered statement. Its asynchronous twin [AsyncSession] wraps the same state around an @moondb.AsyncDriver, so a program can move between the two without relearning the API.

    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_all

    source
    fn[T] Session::add_all(self : Session, model : 
    Model    [T], records : Array[T]) -> Unit

    Queue every record in records for insertion — SQLAlchemy's Session.add_all. One flush writes them in dependency order, so a parent added after its child still goes first.

    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.

    A connection-level option is not undone by the database when the transaction ends, so commit and rollback put it back (see TxOptions::restore_sql).

    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. Any connection-level transaction option is put back before AfterCommit, so a listener already sees the connection as the next borrower will.

    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_all

    source
    fn[T] Session::delete_all(self : Session, model : 
    Model    [T], records : Array[T]) -> Unit raise 
    DbError

    Queue every record in records for deletion — SQLAlchemy's Session.delete_all. They are removed in reverse dependency order at the next flush.

    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::expire_all

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

    Mark every loaded record stale, SQLAlchemy's Session.expire_all: the next get reads the row back instead of handing out the copy this session kept. MoonBit records are read through a call, not an attribute, so expiring eagerly here and reloading lazily there come to the same thing — both drop the copy.

    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::merge

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

    Insert record or update it, whichever its primary key calls for — SQLAlchemy's Session.merge, less the detached-instance copying: MoonBit records are values, so there is nothing to re-attach and the returned record is the one put in the identity map.

    A record whose key the identity map already holds, or whose row the database already has, is queued as an UPDATE; anything else is queued as an INSERT. The lookup runs now, so merge costs one SELECT on a miss and none on a hit. The queue, not this call, decides when the write happens — flush or commit.

    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 [AsyncSession::query_stream] under an event loop.

    Session::refresh

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

    Re-read record's row and replace it in the identity map — SQLAlchemy's Session.refresh. It is what a caller reaches for after a savepoint rollback or a trigger changed the row behind its back.

    Raises QueryError when the record carries no primary key, and LostUpdate when the row is gone: a refresh that silently returned the stale record would be worse than one that says the row is no longer there.

    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 and any connection-level transaction option has been put 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.

    The database is only half of it: the session's queues and identity map are put back as well, so a record inserted inside the savepoint stops being reachable and an updated one goes back to the values the database rolled back to. Anything else would hand a caller rows that no longer exist, or replay a write the rollback undid at the next flush.

    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::scalar

    source

    Build and run a Select and return the first column of its first row, or None when it matched nothing — SQLAlchemy's Session.scalar, and the shape a COUNT, an aggregate or a RETURNING-style probe comes back in.

    Session::scalars

    source

    Build and run a Select and return the first column of every row — SQLAlchemy's Session.scalars. Decoding into a record is fetch_as; this is for the queries whose answer is a single column.

    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.

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io