Skip to main content

Page

Struct Page 

Source
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: i64

FK to cms_page_type.id — the registry row that names the handler responsible for this page.

§title: String§slug: String

URL slug, meant to be unique per parent. Not enforced by a DB constraint; page create / copy / alias dedup against siblings.

§path: String

Materialized path of zero-padded segment ids, trailing slash. Example: 0001/0003/0008/. Indexed for prefix lookups.

§url_path: String

Materialized 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: i32

Cached 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.rs still 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: i32

Ordering among siblings (lowest first).

§status: String

Lifecycle. 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: String

SEO metadata.

§seo_description: String§robots_index: bool

Whether 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: f32

Sitemap 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: String

Where 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: String

Template 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.

§show_in_menus: bool

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

Social-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: String

Twitter card variant. Accepted values: summary, summary_large_image. Default summary_large_image.

§notification_pre_published_sent: bool

Pre-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

Source

pub const id: id_col = __rustango_cols_Page::id_col

Source

pub const page_type_id: page_type_id_col = __rustango_cols_Page::page_type_id_col

Source

pub const title: title_col = __rustango_cols_Page::title_col

Source

pub const slug: slug_col = __rustango_cols_Page::slug_col

Source

pub const path: path_col = __rustango_cols_Page::path_col

Source

pub const url_path: url_path_col = __rustango_cols_Page::url_path_col

Source

pub const depth: depth_col = __rustango_cols_Page::depth_col

Source

pub const parent_id: parent_id_col = __rustango_cols_Page::parent_id_col

Source

pub const locale_variant_of: locale_variant_of_col = __rustango_cols_Page::locale_variant_of_col

Source

pub const alias_of: alias_of_col = __rustango_cols_Page::alias_of_col

Source

pub const theme_id: theme_id_col = __rustango_cols_Page::theme_id_col

Source

pub const sort_order: sort_order_col = __rustango_cols_Page::sort_order_col

Source

pub const status: status_col = __rustango_cols_Page::status_col

Source

pub const published_at: published_at_col = __rustango_cols_Page::published_at_col

Source

pub const last_published_at: last_published_at_col = __rustango_cols_Page::last_published_at_col

Source

pub const go_live_at: go_live_at_col = __rustango_cols_Page::go_live_at_col

Source

pub const expire_at: expire_at_col = __rustango_cols_Page::expire_at_col

Source

pub const seo_title: seo_title_col = __rustango_cols_Page::seo_title_col

Source

pub const seo_description: seo_description_col = __rustango_cols_Page::seo_description_col

Source

pub const robots_index: robots_index_col = __rustango_cols_Page::robots_index_col

Source

pub const sitemap_priority: sitemap_priority_col = __rustango_cols_Page::sitemap_priority_col

Source

pub const preview_path: preview_path_col = __rustango_cols_Page::preview_path_col

Source

pub const template_override: template_override_col = __rustango_cols_Page::template_override_col

Source

pub const show_in_menus: show_in_menus_col = __rustango_cols_Page::show_in_menus_col

Source

pub const og_title: og_title_col = __rustango_cols_Page::og_title_col

Source

pub const og_description: og_description_col = __rustango_cols_Page::og_description_col

Source

pub const og_image_media_id: og_image_media_id_col = __rustango_cols_Page::og_image_media_id_col

Source

pub const twitter_card: twitter_card_col = __rustango_cols_Page::twitter_card_col

Source

pub const notification_pre_published_sent: notification_pre_published_sent_col = __rustango_cols_Page::notification_pre_published_sent_col

Source

pub const created_at: created_at_col = __rustango_cols_Page::created_at_col

Source

pub const updated_at: updated_at_col = __rustango_cols_Page::updated_at_col

Source

pub fn objects() -> QuerySet<Page>

Start a new QuerySet over this model.

Source

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.

Source

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.

Source

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.

Source

pub async fn insert_pool(&mut self, pool: &Pool) -> Result<(), ExecError>

👎Deprecated since 0.62.0:

use insert

Old name of Self::insert.

§Errors

As Self::insert.

Source

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.

Source

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

As Self::bulk_insert.

Source

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 when target is 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.

Source

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

As Self::bulk_upsert_pool.

Source

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.

Source

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.

Source

pub async fn save_pool(&mut self, pool: &Pool) -> Result<u64, ExecError>

👎Deprecated since 0.62.0:

use save

Old name of Self::save.

§Errors

As Self::save.

Source

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.

Source

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.

Source

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.

Source

pub async fn delete_pool(&self, pool: &Pool) -> Result<u64, ExecError>

👎Deprecated since 0.62.0:

use delete

Old name of Self::delete.

§Errors

As Self::delete.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

As Self::save_partial.

Source

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.

Source

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

