sqlx_sqlite_conn_mgr/
lib.rs

1//! # sqlx-sqlite-conn-mgr
2//!
3//! A minimal wrapper around SQLx that enforces pragmatic SQLite connection policies
4//! for mobile and desktop applications.
5//!
6//! ## Core Types
7//!
8//! - **[`SqliteDatabase`]**: Main database type with separate read and write connection pools
9//! - **[`SqliteDatabaseConfig`]**: Configuration for connection pool settings
10//! - **[`WriteGuard`]**: RAII guard ensuring exclusive write access
11//! - **[`Migrator`]**: Re-exported from sqlx for running database migrations
12//! - **[`Error`]**: Error type for database operations
13//!
14//! ## Architecture
15//!
16//! - **Connection pooling**: Separate read-only pool and write pool with a max of 1 connection
17//! - **Lazy WAL mode**: Write-Ahead Logging enabled automatically on first write
18//! - **Exclusive writes**: Single-connection write pool enforces serialized write access
19//! - **Concurrent reads**: Multiple readers can query simultaneously via the read pool
20//!
21//! ## Usage
22//!
23//! ```no_run
24//! use sqlx_sqlite_conn_mgr::SqliteDatabase;
25//! use std::sync::Arc;
26//!
27//! #[tokio::main]
28//! async fn main() -> sqlx_sqlite_conn_mgr::Result<()> {
29//!     // Connect returns Arc<SqliteDatabase>
30//!     let db = SqliteDatabase::connect("example.db", None).await?;
31//!
32//!     // Multiple connects to the same path return the same instance
33//!     let db2 = SqliteDatabase::connect("example.db", None).await?;
34//!     assert!(Arc::ptr_eq(&db, &db2));
35//!
36//!     // Use read_pool() for read queries (concurrent reads)
37//!     let rows = sqlx::query("SELECT * FROM users")
38//!         .fetch_all(db.read_pool()?)
39//!         .await?;
40//!
41//!     // Optionally acquire writer for write queries (exclusive)
42//!     // WAL mode is enabled automatically on first call
43//!     let mut writer = db.acquire_writer().await?;
44//!     sqlx::query("INSERT INTO users (name) VALUES (?)")
45//!         .bind("Alice")
46//!         .execute(&mut *writer)
47//!         .await?;
48//!
49//!     // Close when done
50//!     db.close().await?;
51//!     Ok(())
52//! }
53//! ```
54//!
55//! ## Design Principles
56//!
57//! - Uses sqlx's `SqlitePoolOptions` for all pool configuration
58//! - Uses sqlx's `SqliteConnectOptions` for connection flags and configuration
59//! - Minimal custom logic - delegates to sqlx wherever possible
60//! - Global registry caches new database instances and returns existing ones
61//! - WAL mode is enabled lazily only when writes are needed
62//!
63mod attached;
64mod config;
65mod database;
66mod error;
67mod registry;
68mod write_guard;
69
70// Re-export public types
71pub use attached::{
72   AttachedMode, AttachedReadConnection, AttachedSpec, AttachedWriteGuard,
73   acquire_reader_with_attached, acquire_writer_with_attached,
74};
75pub use config::SqliteDatabaseConfig;
76pub use database::SqliteDatabase;
77pub use error::Error;
78pub use write_guard::WriteGuard;
79
80// Re-export sqlx migrate types for convenience
81pub use sqlx::migrate::Migrator;
82
83/// A type alias for Results with our custom Error type
84pub type Result<T> = std::result::Result<T, Error>;
sqlx_sqlite_conn_mgr/lib.rs

sqlx_sqlite_conn_mgr/
lib.rs
