1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
//! # rok-db
//!
//! An ergonomic, type-safe async ORM for PostgreSQL, built on [`sqlx`].
//!
//! ```no_run
//! use rok_db::prelude::*;
//!
//! #[derive(Debug, Clone, Model)]
//! struct User {
//! #[rok(primary_key, generated)]
//! id: i64,
//! email: String,
//! name: Option<String>,
//! age: i32,
//! }
//!
//! # async fn run() -> rok_db::Result<()> {
//! let db = Db::connect("postgres://postgres@localhost/app").await?;
//!
//! // Create
//! let ann = User { id: 0, email: "ann@example.com".into(), name: None, age: 31 }
//! .insert(&db)
//! .await?;
//!
//! // Read with typed, model-scoped columns
//! let adults = User::filter(User::AGE.gte(18))
//! .filter(User::EMAIL.ends_with("@example.com"))
//! .order_by(User::AGE.desc())
//! .limit(10)
//! .all(&db)
//! .await?;
//!
//! // Update
//! let mut ann = User::find_or_fail(&db, ann.id).await?;
//! ann.name = Some("Ann".into());
//! let ann = ann.save(&db).await?;
//!
//! // Bulk update & delete
//! User::filter(User::AGE.lt(18)).update().set(User::NAME, None::<String>).exec(&db).await?;
//! User::filter(User::EMAIL.is_null()).delete(&db).await?;
//!
//! // Pagination (one round trip)
//! let page = User::order_by(User::ID).paginate(&db, 1, 20).await?;
//! println!("{} of {} users", page.len(), page.total);
//!
//! // Transactions
//! db.transaction(|tx| Box::pin(async move {
//! ann.delete(&mut *tx).await?;
//! Ok::<_, rok_db::Error>(())
//! })).await?;
//! # Ok(()) }
//! ```
//!
//! ## Defining models
//!
//! `#[derive(Model)]` implements [`Model`] and `sqlx::FromRow`, and adds one
//! typed [`Column`] constant per field (`User::EMAIL`, …). See
//! [`derive@Model`] for every attribute.
//!
//! ## Relations
//!
//! `#[rok(belongs_to = User)]`, `#[rok(has_many(posts = Post::USER_ID))]` and
//! `#[rok(has_one(..))]` generate relation constants ([`BelongsTo`],
//! [`HasMany`], [`HasOne`]) and lazy query methods. Eager-load related
//! records for many parents with one extra query: see [`relation`].
//!
//! ## More features
//!
//! - **Streaming**: [`Select::stream`] yields rows one at a time.
//! - **Aggregates & projections**: [`Select::sum`], [`Select::avg`],
//! [`Select::group_by`], [`Select::having`] and [`Select::select`] with
//! [`Projection`]s, decoded into tuples or [`derive@FromRow`] structs.
//! - **Timestamps**: `#[rok(timestamps)]` manages `created_at`/`updated_at`.
//! - **Memoization**: [`Select::memoize`] caches results in the pool's
//! [`QueryCache`] with automatic invalidation on writes.
//! - **Query logging**: every statement is logged through `tracing`
//! (`rok_db::query` at DEBUG, `rok_db::slow_query` at WARN; see
//! [`DbBuilder::slow_query_threshold`]).
//!
//! ## Executors
//!
//! Every query method accepts any [`Executor`]: `&Db`, `&mut Tx` (write
//! `&mut *tx` inside a transaction closure), or a plain sqlx `&PgPool` /
//! `&mut PgConnection` — so rok-db slots into existing sqlx code.
//!
//! ## Raw SQL
//!
//! When the builder isn't enough, [`raw()`] runs any SQL with `?` placeholders
//! and decodes into models or any `FromRow` type; [`Expr::raw`] embeds a raw
//! condition in a builder query. Every builder has a `to_sql()` method for
//! inspecting the generated statement.
//!
//! ## Cargo features
//!
//! | feature | enables |
//! |-----------|------------------------------------------------------|
//! | `chrono` | `chrono` date/time column types |
//! | `uuid` | `uuid::Uuid` columns |
//! | `json` | `serde_json::Value` and `sqlx::types::Json<T>` columns |
//! | `migrate` | [`Db::migrate`] for running sqlx migrations |
//! | `full` | all of the above |
pub use *;
/// Derive [`Model`] for a struct. See the [crate docs](crate) for an example.
pub use Model;
/// Derive `sqlx::FromRow` for a plain struct, without depending on sqlx.
pub use FromRow;
/// Everything you need for day-to-day use: `use rok_db::prelude::*;`