feat: Add types to show API shape and design

- Once we have consensus on the API and types, I'll move on to implementation
details and tests

Author: pmorris-dev

crates/sqlx-sqlite-conn-mgr/Cargo.toml

@@ -8,4 +8,5 @@ rust-version = "1.89"
 
 [dependencies]
 sqlx = { version = "0.8.6", features = ["runtime-tokio", "sqlite"] }
+thiserror = "2.0.17"
 tokio = { version = "1.48.0", features = ["full"] }

crates/sqlx-sqlite-conn-mgr/src/database.rs

@@ -0,0 +1,45 @@
+//! SQLite database with connection pooling and optional write access
+
+use sqlx::{Pool, Sqlite};
+use std::path::PathBuf;
+use std::sync::atomic::AtomicBool;
+
+/// SQLite database with connection pooling for concurrent reads and optional exclusive writes.
+///
+/// ## Architecture
+///
+/// The database maintains two connection pools:
+/// - **`read_pool`**: Pool of read-only connections for concurrent SELECT queries
+/// - **`write_conn`**: Single-connection pool for exclusive write access (enforced by max_connections=1)
+///
+/// ## State Management
+///
+/// - **`wal_initialized`**: Tracks whether WAL journal mode has been enabled (lazy initialization)
+/// - **`closed`**: Prevents use after the database has been closed
+/// - **`path`**: Database file path for cleanup operations
+///
+/// ## Usage Pattern
+///
+/// ```text
+/// 1. Connect to database (creates/reuses connection pools)
+/// 2. Read operations: Access read_pool for concurrent queries
+/// 3. Write operations: Acquire writer (lazily enables WAL on first call)
+/// 4. Close database when done
+/// ```
+#[derive(Debug)]
+pub struct SqliteDatabase {
+   /// Pool of read-only connections (max 6) for concurrent SELECT queries
+   read_pool: Pool<Sqlite>,
+
+   /// Single read-write connection pool (max 1) for serialized writes
+   write_conn: Pool<Sqlite>,
+
+   /// Tracks if WAL mode has been initialized (set on first write)
+   wal_initialized: AtomicBool,
+
+   /// Marks database as closed to prevent further operations
+   closed: AtomicBool,
+
+   /// Path to database file (used for cleanup and registry lookups)
+   path: PathBuf,
+}

crates/sqlx-sqlite-conn-mgr/src/error.rs

@@ -0,0 +1,23 @@
+//! Error types for sqlx-sqlite-conn-mgr
+
+use thiserror::Error;
+
+/// Errors that may occur when working with sqlx-sqlite-conn-mgr
+#[derive(Error, Debug)]
+pub enum Error {
+   /// IO error when accessing database files. Standard library IO errors
+   /// are converted to this variant.
+   #[error("IO error: {0}")]
+   Io(#[from] std::io::Error),
+
+   /// Error from the sqlx library. Standard sqlx errors are converted to this variant
+   #[error("Sqlx error: {0}")]
+   Sqlx(#[from] sqlx::Error),
+
+   /// Database has been closed and cannot be used
+   #[error("Database has been closed")]
+   DatabaseClosed,
+}
+
+/// A type alias for Results with our Error type
+pub type Result<T> = std::result::Result<T, Error>;

crates/sqlx-sqlite-conn-mgr/src/lib.rs

@@ -1 +1,26 @@
-//! # SQLx Connection Pool Manager
+//! # sqlx-sqlite-conn-mgr
+//!
+//! A minimal wrapper around SQLx that enforces pragmatic SQLite connection policies
+//! for mobile and desktop applications.
+//!
+//! ## Core Types
+//!
+//! - **[`SqliteDatabase`]**: Main database type with separate read and write connection pools
+//! - **[`WriteGuard`]**: RAII guard ensuring exclusive write access
+//! - **[`Error`]**: Error type for database operations
+//!
+//! ## Architecture
+//!
+//! - **Dual pools**: Separate read-only pool (max 6 connections) and write pool (max 1 connection)
+//! - **Lazy WAL mode**: Write-Ahead Logging enabled automatically on first write
+//! - **Exclusive writes**: Single-connection write pool enforces serialized write access
+//! - **Concurrent reads**: Multiple readers can query simultaneously via the read pool
+
+mod database;
+mod error;
+mod write_guard;
+
+// Re-export public types
+pub use database::SqliteDatabase;
+pub use error::{Error, Result};
+pub use write_guard::WriteGuard;

crates/sqlx-sqlite-conn-mgr/src/write_guard.rs

@@ -0,0 +1,64 @@
+//! WriteGuard for exclusive write access to the database
+
+use sqlx::Sqlite;
+use sqlx::pool::PoolConnection;
+use sqlx::sqlite::SqliteConnection;
+use std::ops::{Deref, DerefMut};
+
+/// RAII guard for exclusive write access to a database connection
+///
+/// This guard wraps a pool connection and returns it to the pool on drop.
+/// Only one `WriteGuard` can exist at a time (enforced by max_connections=1),
+/// ensuring serialized write access.
+///
+/// The guard derefs to `SqliteConnection` allowing direct use with sqlx queries.
+///
+/// # Example
+///
+/// ```no_run
+/// use sqlx_sqlite_conn_mgr::SqliteDatabase;
+/// use sqlx::query;
+///
+/// # async fn example() -> Result<(), sqlx_sqlite_conn_mgr::Error> {
+/// let db = SqliteDatabase::connect("test.db").await?;
+/// let mut writer = db.acquire_writer().await?;
+/// // Use &mut *writer for INSERT/UPDATE/DELETE queries
+/// query("INSERT INTO users (name) VALUES (?)")
+///     .bind("Alice")
+///     .execute(&mut *writer)
+///     .await?;
+/// // Writer is automatically returned when dropped
+/// # Ok(())
+/// # }
+/// ```
+#[derive(Debug)]
+pub struct WriteGuard {
+   conn: PoolConnection<Sqlite>,
+}
+
+impl WriteGuard {
+   /// Create a new WriteGuard by taking ownership of a pool connection
+   pub(crate) fn new(conn: PoolConnection<Sqlite>) -> Self {
+      Self { conn }
+   }
+}
+
+impl Deref for WriteGuard {
+   type Target = SqliteConnection;
+
+   fn deref(&self) -> &Self::Target {
+      &self.conn
+   }
+}
+
+impl DerefMut for WriteGuard {
+   fn deref_mut(&mut self) -> &mut Self::Target {
+      &mut self.conn
+   }
+}
+
+// Drop is automatically implemented - PoolConnection returns itself to the pool
+
+// WriteGuard must be Send to cross .await boundaries
+// This is safe because SqliteConnection is Send
+unsafe impl Send for WriteGuard {}