As UpdaterPool::execute_pool.

Source

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.

Source

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

As UpdaterPool::execute_pool.

Source

pub async fn decrement_each( col: &str, by: i64, pool: &Pool, ) -> Result<u64, ExecError>

Sibling of Self::increment_each — bulk-decrement.

§Errors

As Self::increment_each.

Source

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

As FetcherPool::fetch.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub async fn pluck<U>( col: &'static str, pool: &Pool, ) -> Result<Vec<U>, ExecError>
where U: FlatScalar,

Single-column projection — `SELECT FROM

`. Returns `Vec` where each element is the decoded value of the column. Eloquent `Model::pluck($column)` parity.

Thin wrapper over QuerySet::<Self>::default() .values_list_flat(col).fetch::<U>(pool). U is a FlatScalar; use Option<_> for a nullable column.

§Errors

As ValuesFlatQuerySet::fetch.

Source

pub async fn chunk<F, Fut>(n: i64, pool: &Pool, cb: F) -> Result<(), ExecError>
where F: FnMut(Vec<Self>) -> Fut, Fut: Future<Output = Result<(), ExecError>>,

Eloquent Model::chunk($n, fn ($chunk) { ... }) — stream every row of this model in batches of n, invoking the callback once per batch. Stable PK-ASC ordering so the LIMIT/OFFSET pagination is deterministic across drivers.

The callback is async — it can do further DB work (writes, related-row lookups, queue dispatch) per batch. Return Err(...) from the callback to abort the iteration early; the error bubbles up.

When to use: bulk processing flows that can’t fit the whole table in memory — sending newsletters, running data migrations, computing summary statistics. For small / known-bounded tables, plain Self::all(&pool) is simpler.

Caveat: ascending OFFSET pagination is O(N²) on large tables. For multi-million-row scans prefer keyset-by-PK (the standard “WHERE id > last_seen” shape) over chunk(...).

Skipped on models without a primary key — chunking needs a stable order to avoid skipping / repeating rows across batches.

Source

pub async fn chunk_by_id<F, Fut>( n: i64, pool: &Pool, cb: F, ) -> Result<(), ExecError>
where F: FnMut(Vec<Self>) -> Fut, Fut: Future<Output = Result<(), ExecError>>,

Eloquent Model::chunkById($n, fn (...)) — same per-batch callback shape as Self::chunk, but uses keyset pagination (WHERE pk > last_seen LIMIT n) instead of OFFSET. O(N) total scan vs OFFSET’s O(N²) — the right choice for multi-million-row sweeps.

The keyset compares the primary key in its own type, so any orderable PK works (i32, i64, UUID, string).

Callback errors abort iteration; the error bubbles up unchanged. Empty table → callback invoked zero times.

Source

pub async fn each<F, Fut>( batch: i64, pool: &Pool, cb: F, ) -> Result<(), ExecError>
where F: FnMut(Self) -> Fut, Fut: Future<Output = Result<(), ExecError>>,

Eloquent Model::each(fn ($row) { ... }, $n) — per-row callback companion to Self::chunk. Streams every row in keyset-paginated batches of batch size, calling cb once per row.

Inherits the keyset-paginated scan of Self::chunk_by_id (O(N) total).

ⓘ
Post::each(500, &pool, |p| async move {
    reindex(p).await?;
    Ok(())
}).await?;

Return Err(...) from the callback to abort iteration; the error bubbles up unchanged.

Source

pub async fn truncate(pool: &Pool) -> Result<u64, ExecError>

Delete every row of this model with one `DELETE FROM

` on every backend; returns the rows deleted. Each FK's `ON DELETE` applies, so a `RESTRICT` / `NO ACTION` row still pointing here refuses it; see [`truncate_cascade`](Self::truncate_cascade).

Use only in tests / fixture-reset flows. No per-row pre_delete / post_delete signals fire. An audited model gets one bulk audit entry, not one per row. Global scopes do not apply: every row goes, generic M2M links too.

§Errors

As truncate.

Source

pub async fn truncate_cascade(pool: &Pool) -> Result<(), ExecError>

truncate, also emptying every table that references this one, transitively and whatever its ON DELETE. The same on every backend.

§Errors

As truncate_cascade.

Source

pub async fn destroy<V>( pks: impl IntoIterator<Item = V>, pool: &Pool, ) -> Result<u64, ExecError>
where V: Into<SqlValue>,

Bulk-delete every row whose primary key is in pks — DELETE FROM <table> WHERE <pk> IN (...). Returns the affected row count.

Eloquent Model::destroy([1, 2, 3]) parity. Empty pks is a no-op (returns 0). All or none: past the bind cap the batches share one transaction.

Accepts any iterable whose elements are Into<SqlValue> — Vec<i64>, &[i64], [i64; N], etc.

§Errors

As delete_pool.

Source

pub async fn where_( col: &str, val: impl Into<SqlValue>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> = <val>. Eloquent Model::where($col, $val)->get() parity.

Thin wrapper over QuerySet::<Self>::default() .filter(col, val).fetch(pool). For one row, use Self::first_where; for a chain that needs further .filter() / .order_by() / .limit(), drop down to Self::query().filter(...) directly.

val accepts any value Into<SqlValue> so plain strings, ints, UUIDs, etc. all work.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_in<V>( col: &str, vals: impl IntoIterator<Item = V>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>
where V: Into<SqlValue>,

Fetch every row where <col> IN (vals). Eloquent Model::whereIn($col, $vals)->get() parity. Empty vals returns no rows (matches SQL’s empty-IN semantics).

vals accepts any iterable whose items are Into<SqlValue> — Vec<i64>, &[&str], [Uuid; N], etc.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_not_in<V>( col: &str, vals: impl IntoIterator<Item = V>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>
where V: Into<SqlValue>,

Fetch every row where <col> NOT IN (vals). Eloquent Model::whereNotIn($col, $vals)->get() parity. Empty vals returns every row (matches SQL’s empty-NOT-IN semantics — vacuously true for every row).

§Errors

As FetcherPool::fetch; ExecError::InListUnsplittable when vals pass the backend’s bind cap.

Source

pub async fn where_null(col: &str, pool: &Pool) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> IS NULL. Eloquent Model::whereNull($col)->get() parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_not_null( col: &str, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> IS NOT NULL. Eloquent Model::whereNotNull($col)->get() parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn random_n(n: i64, pool: &Pool) -> Result<Vec<Self>, ExecError>

Fetch up to n rows in random order. Eloquent Model::inRandomOrder()->limit($n)->get() / Model::query()->inRandomOrder()->get()->take($n) parity. Performance caveat: random ordering forces a full table scan + per-row random key sort; the optimizer cannot use an index. Prefer a pk >= rand_offset LIMIT N walk for huge tables.

§Errors

As FetcherPool::fetch.

Source

pub async fn random(pool: &Pool) -> Result<Option<Self>, ExecError>

Fetch one row in random order. Eloquent Model::inRandomOrder()->first() parity. Same performance caveat as Self::random_n.

§Errors

As FetcherPool::fetch.

Source

pub async fn oldest(field: &str, pool: &Pool) -> Result<Vec<Self>, ExecError>

Fetch every row ordered ASC by field. Eloquent Model::oldest($field)->get() parity — the multi-row counterpart of Self::earliest.

§Errors

As FetcherPool::fetch.

Source

pub async fn newest(field: &str, pool: &Pool) -> Result<Vec<Self>, ExecError>

Fetch every row ordered DESC by field. Eloquent Model::latest($field)->get() parity — the multi-row counterpart of Self::latest.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_year( col: &str, year: i64, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where EXTRACT(YEAR FROM <col>) = year. Eloquent Model::whereYear($col, $year)->get() parity. Routes through the existing __year lookup suffix (issue #829).

§Errors

As FetcherPool::fetch.

Source

pub async fn where_month( col: &str, month: i64, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where EXTRACT(MONTH FROM <col>) = month. Eloquent Model::whereMonth($col, $m)->get() parity. month is 1–12.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_day( col: &str, day: i64, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where EXTRACT(DAY FROM <col>) = day. Eloquent Model::whereDay($col, $d)->get() parity. day is 1–31.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_hour( col: &str, hour: i64, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where EXTRACT(HOUR FROM <col>) = hour. Eloquent Model::whereHour($col, $h)->get() parity. hour is 0–23.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_minute( col: &str, minute: i64, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where EXTRACT(MINUTE FROM <col>) = minute. Eloquent Model::whereMinute($col, $m)->get() parity. minute is 0–59.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_like( col: &str, pattern: impl Into<String>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> LIKE <pattern> — caller-supplied pattern (must include % / _ wildcards manually). Eloquent Model::whereLike parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_ilike( col: &str, pattern: impl Into<String>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> ILIKE <pattern> — case-insensitive LIKE (PG native, MySQL/SQLite emulated via LOWER(col) LIKE LOWER(pattern)).

§Errors

As FetcherPool::fetch.

Source

pub async fn where_starts_with( col: &str, prefix: impl Into<String>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> starts with prefix (auto-appends %). Eloquent whereLike("col", "$prefix%") parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_ends_with( col: &str, suffix: impl Into<String>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> ends with suffix (auto-prepends %). Eloquent whereLike("col", "%$suffix") parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_contains( col: &str, substr: impl Into<String>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> contains substr (auto-wraps with %). Eloquent whereLike("col", "%$substr%") parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_gt( col: &str, val: impl Into<SqlValue>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> > val. Eloquent Model::where($col, ">", $val)->get() parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_gte( col: &str, val: impl Into<SqlValue>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> >= val. Eloquent Model::where($col, ">=", $val)->get() parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_lt( col: &str, val: impl Into<SqlValue>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> < val. Eloquent Model::where($col, "<", $val)->get() parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_lte( col: &str, val: impl Into<SqlValue>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> <= val. Eloquent Model::where($col, "<=", $val)->get() parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_ne( col: &str, val: impl Into<SqlValue>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> <> val. Eloquent Model::where($col, "!=", $val)->get() parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_any( cols: &[&str], val: impl Into<SqlValue>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row matching <col> = val for ANY of the listed columns. Eloquent Model::whereAny($cols, $val) parity. Empty cols returns no rows.

Resolves each &str column to its SCHEMA-registered &'static str once and builds a single OR-composed Q expression (col1 = ? OR col2 = ? OR …).

§Errors

As FetcherPool::fetch; QueryError::UnknownField when any column is not declared on the model.

Source

pub async fn where_all( cols: &[&str], val: impl Into<SqlValue>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row matching <col> = val for ALL listed columns. Eloquent Model::whereAll($cols, $val) parity. Empty cols returns every row (vacuous AND).

§Errors

As Self::where_any.

Source

pub async fn take(n: i64, pool: &Pool) -> Result<Vec<Self>, ExecError>

Fetch up to n rows. Eloquent Model::take($n)->get() parity. PK-ordered is NOT guaranteed without an explicit order_by — drop into Self::query() for that.

§Errors

As FetcherPool::fetch.

Source

pub async fn for_page( page: i64, per_page: i64, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch the page-th window of per_page rows (1-indexed). Eloquent Model::query()->forPage($page, $perPage)->get() parity. The DB scans an OFFSET (page - 1) * per_page LIMIT per_page; for large offsets this is O(N) — prefer keyset pagination via PK on hot paths.

§Errors

As FetcherPool::fetch.

Source

pub async fn paginate( page: i64, per_page: i64, pool: &Pool, ) -> Result<(Vec<Self>, i64), ExecError>

Eloquent Model::paginate($per_page, $page) — fetch one page of rows AND the total row count in one call. Returns (rows, total). Two queries: a LIMIT/OFFSET SELECT for the page + a SELECT COUNT(*) for the total.

Useful for paginated UIs that need both the visible rows AND a “Page X of Y” / total-count widget. For large tables prefer keyset pagination + cached count; every call to paginate re-counts the full table.

Same 1-indexed page convention as Self::for_page.

§Errors

As Self::for_page and Self::count.

Source

pub async fn update_where( where_col: &str, where_val: impl Into<SqlValue>, set_col: &str, set_val: impl Into<SqlValue>, pool: &Pool, ) -> Result<u64, ExecError>

Bulk-update — set set_col = set_val on every row matching where_col = where_val. Returns affected row count. Eloquent Model::where($where_col, $where_val)->update([$set_col => $set_val]) parity.

For multi-column updates drop into the queryset builder: Self::query().filter(...).update().set(...).set(...).execute_pool(&pool).

§Errors

As UpdaterPool::execute_pool.

Source

pub async fn delete_where( where_col: &str, where_val: impl Into<SqlValue>, pool: &Pool, ) -> Result<u64, ExecError>

Bulk-delete — remove every row matching where_col = where_val. Returns affected row count. Eloquent Model::where($where_col, $where_val)->delete() parity.

§Errors

As [#root::sql::delete_pool].

Source

pub async fn update_all( set_col: &str, set_val: impl Into<SqlValue>, pool: &Pool, ) -> Result<u64, ExecError>

Bulk-update — set set_col = set_val on EVERY row of this model’s table. No WHERE clause — use with care. Eloquent Model::query()->update([$col => $val]) parity.

Use for backfills, one-shot reset flows, etc. The returned count is rows affected.

§Errors

As UpdaterPool::execute_pool.

Source

pub async fn where_not_like( col: &str, pattern: impl Into<String>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> NOT LIKE <pattern>. Eloquent Model::whereNotLike parity. Pattern is passed verbatim — caller controls % / _.

§Errors

As FetcherPool::fetch.

Source

pub async fn where_not_ilike( col: &str, pattern: impl Into<String>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> NOT ILIKE <pattern> — case-insensitive NOT LIKE (PG native, MySQL / SQLite emulated via LOWER(col) NOT LIKE LOWER(pattern)).

§Errors

As FetcherPool::fetch.

Source

pub async fn where_not_between( col: &str, lo: impl Into<SqlValue>, hi: impl Into<SqlValue>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> NOT BETWEEN lo AND hi. Eloquent Model::whereNotBetween($col, [$lo, $hi]) parity.

§Errors

As FetcherPool::fetch.

Source

pub fn table_name() -> &'static str

Returns the SQL table name for this model. Eloquent $model->getTable() parity.

Source

pub fn primary_key_column() -> Option<&'static str>

Returns the SQL column name of this model’s primary key, or None when the model has no #[rustango(primary_key)]. Eloquent $model->getKeyName() parity.

Source

pub async fn where_between( col: &str, lo: impl Into<SqlValue>, hi: impl Into<SqlValue>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>

Fetch every row where <col> BETWEEN lo AND hi (inclusive on both ends — same as SQL). Eloquent Model::whereBetween($col, [$lo, $hi])->get() parity.

§Errors

As FetcherPool::fetch.

Source

pub async fn first_where( col: &str, val: impl Into<SqlValue>, pool: &Pool, ) -> Result<Option<Self>, ExecError>

Fetch the first row where <col> = <val>. Returns Ok(None) when no row matches. Eloquent Model::firstWhere($col, $val) parity.

Thin wrapper over QuerySet::<Self>::default() .filter(col, val).first(pool). Use this when you want one row identified by a non-PK column (e.g. User::first_where_pool("email", "x@y.com", &pool)).

val accepts any value Into<SqlValue> so plain strings, ints, UUIDs, etc. all work.

§Errors

As QuerySet::first.

Source

pub async fn value<U>(col: &str, pool: &Pool) -> Result<Option<U>, ExecError>
where U: FlatScalar,

Pluck a single scalar from the first row. Eloquent Model::query()->value($col) parity.

Skipped on models that already declare a field named value. Drop into QuerySet::<Self>::default().values_list_flat(col).first::<U>(&pool) instead.

§Errors

As ValuesFlatQuerySet::first.

Source

pub async fn latest(field: &str, pool: &Pool) -> Result<Option<Self>, ExecError>

Fetch the row with the largest non-NULL field value. Returns Ok(None) when the table is empty or every field is NULL. Thin wrapper over QuerySet::<Self>::default().latest(field, pool).

Field name is the Rust field ident as a string (not the SQL column). It is a runtime &str, so an unknown one compiles and surfaces as ExecError::Query(QueryError::UnknownField) when the query runs.

§Errors

As QuerySet::latest.

Source

pub async fn earliest( field: &str, pool: &Pool, ) -> Result<Option<Self>, ExecError>

Sibling of Self::latest: fetches the row with the smallest non-NULL field value.

§Errors

As Self::latest.

Source

pub async fn count(pool: &Pool) -> Result<i64, ExecError>

Count rows of this model — `SELECT COUNT(*) FROM

`. Eloquent `Model::count()` parity.

Skipped on models that already declare a field named count. Drop into QuerySet::<Self>::default().count(&pool) in that case.

§Errors

As CounterPool::count.

Source

pub async fn exists(pool: &Pool) -> Result<bool, ExecError>

true when the table contains at least one row. Eloquent Model::query()->exists() parity. Thin wrapper over QuerySet::<Self>::default().exists(pool).

§Errors

As ExistsPool::exists.

Source

pub async fn doesnt_exist(pool: &Pool) -> Result<bool, ExecError>

Inverse of Self::exists — returns true when the table has zero rows. Eloquent Model::doesntExist() parity.

§Errors

As Self::exists.

Source

pub async fn contains_pk( pk: impl Into<SqlValue> + Send, pool: &Pool, ) -> Result<bool, ExecError>

Eloquent Model::query()->whereKey($pk)->exists() — true when a row with primary key pk exists in the table. Sugar over QuerySet::<Self>::default().contains_pk(pool, pk).

Differs from Self::exists (which checks “any row in the table”) by checking a specific PK existence. Cheaper than Self::find(pk, &pool).await?.is_some() because the row is never materialized — the SQL is SELECT COUNT(*) > 0 FROM <table> WHERE pk = ?.

§Errors

As [#root::sql::ExistsPool::contains_pk].

Source

pub async fn sum<U>(col: &str, pool: &Pool) -> Result<Option<U>, ExecError>

SUM(col) over every row. Eloquent Model::sum($col). Skipped on models that already declare a field named sum.

§Errors

As [#root::sql::fetch_aggregate_pool].

Source

pub async fn avg<U>(col: &str, pool: &Pool) -> Result<Option<U>, ExecError>

AVG(col). Eloquent Model::avg($col). Skipped on models that already declare a field named avg.

§Errors

As [#root::sql::fetch_aggregate_pool].

Source

pub async fn min<U>(col: &str, pool: &Pool) -> Result<Option<U>, ExecError>

MIN(col). Eloquent Model::min($col). Skipped on models that already declare a field named min.

§Errors

As [#root::sql::fetch_aggregate_pool].

Source

pub async fn max<U>(col: &str, pool: &Pool) -> Result<Option<U>, ExecError>

MAX(col). Eloquent Model::max($col). Skipped on models that already declare a field named max.

§Errors

As [#root::sql::fetch_aggregate_pool].

Source

pub async fn all(pool: &Pool) -> Result<Vec<Self>, ExecError>

Fetch every row of this model from pool. Eloquent Model::all() parity — a thin wrapper over QuerySet::<Self>::default().fetch(pool).

Use with care on large tables — there’s no pagination or limit; the entire table is materialized into memory. For anything beyond fixture / lookup tables, page through QuerySet::<Self>::default() .order_by(...).limit(N).offset(M).fetch(pool) or stream via .iterator(chunk_size).

§Errors

As FetcherPool::fetch.

Source

pub async fn find_many<V>( pks: impl IntoIterator<Item = V>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>
where V: Into<SqlValue>,

Look up every row whose primary key is in pks. Returns the matching rows in inventory order — NOT the order of pks. Empty pks returns an empty Vec. Eloquent Model::find([1, 2, 3]) (when called with a list) parity.

Thin wrapper over QuerySet::<Self>::default() .filter("<pk>__in", SqlValue::List([...])).fetch(pool). Caller-supplied PKs that don’t match a row are silently skipped (the returned vec is shorter than the input list). For an order-preserving / “fail when any missing” variant, build the queryset explicitly with in_bulk instead.

Accepts any iterable whose elements are Into<SqlValue> — Vec<i64>, &[i64], [i64; N], Vec<Uuid>, etc.

§Errors

As FetcherPool::fetch.

Source

pub async fn find( pk: impl Into<SqlValue>, pool: &Pool, ) -> Result<Option<Self>, ExecError>

Look up the row whose primary key equals pk. Returns Ok(None) when no row matches, rather than erroring. Eloquent Model::find shape — accepts any value Into<SqlValue>.

One-liner shortcut for the common QuerySet::<Self>::default().filter("<pk_field>", pk) .limit(1).fetch(pool).await?.into_iter().next() dance.

§Errors

As FetcherPool::fetch.

Source

pub async fn find_or_fail( pk: impl Into<SqlValue>, pool: &Pool, ) -> Result<Self, ExecError>

Look up the row whose primary key equals pk. Errors when no row matches — the throwing counterpart of Self::find. Eloquent Model::findOrFail parity.

Translates the miss into ExecError::Driver(sqlx::Error::RowNotFound)) so callers can ?-bubble straight through the typical ExecError error chain.

§Errors

As Self::find; additionally sqlx::Error::RowNotFound when no row matches.

Source

pub async fn find_many_or_fail<V>( pks: impl IntoIterator<Item = V>, pool: &Pool, ) -> Result<Vec<Self>, ExecError>
where V: Into<SqlValue>,

Look up multiple rows by primary key, failing if any requested PK is missing. Eloquent Model::findOrFail([1, 2, 3]) parity. Returns rows in inventory order (NOT request order — same as Self::find_many).

Empty pks returns an empty Vec (no rows requested → nothing to fail on).

Differs from Self::find_many in that this method requires every PK to resolve. If even one is missing, the call surfaces sqlx::Error::RowNotFound (wrapped in ExecError::Driver). A key counts as found when the database matches it to a row, so repeats and keys its collation folds together (abc / ABC on MySQL) pass.

§Errors

As Self::find_many, plus RowNotFound when a requested PK matches no row.

Source

pub async fn find_or<F>( pk: impl Into<SqlValue>, pool: &Pool, fallback: F, ) -> Result<Self, ExecError>
where F: FnOnce() -> Self,

Find by primary key or run fallback to produce a default row to return. Eloquent Model::findOr($pk, fn() => …) parity.

Unlike Self::find_or_fail (which raises on miss), this is the “give me something sensible” branch: typical use is “fetch the user’s row, else fall back to an anonymous/guest stub”.

fallback runs only when no row matches — the DB round-trip happens unconditionally.

§Errors

As Self::find.

Source

pub async fn find_or_new<F>( pk: impl Into<SqlValue>, pool: &Pool, fallback: F, ) -> Result<(Self, bool), ExecError>
where F: FnOnce() -> Self,

Same as Self::find_or but also returns a bool indicating whether the row was found in the DB (true) or freshly built from fallback (false). Eloquent Model::findOrNew($pk, [attrs]) parity — in PHP the returned model also exposes ->exists; here that’s surfaced as the second tuple element.

Useful for edit-or-create form handlers where the caller needs to know whether to PATCH or POST when the user submits the form.

§Errors

As Self::find.

Source

pub async fn find_or_insert<F>( pk: impl Into<SqlValue>, pool: &Pool, fallback: F, ) -> Result<(Self, bool), ExecError>
where F: FnOnce() -> Self,

Eloquent Model::findOrCreate(pk, defaults) — like Self::find_or_new but persists the new row when the PK isn’t found. Returns (row, exists: bool) — exists=true when the PK was found, false when a fresh row was inserted.

ⓘ
let (post, found) = Post::find_or_insert(
    pk,
    &pool,
    || Post { id: Auto::default(), title: "new".into() },
).await?;
// `found` true → returned existing row;
// `found` false → fallback was inserted, `post.id` populated.

Caveat: two concurrent calls that both miss the find can both INSERT, violating uniqueness. Wrap in a transaction or rely on a UNIQUE constraint + handle the conflict error if you need race-free semantics.

§Errors

As Self::find and Self::save.

Source

pub async fn first_or<F>(pool: &Pool, fallback: F) -> Result<Self, ExecError>
where F: FnOnce() -> Self,

Fetch the first row of the table, or run fallback when the table is empty. Eloquent Model::firstOr(fn() => …) parity.

§Errors

As Self::first.

Source

pub async fn sole( col: &str, val: impl Into<SqlValue>, pool: &Pool, ) -> Result<Self, ExecError>

Fetch exactly one row matching <col> = <val>. Errors when zero rows match (ExecError::Driver(RowNotFound)) or more than one matches (ExecError::Query(QueryError::Sql(MultipleRowsReturned))). Eloquent Model::sole($col, $val) parity.

§Errors

As Self::where_ plus the explicit RowNotFound / MultipleRowsReturned cases above.

Source

pub async fn delete_tx(&self, tx: &mut PoolTx<'_>) -> Result<u64, ExecError>

Delete this row inside an open transaction; an audited model writes its audit row there too.

§Errors

As Self::delete.

Source

pub async fn insert_tx(&mut self, tx: &mut PoolTx<'_>) -> Result<(), ExecError>

Insert this row inside an open transaction; an audited model writes its audit row there too.

§Errors

As Self::insert.

Source

pub async fn save_tx(&mut self, tx: &mut PoolTx<'_>) -> Result<u64, ExecError>

Save this row inside an open transaction; an audited model writes its audit row there too.

§Errors

As Self::save.

Source

pub fn is(&self, other: &Self) -> bool

Returns true when other represents the same DB row as self — i.e. their primary keys compare equal. Eloquent $model->is($other) parity.

Because both arguments are typed &Self, the model/table check is automatic — Post::is cannot be invoked against a Comment at compile time. Only the PK has to be compared at runtime.

Source

pub fn is_not(&self, other: &Self) -> bool

Inverse of Self::is. Eloquent $model->isNot($other) parity.

Source

pub fn get_key(&self) -> SqlValue

Returns this row’s primary-key value as an [#root::core::SqlValue]. Eloquent $model->getKey() parity.

Useful when you need to thread the PK through a generic Into<SqlValue>-bound API without knowing the concrete PK type (i64 vs Uuid vs String).

Source§

impl Page

Typed access to Page::status (#763). The column stays a string — changing the field’s type would break every host that reads or writes it — so code goes through these instead of comparing literals, and the public-visibility rule lives in one place.

Source

pub fn page_status(&self) -> Option<PageStatus>

The page’s status, or None for a stored value no PageStatus names (an old import, a typo).

Source

pub fn set_page_status(&mut self, status: PageStatus)

Set the status from the enum, so only a value every reader understands is ever written.

Source

pub fn is_public(&self) -> bool

Whether visitors may see this page: published or archived. Use this, not status == "published", which misses archived pages.

Source§

impl Page

Source

pub async fn create_root( tenant: &Tenant, new: NewPage, ) -> Result<Self, TreeError>

Insert a new root page. Returns the persisted row with id, path, depth, and sort_order populated.

Source

pub async fn create_root_pool( pool: &Pool, new: NewPage, ) -> Result<Self, TreeError>

Backend-agnostic Self::create_root — takes a &Pool directly, so content can be seeded / scripted outside an HTTP request on any dialect. create_root needs a &Tenant, but Tenant is only publicly constructible on Postgres (test-gated), leaving no way to seed pages on SQLite/MySQL; this is that way.

Source

pub async fn create_child( tenant: &Tenant, parent: &Page, new: NewPage, ) -> Result<Self, TreeError>

Append a new child under parent. Sort order is the next integer after the parent’s existing children.

Validates the type constraint in both directions before inserting: the parent’s allowed_child_types must permit the child’s type, and the child’s allowed_parent_types must permit the parent’s type. Either failure short-circuits the write.

Source

pub async fn create_child_pool( pool: &Pool, parent: &Page, new: NewPage, ) -> Result<Self, TreeError>

Backend-agnostic Self::create_child — takes a &Pool directly so content can be seeded / scripted outside an HTTP request on any dialect (see Self::create_root_pool).

Source

pub async fn children(&self, pool: &Pool) -> Result<Vec<Page>, TreeError>

Immediate children, ordered by sort_order.

Source

pub async fn siblings(&self, pool: &Pool) -> Result<Vec<Page>, TreeError>

Pages that share this page’s parent (excluding self), ordered by sort_order. Roots return all other roots.

Source

pub async fn ancestors(&self, pool: &Pool) -> Result<Vec<Page>, TreeError>

All ancestors of this page from root → immediate parent. Empty for roots. Order is root-first.

Source

pub async fn descendants(&self, pool: &Pool) -> Result<Vec<Page>, TreeError>

All descendants (excluding self), ordered by path (which is also tree-pre-order).

Source

pub async fn move_to( &mut self, tenant: &Tenant, new_parent: Option<&Page>, ) -> Result<(), TreeError>

Move this page (and its entire subtree) under new_parent. Pass None to promote it to a root. The subtree’s url_paths follow in the same transaction, so the tree and the URLs never disagree.

Refuses cycles (moving under self or a descendant) and type-constraint violations (re-checks both directions against the new parent before writing).

Source

pub async fn move_to_in_tx( &mut self, new_parent: Option<&Page>, subtree: Vec<Page>, tx: &mut PoolTx<'_>, ) -> Result<(), TreeError>

Transaction-scoped core of move_to. Assumes cycle / placement validation has already run and subtree (this page’s descendants) was read on the pool before the transaction opened — so this makes no pool reads. That matters: reading the pool while holding a tx connection can deadlock a single-connection SQLite pool. Pre-reading lets a batch (bulk move) reparent many pages in one transaction.

§Errors

Driver errors from the lock / saves, or TreeError from path math.

Trait Implementations§

Source§

impl Clone for Page

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Page

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl<'de> Deserialize<'de> for Page

Source§

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
Source§

impl<'r> FromRow<'r, MySqlRow> for Page

Source§

fn from_row(row: &'r MySqlRow) -> Result<Self, Error>

Source§

impl<'r> FromRow<'r, PgRow> for Page

Available on crate feature postgres only.
Source§

fn from_row(row: &'r PgRow) -> Result<Self, Error>

Source§

impl<'r> FromRow<'r, SqliteRow> for Page

Source§

fn from_row(row: &'r SqliteRow) -> Result<Self, Error>

Source§

impl LoadRelatedMy for Page

Same contract as LoadRelated::__rustango_load_related — returns Ok(true) when field_name matched a known FK and the parent was decoded successfully, Ok(false) for unknown field names (graceful skip). Read more
Source§

impl LoadRelatedSqlite for Page

Same contract as LoadRelated::__rustango_load_related. Read more
Source§

impl Model for Page

Source§

const SCHEMA: &'static ModelSchema

Source§

fn reverse_relations() -> &'static [ReverseRelation]

Reverse-FK existence relations from #[rustango(reverse_has(name, child, child_fk_column))]. The macro overrides this; a model with none keeps the empty default. Read more
Source§

fn generic_reverse_relations() -> &'static [GenericReverseRelation]

Reverse generic-FK existence relations from #[rustango(generic_has(name, child, ct_column, pk_column))]. The macro overrides this; a model with none keeps the empty default. Read more
Source§

impl Serialize for Page

Source§

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer,

Serialize this value into the given Serde serializer. Read more

Auto Trait Implementations§

§

impl Forget for Page

§

impl Freeze for Page

§

impl RefUnwindSafe for Page

§

impl Send for Page

§

impl Sync for Page

§

impl Unpin for Page

§

impl UnsafeUnpin for Page

§

impl UnwindSafe for Page

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> FromRef<T> for T
where T: Clone,

Source§

fn from_ref(input: &T) -> T

Converts to this type from a reference to the input type.
Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<Unshared, Shared> IntoShared<Shared> for Unshared
where Shared: FromUnshared<Unshared>,

Source§

fn into_shared(self) -> Shared

Creates a shared type from an unshared type.
Source§

impl<T> MaybeMyFromRow for T
where T: for<'r> FromRow<'r, MySqlRow>,

Source§

impl<T> MaybeMyLoadRelated for T
where T: LoadRelatedMy,

Source§

impl<T> MaybePgFromRow for T
where T: for<'r> FromRow<'r, PgRow>,

Source§

impl<T> MaybeSqliteFromRow for T
where T: for<'r> FromRow<'r, SqliteRow>,

Source§

impl<T> MaybeSqliteLoadRelated for T

Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more