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
//! Request-bound [SQLx] transactions for [axum].
//!
//! [SQLx]: https://github.com/launchbadge/sqlx#readme
//! [axum]: https://github.com/tokio-rs/axum#readme
//!
//! [`Tx`] is an `axum` [extractor][axum extractors] for obtaining a transaction that's bound to the
//! HTTP request. A transaction begins the first time the extractor is used for a request, and is
//! then stored in [request extensions] for use by other middleware/handlers. The transaction is
//! resolved depending on the status code of the eventual response – successful (HTTP `2XX` or
//! `3XX`) responses will cause the transaction to be committed, otherwise it will be rolled back.
//!
//! This behaviour is often a sensible default, and using the extractor (e.g. rather than directly
//! using [`sqlx::Transaction`]s) means you can't forget to commit the transactions!
//!
//! [axum extractors]: https://docs.rs/axum/latest/axum/#extractors
//! [request extensions]: https://docs.rs/http/latest/http/struct.Extensions.html
//!
//! # Usage
//!
//! To use the [`Tx`] extractor, you must first add [`State`] and [`Layer`] to your app. [`State`]
//! holds the configuration for the extractor, and the [`Layer`] middleware manages the
//! request-bound transaction.
//!
//! ```
//! # async fn foo() {
//! // It's recommended to create aliases specialised for your extractor(s)
//! type Tx = axum_sqlx_tx::Tx<sqlx::Sqlite>;
//!
//! let pool = sqlx::SqlitePool::connect("...").await.unwrap();
//!
//! let (state, layer) = Tx::setup(pool);
//!
//! let app = axum::Router::new()
//! // .route(...)s
//! # .route("/", axum::routing::get(|tx: Tx| async move {}))
//! .layer(layer)
//! .with_state(state);
//! # let listener: tokio::net::TcpListener = todo!();
//! # axum::serve(listener, app);
//! # }
//! ```
//!
//! You can then simply add [`Tx`] as an argument to your handlers:
//!
//! ```
//! type Tx = axum_sqlx_tx::Tx<sqlx::Sqlite>;
//!
//! async fn create_user(mut tx: Tx, /* ... */) {
//! // `&mut Tx` implements `sqlx::Executor`
//! let user = sqlx::query("INSERT INTO users (...) VALUES (...)")
//! .fetch_one(&mut tx)
//! .await
//! .unwrap();
//!
//! // `Tx` also implements `Deref<Target = sqlx::Transaction>` and `DerefMut`
//! use sqlx::Acquire;
//! let inner = tx.begin().await.unwrap();
//! /* ... */
//! }
//! ```
//!
//! ## Error handling
//!
//! `axum` requires that errors can be turned into responses. The [`Error`] type converts into a
//! HTTP 500 response with the error message as the response body. This may be suitable for
//! development or internal services but it's generally not advisable to return internal error
//! details to clients.
//!
//! See [`Error`] for how to customise error handling.
//!
//! ## Multiple databases
//!
//! If you need to work with multiple databases, you can define marker structs for each. See
//! [`Marker`] for an example.
//!
//! It's not currently possible to use `Tx` for a dynamic number of databases. Feel free to open an
//! issue if you have a requirement for this.
//!
//! ## Accessing the pool
//!
//! Note that [`State`] implements [`FromRef`](axum_core::extract::FromRef) into the inner SQLx pool. Therefore,
//! if you still need to access the database pool at some handler, you can use axum's `State`
//! extractor normally.
//!
//! ```
//! use axum::extract::State;
//!
//! async fn this_still_works(State(pool): State<sqlx::SqlitePool>) {
//! /* ... */
//! }
//! ```
//!
//! # Examples
//!
//! See [`examples/`][examples] in the repo for more examples.
//!
//! [examples]: https://github.com/digital-society-coop/axum-sqlx-tx/tree/master/examples
pub use crate::;