tiny_orm/lib.rs
1//! ```rust
2//! use sqlx::{FromRow, Row, types::chrono::{DateTime, Utc}};
3//! use tiny_orm::Table;
4//!
5//! #[derive(Debug, FromRow, Table, Clone)]
6//! #[tiny_orm(all)]
7//! struct Todo {
8//! id: i32,
9//! created_at: DateTime<Utc>,
10//! updated_at: DateTime<Utc>,
11//! description: String,
12//! done: bool,
13//! }
14//! ```
15//!
16//! The code above would generate the following methods on the Todo object
17//! ```rust,ignore
18//! impl Todo {
19//! pub fn get_by_id(pool: &DbPool, id: &i32) -> sqlx::Result<Self> {
20//! // Get a specific record for a given ID
21//! // Use the `id` column by default
22//! }
23//! pub fn list_all(pool: &DbPool) -> sqlx::Result<Vec<Self>> {
24//! // Get all the records
25//! }
26//! pub fn delete(&self, pool: &DbPool) -> sqlx::Result<()> {
27//! // Delete the record in the database
28//! }
29//! pub fn create(&self, pool: &DbPool) -> sqlx::Result<i32> {
30//! // Create the Todo object as a record in
31//! // the database and returns the primary key of the record created.
32//! }
33//! pub fn update(&self, pool: &DbPool) -> sqlx::Result<()> {
34//! // Update the record in the database with the values
35//! // currently part of the Todo object
36//! }
37//! }
38//! ```
39//!
40//! # Examples
41//! More examples can be found in the [examples](./examples) directory.
42//!
43//! ## Options
44//! The Table macro comes with a few options to give flexibility to the user
45//!
46//! ### At the Struct level
47//! - **table_name**: The name of the table in the database.
48//! Default being a snake_case version of the Struct name. So `MyStruct` would have `my_struct` as a default `table_name`.
49//! - **only**: The methods that will only be available to that struct. Multiple values are comma separated.
50//! Default is dependent on the struct name (see below).
51//! - **exclude**: The methods that will be excluded for that struct. Multiple values are comma separated
52//! Default empty vec.
53//! - **add**: The methods that will be added for that struct. Multiple values are comma separated
54//! Default empty vec.
55//! - **all**: All the methods will be available to the struct. This will override the default values when none are provided.
56//! Default none.
57//! - **soft_deletion**: When set to true, it will add a `deleted_at` filter when querying the data. When using the `delete` method, it will set the `deleted_at` column to the current timestamp.
58//! Default false.
59//! - **return_object**: A custom object that would be returned instead of `Self`. Useful when creating or updating records with partial information.
60//! Default is `Self` which corresponds to the current Strut.
61//!
62//! _Note: `only` cannot be used with `exclude` nor `add` cannot be used together._
63//!
64//! By convention, if a struct name
65//! - Starts with `New` then it will automatically use the following arguments
66//! `#[tiny_orm(table_name = "table_name_from_return_object", return_object = "NameWithoutNewAsPrefix", only = "create")]`
67//! - Starts with `Update` then it will automatically use the following arguments
68//! `#[tiny_orm(table_name = "table_name_from_return_object", return_object = "NameWithoutUpdateAsPrefix", only = "update")]`
69//! - Everything else would be the equivalent of using the following
70//! `#[tiny_orm(table_name = "table_name", return_object = "Self", exclude = "create,update")]`
71//!
72//! ### Example using the default options
73//! ```rust
74//! # use tiny_orm::Table;
75//! # use uuid::Uuid;
76//! # use sqlx::{FromRow, types::chrono::{DateTime, Utc}};
77//! #[derive(Debug, FromRow, Table, Clone)]
78//! // #[tiny_orm(table_name = "todo", return_object = "Self", exclude = "create,update")]
79//! struct Todo {
80//! id: i32,
81//! created_at: DateTime<Utc>,
82//! updated_at: DateTime<Utc>,
83//! description: String,
84//! done: bool,
85//! }
86//!
87//! #[derive(Debug, FromRow, Table, Clone)]
88//! // Because the struct name starts with "New", it would automatically use the following options
89//! // #[tiny_orm(table_name = "todo", return_object = "Todo", only = "create")]
90//! struct NewTodo {
91//! description: String,
92//! }
93//!
94//! #[derive(Debug, FromRow, Table, Clone)]
95//! // Because the struct name starts with "Update", it would automatically use the following options
96//! // #[tiny_orm(table_name = "todo", return_object = "Todo", only = "update")]
97//! struct UpdateTodo {
98//! id: i32,
99//! done: bool
100//! }
101//! ```
102//! The above takes the assumption that some columns can be nullable and others are auto generated (eg an ID column that would be auto increment).
103//! Thus it would generate the following
104//! ```rust,ignore
105//! impl NewTodo {
106//! pub fn create(&self, pool: &DbPool) -> sqlx::Result<Todo> {
107//! // Use the NewTodo object to create a record
108//! // in the database and return the record created.
109//!
110//! // This would not be supported for MySQL since
111//! // there is a need to know the primary key (auto increment or not)
112//! // to either return the value or use `last_insert_id()`
113//! }
114//! }
115//!
116//! impl UpdateTodo {
117//! pub fn update(&self, pool: &DbPool) -> sqlx::Result<Todo> {
118//! // Update the Todo object with partial information based
119//! // on the id (default primary_key).
120//! // Because `return_type` is specified, it will return the whole record in the database.
121//! // If `return_type` was not specified, it would simply return nothing `()`.
122//!
123//! // For MySQL, it would always return nothing `()` as it
124//! // cannot return a record after an update.
125//! }
126//! }
127//! ```
128//!
129//! ### Example using the soft_deletion option
130//! ```rust
131//! # use tiny_orm::Table;
132//! # use uuid::Uuid;
133//! # use sqlx::{FromRow, types::chrono::{DateTime, Utc}};
134//! #[derive(Debug, FromRow, Table, Clone)]
135//! #[tiny_orm(soft_deletion)]
136//! struct Todo {
137//! id: i32,
138//! created_at: DateTime<Utc>,
139//! updated_at: DateTime<Utc>,
140//! deleted_at: DateTime<Utc>,
141//! description: String,
142//! done: bool,
143//! }
144//!
145//! #[derive(Debug, FromRow, Table, Clone)]
146//! #[tiny_orm(soft_deletion)]
147//! struct UpdateTodo {
148//! id: i32,
149//! done: bool
150//! }
151//! ```
152//!
153//! ### At the field level
154//! - **primary_key**: The field that would be used as a primary key for the queries. For some methods the primary key is mandatory (eg: `get_by_id()`). If not specified, it will default to `id` if part of the struct.
155//! - **primary_key(auto)**: The field that would be used as a primary key for the queries. When "auto" is set, it will skip the column and returns it during the `create()` method since it will be auto generated by the database itself.
156//!
157//! _Note: MySQL only supports "auto increment" in that case. It does not support returning the default value of a primary key like a UUID._
158//!
159//! Example
160//! ```rust
161//! # use tiny_orm::Table;
162//! # use uuid::Uuid;
163//! # use sqlx::FromRow;
164//! #[derive(Debug, FromRow, Table, Clone)]
165//! struct Todo {
166//! #[tiny_orm(primary_key)]
167//! custom_pk: Uuid,
168//! description: String,
169//! done: bool
170//! }
171//! ```
172//!
173//! ```rust
174//! use tiny_orm::{Table, SetOption};
175//! # use sqlx::FromRow;
176//! #[derive(Debug, FromRow, Table, Clone)]
177//! struct Todo {
178//! #[tiny_orm(primary_key(auto))]
179//! id: i64,
180//! description: SetOption<String>,
181//! done: SetOption<bool>
182//! }
183//! ```
184//!
185//! Thus it would generate the following
186//! ```rust,ignore
187//! impl Todo {
188//! pub fn create(&self, pool: &DbPool) -> sqlx::Result<Uuid> { // or i64 depending on the example
189//! // Create the Todo object as a record in
190//! // the database and returns the created record.
191//! }
192//! }
193//! ```
194
195pub use tiny_orm_macros::*;
196pub use tiny_orm_model::*;