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 `FromRow` for `AnyRow` and `AnyImpl`.
61///
62/// This macro facilitates scanning arbitrary query results (via `AnyRow`) into
63/// Rust structs, handling necessary type conversions (especially for temporal types).
64pub use bottle_orm_macro::FromAnyRow;
65
66// ============================================================================
67// Module Declarations
68// ============================================================================
69
70/// Database connection and driver management.
71///
72/// Contains the `Database` struct for connection pooling and driver detection,
73/// as well as the `Drivers` enum for identifying the database backend.
74pub mod database;
75
76/// Core Model trait and column metadata structures.
77///
78/// Defines the `Model` trait that must be implemented by all ORM entities,
79/// and the `ColumnInfo` struct containing metadata about table columns.
80pub mod model;
81
82/// Support for mapping arbitrary `AnyRow` results to structs.
83///
84/// Defines traits and structures (`AnyImpl`, `AnyInfo`) that support the `FromAnyRow`
85/// derive macro, enabling flexible result mapping.
86pub mod any_struct;
87
88/// Fluent query builder for constructing SQL queries.
89///
90/// Provides the `QueryBuilder` struct with chainable methods for building
91/// SELECT, INSERT, and filtered queries with type-safe parameter binding.
92pub mod query_builder;
93
94/// Schema migration management.
95///
96/// Contains the `Migrator` struct for registering models and executing
97/// automatic table creation and foreign key assignment.
98pub mod migration;
99
100pub mod transaction;
101
102/// Error types and handling.
103///
104/// Defines the `Error` enum with variants for different error scenarios
105/// that can occur during ORM operations.
106pub mod errors;
107
108/// Temporal type conversion and handling.
109///
110/// Provides specialized conversion functions for chrono types (DateTime, NaiveDateTime, etc.)
111/// across different database drivers, optimizing for native database type support.
112pub mod temporal;
113
114/// Value binding utilities for SQL queries.
115///
116/// Provides type-safe value binding with automatic type detection and conversion,
117/// supporting all SQL types across different database drivers.
118pub mod value_binding;
119
120/// Pagination utilities for web framework integration.
121///
122/// Provides the `Pagination` struct which implements `Serialize`/`Deserialize`
123/// for easy extraction from query parameters in frameworks like Axum or Actix-web.
124pub mod pagination;
125
126// ============================================================================
127// Public API Re-exports
128// ============================================================================
129
130/// Re-export of the `Database` struct for connection management.
131///
132/// This is the main entry point for establishing database connections
133/// and creating query builders or migrators.
134pub use database::{Database, DatabaseBuilder};
135
136/// Re-export of the `Model` trait and `ColumnInfo` struct.
137///
138/// The `Model` trait defines the interface for ORM entities, while
139/// `ColumnInfo` contains metadata about individual table columns.
140pub use model::{ColumnInfo, Model};
141
142/// Re-export of `AnyImpl` and `AnyInfo` for dynamic row mapping.
143///
144/// `AnyImpl` is the trait implemented by structs that can be scanned from `AnyRow`,
145/// providing necessary column metadata via `AnyInfo`.
146pub use any_struct::{AnyImpl, AnyInfo};
147
148pub use transaction::Transaction;
149
150/// Re-export of the `QueryBuilder` for constructing and executing queries.
151///
152/// `QueryBuilder` provides a fluent interface for building SELECT and INSERT
153/// queries with filtering, ordering, and pagination capabilities.
154pub use query_builder::QueryBuilder;
155
156/// Re-export of the `Migrator` for schema migration management.
157///
158/// `Migrator` handles the registration of models and execution of
159/// migration tasks to create tables and establish relationships.
160pub use migration::Migrator;
161
162/// Re-export of the `Error` type for error handling.
163///
164/// This is the main error type used throughout Bottle ORM, wrapping
165/// various error scenarios including database errors and validation errors.
166pub use errors::Error;
167
168/// Re-export of `Pagination` struct.
169pub use pagination::Pagination;
bottle_orm/lib.rs

bottle_orm/
lib.rs
