qusql_mysql/
lib.rs

1//! This crate allow efficient async communication with Mariadb/Mysql
2//!
3//! You can either establish a raw connection using [Connection] or
4//! use a [Pool] of connections.
5//!
6//! Drop handling
7//! ------------
8//!
9//! When dropping/cancelling any future or struct returned by the library. The connections
10//! will keep working. This is done by having the [Connection] have an internal state and
11//! finish up any partially executed queries when the next query is executed or when [Connection::cleanup]
12//! is called
13//!
14//! When dropping a [PoolConnection], any partial queries or transactions are finished up in
15//! a spawned task. If this task takes too long to execute the connection is closed an a new
16//! connection may be established.
17//!
18//! This means that if the qusql-mysql is used in a backend to handle web requests, and the
19//! web request is cancelled while performing a long running query. Then the long running
20//! query will be killed shortly after.
21//!
22//! Efficiency
23//! -----------
24//! We spawn very few tasks.  Currently the only task spawned is
25//! when a [PoolConnection] is dropped while there is a ongoing query or transaction.
26//!
27//! We have few memory allocations. In the cause of a normal
28//! query, even one returning a string, no memory will be allocated
29//!
30//! The error types returned are all 8 bytes.
31//!
32//! The benchmark folder contains a benchmark that compares sqlx to qusql-mysql.
33//! When run it shows the we are significantly more efficient than sqlx
34//!
35//! | Test          |   Qusql time |    Sqlx time |
36//! |---------------|--------------|--------------|
37//! | Setup         |     0.921 ms |     1.189 ms |
38//! | Insert        | 14218.778 ms | 15499.612 ms |
39//! | Select all    | 10968.823 ms | 15860.648 ms |
40//! | Select stream |  9991.353 ms | 13215.973 ms |
41//! | Select one    | 19085.157 ms | 34728.834 ms |
42//!
43//! Feature flags
44//! --------------
45//! * stats: Add query count and timing statistics to the [Connection]
46//! * chrono: Add bind and decode support for chrono DateTime and Time
47//! * list_hack: Add support lists as arguments to queries
48//!
49//! Example
50//! --------
51//! ```no_run
52//! use qusql_mysql::{Pool, ConnectionOptions, PoolOptions, ConnectionError, ExecutorExt, Executor};
53//!
54//! async fn test() -> Result<(), ConnectionError> {
55//!     let pool = Pool::connect(
56//!         ConnectionOptions::from_url("mysql://user:pw@127.0.0.1:3307/db").unwrap(),
57//!         PoolOptions::new().max_connections(10)
58//!     ).await?;
59//!
60//!     let mut conn = pool.acquire().await?;
61//!
62//!     let mut tr = conn.begin().await?;
63//!     tr.execute("INSERT INTO `table` (`v`, `t`) VALUES (?)", (42, "test_string")).await?;
64//!     tr.commit().await?;
65//!
66//!     let rows: Vec<(i64, &str)> = conn.fetch_all("SELECT `v`, `t` FROM `table`", ()).await?;
67//!     Ok(())
68//! }
69//! ```
70//!
71//! List hack
72//! ----------
73//! If the list `list_hack` feature is enabled. Support for lists as arguments to queries is added
74//! this is done done by adding a sufficient number of `?`'s to the query.
75//!
76//! ```no_run
77//! # use qusql_mysql::{Connection, ExecutorExt, Executor, list, ConnectionError};
78//! #[cfg(feature="list_hack")]
79//! async fn test(conn: &mut Connection, vs: &[u32]) -> Result<(), ConnectionError> {
80//!     let rows: Vec<(i64, &str)> = conn.fetch_all(
81//!         "SELECT `v`, `t` FROM `table` WHERE `v` IN (_LIST_)", (list(vs),)).await?;
82//!     Ok(())
83//! }
84//! ```
85//! Here the `_LIST_` is replaced with `?,?,..,?` where the number of `?`'s depend on the length
86//! of the list. If the list is empty `_LIST_` is replaced by `NULL`
87pub mod args;
88pub mod auth;
89pub mod bind;
90pub mod connection;
91pub mod constants;
92pub mod decode;
93mod handle_drop;
94mod lru;
95pub mod package_parser;
96pub mod plain_types;
97pub mod pool;
98pub mod row;
99pub use bind::{List, list};
100pub use connection::{
101    ColumnDefinition, Connection, ConnectionError, ConnectionErrorContent, ConnectionOptions,
102    ExecuteResult, Executor, ExecutorExt, Query, QueryIterator, RowMap, Transaction,
103};
104pub use pool::{Pool, PoolConnection, PoolOptions};
105pub use row::Row;
106
107#[cfg(feature = "chrono")]
108pub mod chrono;
qusql_mysql/lib.rs

qusql_mysql/
lib.rs
