pub struct Page {Show 31 fields
pub id: Auto<i64>,
pub page_type_id: i64,
pub title: String,
pub slug: String,
pub path: String,
pub url_path: String,
pub depth: i32,
pub parent_id: Option<i64>,
pub locale_variant_of: Option<i64>,
pub alias_of: Option<i64>,
pub theme_id: Option<i64>,
pub sort_order: i32,
pub status: String,
pub published_at: Option<DateTime<Utc>>,
pub last_published_at: Option<DateTime<Utc>>,
pub go_live_at: Option<DateTime<Utc>>,
pub expire_at: Option<DateTime<Utc>>,
pub seo_title: String,
pub seo_description: String,
pub robots_index: bool,
pub sitemap_priority: f32,
pub preview_path: String,
pub template_override: String,
pub show_in_menus: bool,
pub og_title: String,
pub og_description: String,
pub og_image_media_id: Option<i64>,
pub twitter_card: String,
pub notification_pre_published_sent: bool,
pub created_at: Auto<DateTime<Utc>>,
pub updated_at: Auto<DateTime<Utc>>,
}Expand description
The abstract page record. Each row points at a cms_page_type registry
row via page_type_id; per-type extension data lives in a separate
table authored by user code (multi-table inheritance).
Tree shape: path is a materialized path (e.g. 0001/0003/), depth is
the number of segments, parent_id is the immediate parent (nullable for
roots). Siblings share parent_id and order by sort_order then id.
Fields§
§id: Auto<i64>§page_type_id: i64FK to cms_page_type.id — the registry row that names the
handler responsible for this page.
title: String§slug: StringURL slug, meant to be unique per parent. Not enforced by a DB constraint; page create / copy / alias dedup against siblings.
path: StringMaterialized path of zero-padded segment ids, trailing slash.
Example: 0001/0003/0008/. Indexed for prefix lookups.
url_path: StringMaterialized public URL path, indexed for
single-query lookup. Leading slash, no trailing slash for
non-root pages: /, /about, /about/team. Maintained by
tree_ops whenever a page is created or its slug / parent
changes. The resolver short-circuits via this column instead
of walking ancestor-by-ancestor, turning N queries into 1.
Default '' so AddColumn on existing tables doesn’t need a
backfill — older rows fall through to the slug-walk
resolver until their next save populates the column.
depth: i32Cached number of /-separated segments in path (root = 1).
parent_id: Option<i64>Self-FK. Null means this is a root page.
locale_variant_of: Option<i64>DEPRECATED — the structural-variant escape hatch was
retired in favor of per-field translations. The supported path
for localizing a page is the cms_translation table (one row
per (page_id, locale_id, field_path) override); see
crate::translation.
The column itself is retained so existing tenant rows that already carried a variant pointer don’t 500 the loader. Sitemap
- feed builders still dedup on this column for back-compat;
api/pages.rsstill filters by it for legacy API consumers. No new rows should set this field — the admin UI no longer surfaces the action and the POST handler is gone.
alias_of: Option<i64>Live alias. When set, this row contributes only the URL (slug / url_path / sort_order / parent_id); content fields (title, seo_*, status, page-type extension data) come from the row this FK points at. Edits via the page editor proxy to the source; the alias row stays read-only. Deleting the source demotes every alias into a standalone copy with the source’s last-known content frozen in place.
Differentiation from neighbouring features:
- Clone is a deep copy — divergent edits, separate revisions, no link back to the original.
- Redirect is a 301 from old path to new path with no separate page row at all.
- Alias is one row, two (or more) URLs, content always in sync because there’s only one source-of-truth.
theme_id: Option<i64>Per-page visual theme override. When set, this page (and its
descendants, unless they override too) renders against the
referenced cms_theme row’s design tokens. NULL = inherit
from ancestors / site default / admin default.
sort_order: i32Ordering among siblings (lowest first).
status: StringLifecycle. Stored as the PageStatus::as_str() value.
published_at: Option<DateTime<Utc>>Set when status transitions to Published. Null otherwise.
Note: semantically this is
first_published_at — the renderer + sweep set it once on
the first published transition and never touch it again, so
order_by('-published_at') is the canonical chronological
post-card ordering. For “most-recently-edited” timestamps
see Self::last_published_at.
last_published_at: Option<DateTime<Utc>>Refreshed every time the page is saved while status = published. Sitemap <lastmod> and edge-cache
invalidation use this — published_at (the first-publish
timestamp) is too stable for those.
Initialized to the same value as published_at when the
first-publish happens; subsequent edits bump just this
field. Null for never-published rows.
#[serde(default)] so revision snapshots captured before
this column landed deserialize cleanly (the field arrives
as None, which matches the column’s nullable default).
go_live_at: Option<DateTime<Utc>>Optional schedule — when set with status = scheduled, a worker flips
status to published once now() >= go_live_at.
expire_at: Option<DateTime<Utc>>Opposite of go_live_at — auto-archive at this time.
seo_title: StringSEO metadata.
seo_description: String§robots_index: boolWhether search engines should index this page. false makes
the renderer emit <meta name="robots" content="noindex">
and excludes the page from the generated /sitemap.xml.
Default true.
sitemap_priority: f32Sitemap priority hint, 0.0–1.0 per the sitemaps.org spec.
1.0 = homepage / top of hierarchy; 0.5 = ordinary content
page (the spec’s default); 0.0–0.3 = low-value pages
(terms, archive listings). Communicated to crawlers via the
generated /sitemap.xml’s <priority> element.
preview_path: StringWhere this page lives on a decoupled frontend, when that
differs from url_path.
The site-wide “Headless preview” template substitutes {path}
with url_path, which silently assumes the frontend mirrors the
CMS’s URL structure. Plenty of them do not: a page at
/features/ai-engine here may be /product/ai-engine there, or
/p/9, or on another host entirely.
Three behaviours, chosen by what the editor types:
- empty — use
url_path, i.e. today’s behaviour; - a path (
/product/ai-engine) — substituted for{path}in the site-wide template, so the token and host stay in one place; - an absolute URL (
https://other.example.com/x) — used as the whole preview URL, placeholders and all, for the page that a different app renders.
Default '' so adding the column needs no backfill: every
existing page keeps resolving through url_path.
Deliberately not carried by clone or alias: a copy has its own
url_path, and inheriting the original’s frontend route would
point two pages at one place.
template_override: StringTemplate this page renders through, overriding its page type’s
default_template.
The type’s template is the right default: pages of a type normally look alike, and that is what makes a type worth having. But a type is a content shape, and presentation does not always follow it — a set of pages under one root can want their own layout without becoming a separate type with a duplicate field list. Rather than making authors choose between a type per variation and no variation at all, the page names the template.
Default '' (use the type’s template) so adding the column needs
no backfill and every existing page renders exactly as before.
The name resolves against the tenant’s template set, so an
override can point at a file the template editor (or the
write_template MCP tool) created without a deploy. A name that
resolves to nothing falls back to the type’s template rather than
500ing — a typo should not take the page down.
Opt-in flag — the navigation-menu editor shows this page
in its picker as a suggested entry. Editors flip it in the
Promote tab; defaults to false so the suggestion list stays
curated and doesn’t surface every page in the tree.
og_title: StringSocial-sharing fields. All optional; the renderer falls back to title / seo_description / first body image when empty.
og_description: String§og_image_media_id: Option<i64>§twitter_card: StringTwitter card variant. Accepted values: summary,
summary_large_image. Default summary_large_image.
notification_pre_published_sent: boolPre-publish reminder flag. Set by
run_schedule_sweep_with_mailer when the sweep sends a
“publishes in N minutes” notification to subscribers; cleared
when an editor moves the go_live_at. Prevents duplicate
reminders if the sweep tick rate exceeds 1/hour.
created_at: Auto<DateTime<Utc>>§updated_at: Auto<DateTime<Utc>>Implementations§
Source§impl Page
impl Page
pub const id: id_col = __rustango_cols_Page::id_col
pub const page_type_id: page_type_id_col = __rustango_cols_Page::page_type_id_col
pub const title: title_col = __rustango_cols_Page::title_col
pub const slug: slug_col = __rustango_cols_Page::slug_col
pub const path: path_col = __rustango_cols_Page::path_col
pub const url_path: url_path_col = __rustango_cols_Page::url_path_col
pub const depth: depth_col = __rustango_cols_Page::depth_col
pub const parent_id: parent_id_col = __rustango_cols_Page::parent_id_col
pub const locale_variant_of: locale_variant_of_col = __rustango_cols_Page::locale_variant_of_col
pub const alias_of: alias_of_col = __rustango_cols_Page::alias_of_col
pub const theme_id: theme_id_col = __rustango_cols_Page::theme_id_col
pub const sort_order: sort_order_col = __rustango_cols_Page::sort_order_col
pub const status: status_col = __rustango_cols_Page::status_col
pub const published_at: published_at_col = __rustango_cols_Page::published_at_col
pub const last_published_at: last_published_at_col = __rustango_cols_Page::last_published_at_col
pub const go_live_at: go_live_at_col = __rustango_cols_Page::go_live_at_col
pub const expire_at: expire_at_col = __rustango_cols_Page::expire_at_col
pub const seo_title: seo_title_col = __rustango_cols_Page::seo_title_col
pub const seo_description: seo_description_col = __rustango_cols_Page::seo_description_col
pub const robots_index: robots_index_col = __rustango_cols_Page::robots_index_col
pub const sitemap_priority: sitemap_priority_col = __rustango_cols_Page::sitemap_priority_col
pub const preview_path: preview_path_col = __rustango_cols_Page::preview_path_col
pub const template_override: template_override_col = __rustango_cols_Page::template_override_col
pub const og_title: og_title_col = __rustango_cols_Page::og_title_col
pub const og_description: og_description_col = __rustango_cols_Page::og_description_col
pub const og_image_media_id: og_image_media_id_col = __rustango_cols_Page::og_image_media_id_col
pub const twitter_card: twitter_card_col = __rustango_cols_Page::twitter_card_col
pub const notification_pre_published_sent: notification_pre_published_sent_col = __rustango_cols_Page::notification_pre_published_sent_col
pub const created_at: created_at_col = __rustango_cols_Page::created_at_col
pub const updated_at: updated_at_col = __rustango_cols_Page::updated_at_col
Sourcepub fn query() -> QuerySet<Page>
pub fn query() -> QuerySet<Page>
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 in a single round-trip. 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)(target ignored — 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.
Empty slice is a no-op.
§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 in a single statement,
matched by primary key.
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 one
[#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.
§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.
§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!).
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