Skip to main content

wabot_feature_sqlite/
lib.rs

1//! # wabot-feature-sqlite
2//!
3//! SQLite foundation — the counterpart to `wabot-feature-pg` for a
4//! deployment with no database server.
5//!
6//! * [`SqliteConfig`] / [`SqliteDatabase`] — one writer, a small
7//!   reader pool, WAL, and pragmas chosen for low resident memory.
8//! * [`SqliteJsonbStore`] — the same document shape the Postgres store
9//!   uses (`id` / `created_at` / `data` + promoted columns), created
10//!   on first use, implementing [`CrudRepository`].
11//! * [`MigrationRunner`] — ordered, checksummed SQL migrations for the
12//!   tables an application owns.
13//!
14//! ```ignore
15//! let db = SqliteDatabase::open(SqliteConfig::at("/var/lib/app/app.db"))?;
16//! db.ping().await?;
17//! c.register_instance::<SqliteDatabase>(Arc::new(db.clone()));
18//!
19//! let orders: Arc<dyn CrudRepository<OrderData>> =
20//!     Arc::new(SqliteJsonbStore::new(db, "orders"));
21//! ```
22//!
23//! ## What this is for
24//!
25//! One node, one process, no server to operate. That is a real
26//! deployment target — a self-hosted control plane, an appliance, an
27//! edge box — and until now the framework had nothing for it: `pg` was
28//! the only backend, so "runs on a VM with 2 GB of RAM" meant running
29//! Postgres next to the thing that needed it.
30//!
31//! It is also what lets a test exercise the *real* storage path.
32//! `InMemoryRepository` proves a service compiles against the traits;
33//! it cannot catch a query the SQL builder renders wrongly. An
34//! in-memory SQLite database can, in the same milliseconds.
35//!
36//! ## What it is not
37//!
38//! Not a drop-in replacement for `pg` at scale. There is one writer,
39//! by construction (see [`database`]), and no distributed
40//! [`Locker`](wabot_core::lock::Locker) — a second process writing the
41//! same file is not a supported configuration, and
42//! [`InProcessLocker`](../wabot_feature_async/struct.InProcessLocker.html)
43//! is the correct choice on one node. If you need two nodes, you need
44//! Postgres, and the repository traits are what make that a
45//! configuration change rather than a rewrite.
46//!
47//! [`CrudRepository`]: wabot_core::repository::CrudRepository
48
49pub mod config;
50pub mod database;
51pub mod error;
52pub mod jsonb;
53pub mod migrations;
54pub mod query_sql;
55pub mod repository;
56
57pub use config::SqliteConfig;
58pub use database::SqliteDatabase;
59pub use error::{SqliteError, SqliteResult};
60pub use jsonb::{to_sql_value, PromotedColumn, SqliteJsonbStore};
61pub use migrations::{Migration, MigrationRunner, MigrationStatus};
62pub use query_sql::{build_query_sql, BuiltQuery, FieldPlacement, QuerySqlError};
63
64/// Re-exported because this crate's public API needs it: `query` takes
65/// `Vec<rusqlite::types::Value>`, and `read`/`write` hand the closure a
66/// `rusqlite::Connection`.
67///
68/// An application that resolved its own rusqlite could end up with two
69/// copies in one binary — and since `libsqlite3-sys` sets
70/// `links = "sqlite3"`, that does not merely mismatch types, it fails
71/// to build. Handing out the one this crate links removes the choice.
72pub use rusqlite;