Skip to main content

oxtel_sql/sqlx/
mod.rs

1//! sqlx 0.8 and 0.9, by wrapping the pool: [`v0_8`] with the `sqlx-0.8`
2//! feature, [`v0_9`] with `sqlx-0.9`.
3//!
4//! ```no_run
5//! # #[cfg(feature = "sqlx-0.9")]
6//! # async fn run(pool: sqlx_0_9::PgPool) -> Result<(), sqlx_0_9::Error> {
7//! # use sqlx_0_9 as sqlx;
8//! let pool = oxtel_sql::sqlx::v0_9::Pool::new(pool);
9//!
10//! let users = sqlx::query("SELECT name FROM users").fetch_all(&pool).await?;
11//! let mut tx = pool.begin().await?;
12//! sqlx::query("UPDATE users SET seen = now()").execute(&mut tx).await?;
13//! tx.commit().await?;
14//! # Ok(()) }
15//! ```
16//!
17//! Queries run on the wrapped [`Pool`](v0_9::Pool), on a
18//! [`Transaction`](v0_9::Transaction) from its `begin`, or on a
19//! [`Connection`](v0_9::Connection) from its `acquire` are each recorded as
20//! a database call:
21//!
22//! - **a client span**, named by the query summary, with `db.system.name`
23//!   (`postgresql`, `mysql` or `sqlite`), `db.namespace` and the server from
24//!   the pool's connection options, `db.query.text` (literals replaced by
25//!   `?`) and `db.response.returned_rows`;
26//! - **`db.client.operation.duration`**, from when the query starts on its
27//!   connection;
28//! - for a failed query, the database's error code (a SQLSTATE for
29//!   PostgreSQL and MySQL) as `db.response.status_code` and `error.type`, or
30//!   sqlx's error kind, such as `sqlx::Error::PoolTimedOut`.
31//!
32//! `BEGIN`, `COMMIT` and `ROLLBACK` are calls too. Preparing a statement
33//! isn't. The pool also records the conventions' connection pool metrics
34//! (`db.client.connection.*`): connections in use and idle, callers
35//! waiting, wait and use times, and timeouts. They're still in development
36//! in the conventions.
37//!
38//! The wrappers dereference to sqlx's types, so the rest of their methods
39//! still work. A query run through sqlx's own types, such as `&*pool` or
40//! `&mut **tx`, isn't recorded by the wrapper.
41//!
42//! # This, or oxtel's sqlx mapping
43//!
44//! `oxtel::init()` also records sqlx's queries with no code change, from
45//! the event sqlx writes as each finishes. That event carries no error and
46//! doesn't say which database it's about, so its spans can't be marked as
47//! failed and their `db.system.name` is `other_sql` unless configured. It
48//! needs sqlx's statement logging, which is on by default. The wrapper
49//! records all of it, but only for queries run through it. The two never
50//! count a query twice: the mapping leaves alone the queries the wrapper
51//! records. See `oxtel::mappings` and the
52//! [databases guide](https://agentstatelabs.github.io/oxtel/guide/databases/).
53
54use std::sync::{Arc, Mutex};
55use std::task::{Context, Poll};
56use std::time::Instant;
57
58use futures_core::Stream;
59use futures_core::stream::BoxStream;
60
61use crate::record::{self, Analysis, Call, Failure, UNKNOWN};
62
63#[cfg(feature = "sqlx-0.8")]
64pub mod v0_8;
65#[cfg(feature = "sqlx-0.9")]
66pub mod v0_9;
67
68/// `db.system.name` for a sqlx database, from its `Database::NAME`.
69fn system_of(name: &str) -> &'static str {
70    match name {
71        "PostgreSQL" => "postgresql",
72        "MySQL" => "mysql",
73        "SQLite" => "sqlite",
74        _ => "other_sql",
75    }
76}
77
78/// Whether a database's connection options can be read as a URL: the
79/// drivers that override `ConnectOptions::to_url_lossy`, which panics
80/// otherwise.
81fn has_url(name: &str) -> bool {
82    matches!(name, "PostgreSQL" | "MySQL" | "SQLite")
83}
84
85/// What's known about a pool's database, and the pool's name in its
86/// metrics.
87#[derive(Debug)]
88pub(crate) struct Target {
89    system: &'static str,
90    namespace: Option<String>,
91    server: Option<(String, u16)>,
92    pub(crate) pool_name: Arc<str>,
93}
94
95impl Target {
96    /// For a database named `name` (its `Database::NAME`) at `url`'s host,
97    /// port and path. A file database's path isn't a namespace or a
98    /// server.
99    fn new(name: &str, url: Option<(Option<&str>, Option<u16>, &str)>) -> Self {
100        let system = system_of(name);
101        let (namespace, server) = match url {
102            Some((host, port, path)) if system != "sqlite" => {
103                let namespace = path.trim_start_matches('/');
104                let namespace = (!namespace.is_empty()).then(|| namespace.to_string());
105                let default_port = if system == "mysql" { 3306 } else { 5432 };
106                let server = host
107                    .filter(|h| !h.is_empty())
108                    .map(|h| (h.to_string(), port.unwrap_or(default_port)));
109                (namespace, server)
110            }
111            _ => (None, None),
112        };
113        let pool_name = crate::pool::default_name(
114            system,
115            namespace.as_deref(),
116            server.as_ref().map(|(a, p)| (a.as_str(), *p)),
117        );
118        Target {
119            system,
120            namespace,
121            server,
122            pool_name: pool_name.into(),
123        }
124    }
125
126    fn call<'a>(&'a self, analysis: &'a Analysis) -> Call<'a> {
127        Call {
128            system: self.system,
129            namespace: self.namespace.as_deref(),
130            server: self.server.as_ref().map(|(a, p)| (a.as_str(), *p)),
131            analysis,
132        }
133    }
134
135    fn with_pool_name(&self, name: &str) -> Self {
136        Target {
137            system: self.system,
138            namespace: self.namespace.clone(),
139            server: self.server.clone(),
140            pool_name: name.into(),
141        }
142    }
143}
144
145/// Where a query's text is put once it's known: before the call, for sqlx
146/// 0.8, or as sqlx reads it, for 0.9.
147pub(crate) type Statement = Arc<Mutex<Option<Arc<Analysis>>>>;
148
149fn statement(analysis: Option<Arc<Analysis>>) -> Statement {
150    Arc::new(Mutex::new(analysis))
151}
152
153/// Why a query failed: `error.type`, and the database's code.
154pub(crate) struct Fail {
155    error_type: String,
156    code: Option<String>,
157}
158
159impl Fail {
160    /// A failure the database reported with `code`, or sqlx reported as
161    /// `kind` (such as `PoolTimedOut`), or as a kind this crate doesn't know.
162    fn new(code: Option<String>, kind: Option<&str>) -> Self {
163        let error_type = match (&code, kind) {
164            (Some(code), _) => code.clone(),
165            (None, Some(kind)) => format!("sqlx::Error::{kind}"),
166            (None, None) => "sqlx::Error".to_string(),
167        };
168        Fail { error_type, code }
169    }
170}
171
172/// One query: its span, opened when the call is made, and what's recorded
173/// when it finishes, fails or is dropped.
174pub(crate) struct QueryCall {
175    target: Arc<Target>,
176    span: tracing::Span,
177    started: Instant,
178    rows: u64,
179    statement: Statement,
180    done: bool,
181}
182
183impl QueryCall {
184    fn start(target: &Arc<Target>, statement: Statement) -> Self {
185        let span = record::open_span(
186            target.system,
187            target.namespace.as_deref(),
188            target.server.as_ref().map(|(a, p)| (a.as_str(), *p)),
189        );
190        QueryCall {
191            target: Arc::clone(target),
192            span,
193            started: Instant::now(),
194            rows: 0,
195            statement,
196            done: false,
197        }
198    }
199
200    fn finish(&mut self, failure: Option<Fail>) {
201        if std::mem::replace(&mut self.done, true) {
202            return;
203        }
204        let seconds = self.started.elapsed().as_secs_f64();
205        let analysis = self
206            .statement
207            .lock()
208            .unwrap_or_else(|e| e.into_inner())
209            .take();
210        let analysis = analysis.as_deref().unwrap_or(&UNKNOWN);
211        record::describe(&self.span, analysis);
212        let failure = failure.as_ref().map(|f| Failure {
213            error_type: &f.error_type,
214            status_code: f.code.as_deref(),
215        });
216        match &failure {
217            Some(failure) => failure.record(&self.span),
218            None => {
219                self.span.record("db.response.returned_rows", self.rows);
220            }
221        }
222        // Inside the span, so the measurement's exemplar points at it.
223        let _entered = self.span.enter();
224        self.target
225            .call(analysis)
226            .record_duration(seconds, failure.as_ref());
227    }
228}
229
230impl Drop for QueryCall {
231    fn drop(&mut self) {
232        // Dropped before the end, such as after the first row of a stream.
233        self.finish(None);
234    }
235}
236
237/// A query's results, recorded as they're read.
238pub(crate) struct Recorded<'e, T, E> {
239    inner: BoxStream<'e, Result<T, E>>,
240    call: QueryCall,
241    is_row: fn(&T) -> bool,
242    fail: fn(&E) -> Fail,
243}
244
245impl<'e, T, E> Recorded<'e, T, E> {
246    fn new(
247        inner: BoxStream<'e, Result<T, E>>,
248        call: QueryCall,
249        is_row: fn(&T) -> bool,
250        fail: fn(&E) -> Fail,
251    ) -> Self {
252        Recorded {
253            inner,
254            call,
255            is_row,
256            fail,
257        }
258    }
259}
260
261impl<T, E> Stream for Recorded<'_, T, E> {
262    type Item = Result<T, E>;
263
264    fn poll_next(self: std::pin::Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
265        let this = self.get_mut();
266        let span = this.call.span.clone();
267        let _entered = span.enter();
268        let poll = this.inner.as_mut().poll_next(cx);
269        match &poll {
270            Poll::Ready(Some(Ok(item))) if (this.is_row)(item) => this.call.rows += 1,
271            Poll::Ready(Some(Ok(_))) | Poll::Pending => {}
272            Poll::Ready(Some(Err(error))) => this.call.finish(Some((this.fail)(error))),
273            Poll::Ready(None) => this.call.finish(None),
274        }
275        poll
276    }
277}
278
279/// Run one query future inside its call, recording rows and the outcome.
280async fn record_one<R, E>(
281    mut call: QueryCall,
282    operation: impl std::future::Future<Output = Result<R, E>>,
283    rows: fn(&R) -> u64,
284    fail: fn(&E) -> Fail,
285) -> Result<R, E> {
286    use tracing::Instrument;
287    let result = operation.instrument(call.span.clone()).await;
288    match &result {
289        Ok(value) => {
290            call.rows = rows(value);
291            call.finish(None);
292        }
293        Err(error) => call.finish(Some(fail(error))),
294    }
295    result
296}