wabot-feature-sqlite 0.2.0

SQLite foundation for Wabot — the document store, migrations and connection handling, for a single-node deployment with no database server.
Documentation
//! # wabot-feature-sqlite
//!
//! SQLite foundation — the counterpart to `wabot-feature-pg` for a
//! deployment with no database server.
//!
//! * [`SqliteConfig`] / [`SqliteDatabase`] — one writer, a small
//!   reader pool, WAL, and pragmas chosen for low resident memory.
//! * [`SqliteJsonbStore`] — the same document shape the Postgres store
//!   uses (`id` / `created_at` / `data` + promoted columns), created
//!   on first use, implementing [`CrudRepository`].
//! * [`MigrationRunner`] — ordered, checksummed SQL migrations for the
//!   tables an application owns.
//!
//! ```ignore
//! let db = SqliteDatabase::open(SqliteConfig::at("/var/lib/app/app.db"))?;
//! db.ping().await?;
//! c.register_instance::<SqliteDatabase>(Arc::new(db.clone()));
//!
//! let orders: Arc<dyn CrudRepository<OrderData>> =
//!     Arc::new(SqliteJsonbStore::new(db, "orders"));
//! ```
//!
//! ## What this is for
//!
//! One node, one process, no server to operate. That is a real
//! deployment target — a self-hosted control plane, an appliance, an
//! edge box — and until now the framework had nothing for it: `pg` was
//! the only backend, so "runs on a VM with 2 GB of RAM" meant running
//! Postgres next to the thing that needed it.
//!
//! It is also what lets a test exercise the *real* storage path.
//! `InMemoryRepository` proves a service compiles against the traits;
//! it cannot catch a query the SQL builder renders wrongly. An
//! in-memory SQLite database can, in the same milliseconds.
//!
//! ## What it is not
//!
//! Not a drop-in replacement for `pg` at scale. There is one writer,
//! by construction (see [`database`]), and no distributed
//! [`Locker`](wabot_core::lock::Locker) — a second process writing the
//! same file is not a supported configuration, and
//! [`InProcessLocker`](../wabot_feature_async/struct.InProcessLocker.html)
//! is the correct choice on one node. If you need two nodes, you need
//! Postgres, and the repository traits are what make that a
//! configuration change rather than a rewrite.
//!
//! [`CrudRepository`]: wabot_core::repository::CrudRepository

pub mod config;
pub mod database;
pub mod error;
pub mod jsonb;
pub mod migrations;
pub mod query_sql;
pub mod repository;

pub use config::SqliteConfig;
pub use database::SqliteDatabase;
pub use error::{SqliteError, SqliteResult};
pub use jsonb::{to_sql_value, PromotedColumn, SqliteJsonbStore};
pub use migrations::{Migration, MigrationRunner, MigrationStatus};
pub use query_sql::{build_query_sql, BuiltQuery, FieldPlacement, QuerySqlError};

/// Re-exported because this crate's public API needs it: `query` takes
/// `Vec<rusqlite::types::Value>`, and `read`/`write` hand the closure a
/// `rusqlite::Connection`.
///
/// An application that resolved its own rusqlite could end up with two
/// copies in one binary — and since `libsqlite3-sys` sets
/// `links = "sqlite3"`, that does not merely mismatch types, it fails
/// to build. Handing out the one this crate links removes the choice.
pub use rusqlite;