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

#![doc(
    html_logo_url = "https://raw.githubusercontent.com/RedSoftwareSystems/rust-orma/master/orma.svg?sanitize=true"
)]
//! # orma
//!
//! A PostgreSQL ORM written in Rust language
//!
//! ## Introduction
//!
//! When you feel the need to persist data as documents on PostgreSQL you often want a way to map these documents on structs.
//!
//! If you have such needs and you are using PostgreSQL instead of other databases, it's probably because you also want all other cool stuff present in PostgreSQL.
//!
//! **orma** is a special ORM for PostgreSQL written in Rust language developed just for you!
//!
//! **orma** takes advantage of PostgreSQL JSONB data representation and doesn't give up the relational advantages of a RDBMS like PostgreSQL.
//!
//! **orma** provides out of the box features for search and CRUD operation over your documents
//!
//! **orma** is fast and easy to learn, with a very simple API.
//!
//! ## Quick start
//!
//! **orma** is thought to be mapped over tables that have at least the following columns:
//!
//! ```disable
//! - id: uuid NOT NULL
//! - version: integer NOT NULL
//! - data: jsonb
//! ```
//!
//! - _id_ identifies a record.
//! - _version_ is used for record versioning and prevents a record to be modified if version has changed in another session. orma takes care of record versioning OOTB.
//! - _data_ is used to map the document and it's mapped over structs that implement _DbData_ trait.
//!
//! All structs that implement *DbData* trait need to be serializable too, as they'll be represented as jsonb data in your db records.
//!
//! While _DbData_ is mapped to _data_ column, _DbEntity_ is mapped over the three columns, and table, just described.
//!
//! You can use _DbEntity\<DbData\>_ to perform search and crud operations.
//!
//! If you need to relate two different entities, _DbJoin\<DbData\>_ is used to get entities related to the specified DbData.\
//! You need to use _JoinBuilder_ to create a DbJoin relation, and you can define both simple joins and table joins for M to N relations.
//!
//! # Example
//!
//! Using an imaginary "pgactix" database.
//!
//! ```ignore
//! use orma_derive::DbData;
//! use serde_derive::Serialize;
//! use orma::*;
//!
//! async fn create_connection() -> Connection {
//!     let connection_string = format!(
//!         "host={host} port={port} dbname={dbname} user={user} password={password}",
//!         host = &env::var("INTRARED_DB_HOSTNAME").unwrap_or_else(|_| "localhost".to_string()),
//!         port = env::var("INTRARED_DB_PORT").unwrap_or_else(|_| "5433".to_string()),
//!         dbname = env::var("INTRARED_DB_NAME").unwrap_or_else(|_| "pgactix".to_string()),
//!         user = env::var("INTRARED_DB_USERNAME").unwrap_or_else(|_| "pgactix".to_string()),
//!         password = env::var("INTRARED_DB_PASSWORD").unwrap_or_else(|_| "pgactix".to_string()),
//!     );
//!     let (client, conn) = tokio_postgres::connect(&connection_string, tokio_postgres::NoTls)
//!         .await
//!         .unwrap();
//!     tokio::spawn(conn);
//!     client.into()
//! }
//!
//! #[pk(field_1 = "field1", field_2 = "field2")]
//! #[table("schema.table_name")]
//! #[derive(Serialize, DbData)]
//! struct TestData {
//!     field_1: String,
//!     field_2: String,
//!     some_other_filed: Option<Vec<String>>,
//! }
//! ```

mod db_anti_corruption;
mod dbentity;
mod dbjoin;

pub use db_anti_corruption::*;
pub use dbentity::{DbData, DbEntity};
pub use dbjoin::{DbJoin, JoinBuilder};
pub use uuid::Uuid;

#[cfg(feature = "derive")]
pub mod derive {
    pub use orma_derive::DbData;
}