---
<a id="en"></a>
# tosql : Trait for SQL Struct Serialization
Defines the `ToSqlTrait` trait for serializing Rust structs into binary formats compatible with SQL bulk inserts.
## Table of Contents
- [Introduction](#introduction)
- [Features](#features)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Tech Stack](#tech-stack)
- [Directory Structure](#directory-structure)
## Introduction
`tosql` provides the fundamental `ToSqlTrait` trait used to map Rust structs to SQL table schemas. It works in conjunction with `kind2sql` to enable efficient, type-safe serialization of data for database operations.
## Features
- **Standardized Trait**: Defines a common interface for SQL-compatible structs.
- **Type Safety**: Leverages `kind2sql::Kind` to ensure data types match the database schema.
- **Zero-Copy Friendly**: Designed to work with `bytes::Bytes` for efficient memory usage.
## Usage
The most common way to use `tosql` is with the `tosql_derive` macro to automatically implement the `ToSqlTrait` trait.
First, add dependencies:
```toml
[dependencies]
tosql = "0.1"
tosql_derive = "0.1"
```
Then, derive `ToSql` for your structs:
```rust
use tosql::{SqlField, ToSqlTrait, ToSql, mysql::{KIND, Mysql}};
#[derive(ToSql, Debug)]
struct User {
id: u64,
name: String,
age: u8,
}
fn main() {
let user = User {
id: 1001,
name: "Alice".to_string(),
age: 30,
};
// 1. Get Schema Information
println!("Table Name: {}", User::name());
println!("Fields: {:?}", User::field_li());
println!("Types: {:?}", User::kind_li());
// 2. Serialize Data
let bytes = user.dump();
println!("Serialized bytes: {:?}", bytes);
// 3. Convert to SQL Values (using kind2sql's Mysql implementation)
let sql_values = Mysql::sql_field(&User::kind_li(), bytes).unwrap();
println!("SQL Values: {:?}", sql_values);
// Output: ["1001", "'Alice'", "30"]
// 4. Generate SQL Statement Example
let columns = User::field_li().join(", ");
let values = sql_values.join(", ");
println!("INSERT INTO `{}` ({}) VALUES ({});", User::name(), columns, values);
}
```
## API Reference
### `trait ToSqlTrait`
- `fn name() -> String`: Returns the struct (or table) name.
- `fn kind_li() -> Vec<Kind>`: Returns the list of field types (`Kind`).
- `fn field_li() -> Vec<String>`: Returns the list of field names.
- `fn dump(&self) -> Bytes`: Serializes the struct instance into a binary buffer.
## Tech Stack
- [Rust](https://www.rust-lang.org/)
- `bytes`: For efficient byte buffer management.
- `kind2sql`: For type definitions (`Kind`).
## Related Crates
- [tosql_derive](https://docs.rs/crate/tosql_derive): Macro to derive `ToSqlTrait`.
- [to_mysql](https://docs.rs/crate/to_mysql): MySQL SQL generation logic.
- [tosql_meta](https://docs.rs/crate/tosql_meta): Metadata definition for SQL structs.
## Directory Structure
```
.
├── Cargo.toml # Package manifest
├── readme/ # Documentation
│ ├── en.md # English README
│ └── zh.md # Chinese README
└── src/
└── lib.rs # Trait definition
```
---
## About
This project is an open-source component of [js0.site ⋅ Refactoring the Internet Plan](https://js0.site).
We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:
* [Google Group](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)
---
<a id="zh"></a>
# tosql : SQL结构体序列化Trait
定义了 `ToSqlTrait` trait，用于将 Rust 结构体序列化为兼容 SQL 批量插入的二进制格式。
## 目录
- [简介](#简介)
- [特性](#特性)
- [使用演示](#使用演示)
- [API 参考](#api-参考)
- [技术栈](#技术栈)
- [目录结构](#目录结构)
## 简介
`tosql` 提供了基础的 `ToSqlTrait` trait，用于将 Rust 结构体映射到 SQL 表模式。它与 `kind2sql` 配合使用，实现数据库操作的高效、类型安全的数据序列化。
## 特性
- **标准化接口**：为兼容 SQL 的结构体定义通用接口。
- **类型安全**：利用 `kind2sql::Kind` 确保数据类型与数据库模式匹配。
- **零拷贝友好**：设计用于配合 `bytes::Bytes` 使用，实现高效内存管理。
## 使用演示
使用 `tosql` 最常见的方式是配合 `tosql_derive` 宏自动实现 `ToSqlTrait` trait。
首先，添加依赖：
```toml
[dependencies]
tosql = "0.1"
tosql_derive = "0.1"
```
然后，为你的结构体派生 `ToSql`：
```rust
use tosql::{SqlField, ToSqlTrait, ToSql, mysql::{KIND, Mysql}};
#[derive(ToSql, Debug)]
struct User {
id: u64,
name: String,
age: u8,
}
fn main() {
let user = User {
id: 1001,
name: "Alice".to_string(),
age: 30,
};
// 1. 获取模式信息
println!("表名: {}", User::name());
println!("字段: {:?}", User::field_li());
println!("类型: {:?}", User::kind_li());
// 2. 序列化数据
let bytes = user.dump();
println!("序列化字节: {:?}", bytes);
// 3. 转换为 SQL 值 (使用 kind2sql 的 Mysql 实现)
let sql_values = Mysql::sql_field(&User::kind_li(), bytes).unwrap();
println!("SQL 值: {:?}", sql_values);
// 输出: ["1001", "'Alice'", "30"]
// 4. 生成 SQL 语句示例
let columns = User::field_li().join(", ");
let values = sql_values.join(", ");
println!("INSERT INTO `{}` ({}) VALUES ({});", User::name(), columns, values);
}
```
## API 参考
### `trait ToSqlTrait`
- `fn name() -> String`：返回结构体（或表）名称。
- `fn kind_li() -> Vec<Kind>`：返回字段类型列表 (`Kind`)。
- `fn field_li() -> Vec<String>`：返回字段名称列表。
- `fn dump(&self) -> Bytes`：将结构体实例序列化为二进制缓冲区。
## 技术栈
- [Rust](https://www.rust-lang.org/)
- `bytes`：用于高效字节缓冲区管理。
- `kind2sql`：用于类型定义 (`Kind`)。
## 相关库
- [tosql_derive](https://docs.rs/crate/tosql_derive)：用于派生 `ToSqlTrait` 的宏。
- [to_mysql](https://docs.rs/crate/to_mysql)：MySQL SQL 生成逻辑。
- [tosql_meta](https://docs.rs/crate/tosql_meta)：SQL 结构体的元数据定义。
## 目录结构
```
.
├── Cargo.toml # 包配置
├── readme/ # 文档
│ ├── en.md # 英文 README
│ └── zh.md # 中文 README
└── src/
└── lib.rs # Trait 定义
```
---
## 关于
本项目为 [js0.site ⋅ 重构互联网计划](https://js0.site) 的开源组件。
我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：
* [谷歌邮件列表](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)