# rust-rbatis
**Repository Path**: mirrors/rust-rbatis
## Basic Information
- **Project Name**: rust-rbatis
- **Description**: rbatis 是一个用 Rust 编写的高性能、安全、动态 SQL(编译时)ORM 框架,受 Mybatis 和 MybatisPlus 的启发
- **Primary Language**: Rust
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://www.oschina.net/p/rust-rbatis
- **GVP Project**: No
## Statistics
- **Stars**: 28
- **Forks**: 6
- **Created**: 2021-12-21
- **Last Updated**: 2025-09-27
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Rbatis
##### 📖 [英文文档](Readme.md) | 📖 中文文档
(机翻中文,如有差异,已英文原版为主)
[Website](https://rbatis.github.io/rbatis.io) | [Showcase](https://github.com/rbatis/rbatis/network/dependents) | [Examples](https://github.com/rbatis/rbatis/tree/master/example)
[](https://github.com/zhuxiujia/rbatis/actions)
[](https://docs.rs/rbatis/)
[](https://crates.io/crates/rbatis)
[](https://github.com/rust-secure-code/safety-dance/)
[](https://codecov.io/gh/rbatis/rbatis)
[](https://github.com/rbatis/rbatis/releases)
[](https://github.com/rbatis/rbatis/discussions)
## 简介
Rbatis 是一个基于编译时代码生成的高性能 Rust ORM 框架。它在开发效率、性能和稳定性之间实现了完美平衡,既是一个 ORM,也是一个动态 SQL 编译器。
## AI 支持
* - [rbdc-mcp](https://github.com/rbatis/rbdc-mcp)
## 核心优势
### 1. 高性能
- **编译时动态 SQL 生成**:在编译期间将 SQL 语句转换为 Rust 代码,避免运行时开销
- **基于 Tokio 异步模型**:充分利用 Rust 的异步特性,提升并发性能
- **高效的连接池**:内置多种连接池实现,优化数据库连接管理
### 2. 可靠性
- **Rust 安全特性**:利用 Rust 的所有权和借用检查确保内存和线程安全
- **统一参数占位符**:使用 `?` 作为统一占位符,支持所有驱动
- **两种替换模式**:预编译的 `#{arg}` 和直接替换 `${arg}`,满足不同场景需求
### 3. 开发效率
- **强大的 ORM 能力**:数据库表与 Rust 结构体自动映射
- **多种 SQL 构建方式**:
- **py_sql**:Python 风格的动态 SQL,支持 `if`、`for`、`choose/when/otherwise`、`bind`、`trim` 结构和集合操作(`.sql()`、`.csv()`)
- **html_sql**:类似 MyBatis 的 XML 模板,具有熟悉的标签结构(``、``、``、``),声明式 SQL 构建,自动处理 SQL 片段而无需 CDATA
- **原始 SQL**:直接的 SQL 语句
- **CRUD 宏**:一行代码生成通用 CRUD 操作
- **拦截器插件**:[自定义扩展功能](https://rbatis.github.io/rbatis.io/#/v4/?id=plugin-intercept)
- **表同步插件**:[自动创建/更新表结构](https://rbatis.github.io/rbatis.io/#/v4/?id=plugin-table-sync)
### 4. 可扩展性
- **多数据库支持**:MySQL、PostgreSQL、SQLite、MSSQL、MariaDB、TiDB、CockroachDB、Oracle、TDengine 等
- **自定义驱动接口**:实现简单接口即可添加对新数据库的支持
- **多连接池**:FastPool(默认)、Deadpool、MobcPool
- **兼容多种 Web 框架**:与 ntex、actix-web、axum、hyper、rocket、tide、warp、salvo 等无缝集成
## 支持的数据库驱动
| 数据库 (crates.io) | GitHub 链接 |
|----------------------------------------------------|-----------------------------------------------------------------------------------|
| [MySQL](https://crates.io/crates/rbdc-mysql) | [rbatis/rbdc-mysql](https://github.com/rbatis/rbdc/tree/master/rbdc-mysql) |
| [PostgreSQL](https://crates.io/crates/rbdc-pg) | [rbatis/rbdc-pg](https://github.com/rbatis/rbdc/tree/master/rbdc-pg) |
| [SQLite](https://crates.io/crates/rbdc-sqlite) | [rbatis/rbdc-sqlite](https://github.com/rbatis/rbdc/tree/master/rbdc-sqlite) |
| [MSSQL](https://crates.io/crates/rbdc-mssql) | [rbatis/rbdc-mssql](https://github.com/rbatis/rbdc/tree/master/rbdc-mssql) |
| [MariaDB](https://crates.io/crates/rbdc-mysql) | [rbatis/rbdc-mysql](https://github.com/rbatis/rbdc/tree/master/rbdc-mysql) |
| [TiDB](https://crates.io/crates/rbdc-mysql) | [rbatis/rbdc-mysql](https://github.com/rbatis/rbdc/tree/master/rbdc-mysql) |
| [CockroachDB](https://crates.io/crates/rbdc-pg) | [rbatis/rbdc-pg](https://github.com/rbatis/rbdc/tree/master/rbdc-pg) |
| [Oracle](https://crates.io/crates/rbdc-oracle) | [chenpengfan/rbdc-oracle](https://github.com/chenpengfan/rbdc-oracle) |
| [TDengine](https://crates.io/crates/rbdc-tdengine) | [tdcare/rbdc-tdengine](https://github.com/tdcare/rbdc-tdengine) |
## 支持的连接池
| 连接池 (crates.io) | GitHub 链接 |
|-----------------------------------------------------------|-----------------------------------------------------------------------------------|
| [FastPool (默认)](https://crates.io/crates/rbdc-pool-fast) | [rbatis/fast_pool](https://github.com/rbatis/rbatis/tree/master/rbdc-pool-fast) |
| [Deadpool](https://crates.io/crates/rbdc-pool-deadpool) | [rbatis/rbdc-pool-deadpool](https://github.com/rbatis/rbdc-pool-deadpool) |
| [MobcPool](https://crates.io/crates/rbdc-pool-mobc) | [rbatis/rbdc-pool-mobc](https://github.com/rbatis/rbdc-pool-mobc) |
## 支持的数据类型
| 数据类型 | 支持 |
|-------------------------------------------------------------------------|---------|
| `Option` | ✓ |
| `Vec` | ✓ |
| `HashMap` | ✓ |
| `i32, i64, f32, f64, bool, String` 及其他 Rust 基础类型 | ✓ |
| `rbatis::rbdc::types::{Bytes, Date, DateTime, Time, Timestamp, Decimal, Json}` | ✓ |
| `rbatis::plugin::page::{Page, PageRequest}` | ✓ |
| `rbs::Value` | ✓ |
| `serde_json::Value` 及其他 serde 类型 | ✓ |
| 来自 rbdc-mysql, rbdc-pg, rbdc-sqlite, rbdc-mssql 的驱动特定类型 | ✓ |
## 其他库 crates
| crate | GitHub 链接 |
|---------------------------------------|-------------------------------------------------|
| [rbdc](https://crates.io/crates/rbdc) | [rbdc](https://github.com/rbatis/rbdc) |
| [rbs](https://crates.io/crates/rbs) | [rbs](https://github.com/rbatis/rbs) |
## Rbatis 工作原理
Rbatis 通过 `rbatis-codegen` crate 使用编译时代码生成,这意味着:
1. **零运行时开销**:动态 SQL 在编译期间转换为 Rust 代码,而不是在运行时。这提供了类似于手写代码的性能。
2. **编译过程**:
- **词法分析**:由 `rbatis-codegen` 中的 `func.rs` 使用 Rust 的 `syn` 和 `quote` crates 处理
- **语法解析**:由 `rbatis-codegen` 中的 `parser_html` 和 `parser_pysql` 模块执行
- **抽象语法树**:使用 `rbatis-codegen` 中 `syntax_tree` 包定义的结构构建
- **中间代码生成**:由 `func.rs` 执行,其中包含所有代码生成函数
3. **构建过程集成**:整个过程在 `cargo build` 阶段作为 Rust 的过程宏编译的一部分运行。生成的代码返回给 Rust 编译器进行 LLVM 编译以生成机器代码。
4. **无运行时成本的动态 SQL**:与大多数在运行时解释动态 SQL 的 ORM 不同,Rbatis 在编译时完成所有这些工作,从而产生高效且类型安全的代码。
## 性能基准测试
```
---- bench_raw stdout ----(windows/SingleThread)
Time: 52.4187ms ,each:524 ns/op
QPS: 1906435 QPS/s
---- bench_select stdout ----(macos-M1Cpu/SingleThread)
Time: 112.927916ms ,each:1129 ns/op
QPS: 885486 QPS/s
---- bench_insert stdout ----(macos-M1Cpu/SingleThread)
Time: 346.576666ms ,each:3465 ns/op
QPS: 288531 QPS/s
```
## 快速开始
### 依赖
```toml
# Cargo.toml
[dependencies]
rbs = { version = "4.6"}
rbatis = { version = "4.6"}
#drivers
rbdc-sqlite = { version = "4.6" }
# rbdc-mysql = { version = "4.6" }
# rbdc-pg = { version = "4.6" }
# rbdc-mssql = { version = "4.6" }
# 其他依赖
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
log = "0.4"
fast_log = "1.6"
```
### 基本用法
```rust
use rbatis::rbdc::datetime::DateTime;
use rbs::value;
use rbatis::RBatis;
use rbdc_sqlite::driver::SqliteDriver;
use serde::{Deserialize, Serialize};
use serde_json::json;
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct BizActivity {
pub id: Option,
pub name: Option,
pub status: Option,
pub create_time: Option,
pub additional_field: Option,
}
// 自动生成 CRUD 方法
crud!(BizActivity{});
#[tokio::main]
async fn main() {
// 配置日志
fast_log::init(fast_log::Config::new().console()).expect("rbatis init fail");
// 初始化 rbatis
let rb = RBatis::new();
// 连接数据库
rb.init(SqliteDriver {}, "sqlite://target/sqlite.db").unwrap();
// 或其他数据库
// rb.init(MysqlDriver{}, "mysql://root:123456@localhost:3306/test").unwrap();
// rb.init(PgDriver{}, "postgres://postgres:123456@localhost:5432/postgres").unwrap();
// 创建数据
let activity = BizActivity {
id: Some("1".into()),
name: Some("测试活动".into()),
status: Some(1),
create_time: Some(DateTime::now()),
additional_field: Some("额外信息".into()),
};
// 插入数据
let data = BizActivity::insert(&rb, &activity).await;
// 批量插入
let data = BizActivity::insert_batch(&rb, &vec![BizActivity {
id: Some("2".into()),
name: Some("活动 2".into()),
status: Some(1),
create_time: Some(DateTime::now()),
additional_field: Some("信息 2".into()),
}, BizActivity {
id: Some("3".into()),
name: Some("活动 3".into()),
status: Some(1),
create_time: Some(DateTime::now()),
additional_field: Some("信息 3".into()),
},
], 10).await;
// 根据 map 条件更新
let data = BizActivity::update_by_map(&rb, &activity, value!{ "id": "1" }).await;
// 根据 map 条件查询
let data = BizActivity::select_by_map(&rb, value!{"id":"2","name":"活动 2"}).await;
// LIKE 查询
let data = BizActivity::select_by_map(&rb, value!{"name like ":"%活动%"}).await;
// 大于查询
let data = BizActivity::select_by_map(&rb, value!{"id > ":"2"}).await;
// IN 查询
let data = BizActivity::select_by_map(&rb, value!{"id": &["1", "2", "3"]}).await;
// 根据 map 条件删除
let data = BizActivity::delete_by_map(&rb, value!{"id": &["1", "2", "3"]}).await;
}
```
## 创建自定义数据库驱动
要为 Rbatis 实现自定义数据库驱动:
1. 定义你的驱动项目及依赖:
```toml
[features]
default = ["tls-rustls"]
tls-rustls=["rbdc/tls-rustls"]
tls-native-tls=["rbdc/tls-native-tls"]
[dependencies]
rbs = { version = "4.6"}
rbdc = { version = "4.6", default-features = false, optional = true }
fastdate = { version = "0.3" }
tokio = { version = "1", features = ["full"] }
```
2. 实现所需的 trait:
```rust
use rbdc::db::{Driver, MetaData, Row, Connection, ConnectOptions, Placeholder};
pub struct YourDriver{}
impl Driver for YourDriver{}
pub struct YourMetaData{}
impl MetaData for YourMetaData{}
pub struct YourRow{}
impl Row for YourRow{}
pub struct YourConnection{}
impl Connection for YourConnection{}
pub struct YourConnectOptions{}
impl ConnectOptions for YourConnectOptions{}
pub struct YourPlaceholder{}
impl Placeholder for YourPlaceholder{}
// 然后使用你的驱动:
#[tokio::main]
async fn main() {
let rb = rbatis::RBatis::new();
rb.init(YourDatabaseDriver {}, "database://username:password@host:port/dbname").unwrap();
}
```
## 更多信息
- [完整文档](https://rbatis.github.io/rbatis.io)
- [变更日志](https://github.com/rbatis/rbatis/releases/)
- [rbdc-mcp](https://github.com/rbatis/rbdc-mcp)
## 联系我们
[](https://github.com/rbatis/rbatis/discussions)
### 捐赠或联系
> 微信(添加好友时请备注 'rbatis')
