rat_quickdb

🚀 强大的跨数据库ODM库，支持SQLite、PostgreSQL、MySQL、MongoDB的统一接口

🌐 语言版本: 中文 | English | 日本語

✨ 核心特性

• 🎯 自动索引创建: 基于模型定义自动创建表和索引，无需手动干预
• 🗄️ 多数据库支持: SQLite、PostgreSQL、MySQL、MongoDB
• 🔗 统一API: 一致的接口操作不同数据库
• 🔒 SQLite布尔值兼容: 自动处理SQLite布尔值存储差异，零配置兼容
• 🏊 连接池管理: 高效的连接池和无锁队列架构
• ⚡ 异步支持: 基于Tokio的异步运行时
• 🧠 智能缓存: 内置缓存支持（基于rat_memcache），支持TTL过期和回退机制
• 🆔 多种ID生成策略: AutoIncrement、UUID、Snowflake、ObjectId、Custom前缀
• 📝 日志控制: 由调用者完全控制日志初始化，避免库自动初始化冲突
• 🐍 Python绑定: 可选Python API支持
• 📋 任务队列: 内置异步任务队列系统
• 🔍 类型安全: 强类型模型定义和验证

📦 安装

在Cargo.toml中添加依赖：

[dependencies]
rat_quickdb = "0.3.1"

🔧 特性控制

rat_quickdb 使用 Cargo 特性来控制不同数据库的支持和功能。默认情况下只包含核心功能，你需要根据使用的数据库类型启用相应的特性：

[dependencies]
rat_quickdb = { version = "0.3.1", features = [
    "sqlite-support",    # 支持SQLite数据库
    "postgres-support",  # 支持PostgreSQL数据库
    "mysql-support",     # 支持MySQL数据库
    "mongodb-support",   # 支持MongoDB数据库
] }

可用特性列表

特性名称	描述	默认启用
sqlite-support	SQLite数据库支持	❌
postgres-support	PostgreSQL数据库支持	❌
mysql-support	MySQL数据库支持	❌
mongodb-support	MongoDB数据库支持	❌
melange-storage	已弃用：L2缓存功能已内置在rat_memcache中	❌
python-bindings	Python API绑定	❌
full	启用所有数据库支持	❌

按需启用特性

仅使用SQLite:

[dependencies]
rat_quickdb = { version = "0.3.1", features = ["sqlite-support"] }

使用PostgreSQL:

[dependencies]
rat_quickdb = { version = "0.3.1", features = ["postgres-support"] }

使用所有数据库:

[dependencies]
rat_quickdb = { version = "0.3.1", features = ["full"] }

L2缓存配置注意事项:

• L2缓存功能已内置在 rat_memcache 中，无需额外特性
• L2缓存需要磁盘空间用于缓存持久化
• 配置示例见下面的"缓存配置"部分

运行示例

不同的示例需要不同的特性支持：

# 基础模型定义示例
cargo run --example model_definition --features sqlite-support

# 复杂查询示例
cargo run --example complex_query_demo --features sqlite-support

# 分页查询示例
cargo run --example model_pagination_demo --features sqlite-support

# 特殊类型测试示例
cargo run --example special_types_test --features sqlite-support

# ID生成策略示例
cargo run --example id_strategy_test --features sqlite-support

# 手动表管理示例
cargo run --example manual_table_management --features sqlite-support

# 其他数据库示例
cargo run --example model_definition_mysql --features mysql-support
cargo run --example model_definition_pgsql --features postgres-support
cargo run --example model_definition_mongodb --features mongodb-support

⚠️ 重要架构说明

ODM层使用要求 (v0.3.0+)

从v0.3.0版本开始，强制使用define_model!宏定义模型，不再允许使用普通结构体进行数据库操作。

所有数据库操作必须通过以下方式：

1. 推荐：使用模型API

use rat_quickdb::*;
use rat_quickdb::ModelOperations;

// 定义模型
define_model! {
    struct User {
        id: String,
        username: String,
        email: String,
    }
    // ... 字段定义
}

// 创建和保存
let user = User {
    id: String::new(), // 框架自动生成ID
    username: "张三".to_string(),
    email: "zhangsan@example.com".to_string(),
};
let user_id = user.save().await?;

// 查询
let found_user = ModelManager::<User>::find_by_id(&user_id).await?;

2. 备选：使用ODM API

use rat_quickdb::*;

// 通过add_database添加数据库配置
let config = DatabaseConfig::builder()
    .db_type(DatabaseType::SQLite)
    .connection(ConnectionConfig::SQLite {
        path: "test.db".to_string(),
        create_if_missing: true,
    })
    .alias("main".to_string())
    .build()?;
