Module db 

modo::db

Lightweight libsql (SQLite) database layer with typed row mapping, composable query building, filtering, and pagination.

Core types

Type	Purpose
Database	Clone-able, Arc-wrapped single-connection handle
Config	YAML-deserializable database configuration with PRAGMA defaults
ManagedDatabase	Wrapper for graceful shutdown via modo::run!
DatabasePool	Multi-database pool with lazy shard opening for tenant isolation
PoolConfig	Configuration for database sharding (base_path, lock_shards)
ManagedDatabasePool	Wrapper for graceful pool shutdown via modo::run!

Factory functions

Function	Purpose
managed	Wraps a Database into a ManagedDatabase
managed_pool	Wraps a DatabasePool into a ManagedDatabasePool

Connection & querying

Item	Purpose
connect	Open a database, apply PRAGMAs, optionally run migrations
migrate	Run *.sql migrations from a directory with checksum tracking
ConnExt	Low-level query_raw/execute_raw trait for Connection and Transaction
ConnQueryExt	High-level query_one/query_all/query_optional + _map variants (blanket impl on ConnExt)
SelectBuilder	Composable query builder combining filters, sorting, and pagination

Row mapping

Item	Purpose
FromRow	Trait for converting a libsql::Row into a Rust struct
FromValue	Trait for converting a libsql::Value into a concrete Rust type
ColumnMap	Column name to index lookup for name-based row access

Filtering & pagination

Item	Purpose
Filter	Raw parsed filter from query string (axum extractor)
FilterSchema	Declares allowed filter and sort fields for an endpoint
ValidatedFilter	Schema-validated filter safe for SQL generation
FieldType	Column type enum for filter value validation
PageRequest	Offset-based pagination extractor (?page=N&per_page=N)
Page	Offset-based page response with total/has_next/has_prev
CursorRequest	Cursor-based pagination extractor (?after=<cursor>&per_page=N)
CursorPage	Cursor-based page response with next_cursor/has_more
PaginationConfig	Configurable defaults and limits for pagination extractors

Configuration enums

Enum	Purpose
JournalMode	SQLite journal mode (WAL, Delete, Truncate, Memory, Off)
SynchronousMode	SQLite synchronous mode (Off, Normal, Full, Extra)
TempStore	SQLite temp store location (Default, File, Memory)

Maintenance

Item	Purpose
DbHealth	Page-level health metrics from PRAGMA introspection
VacuumOptions	Configuration for run_vacuum (threshold, dry_run)
VacuumResult	Before/after health snapshots with timing
run_vacuum	VACUUM with threshold guard and health snapshots
vacuum_if_needed	Shorthand for run_vacuum with threshold only
vacuum_handler	Cron handler factory for scheduled maintenance

Re-exports

The libsql crate is re-exported for direct access to low-level types such as libsql::params!, libsql::Value, libsql::Connection, and libsql::Transaction.

Quick start

use modo::db::{self, ConnExt, ConnQueryExt};

// Connect with defaults (data/app.db, WAL mode, FK on)
let db = db::connect(&db::Config::default()).await?;

// Use query helpers via ConnQueryExt
let user: User = db.conn().query_one(
    "SELECT id, name FROM users WHERE id = ?1",
    libsql::params!["user_abc"],
).await?;

// Or use the SelectBuilder for filtered, paginated queries
let page = db.conn()
    .select("SELECT id, name FROM users")
    .filter(validated_filter)
    .order_by("\"created_at\" DESC")
    .page::<User>(page_request)
    .await?;

Re-exports

pub use libsql;

Structs

ColumnMap

Column name to index lookup built from a single row’s column metadata.

Config

Database configuration with sensible defaults for SQLite/libsql.

CursorPage

Cursor-based page response.

CursorRequest

Cursor pagination request extracted from the query string.

Database

Clone-able, single-connection database handle.

DatabasePool

Multi-database connection pool with lazy shard opening.

DbHealth

Database health metrics from PRAGMA introspection.

Filter

Raw parsed filter from query string.

FilterSchema

Declares the allowed filter fields and sort fields for an endpoint.

ManagedDatabase

Wrapper for graceful shutdown integration with crate::run!.

ManagedDatabasePool

Wrapper for graceful shutdown integration with crate::run!.

Page

Offset-based page response.

PageRequest

Offset pagination request extracted from the query string.

PaginationConfig

Pagination defaults applied by PageRequest and CursorRequest extractors.

PoolConfig

Pool configuration for multi-database sharding.

SelectBuilder

Composable query builder combining filters, sorting, and pagination.

VacuumOptions

Options for run_vacuum.

VacuumResult

Result of a run_vacuum call.

ValidatedFilter

Schema-validated filter, safe for SQL generation.

Enums

FieldType

Column type used for validating filter values.

JournalMode

SQLite journal mode.

SynchronousMode

SQLite synchronous mode.

TempStore

SQLite temp store location.

Traits

ConnExt

Low-level query trait implemented for libsql::Connection and libsql::Transaction.

ConnQueryExt

High-level query helpers built on ConnExt.

FromRow

Trait for converting a libsql::Row into a Rust struct.

FromValue

Converts a libsql::Value into a concrete Rust type.

Functions

connect

Open a local libsql database, apply PRAGMAs from Config, and optionally run migrations.

managed

Wrap a Database for use with crate::run!.

managed_pool

Wrap a DatabasePool for use with crate::run!.

migrate

Run SQL migrations from a directory against a connection.

run_vacuum

Run VACUUM with safety checks.

vacuum_handler

Returns a cron handler that checks DB health and vacuums if needed.

vacuum_if_needed

Shorthand: run run_vacuum with the given threshold and default options.