toasty/

lib.rs

#![warn(missing_docs)]
//! Toasty is an async ORM for Rust supporting both SQL (SQLite, PostgreSQL,
//! MySQL) and NoSQL (DynamoDB) databases.
//!
//! This crate is the user-facing API. It contains the database handle,
//! query execution traits, and the types that generated code builds on. For
//! a tutorial-style introduction, see the [Toasty guide].
//!
#![doc = include_str!(concat!(env!("OUT_DIR"), "/guide_link.md"))]
//!
//! # Modules
//!
//! ## [`db`] — database handle and connection pool
//!
//! The [`Db`] type is the entry point for all database interaction. It owns
//! a connection pool and provides [`Db::builder`] for configuration. The
//! module also contains [`Builder`](db::Builder) and the pool internals.
//!
//! ## [`schema`] — model, relation, and schema inspection
//!
//! The [`Model`](schema::Model) trait represents a root model that maps to a
//! database table. It is implemented by `#[derive(Model)]` — users do not
//! implement it manually. The module also contains [`Field`](schema::Field),
//! which provides schema registration and runtime helpers for field types, and
//! [`Auto`](schema::Auto), a wrapper for auto-generated values such as
//! database-assigned IDs.
//!
//! Relation fields can use [`Deferred`](schema::Deferred) for lazy loading or
//! direct relation values for eager loading. Lazy relations are populated
//! through `.include(...)` or generated relation accessors. Eager relations are
//! loaded whenever the model is loaded.
//!
//! The module also re-exports from `toasty-core` for inspecting the
//! app-level and db-level schema representations at runtime.
//!
//! ## [`stmt`] — typed statement and expression types
//!
//! Contains the typed wrappers around the statement AST:
//! [`Query`](stmt::Query), [`Insert`](stmt::Insert),
//! [`Update`](stmt::Update), [`Delete`](stmt::Delete), and
//! [`Statement`]. Also includes expression helpers like [`Expr`](stmt::Expr),
//! [`Path`](stmt::Path), and the [`in_list`](stmt::in_list) function.
//! Generated query builders (e.g. `find_by_*`, `filter_by_*`) produce these
//! types.
//!
//! ## [`sql`] — raw SQL execution helpers
//!
//! Contains [`sql::statement`] and [`sql::query`] for running backend SQL
//! through [`Db`], [`Connection`], or [`Transaction`] handles.
//!
//! # Key traits
//!
//! - [`Model`](schema::Model) — a root model backed by a database table.
//!   Implemented by `#[derive(Model)]`.
//! - [`Embed`](schema::Embed) — an embedded type whose fields are flattened
//!   into the parent model's table. Implemented by `#[derive(Embed)]`.
//! - [`Executor`] — the dyn-compatible interface for running statements.
//!   [`Db`] and [`Transaction`] both implement it. The generic
//!   [`exec`](Executor::exec) method on `dyn Executor` accepts any typed
//!   [`Statement<T>`].
//! - [`Load`](schema::Load) — deserializes a model instance from the database
//!   value representation.
//!
//! # Other key types
//!
//! - [`Transaction`] / [`TransactionBuilder`] — transactions with
//!   auto-rollback on drop and nested savepoint support.
//! - [`Page`](stmt::Page) — a page of results from a paginated query, with cursor-based
//!   navigation.
//! - [`Batch`](stmt::Batch) — groups multiple queries into a single round-trip.
//! - [`Capability`] / [`SqlPlaceholder`] — driver metadata, including SQL
//!   placeholder syntax for raw SQL.
//! - [`Error`] / [`Result`] — re-exported from `toasty-core`.
//!
//! # Derive macros
//!
//! - [`#[derive(Model)]`](derive@Model) — generates the
//!   [`Model`](schema::Model) impl, query builders, create/update builders,
//!   relation accessors, and schema registration for a struct.
//! - [`#[derive(Embed)]`](derive@Embed) — generates the
//!   [`Embed`](schema::Embed) impl for a type whose fields are stored inline
//!   in a parent model's table.
//!
//! # Feature flags
//!
//! Each database driver is behind an optional feature flag:
//!
//! | Feature        | Driver crate                 |
//! |----------------|------------------------------|
//! | `sqlite`       | `toasty-driver-sqlite`       |
//! | `postgresql`   | `toasty-driver-postgresql`   |
//! | `mysql`        | `toasty-driver-mysql`        |
//! | `dynamodb`     | `toasty-driver-dynamodb`     |
//! | `turso`        | `toasty-driver-turso`        |
//!
//! Additional feature flags: `rust_decimal`, `bigdecimal`, `jiff` (date/time
//! via the `jiff` crate), and `serde` (JSON serialization support).
//!
//! # Other crates in the workspace
//!
//! `toasty` depends on several internal crates that most users do not need
//! to use directly:
//!
//! - **`toasty-core`** — shared types used across the workspace: the schema
//!   representations (app-level and db-level), the statement AST, the
//!   [`Driver`](driver::Driver) trait, and [`Error`] / [`Result`].
//! - **`toasty-macros`** — the proc-macro entry points and the code generation
//!   logic they call.
//! - **`toasty-sql`** — serializes the statement AST to SQL strings. Used by
//!   the SQL driver crates.
//! - **`toasty-driver-*`** — one crate per database backend.

mod update_target;
pub use update_target::UpdateTarget;

// `Batch`, `batch()`, and `CreateMany` live in `stmt`.
pub use stmt::{Batch, batch};

/// Database handle, connection pool, executor trait, and transaction support.
pub mod db;
pub use db::{
    Capability, Connection, Db, Executor, SqlPlaceholder, Transaction, TransactionBuilder,
};

mod engine;

/// Schema migration types: history files, snapshots, and generation helpers.
#[cfg(feature = "migration")]
pub mod migration;

/// Model, relation, and schema inspection types.
pub mod schema;
pub use schema::Deferred;

// `Page` lives in `stmt`.

/// Typed statement, expression, and query builder types.
pub mod stmt;
#[cfg(feature = "serde")]
pub use stmt::Json;
pub use stmt::Statement;

/// Raw SQL execution helpers.
pub mod sql;

pub use toasty_macros::{Embed, Model, create, query, update};

pub use toasty_core::{Error, Result, schema::app::ModelSet};

pub mod codegen_support;