uorm

Rust 下的轻量级 ORM 框架，借鉴 Java MyBatis 的设计理念，强调 SQL 与业务逻辑分离：用 XML 管理 SQL，通过 sql_id 调用并把结果自动映射到 Rust 类型；同时支持直接执行原生 SQL，原生支持 async/await。

特性

🚀 MyBatis 风格：支持熟悉的 XML Mapper 语法，通过 namespace.id 唯一定位 SQL。
🎯 动态 SQL：支持 <if>、<foreach>、<include> 等标签，轻松构建复杂 SQL。
📦 类型安全：通过 #[derive(Param)] 自动处理参数绑定与结果映射，支持 #[param] 属性重命名或忽略字段。
⚡ 异步优先：基于 tokio 运行时，全程支持 async/await，适配高并发场景。
🔧 灵活配置：支持多数据源管理、连接池优化、超时设置及事务控制。
🛠️ 过程宏增强：提供 #[sql]、#[uorm::transaction] / #[transaction] 及 mapper_assets! 等宏，极大简化开发工作。
🗄️ 多数据库支持：原生支持 SQLite 和 MySQL，架构易于扩展至其他 UDBC 驱动。
📝 详细日志：集成 log crate，提供 SQL 执行、耗时及参数详情，便于调试。

安装

在 Cargo.toml 中添加依赖：

[dependencies]
uorm = "0.7.3"

特性开关 (Features)

sqlite（默认开启）：支持 SQLite 数据库。
mysql：支持 MySQL 数据库。

[dependencies]
# 仅启用 MySQL 支持
uorm = { version = "0.7.3", default-features = false, features = ["mysql"] }

快速开始

1) 注册数据库驱动

通过 U 全局单例注册驱动。SqliteDriver 和 MysqlDriver 均采用 Builder 模式。

use uorm::driver_manager::U;
use uorm::udbc::sqlite::pool::SqliteDriver;

#[tokio::main]
async fn main() -> uorm::Result<()> {
    // 创建驱动并指定名称（默认为 "default"）
    let driver = SqliteDriver::new("sqlite:./app.db")
        .build()?;
    
    // 注册到全局管理器
    U.register(driver)?;

    Ok(())
}

2) 加载 Mapper XML

uorm 提供两种方式加载 XML 资源：

方式一：编译期内嵌（推荐） 使用 mapper_assets! 宏，在编译时将 XML 文件内容嵌入二进制中，程序启动时自动注册。在调试构建（debug）下会直接从磁盘按 glob 扫描加载，便于开发时热修改 XML。

use uorm::mapper_assets;

// 自动扫描路径下的所有 XML 文件并内嵌
mapper_assets!["resources/mappers"];

方式二：运行时加载

在程序启动后手动扫描文件系统加载 XML。

use uorm::driver_manager::U;

fn init_mappers() -> uorm::Result<()> {
    // 运行时扫描并解析 XML（glob 模式）
    U.assets("resources/mappers")?;
    Ok(())
}

3) 执行 Mapper 调用

use uorm::driver_manager::U;
use uorm::Param;

#[derive(Debug, Param)]
struct User {
    id: i64,
    name: String,
    age: i64,
}

#[derive(Param)]
struct IdArg {
    id: i64,
}

pub async fn get_user_by_id(user_id: i64) -> uorm::Result<Option<User>> {
    let mapper = U.mapper().expect("Driver not found");
    
    // execute 会根据 XML 定义的标签（select/insert/update/delete）自动执行。
    // 对于 select，如果结果只有一行且返回类型是结构体而非 Vec，会自动解包（Unwrap）。
    mapper.execute("user.get_by_id", &IdArg { id: user_id }).await
}

4) 基本类型返回 (Scalar Return)

除了返回结构体或 Vec，execute 也支持直接返回基本类型（如 i64, String, f64 等）及其 Option 包装。适用于 count(*)、max(column) 等聚合查询。

