pub struct Component {
pub id: Auto<i64>,
pub slug: String,
pub label: String,
pub icon: String,
pub description: String,
pub version: i32,
pub document: Value,
pub created_at: Auto<DateTime<Utc>>,
pub updated_at: Auto<DateTime<Utc>>,
}Expand description
A reusable field-group (a component), referenced from
schemas by slug (c_<slug>).
Fields§
§id: Auto<i64>§slug: String§label: String§icon: String§description: String§version: i32Bumped on every save; stamped onto instances for lazy upgrade.
document: Value§created_at: Auto<DateTime<Utc>>§updated_at: Auto<DateTime<Utc>>Implementations§
Source§impl Component
impl Component
pub const id: id_col = __rustango_cols_Component::id_col
pub const slug: slug_col = __rustango_cols_Component::slug_col
pub const label: label_col = __rustango_cols_Component::label_col
pub const icon: icon_col = __rustango_cols_Component::icon_col
pub const description: description_col = __rustango_cols_Component::description_col
pub const version: version_col = __rustango_cols_Component::version_col
pub const document: document_col = __rustango_cols_Component::document_col
pub const created_at: created_at_col = __rustango_cols_Component::created_at_col
pub const updated_at: updated_at_col = __rustango_cols_Component::updated_at_col
Sourcepub fn query() -> QuerySet<Component>
pub fn query() -> QuerySet<Component>
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: &Pool) -> Result<(), ExecError>
pub async fn insert(&mut self, pool: &Pool) -> Result<(), ExecError>
Insert this row on any backend, reading each Auto field
back from the written row.
§Errors
Returns [#root::sql::ExecError] for SQL-writing or driver failures.
Sourcepub async fn insert_on<'_c, _E: SqlExecutor<'_c>>(
&mut self,
_executor: _E,
) -> Result<(), ExecError>
pub async fn insert_on<'_c, _E: SqlExecutor<'_c>>( &mut self, _executor: _E, ) -> Result<(), ExecError>
Self::insert on any [#root::sql::SqlExecutor]. An audited
model refuses it: use Self::insert.
§Errors
As Self::insert.
Sourcepub async fn insert_pool(&mut self, pool: &Pool) -> Result<(), ExecError>
👎Deprecated since 0.62.0: use insert
pub async fn insert_pool(&mut self, pool: &Pool) -> Result<(), ExecError>
use insert
Sourcepub async fn bulk_insert(
rows: &mut [Self],
pool: &Pool,
) -> Result<(), ExecError>
pub async fn bulk_insert( rows: &mut [Self], pool: &Pool, ) -> Result<(), ExecError>
Bulk-insert rows: one statement, or one per chunk in one
transaction past the bind cap. Every row’s Auto<T> PK must
be Auto::Unset (the database fills it) or every one Set.
Each row’s Auto fields are read back from RETURNING; MySQL
has none, so it leaves them unset. An empty slice is a no-op.
§Errors
Returns [#root::sql::ExecError] for validation,
SQL-writing, mixed-Auto rejection, or driver failures.
Sourcepub async fn bulk_insert_on<'_c, _E: SqlExecutor<'_c>>(
rows: &mut [Self],
_executor: _E,
) -> Result<(), ExecError>
pub async fn bulk_insert_on<'_c, _E: SqlExecutor<'_c>>( rows: &mut [Self], _executor: _E, ) -> Result<(), ExecError>
Self::bulk_insert on any [#root::sql::SqlExecutor]. An
audited model refuses it: use Self::bulk_insert.
§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.
A database-filled Auto PK follows Self::bulk_insert: all
Unset leaves it to the database, all Set writes it (so
target = ["id"] updates by id), a mix is BulkAutoMixed.
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_on<'_c, _E: SqlExecutor<'_c>>(
&mut self,
_executor: _E,
) -> Result<u64, ExecError>
pub async fn save_on<'_c, _E: SqlExecutor<'_c>>( &mut self, _executor: _E, ) -> Result<u64, ExecError>
Self::save on any [#root::sql::SqlExecutor]: a held
PoolConn, a PoolTx, a tenant connection or a Postgres sqlx
executor. An audited model refuses it: use Self::save.
§Errors
As Self::save.
Sourcepub async fn save_pool(&mut self, pool: &Pool) -> Result<u64, ExecError>
👎Deprecated since 0.62.0: use save
pub async fn save_pool(&mut self, pool: &Pool) -> Result<u64, ExecError>
use save
Sourcepub async fn upsert(&mut self, pool: &Pool) -> Result<(), ExecError>
pub async fn upsert(&mut self, pool: &Pool) -> Result<(), ExecError>
Insert this row, or update the row it conflicts with: one
INSERT … ON CONFLICT (MySQL: ON DUPLICATE KEY UPDATE).
The target is the first unique_together, else the PK.
Fills the Auto<T> fields from the written row.
§Errors
As Self::insert.
Sourcepub async fn upsert_on<'_c, _E: SqlExecutor<'_c>>(
&mut self,
_executor: _E,
) -> Result<(), ExecError>
pub async fn upsert_on<'_c, _E: SqlExecutor<'_c>>( &mut self, _executor: _E, ) -> Result<(), ExecError>
Self::upsert on any [#root::sql::SqlExecutor]. An
audited model refuses it: use Self::upsert.
§Errors
As Self::upsert.
Sourcepub async fn delete_on<'_c, _E: SqlExecutor<'_c>>(
&self,
_executor: _E,
) -> Result<u64, ExecError>
pub async fn delete_on<'_c, _E: SqlExecutor<'_c>>( &self, _executor: _E, ) -> Result<u64, ExecError>
Self::delete on any [#root::sql::SqlExecutor]. An audited
model refuses it: use Self::delete.
§Errors
As Self::delete.
Sourcepub async fn delete_pool(&self, pool: &Pool) -> Result<u64, ExecError>
👎Deprecated since 0.62.0: use delete
pub async fn delete_pool(&self, pool: &Pool) -> Result<u64, ExecError>
use delete
Sourcepub async fn delete(&self, pool: &Pool) -> Result<u64, ExecError>
pub async fn delete(&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_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(&mut self, pool: &Pool) -> Result<u64, ExecError>
pub async fn save(&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.
A PK with no row is RowNotFound: use insert for a new row.
§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
(or Self::save which dispatches based on
PK state) for the INSERT case.
§Errors
As Self::save, 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