kit_rs/database/
mod.rs

1//! Database module for Kit framework
2//!
3//! Provides a SeaORM-based ORM with Laravel-like API.
4//!
5//! # Quick Start
6//!
7//! ```rust,ignore
8//! use kit::{Config, DB, DatabaseConfig};
9//!
10//! // 1. Register database config (in config/mod.rs)
11//! Config::register(DatabaseConfig::from_env());
12//!
13//! // 2. Initialize connection (in bootstrap.rs)
14//! DB::init().await.expect("Failed to connect to database");
15//!
16//! // 3. Use in controllers
17//! let conn = DB::connection()?;
18//! let users = User::find().all(conn.inner()).await?;
19//! ```
20//!
21//! # Configuration
22//!
23//! Set these environment variables:
24//!
25//! ```env
26//! DATABASE_URL=postgres://user:pass@localhost:5432/mydb
27//! # or for SQLite:
28//! DATABASE_URL=sqlite://./database.db
29//!
30//! # Optional:
31//! DB_MAX_CONNECTIONS=10
32//! DB_MIN_CONNECTIONS=1
33//! DB_CONNECT_TIMEOUT=30
34//! DB_LOGGING=false
35//! ```
36
37pub mod config;
38pub mod connection;
39pub mod model;
40
41pub use config::{DatabaseConfig, DatabaseConfigBuilder, DatabaseType};
42pub use connection::DbConnection;
43pub use model::{Model, ModelMut};
44
45use crate::error::FrameworkError;
46use crate::{App, Config};
47
48/// Database facade - main entry point for database operations
49///
50/// Provides static methods for initializing and accessing the database connection.
51/// The connection is stored in the application container as a singleton.
52///
53/// # Example
54///
55/// ```rust,ignore
56/// use kit::{DB, DatabaseConfig, Config};
57///
58/// // Initialize (usually in bootstrap.rs)
59/// Config::register(DatabaseConfig::from_env());
60/// DB::init().await?;
61///
62/// // Use anywhere in your app
63/// let conn = DB::connection()?;
64/// ```
65pub struct DB;
66
67impl DB {
68    /// Initialize the database connection
69    ///
70    /// Reads configuration from `DatabaseConfig` (must be registered via Config system)
71    /// and establishes a connection pool. The connection is stored in the App container.
72    ///
73    /// # Errors
74    ///
75    /// Returns an error if:
76    /// - `DatabaseConfig` is not registered
77    /// - Connection to the database fails
78    ///
79    /// # Example
80    ///
81    /// ```rust,ignore
82    /// // In bootstrap.rs
83    /// pub async fn register() {
84    ///     DB::init().await.expect("Failed to connect to database");
85    /// }
86    /// ```
87    pub async fn init() -> Result<(), FrameworkError> {
88        let config = Config::get::<DatabaseConfig>().ok_or_else(|| {
89            FrameworkError::internal(
90                "DatabaseConfig not registered. Call Config::register(DatabaseConfig::from_env()) first.",
91            )
92        })?;
93
94        let connection = DbConnection::connect(&config).await?;
95        App::singleton(connection);
96        Ok(())
97    }
98
99    /// Initialize with a custom config
100    ///
101    /// Useful for testing or when you need to connect to a different database.
102    ///
103    /// # Example
104    ///
105    /// ```rust,ignore
106    /// let config = DatabaseConfig::builder()
107    ///     .url("sqlite::memory:")
108    ///     .build();
109    /// DB::init_with(config).await?;
110    /// ```
111    pub async fn init_with(config: DatabaseConfig) -> Result<(), FrameworkError> {
112        let connection = DbConnection::connect(&config).await?;
113        App::singleton(connection);
114        Ok(())
115    }
116
117    /// Get the database connection
118    ///
119    /// Returns the connection from the App container. The connection is wrapped
120    /// in a `DbConnection` which provides convenient access to the underlying
121    /// SeaORM `DatabaseConnection`.
122    ///
123    /// # Errors
124    ///
125    /// Returns an error if `DB::init()` was not called.
126    ///
127    /// # Example
128    ///
129    /// ```rust,ignore
130    /// let conn = DB::connection()?;
131    ///
132    /// // Use with SeaORM queries
133    /// let users = User::find()
134    ///     .all(conn.inner())
135    ///     .await?;
136    /// ```
137    pub fn connection() -> Result<DbConnection, FrameworkError> {
138        App::resolve::<DbConnection>()
139    }
140
141    /// Check if the database connection is initialized
142    ///
143    /// # Example
144    ///
145    /// ```rust,ignore
146    /// if DB::is_connected() {
147    ///     let conn = DB::connection()?;
148    ///     // ...
149    /// }
150    /// ```
151    pub fn is_connected() -> bool {
152        App::has::<DbConnection>()
153    }
154}
155
156// Re-export sea_orm types that users commonly need
157pub use sea_orm;
kit_rs/database/mod.rs

kit_rs/database/
mod.rs
