Expand description
§wordval-db
Wordval 数据库层:Row 模式 CRUD、事务、Hook、SQL 模板、多数据库支持。
§1.0.5 → 1.0.6 升级注意(breaking)
DbError::Rollback由单字段元组变体改为结构体变体Rollback { msg: String, source: Option<Box<dyn Error + Send + Sync>> }。 原来构造/匹配Rollback(m)的代码需改为Rollback { msg, source };Db::transaction_err/transaction_err_with可保留完整 source 链。- feature 拆分:后端(
sqlite/postgres/mysql)与类型扩展 (uuid/rust_decimal/chrono)及工厂(factory)均按 feature 门控。 默认 features =["sqlite", "factory", "chrono", "uuid", "rust_decimal"], 与 1.0.x 行为兼容;仅依赖sqlite时按需补启类型 feature。
§设计理念
- Db + Row 模式 — 无需定义 Model 即可操作,字段追踪 + 类型安全
- 事务 RAII — Rust 的
?天然保证异常时自动回滚 - Hook 生命周期 — before/after 拦截 CRUD,支持审计、时间戳自动填充
- 配置驱动 — 从
AppConfig创建连接池,支持加密密码存储 - 多数据库 — PostgreSQL / MySQL / SQLite,工厂按 type 自动选择
§主要模块
db— 核心Db类型与 CRUD 操作row—Row动态行类型tx— 事务支持hook— CRUD 生命周期钩子query— SQL 查询构建器Qfactory— 数据库连接工厂(featurefactory)sqlite— SQLite 独立连接构建器(featuresqlite)row_executor—Db/ActiveTx共享的 Row 写入 trait(事务内 Row 写)script—split_sql_statements与execute_script(单连接多语句)
§快速开始
ⓘ
use wordval_db::{Db, Row};
let db = wordval_db::create_db(&config.database).await?;
// 插入(表名在 Row 上声明,字段改动会被追踪)
// 注意:Row 携带非 Null 主键值时按该值原样插入、不走自增;
// 需要数据库自增请勿 set 主键字段(或用 Row::without_pk 清除)
let mut row = Row::table("user");
row.set("name", "Alice");
let id = db.insert(&row).await?;
// 查询
let users = db.query("SELECT * FROM user WHERE age > ?", &[18i64.into()]).await?;Re-exports§
pub use ar::ActiveRecord;pub use ar::FromRow;pub use ar::ToRow;pub use ar::TryFromRow;pub use db::Db;pub use db::NamingStrategy;pub use db::SoftDelete;pub use dialect::Dialect;pub use factory::create_db;pub use factory::create_db_if_enabled;pub use hook::Hook;pub use hook::HookChain;pub use param::push_param;pub use param::DbTypeHint;pub use param::IntoParams;pub use param::Param;pub use query::Q;pub use row::FieldValue;pub use row::Row;pub use row::RowExt;pub use row_executor::RowExecutor;pub use script::split_sql_statements;pub use tx::ActiveTx;pub use tx::DbExecutor;pub use tx::Isolation;pub use chrono;pub use uuid;
Modules§
- ar
- ActiveRecord —— 类型化 Model 的 CRUD 抽象
- db
- Db 门面 —— 统一数据库访问入口。
- dialect
- factory
- 数据库工厂:从 DatabaseConfig 创建连接池
- hook
- 数据库 Hook:生命周期拦截(before/after 拦截 CRUD)
- migrate
- 数据库迁移工具
- param
- 类型化查询参数
- query
- SQL 查询构造器 — 跨 PostgreSQL / MySQL / SQLite
- row
- row_
executor - Row 写入执行器 —— 同一份 Row 写代码既能跑池连接也能跑事务(1.0.6 新增)。
- script
- SQL 脚本执行:词法安全的多语句分割与顺序执行(1.0.6 新增)。
- sqlite
- SQLite 独立连接入口(
wordval_db::sqlite::builder),见sqlite模块文档。 SQLite 连接构建器 —— 不依赖wordval-config、零 sqlx 类型暴露的独立入口(1.0.6 新增)。 - tx
- 事务:真正的 Commit/Rollback,闭包内可直接用
?,编译期保证事务句柄不会被遗忘。
Macros§
Structs§
- Page
Query - 分页查询参数(公共类型,所有 crate 可用)
Enums§
- DbError
- wordval-db 错误