bottle_orm/lib.rs
1//! # Bottle ORM
2//!
3//! **Bottle ORM** is a lightweight, async ORM for Rust built on top of [sqlx](https://github.com/launchbadge/sqlx).
4//! It is designed to be simple, efficient, and easy to use, providing a fluent Query Builder
5//! and automatic schema migrations.
6//!
7//! ## Features
8//!
9//! - **Async & Non-blocking**: Built on `tokio` and `sqlx`
10//! - **Multi-Driver Support**: Compatible with PostgreSQL, MySQL, and SQLite (via `sqlx::Any`)
11//! - **Macro-based Models**: Define your schema using standard Rust structs with `#[derive(Model)]`
12//! - **Fluent Query Builder**: Chainable methods for filtering, selecting, pagination, and sorting
13//! - **Auto-Migration**: Automatically creates tables and foreign key constraints based on your structs
14//! - **UUID Support**: Full support for UUID versions 1 through 7
15//!
16//! ## Quick Start Example
17//!
18//! ```rust,ignore
19//! use bottle_orm::{Database, Model};
20//! use serde::{Deserialize, Serialize};
21//! use sqlx::FromRow;
22//!
23//! #[derive(Model, Debug, Clone, Serialize, Deserialize, FromRow)]
24//! struct User {
25//! #[orm(primary_key)]
26//! id: i32,
27//! #[orm(size = 50, unique)]
28//! username: String,
29//! age: i32,
30//! }
31//!
32//! #[tokio::main]
33//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
34//! let db = Database::connect("sqlite::memory:").await?;
35//!
36//! db.migrator()
37//! .register::<User>()
38//! .run()
39//! .await?;
40//!
41//! let users: Vec<User> = db.model::<User>()
42//! .filter("age", ">=", 18)
43//! .scan()
44//! .await?;
45//!
46//! Ok(())
47//! }
48//! ```
49
50// ============================================================================
51// Macro Re-exports
52// ============================================================================
53
54/// Re-export of the procedural macro for deriving the `Model` trait.
55///
56/// This macro is defined in the `bottle-orm-macro` crate and allows automatic
57/// implementation of the `Model` trait for structs representing database tables.
58pub use bottle_orm_macro::Model;
59
60/// Re-export of the procedural macro for deriving `Display` and `FromStr` for enums.
61pub use bottle_orm_macro::BottleEnum;
62
63/// Re-export of the procedural macro for deriving `FromRow` for `AnyRow` and `AnyImpl`.
64///
65/// This macro facilitates scanning arbitrary query results (via `AnyRow`) into
66/// Rust structs, handling necessary type conversions (especially for temporal types).
67pub use bottle_orm_macro::FromAnyRow;
68
69// ============================================================================
70// Module Declarations
71// ============================================================================
72
73/// Database connection and driver management.
74///
75/// Contains the `Database` struct for connection pooling and driver detection,
76/// as well as the `Drivers` enum for identifying the database backend.
77pub mod database;
78
79/// Core Model trait and column metadata structures.
80///
81/// Defines the `Model` trait that must be implemented by all ORM entities,
82/// and the `ColumnInfo` struct containing metadata about table columns.
83pub mod model;
84
85/// Support for mapping arbitrary `AnyRow` results to structs.
86///
87/// Defines traits and structures (`AnyImpl`, `AnyInfo`) that support the `FromAnyRow`
88/// derive macro, enabling flexible result mapping.
89pub mod any_struct;
90
91/// Fluent query builder for constructing SQL queries.
92///
93/// Provides the `QueryBuilder` struct with chainable methods for building
94/// SELECT, INSERT, and filtered queries with type-safe parameter binding.
95pub mod query_builder;
96
97/// Schema migration management.
98///
99/// Contains the `Migrator` struct for registering models and executing
100/// automatic table creation and foreign key assignment.
101pub mod migration;
102
103pub mod transaction;
104
105/// Error types and handling.
106///
107/// Defines the `Error` enum with variants for different error scenarios
108/// that can occur during ORM operations.
109pub mod errors;
110
111/// Temporal type conversion and handling.
112///
113/// Provides specialized conversion functions for chrono types (DateTime, NaiveDateTime, etc.)
114/// across different database drivers, optimizing for native database type support.
115pub mod temporal;
116
117/// Value binding utilities for SQL queries.
118///
119/// Provides type-safe value binding with automatic type detection and conversion,
120/// supporting all SQL types across different database drivers.
121pub mod value_binding;
122
123/// Pagination utilities for web framework integration.
124///
125/// Provides the `Pagination` struct which implements `Serialize`/`Deserialize`
126/// for easy extraction from query parameters in frameworks like Axum or Actix-web.
127pub mod pagination;
128
129// ============================================================================
130// Public API Re-exports
131// ============================================================================
132
133/// Re-export of the `Database` struct for connection management.
134///
135/// This is the main entry point for establishing database connections
136/// and creating query builders or migrators.
137pub use database::{Database, DatabaseBuilder, RawQuery};
138
139/// Re-export of the `Model` trait and `ColumnInfo` struct.
140///
141/// The `Model` trait defines the interface for ORM entities, while
142/// `ColumnInfo` contains metadata about individual table columns.
143pub use model::{ColumnInfo, Model};
144
145/// Re-export of `AnyImpl` and `AnyInfo` for dynamic row mapping.
146///
147/// `AnyImpl` is the trait implemented by structs that can be scanned from `AnyRow`,
148/// providing necessary column metadata via `AnyInfo`.
149pub use any_struct::{AnyImpl, AnyInfo, FromAnyRow};
150
151pub use transaction::Transaction;
152
153/// Re-export of the `QueryBuilder` for constructing and executing queries.
154///
155/// `QueryBuilder` provides a fluent interface for building SELECT and INSERT
156/// queries with filtering, ordering, and pagination capabilities.
157pub use query_builder::{Op, QueryBuilder};
158
159/// Re-export of the `Migrator` for schema migration management.
160///
161/// `Migrator` handles the registration of models and execution of
162/// migration tasks to create tables and establish relationships.
163pub use migration::Migrator;
164
165/// Re-export of the `Error` type for error handling.
166///
167/// This is the main error type used throughout Bottle ORM, wrapping
168/// various error scenarios including database errors and validation errors.
169pub use errors::Error;
170
171/// Re-export of `Pagination` struct.
172pub use pagination::Pagination;