spg_sqlx/lib.rs
1// v7.16.0 — every public item carries a doc-comment.
2#![deny(missing_docs)]
3
4//! # spg-sqlx
5//!
6//! sqlx 0.8 Database driver for [`spg-embedded`]. Lets
7//! in-process callers swap `sqlx::PgPool` for `SpgPool` and keep
8//! the rest of their `sqlx::query` / `sqlx::query_as` /
9//! `pool.begin` cement unchanged — backs mailrs's drop-in
10//! "PgPool → SpgPool" goal from the gap evaluation (E1).
11//!
12//! ## v7.16.0 MVP scope
13//!
14//! - [`Spg`] marker type + the 11 associated types `sqlx::Database`
15//! requires, all wired up to compile.
16//! - [`SpgPool`] / [`SpgConnection`] wrap [`spg_embedded_tokio::AsyncDatabase`]
17//! so a single in-process database is the "pool". No real
18//! pooling — every "connection" handle is a cheap clone of
19//! the underlying `Arc<Mutex<Database>>`.
20//! - Bind-time [`Value`][SpgValue] encoding for the basic scalar
21//! surface: `i32`, `i64`, `bool`, `String`, `Vec<u8>`. Round-trip
22//! verified end-to-end against `sqlx::query("INSERT …").bind(…)`
23//! in the test suite.
24//! - Transactions via the engine's BEGIN/COMMIT/ROLLBACK; the
25//! [`SpgTransactionManager`] wraps that for `pool.begin()`.
26//!
27//! ## v7.16.x / v7.17 follow-up
28//!
29//! - Encode/Decode for the remaining mailrs-side types:
30//! TIMESTAMPTZ (`chrono::DateTime<Utc>`), JSON / JSONB
31//! (`serde_json::Value`), `tsvector`, `VECTOR(N)`,
32//! `INT[]` / `TEXT[]`, `BYTEA` (Vec<u8> beyond the basic path),
33//! numeric.
34//! - `FromRow` derive support — the macro's generated impl reads
35//! columns by index/name via the [`Row`][sqlx_core::row::Row]
36//! trait, so wiring `SpgRow::try_get` is enough for the derive
37//! to "just work" once the per-type Decode lands.
38//! - `sqlx::query!()` compile-time validation via sqlx's offline
39//! mode (`SQLX_OFFLINE=true` + a checked-in `.sqlx/` dir). The
40//! adapter itself doesn't need a DESCRIBE protocol —
41//! `Spg`-shaped offline cache mirrors what mailrs ships
42//! against PG today.
43//!
44//! ## Quick start
45//!
46//! ```no_run
47//! use spg_sqlx::{SpgPool, SpgPoolExt};
48//!
49//! # async fn _f() -> Result<(), Box<dyn std::error::Error>> {
50//! let pool = SpgPool::connect_in_memory().await?;
51//! sqlx::query("CREATE TABLE users (id INT NOT NULL, name TEXT NOT NULL)")
52//! .execute(&pool)
53//! .await?;
54//! sqlx::query("INSERT INTO users VALUES ($1, $2)")
55//! .bind(1_i32)
56//! .bind("alice")
57//! .execute(&pool)
58//! .await?;
59//! # Ok(())
60//! # }
61//! ```
62
63mod arguments;
64mod column;
65mod connection;
66mod database;
67mod error;
68mod options;
69mod pool;
70mod query_result;
71mod row;
72mod statement;
73mod transaction;
74mod type_info;
75mod types;
76mod value;
77
78pub use crate::arguments::{SpgArgumentValue, SpgArguments};
79pub use crate::column::SpgColumn;
80pub use crate::connection::SpgConnection;
81pub use crate::database::Spg;
82pub use crate::options::SpgConnectOptions;
83pub use crate::pool::{SpgPool, SpgPoolExt, SpgPoolOptions};
84pub use crate::query_result::SpgQueryResult;
85pub use crate::row::SpgRow;
86pub use crate::statement::SpgStatement;
87pub use crate::transaction::SpgTransactionManager;
88pub use crate::type_info::SpgTypeInfo;
89pub use crate::value::{SpgValue, SpgValueRef};
90
91// Re-export the embedded engine's owned-value type so consumers
92// don't have to depend on spg-embedded directly to construct or
93// pattern-match values returned from the adapter.
94pub use spg_embedded::Value as EngineValue;