sqlx-xugu 0.8.6-2

Xugu driver implementation for SQLx. Not for direct use; see the `sqlx` crate for details.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

# sqlx-xugu

[![github](https://img.shields.io/badge/Github-BrightX/sqlx--xugu-blue?logo=github)](https://github.com/BrightX/sqlx-xugu)
[![gitee](https://img.shields.io/badge/Gitee-BrightXu/sqlx--xugu-8da0cb?labelColor=C71D23&logo=gitee)](https://gitee.com/BrightXu/sqlx-xugu)
[![crate](https://img.shields.io/crates/v/sqlx-xugu.svg?logo=rust)](https://crates.io/crates/sqlx-xugu)
[![documentation](https://img.shields.io/badge/docs.rs-sqlx--xugu-66c2a5?labelColor=555555&logo=docs.rs)](https://docs.rs/sqlx-xugu)
[![minimum rustc 1.60](https://img.shields.io/badge/rustc-1.60+-red.svg?logo=rust)](https://rust-lang.github.io/rfcs/2495-min-rust-version.html)
![License](https://img.shields.io/crates/l/sqlx-xugu)

> 基于 `sqlx` 的 `rust` 虚谷数据库驱动。
> 
> 支持虚谷数据库 `v11`/`v12`。

## Install

添加依赖，注意版本要跟 `sqlx` 保持一致

```toml
# Cargo.toml
sqlx = { version = "=0.8.6", features = ["runtime-tokio"] }
sqlx-xugu = { version = "0.8.6-2" }

```

#### Cargo Feature Flags

添加 feature, 注意要跟 `sqlx` 保持一致

```toml
# Cargo.toml
sqlx = { version = "=0.8.6", features = ["runtime-tokio", "chrono", "uuid", "rust_decimal", "bigdecimal", "time"] }
sqlx-xugu = { version = "0.8.6-2", features = ["chrono", "uuid", "rust_decimal", "bigdecimal", "time"] }
```

-   `uuid`: 添加对 UUID 的支持。

-   `chrono`: 添加对 `chrono` 中的日期和时间类型的支持。

-   `time`: 添加对 `time` crate 中的日期和时间类型的支持 (alternative to `chrono`, which is preferred by `query!` macro, if both enabled)

-   `bigdecimal`: 使用 `bigdecimal` crate 添加对 `NUMERIC` 的支持。

-   `rust_decimal`: 使用 `rust_decimal` crate 添加对 `NUMERIC` 的支持。

-   `json`: 使用 `serde_json` crate 添加对 `JSON` 的支持。

## Usage

### 快速入门

```rust
use sqlx_xugu::XuguPoolOptions;

#[tokio::main] // Requires the `attributes` feature of `tokio`
// or #[async_std::main]
// or #[actix_web::main]
async fn main() -> Result<(), sqlx::Error> {
    // Create a connection pool
    //  for Xugu, use XuguPoolOptions::new()
    let pool = XuguPoolOptions::new()
        .max_connections(5)
        .connect("xugu://user:password@127.0.0.1:5138/SYSTEM").await?;

    // 进行简单的查询以返回给定的参数 (使用问号 `?` 占位符)
    let row: (i64,) = sqlx::query_as("SELECT ?")
        .bind(150_i64)
        .fetch_one(&pool).await?;

    assert_eq!(row.0, 150);

    Ok(())
}
```

### 建立连接

可以使用 `XuguConnection` 并调用 `connect()` 建立单个连接。

```rust
use sqlx::Connection;
use sqlx_xugu::XuguConnection;

let conn = XuguConnection::connect("xugu://user:password@127.0.0.1:5138/SYSTEM").await?;
```

通常，您需要为应用程序创建一个连接池 (`sqlx::Pool`) 来调节它正在使用的服务器端连接数。

```rust
let pool = XuguPool::connect("xugu://user:password@127.0.0.1:5138/SYSTEM").await?;

// 指定连接池大小和连接时间等参数
let pool = XuguPoolOptions::new()
    .max_connections(50)
    .acquire_timeout(std::time::Duration::from_secs(5))
    .idle_timeout(std::time::Duration::from_secs(300))
    .max_lifetime(std::time::Duration::from_secs(86400))
    .connect("xugu://user:password@127.0.0.1:5138/SYSTEM?ssl=ssl")
    .await?;
```

sqlx-xugu 驱动url格式，支持以下几种

```
1. xugu://ip:port/databaseName[?property=value[&property=value]]
  * 例：xugu://127.0.0.1:5138/SYSTEM?user=GUEST&password=GUEST&version=301&time_zone=GMT

2. xugu://user:passwd@ip:port/databaseName[?property=value[&property=value]]
  * 例：xugu://GUEST:GUEST@127.0.0.1:5138/SYSTEM?version=301&time_zone=GMT

```

#### 连接参数

| 参数名             | 说明                                                                                                                         | 初始值                |
|:----------------|:---------------------------------------------------------------------------------------------------------------------------|:-------------------|
| database        | 数据库名                                                                                                                       |                    |
| user            | 用户名                                                                                                                        |                    |
| password        | 用户密码                                                                                                                       |                    |
| version         | 服务器版本                                                                                                                      | 301                |
| encryptor       | 数据库解密密钥                                                                                                                    |                    |
| charset         | 客户端字符集(**utf8**或**gbk**)                                                                                                   | utf8               |
| lob_ret         | 大对象返回方式                                                                                                                    |                    |
| time_zone       | 客户端时区                                                                                                                      |                    |
| iso_level       | 事务隔离级别                                                                                                                     | READ COMMITTED读已提交 |
| lock_timeout    | 最大加锁等候时间                                                                                                                   |                    |
| auto_commit     | 是否自动提交                                                                                                                     | on                 |
| return_rowid    | 是否返回**rowid**                                                                                                              | false              |
| return_schema   | 查询**SQL**是否返回模式信息（此参数存在一个疑问）                                                                                               | on                 |
| identity_mode   | 数据库服务端自增长使用模式（**DEFAULT**：**default**自增,**NULL_AS_AUTO_INCREMENT**：**NULL**自增,**ZERO_AS_AUTO_INCREMENT**：**0**和**NULL**自增） |                    |
| keyword_filter  | 数据库连接配置连接上需要开放的关键字串，已逗号分隔，例如**TABLE,FUNCTION,CONSTANT**                                                                    |                    |
| disable_binlog  | 不记载**binlog**日志                                                                                                            |                    |
| current_schema  | 指定连接的模式名                                                                                                                   |                    |
| compatible_mode | 适配其他数据库(**MySQL/ORACLE/PostgreSQL**)                                                                                       | NONE               |
| use_ssl         | 是否开启传输数据加密保护 `on`: 启用加密，`off`: 禁用加密                                                                                        | off                |
| ssl             | 同上 `ssl=ssl`: 启用加密，`ssl=nssl`: 禁用加密                                                                                        | nssl               |

### 更多请参考 `sqlx` 相关文档

* `docs.rs`: https://docs.rs/sqlx/latest/sqlx/ 
* `Github`: https://github.com/launchbadge/sqlx 
* `crates.io`: https://crates.io/crates/sqlx 

## 联系方式

- **Bug 反馈**: [GitHub Issues](https://github.com/BrightX/sqlx-xugu/issues)
- **一般讨论**: [GitHub Discussions](https://github.com/BrightX/sqlx-xugu/discussions)
- **商务合作**: [BrightXu666@163.com](mailto:BrightXu666@163.com)

## 许可证

[MIT](https://opensource.org/license/mit) or [Apache 2.0](https://opensource.org/licenses/Apache-2.0)

### 免责声明

**sqlx-xugu** 跟 **成都虚谷伟业科技有限公司** 不构成任何知识产权归属关系。这个程序不含任何担保。

软件以“现状”提供，不提供任何明示或暗示的保证，包括但不限于可销性、特定用途适用性和非侵权等保证。
无论如何，作者或版权持有人对因软件或软件使用或其他交易产生的、涉及合同、侵权或其他诉讼的索赔、损害或其他责任均不承担责任。