add_database(config).await?;

// 使用ODM操作数据库
let mut user_data = HashMap::new();
user_data.insert("username".to_string(), DataValue::String("张三".to_string()));
create("users", user_data, Some("main")).await?;

3. 禁止的用法

// ❌ 错误：不再允许直接访问连接池管理器
// let pool_manager = get_global_pool_manager();
// let pool = pool_manager.get_connection_pools().get("main");

这种设计确保了：

• 架构完整性: 统一的数据访问层
• 安全性: 防止直接操作底层连接池导致的资源泄漏
• 一致性: 所有操作都经过相同的ODM层处理
• 维护性: 统一的错误处理和日志记录

📋 从旧版本升级

从 v0.2.x 升级到 v0.3.0

v0.3.0 是一个重大变更版本，包含破坏性更改。请查看详细的迁移指南。

主要变更：

• ✅ 强制使用 define_model! 宏定义模型
• ✅ 消除动态表结构推断的"保姆设置"问题
• ✅ 提供更明确的类型安全和字段定义
• ✅ 修复重大架构Bug

🚀 快速开始

基本使用

查看 examples/model_definition.rs 了解完整的模型定义和使用方法。

ID生成策略示例

查看 examples/id_strategy_test.rs 了解不同ID生成策略的使用方法。

数据库适配器示例

• SQLite: examples/model_definition.rs (运行时使用 --features sqlite-support)
• PostgreSQL: examples/model_definition_pgsql.rs
• MySQL: examples/model_definition_mysql.rs
• MongoDB: examples/model_definition_mongodb.rs

模型定义（推荐方式）

查看 examples/model_definition.rs 了解完整的模型定义、CRUD操作和复杂查询示例。

字段类型和验证

查看 examples/model_definition.rs 中包含的字段类型定义和验证示例。

索引管理

索引会根据模型定义自动创建，无需手动管理。参考 examples/model_definition.rs 了解索引定义方式。

🔒 SQLite布尔值兼容性

SQLite数据库将布尔值存储为整数（0和1），这可能导致serde反序列化错误。rat_quickdb提供了多种解决方案：

方案1: sqlite_bool_field() - 推荐（零配置）

use rat_quickdb::*;

rat_quickdb::define_model! {
    struct User {
        id: Option<i32>,
        username: String,
        is_active: bool,        // 自动SQLite兼容
        is_pinned: bool,        // 自动SQLite兼容
        is_verified: bool,      // 自动SQLite兼容
    }

    collection = "users",
    fields = {
        id: integer_field(None, None),
        username: string_field(Some(50), Some(3), None).required(),
        // 使用sqlite_bool_field() - 自动处理SQLite布尔值兼容性
        is_active: sqlite_bool_field(),
        is_pinned: sqlite_bool_field(),
        is_verified: sqlite_bool_field_with_default(false),
    }
}

方案2: 手动serde属性 + 通用反序列化器

use rat_quickdb::*;
use serde::Deserialize;

#[derive(Debug, Serialize, Deserialize)]
struct User {
    id: Option<i32>,
    username: String,

    // 手动指定反序列化器
    #[serde(deserialize_with = "rat_quickdb::sqlite_bool::deserialize_bool_from_any")]
    is_active: bool,

    #[serde(deserialize_with = "rat_quickdb::sqlite_bool::deserialize_bool_from_int")]
    is_pinned: bool,
}

rat_quickdb::define_model! {
    struct User {
        id: Option<i32>,
        username: String,
        is_active: bool,
        is_pinned: bool,
    }

    collection = "users",
    fields = {
        id: integer_field(None, None),
        username: string_field(Some(50), Some(3), None).required(),
        // 使用传统boolean_field() - 配合手动serde属性
        is_active: boolean_field(),
        is_pinned: boolean_field(),
    }
}

方案3: 传统方式（需要手动处理）

// 对于已有代码，可以使用传统boolean_field()
// 但需要确保数据源中的布尔值格式正确
rat_quickdb::define_model! {
    struct User {
        id: Option<i32>,
        username: String,
        is_active: bool,        // 需要手动处理兼容性
    }

    collection = "users",
    fields = {
        id: integer_field(None, None),
        username: string_field(Some(50), Some(3), None).required(),
        is_active: boolean_field(),  // 传统方式
    }
}

反序列化器选择指南

• deserialize_bool_from_any(): 支持整数、布尔值、字符串 "true"/"false"
• deserialize_bool_from_int(): 支持整数和布尔值
• sqlite_bool_field(): 自动选择最佳反序列化器

迁移指南

从传统boolean_field()迁移到sqlite_bool_field()：

