Skip to main content

Crate wordval_db

Crate wordval_db 

Source
Expand description

§wordval-db

Wordval 数据库层:Row 模式 CRUD、事务、Hook、SQL 模板、多数据库支持。

§1.0.5 → 1.0.6 升级注意(breaking)

  1. DbError::Rollback 由单字段元组变体改为结构体变体 Rollback { msg: String, source: Option<Box<dyn Error + Send + Sync>> }。 原来构造/匹配 Rollback(m) 的代码需改为 Rollback { msg, source }; Db::transaction_err / transaction_err_with 可保留完整 source 链。
  2. feature 拆分:后端(sqlite / postgres / mysql)与类型扩展 (uuid / rust_decimal / chrono)及工厂(factory)均按 feature 门控。 默认 features = ["sqlite", "factory", "chrono", "uuid", "rust_decimal"], 与 1.0.x 行为兼容;仅依赖 sqlite 时按需补启类型 feature。

§设计理念

  1. Db + Row 模式 — 无需定义 Model 即可操作,字段追踪 + 类型安全
  2. 事务 RAII — Rust 的 ? 天然保证异常时自动回滚
  3. Hook 生命周期 — before/after 拦截 CRUD,支持审计、时间戳自动填充
  4. 配置驱动 — 从 AppConfig 创建连接池,支持加密密码存储
  5. 多数据库 — PostgreSQL / MySQL / SQLite,工厂按 type 自动选择

§主要模块

  • db — 核心 Db 类型与 CRUD 操作
  • row — Row 动态行类型
  • tx — 事务支持
  • hook — CRUD 生命周期钩子
  • query — SQL 查询构建器 Q
  • factory — 数据库连接工厂(feature factory)
  • sqlite — SQLite 独立连接构建器(feature sqlite)
  • 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§

p
p! —— params! 的别名(Vec<Param>)。
params
构建 Vec<Param>,自动展开 Vec 为 Param::Many:

Structs§

PageQuery
分页查询参数(公共类型,所有 crate 可用)

Enums§

DbError
wordval-db 错误

Type Aliases§

DbResult