Model API Reference
RustF provides a database model system with query builders and type-safe database access.
Model Traits
BaseModel
All database models implement the BaseModel trait. It uses associated constants
(TABLE_NAME, PRIMARY_KEY) and an associated type (IdType) rather than methods.
The trait is async (it uses #[async_trait]).
#![allow(unused)]
fn main() {
#[async_trait]
pub trait BaseModel: ChangeTracking + Sized + Clone + Send + Sync + 'static
where
Self: Serialize + for<'de> Deserialize<'de>,
{
/// The Rust type of the primary key (e.g. i32, i64, String, Uuid)
type IdType: Clone + Send + Sync + Display + Into<SqlValue> + 'static;
/// The database table name
const TABLE_NAME: &'static str;
/// The primary key column name (e.g. "id")
const PRIMARY_KEY: &'static str;
/// Get the ID value of this instance
fn id(&self) -> Self::IdType;
// ... plus static helpers (query, get_by_id, get_all, count, ...)
// and instance methods (update, delete) shown below.
}
}
A generated model declares these like so:
#![allow(unused)]
fn main() {
impl BaseModel for Users {
type IdType = i32;
const TABLE_NAME: &'static str = "users";
const PRIMARY_KEY: &'static str = "id";
fn id(&self) -> Self::IdType {
self.id
}
// ...
}
}
ModelQuery
ModelQuery<T> is a struct (not a trait) that wraps the query builder and
returns typed results. You obtain one from Model::query() and chain methods on it.
#![allow(unused)]
fn main() {
pub struct ModelQuery<T> { /* ... */ }
}
Query Builder
Basic Queries
All of these are async and return rustf::Result.
#![allow(unused)]
fn main() {
use rustf::prelude::*;
// Fetch by primary key -> Result<Option<Users>>
let user = Users::get_by_id(1).await?;
// Fetch all rows -> Result<Vec<Users>>
let users = Users::get_all().await?;
// Query with conditions. `query()` returns Result, so it needs `?`.
// Terminate the chain with `.get()` (Vec) or `.get_first()` (Option).
let active_users = Users::query()?
.where_eq("is_active", true)
.get()
.await?;
}
Where Clauses
#![allow(unused)]
fn main() {
Users::query()?
.where_eq("status", "active")
.where_ne("deleted", true)
.where_gt("age", 18)
.where_lt("created_at", "2024-01-01")
.where_like("name", "%john%")
.where_in("id", vec![1, 2, 3])
.get()
.await?;
}
Ordering
#![allow(unused)]
fn main() {
Users::query()?
.order_by("created_at", OrderDirection::Desc)
.get()
.await?;
}
Pagination
#![allow(unused)]
fn main() {
// Simple pagination (legacy)
Users::query()?
.limit(10)
.offset(20)
.get_all()
.await?;
// Pagination with metadata (recommended)
let result = Users::query()?
.where_eq("is_active", true)
.get_paginated(2, 20)
.await?;
// Access data and metadata
for user in &result.rows {
println!("User: {}", user.username);
}
println!("Page {} of {}", result.page, result.total_pages);
println!("Total: {}", result.total_rows);
// Convert to Pagination for templates
let pagination = U::pagination_from_paged_result(&result, "/users?page={0}");
}
Aggregations
count() is an async terminator on ModelQuery. There are no dedicated max() /
avg() helpers — for those, use select_raw(...) with get_raw(), which returns
the rows as serde_json::Value.
#![allow(unused)]
fn main() {
// Count matching rows -> Result<i64>
let count = Users::query()?
.where_eq("is_active", true)
.count()
.await?;
// MAX / AVG via raw SELECT expressions
let rows = Users::query()?
.select_raw(&["MAX(age) as max_age", "AVG(score) as avg_score"])
.get_raw()
.await?;
let max_age = rows[0]["max_age"].as_i64().unwrap_or(0);
let avg_score = rows[0]["avg_score"].as_f64().unwrap_or(0.0);
}
Model Operations
BaseModel itself exposes only update(&mut self) and delete(self) for
persistence — there is no create() or save() on the trait. New records are
inserted through the generated builder, whose save() validates the fields
and performs the INSERT.
Create
#![allow(unused)]
fn main() {
// Each generated model has a typed builder with one method per column.
let user = Users::builder()
.username("jdoe")
.email("john@example.com")
.first_name("John")
.last_name("Doe")
.save()
.await?; // -> rustf::Result<Users>
}
Update
update() uses change tracking and only writes the fields you modified via the
generated set_* setters.
#![allow(unused)]
fn main() {
let mut user = Users::get_by_id(1).await?.unwrap();
user.set_first_name("Jane");
user.update().await?; // consumes &mut self
}
Delete
#![allow(unused)]
fn main() {
let user = Users::get_by_id(1).await?.unwrap();
user.delete().await?; // consumes self
}
Global Database Access
DB::query() takes no arguments and returns a Result<QueryBuilder> you build
up programmatically. For raw parameterized SQL, use DB::fetch_all_with_params
(returns rows as serde_json::Value) or DB::execute_with_params (returns the
number of affected rows).
#![allow(unused)]
fn main() {
use rustf::db::DB;
use rustf::database::types::SqlValue;
// Start a programmatic query builder (no SQL string, no args)
let qb = DB::query()?;
// Raw parameterized SELECT -> Result<Vec<serde_json::Value>>
let rows = DB::fetch_all_with_params(
"SELECT * FROM users WHERE id = ?",
vec![SqlValue::Int(1)],
).await?;
// Raw parameterized INSERT/UPDATE/DELETE -> Result<u64> (rows affected)
let affected = DB::execute_with_params(
"UPDATE users SET is_active = ? WHERE id = ?",
vec![SqlValue::Bool(false), SqlValue::Int(1)],
).await?;
}
Transactions: there is no
DB::transaction(...)helper in the current API. Use raw SQL (BEGIN/COMMIT/ROLLBACK) viaDB::execute_with_params, or the underlying SQLx pool obtained fromDB(e.g.DB::sqlite_pool()), if you need transactional control.
Model Registration
Models are auto-discovered:
#![allow(unused)]
fn main() {
let app = RustF::new()
.models(auto_models!());
}
Examples
Complete Model Usage
#![allow(unused)]
fn main() {
// Find user by primary key
let user = Users::get_by_id(1).await?;
// Query with conditions
let active_users = Users::query()?
.where_eq("is_active", true)
.order_by("created_at", OrderDirection::Desc)
.limit(10)
.get()
.await?;
// Create new user via the generated builder
let new_user = Users::builder()
.username("alice")
.email("alice@example.com")
.first_name("Alice")
.save()
.await?;
// Update user (only changed fields are written)
let mut user = Users::get_by_id(1).await?.unwrap();
user.set_first_name("Bob");
user.update().await?;
// Delete user
let user = Users::get_by_id(1).await?.unwrap();
user.delete().await?;
}