Crate sqlx_sqlite_conn_mgr 

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
• SqliteDatabaseConfig: Configuration for connection pool settings
• WriteGuard: RAII guard ensuring exclusive write access
• Migrator: Re-exported from sqlx for running database migrations
• Error: Error type for database operations

Architecture

• Connection pooling: Separate read-only pool and write pool with a max of 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

Usage

use sqlx_sqlite_conn_mgr::SqliteDatabase;
use std::sync::Arc;

#[tokio::main]
async fn main() -> sqlx_sqlite_conn_mgr::Result<()> {
    // Connect returns Arc<SqliteDatabase>
    let db = SqliteDatabase::connect("example.db", None).await?;

    // Multiple connects to the same path return the same instance
    let db2 = SqliteDatabase::connect("example.db", None).await?;
    assert!(Arc::ptr_eq(&db, &db2));

    // Use read_pool() for read queries (concurrent reads)
    let rows = sqlx::query("SELECT * FROM users")
        .fetch_all(db.read_pool()?)
        .await?;

    // Optionally acquire writer for write queries (exclusive)
    // WAL mode is enabled automatically on first call
    let mut writer = db.acquire_writer().await?;
    sqlx::query("INSERT INTO users (name) VALUES (?)")
        .bind("Alice")
        .execute(&mut *writer)
        .await?;

    // Close when done
    db.close().await?;
    Ok(())
}

Design Principles

• Uses sqlx’s SqlitePoolOptions for all pool configuration
• Uses sqlx’s SqliteConnectOptions for connection flags and configuration
• Minimal custom logic - delegates to sqlx wherever possible
• Global registry caches new database instances and returns existing ones
• WAL mode is enabled lazily only when writes are needed

Structs

AttachedReadConnection

Guard holding a read connection with attached database(s)

AttachedSpec

Specification for attaching a database to a connection

AttachedWriteGuard

Guard holding a write connection with attached database(s)

Migrator

A resolved set of migrations, ready to be run.

SqliteDatabase

SQLite database with connection pooling for concurrent reads and optional exclusive writes.

SqliteDatabaseConfig

Configuration for SqliteDatabase connection pools

WriteGuard

RAII guard for exclusive write access to a database connection

Enums

AttachedMode

Mode for attaching a database

Error

Errors that may occur when working with sqlx-sqlite-conn-mgr

Functions

acquire_reader_with_attached

Acquire a read connection with attached database(s)

acquire_writer_with_attached

Acquire a write connection with attached database(s)

Type Aliases

Result

A type alias for Results with our custom Error type