pub struct EditingSession {
pub id: Auto<i64>,
pub page_id: i64,
pub user_id: i64,
pub last_seen_at: DateTime<Utc>,
pub is_editing: bool,
}Fields§
§id: Auto<i64>§page_id: i64§user_id: i64§last_seen_at: DateTime<Utc>Bumped by each heartbeat. The active-vs-stale gate compares
this against now() - ACTIVE_WINDOW_SECS.
is_editing: booltrue once the editor JS has detected a form touch on this
page. Set by the heartbeat ping body (?is_editing=1) and
reset to false on a fresh page load.
Implementations§
Source§impl EditingSession
impl EditingSession
pub const id: id_col = __rustango_cols_EditingSession::id_col
pub const page_id: page_id_col = __rustango_cols_EditingSession::page_id_col
pub const user_id: user_id_col = __rustango_cols_EditingSession::user_id_col
pub const last_seen_at: last_seen_at_col = __rustango_cols_EditingSession::last_seen_at_col
pub const is_editing: is_editing_col = __rustango_cols_EditingSession::is_editing_col
Sourcepub fn objects() -> QuerySet<EditingSession>
pub fn objects() -> QuerySet<EditingSession>
Start a new QuerySet over this model.
Sourcepub fn query() -> QuerySet<EditingSession>
pub fn query() -> QuerySet<EditingSession>
Eloquent-shape alias of Self::objects. Returns
a fresh QuerySet<Self> ready for .filter() /
.where_() / etc. Matches Laravel muscle-memory:
// Eloquent: Post::query()->where('published', true)
// rustango: Post::query().filter("published", true)
// or: Post::objects().filter("published", true)Both names point at the same underlying constructor; neither is preferred.
Sourcepub async fn insert(&mut self, pool: &PgPool) -> Result<(), ExecError>
pub async fn insert(&mut self, pool: &PgPool) -> Result<(), ExecError>
Insert this row into its table. Skips columns whose
Auto<T> value is Unset so Postgres’ SERIAL/BIGSERIAL
sequence fills them in, then reads each Auto column
back via RETURNING and stores it on self.
Postgres only — prefer Self::insert_pool. This takes
a driver-specific PgPool, so it does not exist on a build
without the postgres feature. Self::insert_pool takes
rustango::sql::Pool and works on all three. The naming is
inverted; tracked in #1293.
§Errors
Returns [#root::sql::ExecError] for SQL-writing or
driver failures.
Sourcepub async fn insert_on<'_c, _E>(
&mut self,
_executor: _E,
) -> Result<(), ExecError>
pub async fn insert_on<'_c, _E>( &mut self, _executor: _E, ) -> Result<(), ExecError>
Like Self::insert but accepts any sqlx executor.
See Self::save_on for tenancy-scoped rationale.
§Errors
As Self::insert.
Sourcepub async fn insert_on_with<'_c, _E>(
&mut self,
_executor: _E,
source: AuditSource,
) -> Result<(), ExecError>
pub async fn insert_on_with<'_c, _E>( &mut self, _executor: _E, source: AuditSource, ) -> Result<(), ExecError>
Per-call audit-source override for Self::insert_on.
See Self::save_on_with for shape rationale.
§Errors
As Self::insert_on.
Sourcepub async fn bulk_insert(
rows: &mut [Self],
pool: &PgPool,
) -> Result<(), ExecError>
pub async fn bulk_insert( rows: &mut [Self], pool: &PgPool, ) -> Result<(), ExecError>
Bulk-insert rows: one statement, or one per chunk in a
transaction past the bind cap. Every row’s
Auto<T> PK fields must uniformly be Auto::Unset
(sequence fills them in) or uniformly Auto::Set(_)
(caller-supplied values). Mixed Set/Unset is rejected
— call insert per row for that case.
Empty slice is a no-op. Each row’s Auto fields are
populated from the RETURNING clause in input order
before this returns.
§Errors
Returns [#root::sql::ExecError] for validation,
SQL-writing, mixed-Auto rejection, or driver failures.
Sourcepub async fn bulk_insert_on<'_c, _E>(
rows: &mut [Self],
_executor: _E,
) -> Result<(), ExecError>
pub async fn bulk_insert_on<'_c, _E>( rows: &mut [Self], _executor: _E, ) -> Result<(), ExecError>
Like Self::bulk_insert but accepts any sqlx executor.
See Self::save_on for tenancy-scoped rationale.
§Errors
Sourcepub async fn bulk_upsert_pool(
rows: &[Self],
target: &[&'static str],
update_cols: &[&'static str],
pool: &Pool,
) -> Result<(), ExecError>
pub async fn bulk_upsert_pool( rows: &[Self], target: &[&'static str], update_cols: &[&'static str], pool: &Pool, ) -> Result<(), ExecError>
Tri-dialect bulk insert that updates on conflict — the “import a batch idempotently” shape. Issue #267 / T1.5.
Per-row values are extracted and lowered into a
[#root::core::BulkInsertQuery] with
on_conflict = DoUpdate { target, update_columns }. The
writer dispatches per-dialect:
- Postgres / SQLite:
INSERT … ON CONFLICT (target) DO UPDATE SET col = EXCLUDED.col - MySQL:
INSERT … ON DUPLICATE KEY UPDATE col = VALUES(col); refused whentargetis not the only unique key, since MySQL matches every UNIQUE index
target names the column(s) whose unique constraint
defines the conflict (typically a unique or
unique_together natural-key column, NOT the Auto<T>
PK). update_cols names the columns to overwrite on
conflict — every other column is left untouched on the
existing row.
Auto-PK rows must all have Auto::Unset (the sequence
picks the PK on insert; the update path never touches
the Auto column). Auto-set rows trigger a hard error.
Rows repeating a target key: the last one wins.
Empty slice is a no-op. On an audited model each written
row gets a create or update audit row; MySQL refuses it.
§Errors
Returns [#root::sql::ExecError] for validation,
SQL-writing, or driver failures.
Sourcepub async fn bulk_insert_or_ignore_pool(
rows: &[Self],
pool: &Pool,
) -> Result<(), ExecError>
pub async fn bulk_insert_or_ignore_pool( rows: &[Self], pool: &Pool, ) -> Result<(), ExecError>
Tri-dialect bulk_create(ignore_conflicts=True) — silently
skip rows that would violate a unique constraint. Issue
#267 / T1.5. Same per-dialect dispatch as
Self::bulk_upsert_pool but with ON CONFLICT … DO NOTHING (Postgres / SQLite) / ON DUPLICATE KEY UPDATE <pivot> = <pivot> (MySQL no-op write).
§Errors
Sourcepub async fn bulk_update(
objs: &[Self],
fields: &[&str],
pool: &Pool,
) -> Result<u64, ExecError>
pub async fn bulk_update( objs: &[Self], fields: &[&str], pool: &Pool, ) -> Result<u64, ExecError>
Write per-row-different values for the named fields
across every object in objs, matched by primary key.
Past the backend’s bind cap the rows go in batches inside
one transaction, so the update is all or none.
fields names the columns to update. The primary
key identifies each row and cannot itself be updated
(pass it and you get
[#root::core::QueryError::BulkUpdatePrimaryKey]).
Empty objs or fields is a no-op returning 0.
Objects whose PK matches no row are simply not updated.
Returns the number of rows affected.
Tri-dialect: lowers to a
[#root::core::BulkUpdateQuery] and dispatches
per-backend — UPDATE … FROM (VALUES …) on Postgres,
a CTE + correlated subquery on SQLite, an inner
JOIN (VALUES …) on MySQL.
§Errors
[#root::core::QueryError::UnknownField] for a name
that isn’t a column on this model,
[#root::core::QueryError::BulkUpdatePrimaryKey] if
fields names the PK, or [#root::sql::ExecError] for
SQL-writing / driver failures.
Sourcepub async fn save(&mut self, pool: &PgPool) -> Result<u64, ExecError>
pub async fn save(&mut self, pool: &PgPool) -> Result<u64, ExecError>
Insert this row if its Auto<T> primary key is
Unset, otherwise update the existing row matching the
PK. The caller doesn’t need to pick insert vs the
bulk-update path manually.
On the insert branch, populates the PK from RETURNING
(same behavior as insert). On the update branch,
writes every non-PK column back; if no row matches the
PK, returns Ok(()) silently.
Only generated when the primary key is declared as
Auto<T>. Models with a manually-managed PK must use
insert or the QuerySet update builder.
Postgres only — prefer Self::save_pool. This takes a
driver-specific PgPool, so it does not exist at all on a
build without the postgres feature: selecting sqlite
makes the method vanish rather than fail with anything that
names the cause.
Self::save_pool takes rustango::sql::Pool and works on
all three backends. The naming is inverted — the short name
is the narrow one — and that is tracked in #1293.
§Errors
Returns [#root::sql::ExecError] for SQL-writing
or driver failures.
Sourcepub async fn save_on<'_c, _E>(
&mut self,
_executor: _E,
) -> Result<u64, ExecError>
pub async fn save_on<'_c, _E>( &mut self, _executor: _E, ) -> Result<u64, ExecError>
Like Self::save but accepts any sqlx executor —
&PgPool, &mut PgConnection, or a transaction. The
escape hatch for tenant-scoped writes: schema-mode
tenants share the registry pool but rely on a per-
checkout SET search_path, so passing &PgPool would
silently hit the wrong schema. Acquire a connection
via TenantPools::acquire(&org) and pass &mut *conn.
§Errors
As Self::save.
Sourcepub async fn save_on_with<'_c, _E>(
&mut self,
_executor: _E,
source: AuditSource,
) -> Result<u64, ExecError>
pub async fn save_on_with<'_c, _E>( &mut self, _executor: _E, source: AuditSource, ) -> Result<u64, ExecError>
Per-call override for the audit source. Runs
Self::save_on inside an [#root::audit::with_source]
scope so the resulting audit entry records source
instead of the task-local default. Useful for seed
scripts and one-off CLI tools that don’t sit inside an
admin handler. The override applies only to this call;
no global state changes.
§Errors
As Self::save_on.
Sourcepub async fn upsert(&mut self, pool: &PgPool) -> Result<(), ExecError>
pub async fn upsert(&mut self, pool: &PgPool) -> Result<(), ExecError>
Insert this row or update it in-place if the primary key already
exists — single round-trip via INSERT … ON CONFLICT (pk) DO UPDATE.
With Auto::Unset PK the server assigns a new key and no conflict
can occur (equivalent to insert). With Auto::Set PK the row is
inserted if absent or all non-PK columns are overwritten if present.
§Errors
As Self::insert_on.
Sourcepub async fn upsert_on<'_c, _E>(
&mut self,
_executor: _E,
) -> Result<(), ExecError>
pub async fn upsert_on<'_c, _E>( &mut self, _executor: _E, ) -> Result<(), ExecError>
Like Self::upsert but accepts any sqlx executor.
See Self::save_on for tenancy-scoped rationale.
§Errors
As Self::upsert.
Sourcepub async fn delete(&self, pool: &PgPool) -> Result<u64, ExecError>
pub async fn delete(&self, pool: &PgPool) -> Result<u64, ExecError>
Delete the row identified by this instance’s primary key.
Returns the number of rows affected (0 or 1).
Postgres only — prefer Self::delete_pool. This takes
a driver-specific PgPool, so it does not exist on a build
without the postgres feature. Self::delete_pool takes
rustango::sql::Pool and works on all three. The naming is
inverted; tracked in #1293.
§Errors
Returns [#root::sql::ExecError] for SQL-writing or
driver failures.
Sourcepub async fn delete_on<'_c, _E>(&self, _executor: _E) -> Result<u64, ExecError>
pub async fn delete_on<'_c, _E>(&self, _executor: _E) -> Result<u64, ExecError>
Like Self::delete but accepts any sqlx executor —
for tenant-scoped deletes against an explicitly-acquired
connection. See Self::save_on for the rationale.
§Errors
As Self::delete.
Sourcepub async fn delete_on_with<'_c, _E>(
&self,
_executor: _E,
source: AuditSource,
) -> Result<u64, ExecError>
pub async fn delete_on_with<'_c, _E>( &self, _executor: _E, source: AuditSource, ) -> Result<u64, ExecError>
Per-call audit-source override for Self::delete_on.
See Self::save_on_with for shape rationale.
§Errors
As Self::delete_on.
Sourcepub async fn delete_pool(&self, pool: &Pool) -> Result<u64, ExecError>
pub async fn delete_pool(&self, pool: &Pool) -> Result<u64, ExecError>
Delete the row identified by this instance’s primary key
against either backend. Equivalent to Self::delete but
takes [#root::sql::Pool] and dispatches per backend.
Global scopes do not apply.
§Errors
As Self::delete.
Sourcepub async fn insert_pool(&mut self, pool: &Pool) -> Result<(), ExecError>
pub async fn insert_pool(&mut self, pool: &Pool) -> Result<(), ExecError>
Insert this row against either backend, populating any
Auto<T> PK from the auto-assigned value.
§Errors
As Self::insert.
Sourcepub async fn insert_or_ignore(&mut self, pool: &Pool) -> Result<bool, ExecError>
pub async fn insert_or_ignore(&mut self, pool: &Pool) -> Result<bool, ExecError>
Eloquent Model::insertOrIgnore() — INSERT this
row or silently skip on unique-constraint
violation. Returns Ok(true) when a row was
inserted, Ok(false) when a conflict caused the
INSERT to silently skip.
Caveat on auto-PK models: when the row is
skipped (conflict), this instance’s Auto<T>
fields stay Unset — no PK is back-populated
because the server didn’t auto-assign one. For
“insert then read back the PK or the existing
row’s PK”, use the upsert family or
get_or_create.
§Errors
As Self::insert.
Sourcepub async fn save_pool(&mut self, pool: &Pool) -> Result<u64, ExecError>
pub async fn save_pool(&mut self, pool: &Pool) -> Result<u64, ExecError>
Save this row to its table against either backend.
INSERT when the Auto<T> PK is Unset, else
UPDATE keyed on the PK; global scopes do not apply.
§Errors
As Self::save.
Sourcepub async fn save_partial(
&mut self,
fields: &[&str],
pool: &Pool,
) -> Result<u64, ExecError>
pub async fn save_partial( &mut self, fields: &[&str], pool: &Pool, ) -> Result<u64, ExecError>
Save (UPDATE) only the listed Rust-side fields, leaving every other column untouched. Issue #66.
fields are Rust-side struct field names; the macro
resolves each to its SQL column. Unknown field
names return [#root::core::QueryError::UnknownField]
wrapped in ExecError::Query. An empty list is a
no-op (returns Ok(()) and logs a tracing::warn!).
On an audited model the audit diff covers only these fields.
Use this when:
- you only mutated a couple of fields on a wide row (avoid re-writing every column on every save), or
- two writers diverged after their initial read and you want to preserve the other writer’s changes to columns you didn’t touch.
Auto-PK models with an unset PK return
[#root::core::QueryError::UnknownField] with
field name <pk> — save_partial is an
UPDATE-only path. Call Self::insert_pool
(or Self::save_pool which dispatches based on
PK state) for the INSERT case.
§Errors
As Self::save_pool, plus UnknownField for
unknown / empty / Auto-Unset cases.
Sourcepub async fn save_partial_typed<L: TypedFieldList<Self>>(
&mut self,
fields: L,
pool: &Pool,
) -> Result<u64, ExecError>
pub async fn save_partial_typed<L: TypedFieldList<Self>>( &mut self, fields: L, pool: &Pool, ) -> Result<u64, ExecError>
Typed-column counterpart of Self::save_partial —
issue #67. fields is a tuple of Column
constants whose Model matches Self; typos and
model mismatches surface at compile time
(Author::name inside a Post::save_partial_typed
call is a type error, no runtime check).
post.save_partial_typed((Post::title, Post::slug), &pool).await?;Lowers to Self::save_partial under the hood — the
tuple is reduced to a &[&str] slice of Rust-side
field names and forwarded.
§Errors
Sourcepub async fn refresh_from_db(&mut self, pool: &Pool) -> Result<(), ExecError>
pub async fn refresh_from_db(&mut self, pool: &Pool) -> Result<(), ExecError>
Re-SELECT this row by its primary key and overwrite every in-memory field with the freshly-fetched value. Issue #825.
Use this when the row may have been modified by another process / connection / job since you read it — e.g. after a queued task callback, or to re-sync stale UI state before re-saving.
Returns [ExecError::Driver(sqlx::Error::RowNotFound)]
when the primary key no longer matches any row (e.g.
the row was deleted concurrently).
§Errors
As FetcherPool::fetch; also RowNotFound when
the PK no longer exists.
Sourcepub async fn increment(
&self,
col: &str,
by: i64,
pool: &Pool,
) -> Result<u64, ExecError>
pub async fn increment( &self, col: &str, by: i64, pool: &Pool, ) -> Result<u64, ExecError>
Atomically increment the integer column col by
by for this row. Equivalent to
UPDATE <table> SET <col> = <col> + $1 WHERE <pk> = $2.
Doesn’t mutate self — the in-memory copy is now
stale; call Self::refresh_from_db /
Self::fresh to re-sync. Returns the rows-
affected count (0 when the PK doesn’t match any row,
1 on success).
col is the Rust field name as a string; unknown
fields surface as UnknownField at runtime. Negative
by values atomically decrement (see also
Self::decrement).
§Errors
Sourcepub async fn decrement(
&self,
col: &str,
by: i64,
pool: &Pool,
) -> Result<u64, ExecError>
pub async fn decrement( &self, col: &str, by: i64, pool: &Pool, ) -> Result<u64, ExecError>
Sibling of Self::increment — atomically
decrement this row’s col by by. Eloquent
$model->decrement($col, $by) parity. Equivalent to
self.increment(col, -by, &pool); the separate name
keeps call sites readable.
§Errors
As Self::increment.
Sourcepub async fn increment_each(
col: &str,
by: i64,
pool: &Pool,
) -> Result<u64, ExecError>
pub async fn increment_each( col: &str, by: i64, pool: &Pool, ) -> Result<u64, ExecError>
Bulk-increment: add by to col on every row of the
table. Eloquent Model::query()->increment($col, $by)
parity. Use for counters, score adjustments, view
rollups.
§Errors
Sourcepub async fn fresh(&self, pool: &Pool) -> Result<Option<Self>, ExecError>
pub async fn fresh(&self, pool: &Pool) -> Result<Option<Self>, ExecError>
Re-SELECT this row by its primary key and return a
new instance with the freshly-fetched fields.
Eloquent Model::fresh() parity — non-mutating
counterpart of Self::refresh_from_db.
Returns Ok(None) when the row was deleted
concurrently — vs Self::refresh_from_db
which surfaces that as RowNotFound because
in-place mutation has nothing to write to.
Useful when you want to compare the in-memory instance against the persisted state (audit-style diffs, conflict detection) without mutating the reference you already hold.
§Errors
Sourcepub fn replicate(&self) -> Self
pub fn replicate(&self) -> Self
Eloquent-style replicate() — return a clone of this
row with the primary key reset to Auto::Unset so
the copy is ready for insert_pool / save_pool to
allocate a fresh autoincrement value. Every other
field is Cloned verbatim. Issue #825.
auto_now_add / auto_now timestamp fields are
not reset (Eloquent’s replicate doesn’t reset
them either) — pass them through the normal insert
path if you want fresh values, or assign them
explicitly after the call.
Sourcepub async fn first(pool: &Pool) -> Result<Option<Self>, ExecError>
pub async fn first(pool: &Pool) -> Result<Option<Self>, ExecError>
First row of this model. Eloquent Model::first().
Skipped on models that already declare a field named
first. Drop into QuerySet::<Self>::default().first(&pool).
§Errors
As QuerySet::first.
Sourcepub async fn last(pool: &Pool) -> Result<Option<Self>, ExecError>
pub async fn last(pool: &Pool) -> Result<Option<Self>, ExecError>
Last row of this model by primary-key DESC.
Eloquent Model::query()->latest('id')->first()
parity — fetches the highest-PK row without
requiring the caller to spell the PK column.
Returns None on an empty table.
Equivalent to QuerySet::<Self>::default().last(&pool).
Skipped on models that already declare a field
named last.
§Errors
As QuerySet::last.
Sourcepub async fn first_or_fail(pool: &Pool) -> Result<Self, ExecError>
pub async fn first_or_fail(pool: &Pool) -> Result<Self, ExecError>
Throwing counterpart of Self::first —
errors with RowNotFound when the table is empty.
Eloquent Model::firstOrFail() parity.
§Errors
As Self::first; additionally
sqlx::Error::RowNotFound on empty tables.
Sourcepub async fn pluck<U>(
col: &'static str,
pool: &Pool,
) -> Result<Vec<U>, ExecError>where
U: FlatScalar,
pub async fn pluck<U>(
col: &'static str,
pool: &Pool,
) -> Result<Vec<U>, ExecError>where
U: FlatScalar,
Single-column projection — `SELECT