Skip to main content

Crate sqlmodel_session

Crate sqlmodel_session 

Source
Expand description

Session and Unit of Work for SQLModel Rust.

sqlmodel-session is the unit-of-work layer. It coordinates object identity, change tracking, and transactional persistence in a way that mirrors Python SQLModel while staying explicit and Rust-idiomatic.

§Role In The Architecture

  • Identity map: ensures a single in-memory instance per primary key.
  • Change tracking: records inserts, updates, and deletes before flush.
  • Transactional safety: wraps flush/commit/rollback around a Connection.

§Design Philosophy

  • Explicit over implicit: No autoflush by default.
  • Ownership clarity: Session owns the connection or pooled connection.
  • Type erasure: Identity map stores Box<dyn Any> for heterogeneous models.
  • Cancel-correct: All async operations use Cx + Outcome via sqlmodel-core.

§Example

ⓘ
// Create session from pool
let mut session = Session::new(&pool).await?;

// Add new objects (will be INSERTed on flush)
session.add(&hero);

// Get by primary key (uses identity map)
let hero = session.get::<Hero>(1).await?;

// Mark for deletion
session.delete(&hero);

// Flush pending changes to DB
session.flush().await?;

// Commit the transaction
session.commit().await?;

Re-exports§

pub use change_tracker::ChangeTracker;
pub use change_tracker::ObjectSnapshot;
pub use flush::FlushOrderer;
pub use flush::FlushPlan;
pub use flush::FlushResult;
pub use flush::LinkTableOp;
pub use flush::PendingOp;
pub use identity_map::IdentityMap;
pub use identity_map::ModelReadGuard;
pub use identity_map::ModelRef;
pub use identity_map::ModelWriteGuard;
pub use identity_map::WeakIdentityMap;
pub use n1_detection::CallSite;
pub use n1_detection::N1DetectionScope;
pub use n1_detection::N1QueryTracker;
pub use n1_detection::N1Stats;
pub use unit_of_work::PendingCounts;
pub use unit_of_work::UnitOfWork;
pub use unit_of_work::UowError;

Modules§

change_tracker
Change tracking and dirty detection for SQLModel Session.
flush
Flush operation ordering and batching for SQLModel Session.
identity_map
Identity Map pattern for tracking unique object instances per primary key.
n1_detection
N+1 Query Detection for SQLModel Rust.
unit_of_work
Unit of Work pattern implementation for SQLModel Session.

Structs§

GetOptions
Options for Session::get_with_options().
ObjectKey
Unique key for an object in the identity map.
Session
The Session is the central unit-of-work manager.
SessionConfig
Configuration for Session behavior.
SessionDebugInfo
Debug information about session state.
SessionEventCallbacks
Holds registered session-level event callbacks.

Enums§

ObjectState
State of a tracked object in the session.
SessionEvent
Session lifecycle events.