@@ -6,13 +6,180 @@ Rust's type system to create a low overhead query builder that "feels like
66Rust."
77
88Diesel-async provides an async implementation of diesels connection implementation
9- and any method that may issue an query. It is designed as pure async drop in replacement
10- for the corresponding diesel methods.
9+ and any method that may issue an query. It is designed as pure async drop-in replacement
10+ for the corresponding diesel methods. Similar to diesel the crate is designed in a way
11+ that allows third party crates to extend the existing infrastructure and even provide
12+ their own connection implementations.
1113
1214Supported databases:
15+
13161 . PostgreSQL
14172 . MySQL
1518
19+ ## Usage
20+
21+ ### Simple usage
22+
23+ Diesel-async is designed to work in combination with diesel, not to replace diesel. For this it
24+ provides drop-in replacement for diesel functionality that actually interacts with the database.
25+
26+ A normal project should use a setup similar to the following one:
27+
28+ ``` toml
29+ [dependencies ]
30+ diesel = " 2.0.3" # no backend features need to be enabled
31+ diesel-async = { version = " 0.2.1" features = [" postgres"
32+ ```
33+
34+ This allows to import the relevant traits from both crates:
35+
36+ ``` rust
37+ use diesel :: prelude :: * ;
38+ use diesel_async :: {RunQueryDsl , AsyncConnection , AsyncPgConnection };
39+
40+ // ordinary diesel model setup
41+
42+ table! {
43+ users {
44+ id -> Integer ,
45+ name -> Text ,
46+ }
47+ }
48+
49+ #[derive(Queryable , Selectable )]
50+ #[diesel(table_name = users)]
51+ struct User {
52+ id : i32 ,
53+ name : Text ,
54+ }
55+
56+ // create an async connection
57+ let mut connection = AsyncPgConnection :: establish (std :: env :: var (" DATABASE_URL" ? ). await ? ;
58+
59+ // use ordinary diesel query dsl to construct your query
60+ let data : Vec <User > = users :: table
61+ . filter (users :: id . gt (0 ))
62+ . or_filter (users :: name . like (" %Luke"
63+ . select (User :: as_select ())
64+ // execute the query via the provided
65+ // async `diesel_async::RunQueryDsl`
66+ . load (& mut connection )
67+ . await ? ;
68+ ```
69+
70+ ### Async Transaction Support
71+
72+ Diesel-async provides an ergonomic interface to wrap several statements into a shared
73+ database transaction. Such transactions are automatically rolled back as soon as
74+ the inner closure returns an error
75+
76+ ``` rust
77+ connection . transaction :: <_ , diesel :: result :: Error , _ >(| conn | async move {
78+ diesel :: insert_into (users :: table )
79+ . values (users :: name . eq (" Ruby"
80+ . execute (conn )
81+ . await ? ;
82+
83+ let all_names = users :: table . select (users :: name ). load :: <String >(conn ). await ? ;
84+ Ok (())
85+ }. scope_boxed ()
86+ ). await ? ;
87+ ```
88+
89+ ### Streaming Query Support
90+
91+ Beside loading data directly into a vector, diesel-async also supports returning a
92+ value stream for each query. This allows to process data from the database while they
93+ are still received.
94+
95+ ``` rust
96+ // use ordinary diesel query dsl to construct your query
97+ let data : impl Stream <Item = QueryResult <User >> = users :: table
98+ . filter (users :: id . gt (0 ))
99+ . or_filter (users :: name . like (" %Luke"
100+ . select (User :: as_select ())
101+ // execute the query via the provided
102+ // async `diesel_async::RunQueryDsl`
103+ . load_stream (& mut connection )
104+ . await ? ;
105+
106+ ```
107+
108+ ### Built-in Connection Pooling Support
109+
110+ Diesel-async provides built-in support for several connection pooling crates. This includes support
111+ for:
112+
113+ * [ deadpool] ( https://crates.io/crates/deadpool )
114+ * [ bb8] ( https://crates.io/crates/bb8 )
115+ * [ mobc] ( https://crates.io/crates/mobc )
116+
117+ #### Deadpool
118+
119+ ``` rust
120+ use diesel_async :: pooled_connection :: AsyncDieselConnectionManager ;
121+ use diesel_async :: pooled_connection :: deadpool :: Pool ;
122+ use diesel_async :: RunQueryDsl ;
123+
124+ // create a new connection pool with the default config
125+ let config = AsyncDieselConnectionManager :: <diesel_async :: AsyncPgConnection >:: new (std :: env :: var (" DATABASE_URL" ? );
126+ let pool = Pool :: builder (). build (config )? ;
127+
128+ // checkout a connection from the pool
129+ let mut conn = pool . get (). await ? ;
130+
131+ // use the connection as ordinary diesel-async connection
132+ let res = users :: table . select (User :: as_select ()). load :: (& mut conn ). await ? ;
133+ ```
134+
135+ #### BB8
136+
137+ ``` rust
138+ use diesel_async :: pooled_connection :: AsyncDieselConnectionManager ;
139+ use diesel_async :: pooled_connection :: bb8 :: Pool ;
140+ use diesel_async :: RunQueryDsl ;
141+
142+ // create a new connection pool with the default config
143+ let config = AsyncDieselConnectionManager :: <diesel_async :: AsyncPgConnection >:: new (std :: env :: var (" DATABASE_URL" ? );
144+ let pool = Pool :: builder (). build (config ). await ? ;
145+
146+ // checkout a connection from the pool
147+ let mut conn = pool . get (). await ? ;
148+
149+ // use the connection as ordinary diesel-async connection
150+ let res = users :: table . select (User :: as_select ()). load :: (& mut conn ). await ? ;
151+ ```
152+
153+ #### Mobc
154+
155+ ``` rust
156+ use diesel_async :: pooled_connection :: AsyncDieselConnectionManager ;
157+ use diesel_async :: pooled_connection :: mobc :: Pool ;
158+ use diesel_async :: RunQueryDsl ;
159+
160+ // create a new connection pool with the default config
161+ let config = AsyncDieselConnectionManager :: <diesel_async :: AsyncPgConnection >:: new (std :: env :: var (" DATABASE_URL" ? );
162+ let pool = Pool :: new (config );
163+
164+ // checkout a connection from the pool
165+ let mut conn = pool . get (). await ? ;
166+
167+ // use the connection as ordinary diesel-async connection
168+ let res = users :: table . select (User :: as_select ()). load :: (& mut conn ). await ? ;
169+ ```
170+
171+ ## Crate Feature Flags
172+
173+ Diesel-async offers several configurable features:
174+
175+ * ` postgres ` : Enables the implementation of ` AsyncPgConnection `
176+ * ` mysql ` : Enables the implementation of ` AsyncMysqlConnection `
177+ * ` deadpool ` : Enables support for the ` deadpool ` connection pool implementation
178+ * ` bb8 ` : Enables support for the ` bb8 ` connection pool implementation
179+ * ` mobc ` : Enables support for the ` mobc ` connection pool implementation
180+
181+ By default no features are enabled.
182+
16183## Code of conduct
17184
18185Anyone who interacts with Diesel in any space, including but not limited to
@@ -28,6 +195,10 @@ Licensed under either of these:
28195 https://opensource.org/licenses/MIT )
29196
30197### Contributing
198+
199+ Contributions are explicitly welcome. Please consider opening a [ discussion] ( https://github.com/weiznich/diesel_async/discussions/categories/ideas )
200+ with your idea first, to discuss possible designs.
201+
31202Unless you explicitly state otherwise, any contribution you intentionally submit
32203for inclusion in the work, as defined in the Apache-2.0 license, shall be
33204dual-licensed as above, without any additional terms or conditions.
0 commit comments