nusadb 0.1.0

Fast, stable native Rust driver and ORM for NusaDB (Nusa Wire Protocol 1.1).
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

//! # nusadb — native Rust driver + ORM for NusaDB
//!
//! `nusadb` speaks the [Nusa Wire Protocol](../../../docs/wire-protocol.md) (`PROTOCOL_VERSION 1.1`)
//! directly over TCP — no engine linkage, no C bindings, no async runtime. It is built for three
//! things: **fast** (buffered framing, native value decoding, pooled connections), **stable**
//! (no panics in the library path, bounds-checked decoding, constant-time SCRAM verification), and
//! **complete** — because a driver is a SQL-text transport, it supports *every* query the server
//! accepts: any DDL/DML/SELECT, joins, CTEs, window functions, subqueries, set-ops, transactions,
//! stored procedures, and all 16 value types are decoded to native Rust.
//!
//! ## Quick start
//!
//! ```no_run
//! use nusadb::{Connection, Value};
//!
//! let mut conn = Connection::connect("nusadb://nusa-root@127.0.0.1:5678/nusadb")?;
//! conn.execute("CREATE TABLE t (id INT NOT NULL, name TEXT, PRIMARY KEY (id))")?;
//! conn.query_params("INSERT INTO t VALUES ($1, $2)", &[&1_i64, &"alice"])?;
//!
//! let result = conn.query("SELECT id, name FROM t ORDER BY id")?;
//! for row in &result.rows {
//!     let id: i64 = row.get(0)?;
//!     let name: String = row.get(1)?;
//!     println!("{id} {name}");
//! }
//! # Ok::<(), nusadb::Error>(())
//! ```
//!
//! ## Transactions, pooling, ORM
//!
//! ```no_run
//! use nusadb::{Pool, Config};
//! use nusadb::orm::{Select, Insert};
//!
//! let pool = Pool::new(Config::from_url("nusadb://nusa-root@127.0.0.1:5678/nusadb")?, 8)?;
//! let mut conn = pool.get()?;
//!
//! conn.transaction(|tx| {
//!     Insert::into("t").set("id", 2_i64).set("name", "bob").run(tx)?;
//!     Ok(())
//! })?;
//!
//! let rows = Select::from("t").filter("id", 2_i64).limit(1).fetch(&mut conn)?;
//! # Ok::<(), nusadb::Error>(())
//! ```

#![forbid(unsafe_code)]
#![warn(missing_docs)]
#![warn(clippy::all)]

mod connection;
mod error;
mod pool;
mod protocol;
mod scram;
mod tls;
mod transport;
mod value;

/// Query-builder ORM (`Select`/`Insert`/`Update`/`Delete`, [`orm::FromRow`]).
pub mod orm;

/// Async API on the Tokio runtime (feature `async`): [`aio::AsyncConnection`] and [`aio::AsyncPool`].
#[cfg(feature = "async")]
pub mod aio;

#[cfg(feature = "async")]
pub use aio::{AsyncConnection, AsyncPool, AsyncPooled};

pub use connection::{CancelHandle, Config, Connection, Notification, Prepared, QueryResult, Row};
pub use error::{Error, Result};
pub use orm::{Delete, FromRow, Insert, Select, Update};
pub use pool::{Pool, PooledConnection};
pub use protocol::TypeTag;
pub use tls::TlsConfig;
pub use value::{FromSql, ToSql, Value};

/// Open a connection from a `nusadb://[user[:password]@]host[:port]/database` URL.
///
/// # Errors
/// Returns [`Error::Config`] on a malformed URL, [`Error::Io`] on a connect failure, and
/// [`Error::Auth`] / [`Error::Server`] if the handshake is rejected.
pub fn connect(url: &str) -> Result<Connection> {
    Connection::connect(url)
}