pub async fn scalar_example() -> uorm::Result<()> {
    let mapper = U.mapper().expect("Driver not found");

    // 返回单个整数 (例如 count(*))
    let count: i64 = mapper.execute("user.count", &()).await?;

    // 返回单个字符串 (例如 max(name))
    let name: String = mapper.execute("user.max_name", &()).await?;

    // 返回 Option (处理可能为空的结果)
    let max_id: Option<i64> = mapper.execute("user.max_id", &()).await?;
    
    Ok(())
}

SQL 过程宏 (`#[sql]`)

使用 #[sql] 宏可以像定义 DAO 接口一样操作数据库，代码更加优雅。

use uorm::{sql, Param, Result};

#[derive(Debug, Param)]
struct User {
    id: i64,
    name: String,
}

#[sql("user")] // 指定 XML 的 namespace
struct UserDao;

impl UserDao {
    #[sql("get_by_id")] // 对应 user.get_by_id
    pub async fn get(id: i64) -> Result<Option<User>> {
        // exec!() 是由 #[sql] 宏在函数内部注入的局部宏
        // 它会自动捕获函数参数、namespace 和 id 并执行调用
        exec!() 
    }

    #[sql(id = "list_all", database = "other_db")] // 可指定特定的数据库名称
    pub async fn list_all() -> Result<Vec<User>> {
        exec!()
    }
}

直接执行 SQL (`Session`)

如果不想使用 XML，也可以通过 Session 直接执行带有命名参数的 SQL。uorm 内部集成了轻量级模板引擎。

use uorm::driver_manager::U;
use uorm::Param;

#[derive(Param)]
struct UserParam {
    name: String,
    age: i32,
}

pub async fn add_user() -> uorm::Result<u64> {
    let session = U.session().expect("Default driver not found");

    // 支持 #{field} 语法绑定参数，内部会自动处理 SQL 注入防护
    let affected = session.execute(
        "INSERT INTO users(name, age) VALUES (#{name}, #{age})",
        &UserParam { name: "Alice".to_string(), age: 18 }
    ).await?;

    Ok(affected)
}

事务管理

自动事务宏 (`#[uorm::transaction]`)

使用 #[transaction] 宏可以简化事务代码：它会在执行函数体前尝试开启事务，当函数返回 Ok(_) 时提交事务（commit()），返回 Err(_) 时回滚事务（rollback()）。如果当前线程已存在同库的事务上下文（例如嵌套调用），宏不会重复开启/提交事务。该宏要求被标注的函数返回 Result<T, E>，并且 E 能从 uorm::error::Error 转换（即满足 E: From<Error>），以便将 begin/commit 的错误向外返回。注意：回滚失败会被忽略并优先返回原始业务错误。

另外，事务上下文基于线程局部存储（TLS）。在 tokio 多线程运行时下，任务可能跨线程恢复执行；如需严格保证同一事务内共享同一连接，请使用单线程运行时或确保任务固定在线程上执行。

use uorm::driver_manager::U;
use uorm::Param;

#[derive(Param)]
struct MyData {
    id: i64,
    name: String,
}

#[uorm::transaction]
async fn transfer_data(data: &MyData) -> uorm::Result<()> {
    let session = U.session().expect("Default driver not found");
    session
        .execute("INSERT INTO t(id, name) VALUES (#{id}, #{name})", data)
        .await?;
    session
        .execute("UPDATE t SET name = #{name} WHERE id = #{id}", data)
        .await?;
    Ok(())
}

#[derive(Param)]
struct IdArg {
    id: i64,
}

#[uorm::transaction(database = "other_db")]
async fn custom_session_name() -> uorm::Result<()> {
    let session = U.session_by_name("other_db").expect("Database driver not found");
    session.execute("DELETE FROM t WHERE id = #{id}", &IdArg { id: 1 })
        .await?;
    Ok(())
}

手动管理事务

uorm 使用线程局部存储（Thread Local Storage）管理事务上下文，确保在同一线程内的操作共享同一个事务连接。

use uorm::driver_manager::U;

async fn manual_transaction() -> uorm::Result<()> {
    let session = U.session().expect("Default driver not found");
    session.begin().await?;

    match do_work(&session).await {
        Ok(_) => session.commit().await?,
        Err(e) => {
            session.rollback().await?;
            return Err(e);
        }
    }
    Ok(())
}

