Expand description
Core runtime of rok-db.
Most users should depend on the rok-db crate, which re-exports
everything here together with the #[derive(Model)] macro.
Re-exports§
pub use join::InScope;pub use join::IntoJoin;pub use join::JoinOn;pub use join::Joined;pub use notify::Change;pub use notify::ChangeOp;pub use notify::ChangeStream;pub use notify::Listener;pub use notify::Notification;pub use relation::BelongsTo;pub use relation::HasMany;pub use relation::HasOne;pub use validate::ValidationErrors;pub use sqlx;
Modules§
- audit
- A trigger-based audit log (feature
json): every insert, update and delete of an audited table — through rok-db, bulk queries or raw SQL — is recorded inrok_audit_logwith the old and new row as JSONB. - join
- Typed joins (RFC 0001).
- metrics
- Metrics through the
metricsfacade (featuremetrics). Install any recorder (Prometheus, StatsD, OpenTelemetry, …) and rok-db reports: - migration
- Versioned migrations embedded in Rust code.
- notify
- PostgreSQL
LISTEN/NOTIFY, and typed change feeds for models. - relation
- Relations between models, declared with
#[derive(Model)]attributes. The parent model must have a single-column primary key. - tenant
- Row-level multi-tenancy for models with a
#[rok(tenant)]column. - testing
- Test support: a fresh, isolated database per test (feature
testing). - validate
- Validation of model fields, run automatically before
insert,save,upsertandinsert_many. - web
- Web integration: serde support (feature
serde) and axum responses (featureaxum).
Macros§
- impl_
value - Make a type usable as a rok-db column value (in models, filters and
set), given that it already implements sqlx’sTypeandEncodefor PostgreSQL plusClone + Debug. ImplementsCustomTypeandFrom<T>/From<&T>forValue(Option<T>then works too).
Structs§
- Cache
Stats - Counters describing how a
QueryCacheis performing. - Column
- A column of model
M. - Cursor
- An opaque position in a keyset-paginated result, returned by
Select::cursor_paginate. - Cursor
Page - One page of a keyset-paginated query.
- Custom
Value - A value of a user-defined type; see
Value::custom. - Db
- A pooled PostgreSQL connection handle — the entry point of rok-db.
- DbBuilder
- Builder for a
Dbconnection pool, created withDb::builder. - Expr
- A boolean condition on model
M, used inWHEREclauses. - Insert
- An
INSERTof a single row built column by column, created withModel::create. Columns you don’t set get their database default; timestamp columns default tonow(). - Insert
Many - An
INSERTof whole records, created withModel::insert_many. Generated columns are skipped and timestamps are set tonow(). - Memoized
- A
Selectwhose results are cached, created withSelect::memoize. - Order
- An
ORDER BYterm on modelM, created withColumn::ascorColumn::desc. - Page
- One page of results, returned by
Select::paginate. - Pool
Stats - Connection pool statistics, from
Db::stats. - Projected
- A
SELECTof specific columns or aggregates, created withSelect::select. Decode rows into tuples or anysqlx::FromRowtype. - Projection
- A value expression of model
Mthat can be selected: a column, an aggregate (User::AGE.avg()), a cast or raw SQL. - Query
Cache - An in-memory cache for memoized query results.
- Raw
- A raw SQL query with bound parameters, created with
raw. - Select
- A
SELECTquery over modelM, created withModel::queryorModel::filter. - Sql
- A rendered SQL statement together with its bound parameters.
- Tracked
- A record that remembers its loaded values, so
savewrites only the columns you changed — or nothing at all. - Tx
- An open database transaction, created with
Db::begin. - TxOptions
- Settings for
Db::transaction_with. - Update
- A bulk
UPDATEover modelM, created withModel::update_allorSelect::update.
Enums§
- Copy
Target - Where
Model::copy_inruns: a pool (one connection is borrowed), a transaction or a plain connection. - Direction
- Sort direction for
ORDER BY. - Error
- Every error rok-db can produce.
- Isolation
- Transaction isolation level, see
TxOptions::isolation. - Value
- A dynamically typed, bindable SQL value.
Traits§
- Custom
Type - Marker for user-defined column types stored through
Value::custom. - Executor
- Anything that can run a query:
&Db,&mut Tx, a plain sqlx&PgPoolor&mut PgConnection. - Hooks
- Lifecycle hooks, called around the record-level writes of
Model(insert,insert_all/insert_many,upsert,save,delete,force_delete). Bulk query operations (Select::update,Select::delete, …) don’t call hooks. - IntoKey
- A primary key value: a single value, or a tuple for models with a
composite primary key (
#[rok(primary_key)]on several fields). - Into
Projections - A list of
Projections: a single column or projection, a tuple of up to 12 of them, an array or aVec. - Model
- A database-backed record.
- Retryable
- Errors that can tell whether retrying the transaction might succeed.
Implemented for
Error; implement it for your own error type (usually by delegating to a wrappedrok_db::Error) to use it withDb::transaction_with. - Stream
Ext - Extension traits for consuming streams (
try_next,try_collect, …). An extension trait forStreams that provides a variety of convenient combinator functions. - TryStream
Ext - Extension traits for consuming streams (
try_next,try_collect, …). Adapters specific toResult-returning streams
Functions§
- raw
- Start a raw SQL query — the escape hatch for anything the query builder doesn’t express.
Type Aliases§
- BoxFuture
- A boxed
Sendfuture, as returned byDb::transactionclosures. An owned dynamically typedFuturefor use in cases where you can’t statically type your result or need to add some indirection. - BoxStream
- A boxed
Sendstream, as returned bySelect::stream. An owned dynamically typedStreamfor use in cases where you can’t statically type your result or need to add some indirection. - Result
- Convenient alias for results returned by rok-db.