Skip to main content

oxtel_sql/
postgres.rs

1//! PostgreSQL through tokio-postgres, and deadpool-postgres pools.
2//!
3//! tokio-postgres doesn't say what SQL a prepared statement holds, and its
4//! traits are sealed, so instrumenting it means wrapping the client. Wrap it
5//! where the connection is made:
6//!
7//! ```no_run
8//! # async fn run() -> Result<(), tokio_postgres::Error> {
9//! let config: tokio_postgres::Config = "host=localhost user=app dbname=shop".parse()?;
10//! let (client, connection) = config.connect(tokio_postgres::NoTls).await?;
11//! tokio::spawn(connection);
12//! let client = oxtel_sql::postgres::Client::new(client, &config);
13//!
14//! let rows = client.query("SELECT name FROM users WHERE id = $1", &[&7i32]).await?;
15//! # Ok(()) }
16//! ```
17//!
18//! [`Client`] and [`Transaction`] have tokio-postgres's `query`,
19//! `query_one`, `query_opt`, `execute`, `batch_execute` and `simple_query`,
20//! each recorded as one database call: a client span named by the query
21//! summary, with `db.namespace`, `server.address` and `server.port` from the
22//! connection's configuration, and `db.client.operation.duration`. A call
23//! that fails records the error's SQLSTATE as `db.response.status_code` and
24//! `error.type`. Starting, committing and rolling back a transaction are
25//! calls too.
26//!
27//! [`prepare`](Client::prepare) returns a [`Statement`] that keeps its text,
28//! so calls running it are named like any other. Preparing isn't recorded
29//! as a call of its own. Both types dereference to tokio-postgres's, so
30//! anything else, such as `copy_in` or `query_raw`, still works, without
31//! telemetry.
32//!
33//! Helpers that should take either a client or a transaction can be generic
34//! over [`GenericClient`]. With the `deadpool-postgres` feature, [`Pool`]
35//! wraps a pool so that every client taken from it is instrumented, and
36//! records the conventions' connection pool metrics.
37
38use std::future::Future;
39use std::ops::{Deref, DerefMut};
40use std::sync::Arc;
41use std::time::Instant;
42
43use tokio_postgres::error::SqlState;
44use tokio_postgres::types::ToSql;
45use tokio_postgres::{Error, Row, SimpleQueryMessage};
46use tracing::Instrument;
47
48use crate::record::{Analysis, Call, Failure, analyze};
49
50const POSTGRESQL: &str = "postgresql";
51
52/// `error.type` for a failure that has no SQLSTATE, such as a lost
53/// connection.
54const CLIENT_ERROR: &str = "tokio_postgres::Error";
55
56/// Where a client's connections go, for `db.namespace`, `server.address`
57/// and `server.port`. Cheap to clone.
58#[derive(Clone, Debug, Default)]
59pub struct Database(Arc<Target>);
60
61#[derive(Debug, Default)]
62struct Target {
63    namespace: Option<String>,
64    server: Option<(String, u16)>,
65}
66
67impl Database {
68    /// The database a configuration connects to. The server is recorded
69    /// only when the configuration names exactly one host, since with
70    /// several there's no telling which one answered.
71    pub fn new(config: &tokio_postgres::Config) -> Self {
72        crate::record::describe_metrics();
73        let server = match config.get_hosts() {
74            [host] => {
75                let address = match host {
76                    tokio_postgres::config::Host::Tcp(name) => name.clone(),
77                    #[cfg(unix)]
78                    tokio_postgres::config::Host::Unix(path) => path.display().to_string(),
79                };
80                let port = config.get_ports().first().copied().unwrap_or(5432);
81                Some((address, port))
82            }
83            _ => None,
84        };
85        Database(Arc::new(Target {
86            namespace: config.get_dbname().map(str::to_owned),
87            server,
88        }))
89    }
90
91    fn call<'a>(&'a self, analysis: &'a Analysis) -> Call<'a> {
92        Call {
93            system: POSTGRESQL,
94            namespace: self.0.namespace.as_deref(),
95            server: self.0.server.as_ref().map(|(a, p)| (a.as_str(), *p)),
96            analysis,
97        }
98    }
99}
100
101/// Run one database call inside its span, then record its duration and,
102/// if it failed, why.
103async fn record<R>(
104    database: &Database,
105    analysis: &Analysis,
106    operation: impl Future<Output = Result<R, Error>>,
107) -> Result<R, Error> {
108    let call = database.call(analysis);
109    let span = call.span();
110    let started = Instant::now();
111    let result = operation.instrument(span.clone()).await;
112    let seconds = started.elapsed().as_secs_f64();
113    // Inside the span, so the measurement's exemplar points at it.
114    let _entered = span.enter();
115    match &result {
116        Ok(_) => call.record_duration(seconds, None),
117        Err(error) => {
118            let code = error.code().map(SqlState::code);
119            let failure = Failure {
120                error_type: code.unwrap_or(CLIENT_ERROR),
121                status_code: code,
122            };
123            failure.record(&span);
124            call.record_duration(seconds, Some(&failure));
125        }
126    }
127    result
128}
129
130/// A statement prepared through an instrumented client: tokio-postgres's
131/// [`Statement`](tokio_postgres::Statement), keeping its text so the calls
132/// that run it are named. It dereferences to tokio-postgres's.
133#[derive(Clone)]
134pub struct Statement {
135    inner: tokio_postgres::Statement,
136    analysis: Arc<Analysis>,
137}
138
139impl Statement {
140    /// tokio-postgres's statement.
141    pub fn into_inner(self) -> tokio_postgres::Statement {
142        self.inner
143    }
144}
145
146impl Deref for Statement {
147    type Target = tokio_postgres::Statement;
148
149    fn deref(&self) -> &tokio_postgres::Statement {
150        &self.inner
151    }
152}
153
154impl std::fmt::Debug for Statement {
155    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
156        f.debug_struct("Statement")
157            .field("summary", &self.analysis.summary)
158            .finish_non_exhaustive()
159    }
160}
161
162/// A statement the instrumented clients run: SQL text, a [`Statement`]
163/// prepared through them, or one of tokio-postgres's own, which is recorded
164/// without a name or text.
165pub trait Query: sealed::Query + Sync {}
166
167impl Query for str {}
168impl Query for String {}
169impl Query for Statement {}
170impl Query for tokio_postgres::Statement {}
171
172mod sealed {
173    use crate::record::Analysis;
174
175    pub enum Target<'a> {
176        Text(&'a str),
177        Prepared(Prepared<'a>),
178    }
179
180    /// A prepared statement and what's known about its text.
181    pub struct Prepared<'a> {
182        pub(crate) statement: &'a tokio_postgres::Statement,
183        pub(crate) analysis: &'a Analysis,
184    }
185
186    pub trait Query {
187        fn target(&self) -> Target<'_>;
188    }
189
190    impl Query for str {
191        fn target(&self) -> Target<'_> {
192            Target::Text(self)
193        }
194    }
195
196    impl Query for String {
197        fn target(&self) -> Target<'_> {
198            Target::Text(self)
199        }
200    }
201
202    impl Query for super::Statement {
203        fn target(&self) -> Target<'_> {
204            Target::Prepared(Prepared {
205                statement: &self.inner,
206                analysis: &self.analysis,
207            })
208        }
209    }
210
211    impl Query for tokio_postgres::Statement {
212        fn target(&self) -> Target<'_> {
213            Target::Prepared(Prepared {
214                statement: self,
215                analysis: &crate::record::UNKNOWN,
216            })
217        }
218    }
219}
220
221use sealed::Target as Run;
222
223/// The instrumented calls, on [`Client`] and [`Transaction`] alike. Each
224/// type has `fn pg(&self)`, returning tokio-postgres's client or
225/// transaction, and a `database` field.
226macro_rules! calls {
227    () => {
228        /// Prepare a statement, keeping its text so that calls running it
229        /// are named. Preparing isn't recorded as a call.
230        pub async fn prepare(&self, query: &str) -> Result<Statement, Error> {
231            let inner = self.pg().prepare(query).await?;
232            Ok(Statement {
233                inner,
234                analysis: analyze(query),
235            })
236        }
237
238        /// Run a statement and return the rows it produced.
239        pub async fn query<T>(
240            &self,
241            statement: &T,
242            params: &[&(dyn ToSql + Sync)],
243        ) -> Result<Vec<Row>, Error>
244        where
245            T: ?Sized + Query,
246        {
247            match statement.target() {
248                Run::Text(sql) => {
249                    record(&self.database, &analyze(sql), self.pg().query(sql, params)).await
250                }
251                Run::Prepared(p) => {
252                    record(
253                        &self.database,
254                        p.analysis,
255                        self.pg().query(p.statement, params),
256                    )
257                    .await
258                }
259            }
260        }
261
262        /// Run a statement that returns exactly one row.
263        pub async fn query_one<T>(
264            &self,
265            statement: &T,
266            params: &[&(dyn ToSql + Sync)],
267        ) -> Result<Row, Error>
268        where
269            T: ?Sized + Query,
270        {
271            match statement.target() {
272                Run::Text(sql) => {
273                    record(
274                        &self.database,
275                        &analyze(sql),
276                        self.pg().query_one(sql, params),
277                    )
278                    .await
279                }
280                Run::Prepared(p) => {
281                    record(
282                        &self.database,
283                        p.analysis,
284                        self.pg().query_one(p.statement, params),
285                    )
286                    .await
287                }
288            }
289        }
290
291        /// Run a statement that returns at most one row.
292        pub async fn query_opt<T>(
293            &self,
294            statement: &T,
295            params: &[&(dyn ToSql + Sync)],
296        ) -> Result<Option<Row>, Error>
297        where
298            T: ?Sized + Query,
299        {
300            match statement.target() {
301                Run::Text(sql) => {
302                    record(
303                        &self.database,
304                        &analyze(sql),
305                        self.pg().query_opt(sql, params),
306                    )
307                    .await
308                }
309                Run::Prepared(p) => {
310                    record(
311                        &self.database,
312                        p.analysis,
313                        self.pg().query_opt(p.statement, params),
314                    )
315                    .await
316                }
317            }
318        }
319
320        /// Run a statement and return how many rows it changed.
321        pub async fn execute<T>(
322            &self,
323            statement: &T,
324            params: &[&(dyn ToSql + Sync)],
325        ) -> Result<u64, Error>
326        where
327            T: ?Sized + Query,
328        {
329            match statement.target() {
330                Run::Text(sql) => {
331                    record(
332                        &self.database,
333                        &analyze(sql),
334                        self.pg().execute(sql, params),
335                    )
336                    .await
337                }
338                Run::Prepared(p) => {
339                    record(
340                        &self.database,
341                        p.analysis,
342                        self.pg().execute(p.statement, params),
343                    )
344                    .await
345                }
346            }
347        }
348
349        /// Run statements separated by semicolons, without parameters, as
350        /// one call.
351        pub async fn batch_execute(&self, query: &str) -> Result<(), Error> {
352            record(
353                &self.database,
354                &analyze(query),
355                self.pg().batch_execute(query),
356            )
357            .await
358        }
359
360        /// Run statements through the simple query protocol, as one call.
361        pub async fn simple_query(&self, query: &str) -> Result<Vec<SimpleQueryMessage>, Error> {
362            record(
363                &self.database,
364                &analyze(query),
365                self.pg().simple_query(query),
366            )
367            .await
368        }
369    };
370}
371
372/// An instrumented tokio-postgres client, or a pooled one (see [`AsClient`]).
373/// It dereferences to tokio-postgres's [`Client`](tokio_postgres::Client),
374/// so methods it doesn't wrap still work, without telemetry.
375pub struct Client<C = tokio_postgres::Client> {
376    inner: C,
377    database: Database,
378    // Declared after `inner`, so a pooled connection is back in its pool
379    // when the lease ends.
380    _lease: Option<Lease>,
381}
382
383// A pooled client's time out of its pool.
384#[cfg(feature = "deadpool-postgres")]
385use crate::pool::Lease;
386#[cfg(not(feature = "deadpool-postgres"))]
387type Lease = std::convert::Infallible;
388
389/// The clients a [`Client`] can wrap: tokio-postgres's own, and with the
390/// `deadpool-postgres` feature, a client taken from a deadpool pool.
391pub trait AsClient {
392    /// tokio-postgres's client.
393    fn as_client(&self) -> &tokio_postgres::Client;
394    /// tokio-postgres's client, mutably, for starting transactions.
395    fn as_client_mut(&mut self) -> &mut tokio_postgres::Client;
396}
397
398impl AsClient for tokio_postgres::Client {
399    fn as_client(&self) -> &tokio_postgres::Client {
400        self
401    }
402
403    fn as_client_mut(&mut self) -> &mut tokio_postgres::Client {
404        self
405    }
406}
407
408impl<C: AsClient> Client<C> {
409    /// Instrument a client connected with `config`.
410    pub fn new(client: C, config: &tokio_postgres::Config) -> Self {
411        Self::with_database(client, &Database::new(config))
412    }
413
414    /// Instrument a client, with what's known about where it's connected.
415    /// For many clients to one database, work that out once with
416    /// [`Database::new`].
417    pub fn with_database(client: C, database: &Database) -> Self {
418        Client {
419            inner: client,
420            database: database.clone(),
421            _lease: None,
422        }
423    }
424
425    /// The wrapped client.
426    pub fn get_ref(&self) -> &C {
427        &self.inner
428    }
429
430    /// The wrapped client, without the instrumentation. For a client from
431    /// a [`Pool`], its use ends here as far as the pool's metrics go.
432    pub fn into_inner(self) -> C {
433        self.inner
434    }
435
436    fn pg(&self) -> &tokio_postgres::Client {
437        self.inner.as_client()
438    }
439
440    calls!();
441
442    /// Start a transaction. Its `BEGIN` is recorded as a call.
443    pub async fn transaction(&mut self) -> Result<Transaction<'_>, Error> {
444        let database = self.database.clone();
445        let inner = record(
446            &database,
447            &analyze("BEGIN"),
448            self.inner.as_client_mut().transaction(),
449        )
450        .await?;
451        Ok(Transaction { inner, database })
452    }
453}
454
455impl<C: AsClient> Deref for Client<C> {
456    type Target = tokio_postgres::Client;
457
458    fn deref(&self) -> &tokio_postgres::Client {
459        self.inner.as_client()
460    }
461}
462
463impl<C: AsClient> DerefMut for Client<C> {
464    fn deref_mut(&mut self) -> &mut tokio_postgres::Client {
465        self.inner.as_client_mut()
466    }
467}
468
469impl<C> std::fmt::Debug for Client<C> {
470    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
471        f.debug_struct("Client")
472            .field("database", &self.database)
473            .finish_non_exhaustive()
474    }
475}
476
477/// An instrumented transaction, from [`Client::transaction`]. Like
478/// tokio-postgres's, dropping it without committing rolls it back, but that
479/// rollback isn't recorded. It dereferences to tokio-postgres's
480/// [`Transaction`](tokio_postgres::Transaction).
481pub struct Transaction<'a> {
482    inner: tokio_postgres::Transaction<'a>,
483    database: Database,
484}
485
486impl<'a> Transaction<'a> {
487    fn pg(&self) -> &tokio_postgres::Transaction<'a> {
488        &self.inner
489    }
490
491    calls!();
492
493    /// Commit, recorded as a call.
494    pub async fn commit(self) -> Result<(), Error> {
495        record(&self.database, &analyze("COMMIT"), self.inner.commit()).await
496    }
497
498    /// Roll back, recorded as a call.
499    pub async fn rollback(self) -> Result<(), Error> {
500        record(&self.database, &analyze("ROLLBACK"), self.inner.rollback()).await
501    }
502
503    /// Start a nested transaction, which is a savepoint, recorded as a call.
504    pub async fn transaction(&mut self) -> Result<Transaction<'_>, Error> {
505        let database = self.database.clone();
506        let inner = record(&database, &analyze("SAVEPOINT"), self.inner.transaction()).await?;
507        Ok(Transaction { inner, database })
508    }
509}
510
511impl<'a> Deref for Transaction<'a> {
512    type Target = tokio_postgres::Transaction<'a>;
513
514    fn deref(&self) -> &tokio_postgres::Transaction<'a> {
515        &self.inner
516    }
517}
518
519impl std::fmt::Debug for Transaction<'_> {
520    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
521        f.debug_struct("Transaction")
522            .field("database", &self.database)
523            .finish_non_exhaustive()
524    }
525}
526
527/// The instrumented calls of a [`Client`] or a [`Transaction`], for helpers
528/// that take either. tokio-postgres's own `GenericClient` is sealed.
529pub trait GenericClient: Sync {
530    /// See [`Client::prepare`].
531    fn prepare(&self, query: &str) -> impl Future<Output = Result<Statement, Error>> + Send;
532
533    /// See [`Client::query`].
534    fn query<T>(
535        &self,
536        statement: &T,
537        params: &[&(dyn ToSql + Sync)],
538    ) -> impl Future<Output = Result<Vec<Row>, Error>> + Send
539    where
540        T: ?Sized + Query;
541
542    /// See [`Client::query_one`].
543    fn query_one<T>(
544        &self,
545        statement: &T,
546        params: &[&(dyn ToSql + Sync)],
547    ) -> impl Future<Output = Result<Row, Error>> + Send
548    where
549        T: ?Sized + Query;
550
551    /// See [`Client::query_opt`].
552    fn query_opt<T>(
553        &self,
554        statement: &T,
555        params: &[&(dyn ToSql + Sync)],
556    ) -> impl Future<Output = Result<Option<Row>, Error>> + Send
557    where
558        T: ?Sized + Query;
559
560    /// See [`Client::execute`].
561    fn execute<T>(
562        &self,
563        statement: &T,
564        params: &[&(dyn ToSql + Sync)],
565    ) -> impl Future<Output = Result<u64, Error>> + Send
566    where
567        T: ?Sized + Query;
568
569    /// See [`Client::batch_execute`].
570    fn batch_execute(&self, query: &str) -> impl Future<Output = Result<(), Error>> + Send;
571}
572
573/// Implements [`GenericClient`] by calling the type's own methods.
574macro_rules! generic_client {
575    () => {
576        fn prepare(&self, query: &str) -> impl Future<Output = Result<Statement, Error>> + Send {
577            Self::prepare(self, query)
578        }
579
580        fn query<T>(
581            &self,
582            statement: &T,
583            params: &[&(dyn ToSql + Sync)],
584        ) -> impl Future<Output = Result<Vec<Row>, Error>> + Send
585        where
586            T: ?Sized + Query,
587        {
588            Self::query(self, statement, params)
589        }
590
591        fn query_one<T>(
592            &self,
593            statement: &T,
594            params: &[&(dyn ToSql + Sync)],
595        ) -> impl Future<Output = Result<Row, Error>> + Send
596        where
597            T: ?Sized + Query,
598        {
599            Self::query_one(self, statement, params)
600        }
601
602        fn query_opt<T>(
603            &self,
604            statement: &T,
605            params: &[&(dyn ToSql + Sync)],
606        ) -> impl Future<Output = Result<Option<Row>, Error>> + Send
607        where
608            T: ?Sized + Query,
609        {
610            Self::query_opt(self, statement, params)
611        }
612
613        fn execute<T>(
614            &self,
615            statement: &T,
616            params: &[&(dyn ToSql + Sync)],
617        ) -> impl Future<Output = Result<u64, Error>> + Send
618        where
619            T: ?Sized + Query,
620        {
621            Self::execute(self, statement, params)
622        }
623
624        fn batch_execute(&self, query: &str) -> impl Future<Output = Result<(), Error>> + Send {
625            Self::batch_execute(self, query)
626        }
627    };
628}
629
630impl<C: AsClient + Sync> GenericClient for Client<C> {
631    generic_client!();
632}
633
634impl GenericClient for Transaction<'_> {
635    generic_client!();
636}
637
638#[cfg(feature = "deadpool-postgres")]
639mod pool {
640    use super::*;
641
642    impl AsClient for deadpool_postgres::Object {
643        fn as_client(&self) -> &tokio_postgres::Client {
644            self
645        }
646
647        fn as_client_mut(&mut self) -> &mut tokio_postgres::Client {
648            self
649        }
650    }
651
652    impl Client<deadpool_postgres::Object> {
653        /// Prepare a statement through the pooled connection's statement
654        /// cache, keeping its text so that calls running it are named.
655        pub async fn prepare_cached(&self, query: &str) -> Result<Statement, Error> {
656            let inner = self.inner.prepare_cached(query).await?;
657            Ok(Statement {
658                inner,
659                analysis: analyze(query),
660            })
661        }
662    }
663
664    /// A deadpool-postgres pool whose clients are instrumented. It
665    /// dereferences to deadpool's [`Pool`](deadpool_postgres::Pool).
666    ///
667    /// It also records the conventions' connection pool metrics, labelled
668    /// with `db.client.connection.pool.name`:
669    ///
670    /// - `db.client.connection.count`, by `db.client.connection.state`
671    ///   (`idle` or `used`), and `db.client.connection.max`;
672    /// - `db.client.connection.pending_requests`: callers waiting for a
673    ///   connection;
674    /// - `db.client.connection.wait_time` and `db.client.connection.use_time`,
675    ///   in seconds;
676    /// - `db.client.connection.timeouts`.
677    ///
678    /// The counts are taken from the pool's status whenever a client is
679    /// taken or returned. These metrics are still in development in the
680    /// conventions, so their names may change. The counts carry no unit,
681    /// since the `metrics` facade can't express `{connection}`.
682    #[derive(Clone)]
683    pub struct Pool {
684        inner: deadpool_postgres::Pool,
685        database: Database,
686        name: Arc<str>,
687    }
688
689    impl Pool {
690        /// Instrument a pool whose connections are made with `config`. Its
691        /// name in the pool metrics is `server.address:server.port/db.namespace`,
692        /// as the conventions suggest for a pool without one.
693        pub fn new(pool: deadpool_postgres::Pool, config: &tokio_postgres::Config) -> Self {
694            crate::pool::describe_metrics();
695            let database = Database::new(config);
696            let name = crate::pool::default_name(
697                POSTGRESQL,
698                database.0.namespace.as_deref(),
699                database.0.server.as_ref().map(|(a, p)| (a.as_str(), *p)),
700            );
701            Pool {
702                inner: pool,
703                database,
704                name: name.into(),
705            }
706        }
707
708        /// Name the pool in its metrics, for a program with more than one.
709        pub fn with_name(mut self, name: impl Into<String>) -> Self {
710            self.name = name.into().into();
711            self
712        }
713
714        /// Take a client from the pool, instrumented.
715        pub async fn get(
716            &self,
717        ) -> Result<Client<deadpool_postgres::Object>, deadpool_postgres::PoolError> {
718            let waiting = crate::pool::Waiting::start(&self.name);
719            let started = Instant::now();
720            let result = self.inner.get().await;
721            drop(waiting);
722            let timed_out = matches!(&result, Err(deadpool_postgres::PoolError::Timeout(_)));
723            crate::pool::record_wait(&self.name, started, timed_out);
724            sample(&self.inner, &self.name);
725            let client = result?;
726            let (pool, name) = (self.inner.clone(), Arc::clone(&self.name));
727            Ok(Client {
728                inner: client,
729                database: self.database.clone(),
730                _lease: Some(Lease::start(&self.name, move || sample(&pool, &name))),
731            })
732        }
733    }
734
735    /// Set the connection counts and the pool's size limit from its status.
736    fn sample(pool: &deadpool_postgres::Pool, name: &str) {
737        let status = pool.status();
738        crate::pool::record_counts(
739            name,
740            status.available,
741            status.size.saturating_sub(status.available),
742            status.max_size,
743        );
744    }
745
746    impl Deref for Pool {
747        type Target = deadpool_postgres::Pool;
748
749        fn deref(&self) -> &deadpool_postgres::Pool {
750            &self.inner
751        }
752    }
753
754    impl std::fmt::Debug for Pool {
755        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
756            f.debug_struct("Pool")
757                .field("database", &self.database)
758                .finish_non_exhaustive()
759        }
760    }
761}
762
763#[cfg(feature = "deadpool-postgres")]
764pub use pool::Pool;