XML Mapper 示例

<mapper namespace="user">
  <!-- 基本查询 -->
  <select id="get_by_id">
    SELECT id, name, age FROM users WHERE id = #{id}
  </select>

  <!-- 动态 SQL：if 标签 -->
  <select id="search">
    SELECT * FROM users
    <where>
      <if test="name != null">
        AND name LIKE #{name}
      </if>
      <if test="min_age != null">
        AND age >= #{min_age}
      </if>
    </where>
  </select>

  <!-- 动态 SQL：foreach 标签 -->
  <select id="list_by_ids">
    SELECT * FROM users
    WHERE id IN
    <foreach item="id" collection="ids" open="(" separator="," close=")">
      #{id}
    </foreach>
  </select>

  <!-- 插入并获取自增 ID -->
  <!-- 当 returnKey 为 true 时，execute 将返回最后插入的 ID -->
  <insert id="insert_user" returnKey="true">
    INSERT INTO users(name, age) VALUES (#{name}, #{age})
  </insert>
</mapper>

高级配置

连接池与超时

use uorm::udbc::PoolOptions;
use uorm::udbc::mysql::pool::MysqlDriver;

fn build_mysql_driver() -> uorm::Result<MysqlDriver> {
    let options = PoolOptions {
        max_open_conns: 20,
        max_idle_conns: 5,
        max_lifetime: 3600,
        timeout: 5, // 连接获取超时（秒）
    };

    MysqlDriver::new("mysql://user:pass@localhost/db")
        .options(options)
        .build()
}

SQLite 特殊说明

并发性：SQLite 驱动默认开启了 WAL 模式（Write-Ahead Logging）和 foreign_keys 支持，显著提升并发读写性能。
内存数据库：使用 sqlite::memory: 或 sqlite://:memory:。注意：当前 SQLite 驱动每次 acquire() 都会创建新连接；对 :memory: 而言，这意味着每次都是全新的空库。需要共享状态时建议使用文件数据库，或使用 SQLite URI 共享内存（例如 sqlite:file:app?mode=memory&cache=shared）。

日志监控

uorm 使用 log crate 输出详细的执行日志。

fn init_logging() {
    // 建议在开发环境下开启 Debug 级别
    // 输出示例:
    // DEBUG [uorm] Query: sql=SELECT ... WHERE id = ?, params=[("id", I64(1))], elapsed=2ms, rows=1
    env_logger::Builder::new().filter_level(log::LevelFilter::Debug).init();
}

License

Apache-2.0

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.github/workflows		.github/workflows
src		src
tests		tests
uorm-macros		uorm-macros
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
publish.sh		publish.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

uorm

特性

安装

特性开关 (Features)

快速开始

1) 注册数据库驱动

2) 加载 Mapper XML

3) 执行 Mapper 调用

4) 基本类型返回 (Scalar Return)

SQL 过程宏 (`#[sql]`)

直接执行 SQL (`Session`)

事务管理

自动事务宏 (`#[uorm::transaction]`)

手动管理事务

XML Mapper 示例

高级配置

连接池与超时

SQLite 特殊说明

日志监控

License

About

Uh oh!

Releases 13

Packages

Contributors 2

Uh oh!

Languages

License

uporm/uorm

Folders and files

Latest commit

History

Repository files navigation

uorm

特性

安装

特性开关 (Features)

快速开始

1) 注册数据库驱动

2) 加载 Mapper XML

3) 执行 Mapper 调用

4) 基本类型返回 (Scalar Return)

SQL 过程宏 (#[sql])

直接执行 SQL (Session)

事务管理

自动事务宏 (#[uorm::transaction])

手动管理事务

XML Mapper 示例

高级配置

连接池与超时

SQLite 特殊说明

日志监控

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 13

Packages 0

Contributors 2

Uh oh!

Languages

SQL 过程宏 (`#[sql]`)

直接执行 SQL (`Session`)

自动事务宏 (`#[uorm::transaction]`)

Packages