// 之前（可能有兼容性问题）
is_active: boolean_field(),

// 之后（完全兼容）
is_active: sqlite_bool_field(),

🆔 ID生成策略

rat_quickdb支持多种ID生成策略，满足不同场景的需求：

AutoIncrement（自增ID）

DatabaseConfig::builder()
    .id_strategy(IdStrategy::AutoIncrement)
    .build()?

UUID（通用唯一标识符）

DatabaseConfig::builder()
    .id_strategy(IdStrategy::Uuid)
    .build()?

Snowflake（雪花算法）

DatabaseConfig::builder()
    .id_strategy(IdStrategy::Snowflake {
        machine_id: 1,
        datacenter_id: 1
    })
    .build()?

ObjectId（MongoDB风格）

DatabaseConfig::builder()
    .id_strategy(IdStrategy::ObjectId)
    .build()?

Custom（自定义前缀）

DatabaseConfig::builder()
    .id_strategy(IdStrategy::Custom("user_".to_string()))
    .build()?

🧠 缓存配置

基本缓存配置（仅L1内存缓存）

use rat_quickdb::types::{CacheConfig, CacheStrategy, TtlConfig, L1CacheConfig};

let cache_config = CacheConfig {
    enabled: true,
    strategy: CacheStrategy::Lru,
    ttl_config: TtlConfig {
        default_ttl_secs: 300,  // 5分钟缓存
        max_ttl_secs: 3600,     // 最大1小时
        check_interval_secs: 60, // 检查间隔
    },
    l1_config: L1CacheConfig {
        max_capacity: 1000,     // 最多1000个条目
        max_memory_mb: 64,       // 64MB内存限制
        enable_stats: true,      // 启用统计
    },
    l2_config: None,           // 不使用L2磁盘缓存
    compression_config: CompressionConfig::default(),
    version: "1".to_string(),
};

DatabaseConfig::builder()
    .cache(cache_config)
    .build()?

L1+L2缓存配置（内置L2缓存支持）

use rat_quickdb::types::{CacheConfig, CacheStrategy, TtlConfig, L1CacheConfig, L2CacheConfig};
use std::path::PathBuf;

let cache_config = CacheConfig {
    enabled: true,
    strategy: CacheStrategy::Lru,
    ttl_config: TtlConfig {
        default_ttl_secs: 1800, // 30分钟缓存
        max_ttl_secs: 7200,     // 最大2小时
        check_interval_secs: 120, // 检查间隔
    },
    l1_config: L1CacheConfig {
        max_capacity: 5000,     // 最多5000个条目
        max_memory_mb: 128,      // 128MB内存限制
        enable_stats: true,      // 启用统计
    },
    l2_config: Some(L2CacheConfig {
        max_size_mb: 1024,      // 1GB磁盘缓存
        cache_dir: PathBuf::from("./cache"), // 缓存目录
        enable_persistence: true, // 启用持久化
        enable_compression: true, // 启用压缩
        cleanup_interval_secs: 300, // 清理间隔
    }),
    compression_config: CompressionConfig::default(),
    version: "1".to_string(),
};

DatabaseConfig::builder()
    .cache(cache_config)
    .build()?

L2缓存特性说明:

• L2缓存功能已内置在 rat_memcache 中，无需额外特性
• 需要磁盘空间存储缓存数据
• 适合缓存大量数据或需要持久化的场景
• 只需在 CacheConfig 中配置 l2_config 即可启用L2缓存

缓存统计和管理

// 获取缓存统计信息
let stats = get_cache_stats("default").await?;
println!("缓存命中率: {:.2}%", stats.hit_rate * 100.0);
println!("缓存条目数: {}", stats.entries);

// 清理缓存
clear_cache("default").await?;
clear_all_caches().await?;

📝 日志控制

rat_quickdb现在完全由调用者控制日志初始化：

use rat_logger::{Logger, LoggerBuilder, LevelFilter};

// 调用者负责初始化日志系统
let logger = LoggerBuilder::new()
    .with_level(LevelFilter::Debug)
    .with_file("app.log")
    .build();

logger.init().expect("日志初始化失败");

// 然后初始化rat_quickdb（不再自动初始化日志）
rat_quickdb::init();

🔧 数据库配置

SQLite

use rat_quickdb::*;

let pool_config = PoolConfig::default();

let config = sqlite_config(
    "sqlite_db",
    "./test.db",
    pool_config
)?;
add_database(config).await?;

PostgreSQL

use rat_quickdb::*;

let pool_config = PoolConfig::default();
let config = postgres_config(
    "postgres_db",
    "localhost",
    5432,
    "mydatabase",
    "username",
    "password",
    pool_config
)?;
add_database(config).await?;

