# 数据库支持
HwhKit 提供了对关系数据库和向量数据库的支持，可以根据配置灵活加载。
## 功能特性
- **关系数据库支持**: 通过 SQLx 支持 PostgreSQL、MySQL 和 SQLite
- **向量数据库支持**: 集成 Qdrant 向量数据库
- **配置驱动**: 通过配置文件控制数据库的启用和连接参数
- **连接池管理**: 自动管理数据库连接池
- **健康检查**: 提供数据库连接状态检查
## 启用数据库功能
### 1. 在 Cargo.toml 中启用特性
```toml
[dependencies]
hwhkit = { version = "0.1", features = ["database", "vector"] }
```
或者只启用需要的功能：
```toml
# 只启用关系数据库
hwhkit = { version = "0.1", features = ["database"] }
# 只启用向量数据库
hwhkit = { version = "0.1", features = ["vector"] }
```
### 2. 配置数据库
在配置文件（如 `config.toml`）中添加数据库配置：
#### 关系数据库配置
```toml
[database]
enabled = true
db_type = "postgres" # 支持: postgres, mysql, sqlite
url = "postgresql://user:password@localhost:5432/myapp"
max_connections = 10
min_connections = 2
connect_timeout = 30
auto_migrate = false
```
**配置说明：**
- `enabled`: 是否启用数据库（true/false）
- `db_type`: 数据库类型，支持 `postgres`、`mysql`、`sqlite`
- `url`: 数据库连接 URL
- `max_connections`: 连接池最大连接数
- `min_connections`: 连接池最小连接数
- `connect_timeout`: 连接超时时间（秒）
- `auto_migrate`: 是否自动运行迁移（当前版本保留字段）
**连接 URL 示例：**
```toml
# PostgreSQL
url = "postgresql://user:password@localhost:5432/database"
# MySQL
url = "mysql://user:password@localhost:3306/database"
# SQLite (文件)
url = "sqlite:./app.db"
# SQLite (内存)
url = "sqlite::memory:"
```
#### Qdrant 向量数据库配置
```toml
[qdrant]
enabled = true
url = "http://localhost:6334"
api_key = "" # 可选，如果 Qdrant 需要认证
timeout = 30
default_collection = "default"
```
**配置说明：**
- `enabled`: 是否启用向量数据库（true/false）
- `url`: Qdrant 服务器地址
- `api_key`: API 密钥（可选）
- `timeout`: 请求超时时间（秒）
- `default_collection`: 默认集合名称
## 使用示例
### 基本使用
```rust
use hwhkit::{WebServerBuilder, database::Database};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// 创建服务器（数据库会根据配置自动初始化）
let server = WebServerBuilder::new()
.config_from_file("config.toml")
.routes(app_routes)
.build()
.await?;
// 获取数据库实例
if let Some(db) = server.database() {
println!("数据库已连接");
// 测试连接
db.ping().await?;
}
server.serve().await?;
Ok(())
}
```
### 在 Axum 路由中使用
```rust
use axum::{extract::State, Json};
use hwhkit::database::Database;
// 定义应用状态
#[derive(Clone)]
struct AppState {
db: Database,
}
// 路由处理函数
async fn list_users(State(state): State<AppState>) -> Json<Vec<User>> {
let pool = state.db.pool();
// 使用 SQLx 查询
let users = sqlx::query_as::<_, User>("SELECT * FROM users")
.fetch_all(pool)
.await
.unwrap();
Json(users)
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let server = WebServerBuilder::new()
.config_from_file("config.toml")
.build()
.await?;
let state = AppState {
db: server.database().unwrap().clone(),
};
let app = Router::new()
.route("/users", get(list_users))
.with_state(state);
let final_server = hwhkit::server::WebServer::new(app, server.config().clone());
final_server.serve().await?;
Ok(())
}
```
### 使用向量数据库
```rust
use hwhkit::database::VectorDatabase;
async fn search_vectors(State(state): State<AppState>) -> Json<SearchResult> {
if let Some(vdb) = &state.vector_db {
// 列出所有集合
let collections = vdb.list_collections().await?;
// 使用 Qdrant 客户端
let client = vdb.client();
// ... 执行向量搜索操作
}
Json(result)
}
```
## 数据库操作
### 关系数据库
```rust
// 获取连接池
let pool = db.pool();
// 执行查询
let users = sqlx::query_as::<_, User>("SELECT * FROM users WHERE id = ?")
.bind(user_id)
.fetch_all(pool)
.await?;
// 执行插入
sqlx::query("INSERT INTO users (name, email) VALUES (?, ?)")
.bind(&user.name)
.bind(&user.email)
.execute(pool)
.await?;
// 执行原始 SQL
db.execute_raw("CREATE TABLE IF NOT EXISTS users (...)").await?;
```
### 向量数据库
```rust
use qdrant_client::qdrant::{CreateCollection, VectorParams, Distance};
// 创建集合
let client = vdb.client();
client.create_collection(&CreateCollection {
collection_name: "my_collection".to_string(),
vectors_config: Some(VectorParams {
size: 384,
distance: Distance::Cosine.into(),
..Default::default()
}.into()),
..Default::default()
}).await?;
// 检查集合是否存在
let exists = vdb.collection_exists("my_collection").await?;
// 列出所有集合
let collections = vdb.list_collections().await?;
```
## 示例项目
查看完整的示例代码：
```bash
# 运行数据库示例（需要启用 database 特性）
cargo run --example database-example --features database
# 运行带向量数据库的示例（需要 Qdrant 服务运行）
cargo run --example database-example --features "database,vector"
```
示例文件位置：
- `examples/database-example.rs` - 完整的数据库使用示例
- `examples/database-config.toml` - 示例配置文件
## 迁移管理
HwhKit 推荐使用 SQLx 的迁移功能管理数据库模式：
```bash
# 安装 sqlx-cli
cargo install sqlx-cli
# 创建迁移
sqlx migrate add create_users_table
# 运行迁移
sqlx migrate run --database-url "postgresql://..."
```
## 最佳实践
1. **连接池配置**: 根据应用负载调整 `max_connections` 和 `min_connections`
2. **错误处理**: 始终处理数据库操作可能的错误
3. **安全性**:
- 不要在代码中硬编码数据库凭证
- 使用环境变量或安全的配置管理
- 在生产环境使用强密码
4. **性能优化**:
- 使用连接池
- 适当使用索引
- 批量操作时使用事务
5. **监控**: 定期检查数据库连接状态和性能
## 故障排查
### 数据库连接失败
如果遇到连接问题：
1. 检查配置文件中的 URL 格式是否正确
2. 确认数据库服务正在运行
3. 检查网络连接和防火墙设置
4. 查看应用日志中的详细错误信息
### 向量数据库连接失败
1. 确认 Qdrant 服务正在运行：`docker ps` 或检查服务状态
2. 验证 URL 配置正确
3. 如果使用 API Key，确保配置正确
## 更多资源
- [SQLx 文档](https://docs.rs/sqlx/)
- [Qdrant 文档](https://qdrant.tech/documentation/)
- [HwhKit 完整文档](./README.md)