# vds-rust-sdk

**Repository Path**: bigant/vds-rust-sdk

## Basic Information

- **Project Name**: vds-rust-sdk
- **Description**: Rust 的 SDK以便支持对VDS的使用
- **Primary Language**: Rust
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VDS Rust SDK

Rust SDK for [VDS (Versatile Database System)](https://gitee.com/bigant/vds) - 为 Rust 应用提供访问 VDS 数据库的能力。

## 特性

- ✅ **同步 API** - 简单易用的阻塞式接口
- ✅ **连接池** - 自动管理多个 TCP 连接，支持多线程并发
- ✅ **事务支持** - 完整的事务管理，自动回滚保护
- ✅ **类型安全** - 强类型的查询结果访问
- ✅ **进程管理** - 自动启动和管理 VDS Server 子进程
- ✅ **纯 Rust** - 无需 FFI，通过 TCP 协议通信

## 安装

在 `Cargo.toml` 中添加依赖：

```toml
[dependencies]
vds-client = { git = "https://gitee.com/bigant/vds-rust-sdk.git" }
```

## 快速开始

```rust
use vds_client::{VdsManager, VdsConfig};
use std::path::PathBuf;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. 配置 VDS
    let config = VdsConfig {
        data_dir: PathBuf::from("./data"),           // 数据目录
        port: 17788,                                  // 监听端口
        vds_server_path: PathBuf::from("./vds-server.exe"),
        max_connections: 10,                          // 连接池大小
    };

    // 2. 启动 VDS Server
    let manager = VdsManager::new(config)?;
    manager.start()?;

    // 3. 获取数据库连接
    let db = manager.get_client()?;

    // 4. 创建表
    db.execute(
        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)",
        &[]
    )?;

    // 5. 插入数据
    db.execute("INSERT INTO users (name, age) VALUES (?, ?)", &["Alice", "30"])?;
    db.execute("INSERT INTO users (name, age) VALUES (?, ?)", &["Bob", "25"])?;

    // 6. 查询数据
    let rows = db.query("SELECT id, name, age FROM users")?;
    for row in rows {
        let id = row.get_i64("id")?;
        let name = row.get_string("name")?;
        let age = row.get_i64("age")?;
        println!("User {}: {} ({})", id, name, age);
    }

    // 7. 关闭
    manager.shutdown()?;

    Ok(())
}
```

## 使用指南

### 基本 CRUD 操作

```rust
// 插入
let rows_affected = db.execute(
    "INSERT INTO users (name, age) VALUES (?, ?)",
    &["Charlie", "35"]
)?;

// 查询
let rows = db.query("SELECT * FROM users WHERE age > 25")?;
for row in rows {
    let name = row.get_string("name")?;
    println!("{}", name);
}

// 更新
db.execute("UPDATE users SET age = ? WHERE name = ?", &["36", "Charlie"])?;

// 删除
db.execute("DELETE FROM users WHERE name = ?", &["Charlie"])?;
```

### 事务

```rust
// 开始事务
let mut tx = db.begin()?;

// 在事务中执行操作
tx.execute("INSERT INTO users (name, age) VALUES (?, ?)", &["David", "28"])?;
tx.execute("UPDATE users SET age = age + 1 WHERE name = ?", &["Alice"])?;

// 提交事务
tx.commit()?;

// 或者回滚
// tx.rollback()?;
```

**自动回滚**：如果 `Transaction` 在未提交的情况下被 Drop，会自动回滚。

```rust
{
    let mut tx = db.begin()?;
    tx.execute("INSERT INTO users (name, age) VALUES (?, ?)", &["Eve", "22"])?;
    // tx Drop，自动回滚
}
```

### 多线程并发

```rust
use std::sync::Arc;
use std::thread;

let manager = Arc::new(VdsManager::new(config)?);
manager.start()?;

let mut handles = vec![];
for i in 0..5 {
    let m = Arc::clone(&manager);
    let handle = thread::spawn(move || {
        // 每个线程从连接池获取独立连接
        let db = m.get_client().unwrap();
        db.execute(
            "INSERT INTO users (name, age) VALUES (?, ?)",
            &[&format!("User{}", i), "20"]
        ).unwrap();
    });
    handles.push(handle);
}

for handle in handles {
    handle.join().unwrap();
}
```

### 类型安全的列访问

```rust
let rows = db.query("SELECT id, name, age, active FROM users")?;
for row in rows {
    // 整数
    let id: i64 = row.get_i64("id")?;
    
    // 字符串
    let name: String = row.get_string("name")?;
    
    // 浮点数
    // let score: f64 = row.get_f64("score")?;
    
    // 布尔值
    // let active: bool = row.get_bool("active")?;
    
    // 二进制
    // let data: Vec<u8> = row.get_bytes("data")?;
    
    // 检查 NULL
    if row.is_null("age") {
        println!("Age is NULL");
    }
}
```

### 自定义数据目录

```rust
// 方案 1: 应用启动目录
let data_dir = std::env::current_exe()?
    .parent()
    .unwrap()
    .join("data");

// 方案 2: 用户配置目录（需要 dirs crate）
// let data_dir = dirs::config_dir()
//     .unwrap()
//     .join("YourAppName")
//     .join("database");

// 方案 3: 完全自定义
// let data_dir = PathBuf::from(r"D:\MyData\YourApp");

let config = VdsConfig {
    data_dir,
    port: 17788,
    vds_server_path: PathBuf::from("./vds-server.exe"),
    max_connections: 10,
};
```

## API 参考

### `VdsManager`

管理 VDS Server 进程和连接池。

```rust
pub fn new(config: VdsConfig) -> Result<Self>;
pub fn start(&self) -> Result<()>;
pub fn get_client(&self) -> Result<VdsClient>;
pub fn shutdown(self) -> Result<()>;
pub fn pool_stats(&self) -> PoolStats;
```

### `VdsClient`

数据库客户端，提供 SQL 操作接口。

```rust
pub fn execute(&self, sql: &str, params: &[&str]) -> Result<u64>;
pub fn execute_returning_id(&self, sql: &str, params: &[&str]) -> Result<i64>;
pub fn query(&self, sql: &str) -> Result<Vec<Row>>;
pub fn query_one(&self, sql: &str, params: &[&str]) -> Result<Option<Row>>;
pub fn begin(&self) -> Result<Transaction>;
pub fn ping(&self) -> Result<()>;
```

### `Transaction`

事务对象，Drop 时自动回滚（如果未提交）。

```rust
pub fn commit(self) -> Result<()>;
pub fn rollback(self) -> Result<()>;
pub fn execute(&mut self, sql: &str, params: &[&str]) -> Result<u64>;
pub fn execute_returning_id(&mut self, sql: &str, params: &[&str]) -> Result<i64>;
pub fn query(&mut self, sql: &str) -> Result<Vec<Row>>;
pub fn query_one(&mut self, sql: &str, params: &[&str]) -> Result<Option<Row>>;
```

### `Row`

查询结果行，提供类型安全的列访问。

```rust
pub fn get_i64(&self, column: &str) -> Result<i64>;
pub fn get_f64(&self, column: &str) -> Result<f64>;
pub fn get_string(&self, column: &str) -> Result<String>;
pub fn get_bytes(&self, column: &str) -> Result<Vec<u8>>;
pub fn get_bool(&self, column: &str) -> Result<bool>;
pub fn is_null(&self, column: &str) -> bool;
pub fn columns(&self) -> Vec<String>;
```

## 部署

应用安装包需要包含：

```
YourApp/
├── your_app.exe          # 你的应用
├── vds-server.exe        # VDS 服务器（从 VDS 项目编译）
└── data/                 # 数据目录（自动创建）
    └── vds.db            # 数据库文件
```

**编译 vds-server.exe**：

```bash
# 在 VDS 主项目根目录
cd path/to/vds
go build -o vds-server.exe ./cmd/vds-server
```

## 示例

完整示例参见 [examples/demo.rs](examples/demo.rs)。

运行示例（需要先编译 vds-server.exe）：

```bash
cargo run --example demo
```

## 文档

- [设计文档](docs/DESIGN.md) - SDK 架构设计
- [集成指南](docs/INTEGRATION_GUIDE.md) - 详细的 API 文档和使用指南

## 错误处理

```rust
use vds_client::VdsError;

match db.execute("INSERT INTO users ...", &[...]) {
    Ok(rows) => println!("插入成功: {} 行", rows),
    Err(VdsError::Connection(msg)) => eprintln!("连接错误: {}", msg),
    Err(VdsError::Sql(msg)) => eprintln!("SQL 错误: {}", msg),
    Err(VdsError::Protocol(msg)) => eprintln!("协议错误: {}", msg),
    Err(e) => eprintln!("其他错误: {}", e),
}
```

## 限制

- 当前仅支持同步 API（异步版本计划中）
- `execute_returning_id` 需要 VDS Server 支持返回 last_insert_id
- 连接池大小固定，不支持动态调整

## 许可证

MIT License

## 相关项目

- [VDS](https://gitee.com/bigant/vds) - VDS 数据库主项目