MySQL

use rat_quickdb::*;

let pool_config = PoolConfig::default();
let config = mysql_config(
    "mysql_db",
    "localhost",
    3306,
    "mydatabase",
    "username",
    "password",
    pool_config
)?;
add_database(config).await?;

MongoDB

基础配置（使用便捷函数）

use rat_quickdb::*;

let pool_config = PoolConfig::default();
let config = mongodb_config(
    "mongodb_db",
    "localhost",
    27017,
    "mydatabase",
    Some("username"),
    Some("password"),
    pool_config
)?;
add_database(config).await?;

高级配置（使用构建器）

use rat_quickdb::*;

let pool_config = PoolConfig::default();
let tls_config = TlsConfig {
    enabled: true,
    verify_server_cert: false,
    verify_hostname: false,
    ..Default::default()
};

let zstd_config = ZstdConfig {
    enabled: true,
    compression_level: Some(3),
    compression_threshold: Some(1024),
};

let builder = MongoDbConnectionBuilder::new("localhost", 27017, "mydatabase")
    .with_auth("username", "password")
    .with_auth_source("admin")
    .with_direct_connection(true)
    .with_tls_config(tls_config)
    .with_zstd_config(zstd_config);

let config = mongodb_config_with_builder(
    "mongodb_db",
    builder,
    pool_config,
)?;
add_database(config).await?;

🛠️ 核心API

数据库管理

• init() - 初始化库
• add_database(config) - 添加数据库配置
• remove_database(alias) - 移除数据库配置
• get_aliases() - 获取所有数据库别名
• set_default_alias(alias) - 设置默认数据库别名

模型操作（推荐）

// 保存记录
let user_id = user.save().await?;

// 查询记录
let found_user = ModelManager::<User>::find_by_id(&user_id).await?;
let users = ModelManager::<User>::find(conditions, options).await?;

// 更新记录
let mut updates = HashMap::new();
updates.insert("username".to_string(), DataValue::String("新名字".to_string()));
let updated = user.update(updates).await?;

// 删除记录
let deleted = user.delete().await?;

ODM操作（底层接口）

• create(collection, data, alias) - 创建记录
• find_by_id(collection, id, alias) - 根据ID查找
• find(collection, conditions, options, alias) - 查询记录
• update(collection, id, data, alias) - 更新记录
• delete(collection, id, alias) - 删除记录
• count(collection, query, alias) - 计数
• exists(collection, query, alias) - 检查是否存在

🏗️ 架构特点

rat_quickdb采用现代化架构设计：

1. 无锁队列架构: 避免直接持有数据库连接的生命周期问题
2. 模型自动注册: 首次使用时自动注册模型元数据
3. 自动索引管理: 根据模型定义自动创建表和索引
4. 跨数据库适配: 统一的接口支持多种数据库类型
5. 异步消息处理: 基于Tokio的高效异步处理

🔄 工作流程

应用层 → 模型操作 → ODM层 → 消息队列 → 连接池 → 数据库
    ↑                                        ↓
    └────────────── 结果返回 ←────────────────┘

📊 性能特性

• 连接池管理: 智能连接复用和管理
• 异步操作: 非阻塞的数据库操作
• 批量处理: 支持批量操作优化
• 缓存集成: 内置缓存减少数据库访问
• 压缩支持: MongoDB支持ZSTD压缩

🎯 支持的字段类型

• integer_field - 整数字段（支持范围和约束）
• string_field - 字符串字段（支持长度限制，可设置大长度作为长文本使用）
• float_field - 浮点数字段（支持范围和精度）
• boolean_field - 布尔字段
• datetime_field - 日期时间字段
• uuid_field - UUID字段
• json_field - JSON字段
• array_field - 数组字段
• list_field - 列表字段（array_field的别名）
• dict_field - 字典/对象字段（基于Object类型）
• reference_field - 引用字段（外键）

📝 索引支持

• 唯一索引: unique() 约束
• 复合索引: 多字段组合索引
• 普通索引: 基础查询优化索引
• 自动创建: 基于模型定义自动创建
• 跨数据库: 支持所有数据库类型的索引

🌟 版本信息

当前版本: 0.3.1

支持Rust版本: 1.70+

重要更新: v0.3.0 强制使用define_model!宏定义模型，修复重大架构问题，提升类型安全性！

📄 许可证

本项目采用 LGPL-v3 许可证。

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目！

📞 联系方式

如有问题或建议，请通过以下方式联系：

• 创建Issue: GitHub Issues
• 邮箱: oldmos@gmail.com