Skip to main content

sqlx_postgres/
listener.rs

1use std::fmt::{self, Debug};
2use std::str::from_utf8;
3
4use futures_channel::mpsc;
5use futures_core::future::BoxFuture;
6use futures_core::stream::{BoxStream, Stream};
7use futures_util::{FutureExt, StreamExt, TryFutureExt, TryStreamExt};
8use sqlx_core::acquire::Acquire;
9use sqlx_core::sql_str::{AssertSqlSafe, SqlStr};
10use sqlx_core::transaction::Transaction;
11use sqlx_core::Either;
12use tracing::Instrument;
13
14use crate::error::Error;
15use crate::executor::{Execute, Executor};
16use crate::message::{BackendMessageFormat, Notification};
17use crate::pool::PoolOptions;
18use crate::pool::{Pool, PoolConnection};
19use crate::{PgConnection, PgQueryResult, PgRow, PgStatement, PgTypeInfo, Postgres};
20
21/// A stream of asynchronous notifications from Postgres.
22///
23/// This listener will auto-reconnect. If the active
24/// connection being used ever dies, this listener will detect that event, create a
25/// new connection, will re-subscribe to all of the originally specified channels, and will resume
26/// operations as normal.
27pub struct PgListener {
28    pool: Pool<Postgres>,
29    connection: Option<PoolConnection<Postgres>>,
30    buffer_rx: mpsc::UnboundedReceiver<Notification>,
31    buffer_tx: Option<mpsc::UnboundedSender<Notification>>,
32    channels: Vec<String>,
33    ignore_close_event: bool,
34    eager_reconnect: bool,
35}
36
37/// An asynchronous notification from Postgres.
38#[derive(Clone)]
39pub struct PgNotification(Notification);
40
41impl PgListener {
42    pub async fn connect(url: &str) -> Result<Self, Error> {
43        // Create a pool of 1 without timeouts (as they don't apply here)
44        // We only use the pool to handle re-connections
45        let pool = PoolOptions::<Postgres>::new()
46            .max_connections(1)
47            .max_lifetime(None)
48            .idle_timeout(None)
49            .connect(url)
50            .await?;
51
52        let mut this = Self::connect_with(&pool).await?;
53        // We don't need to handle close events
54        this.ignore_close_event = true;
55
56        Ok(this)
57    }
58
59    pub async fn connect_with(pool: &Pool<Postgres>) -> Result<Self, Error> {
60        // Pull out an initial connection
61        let mut connection = pool.acquire().await?;
62
63        // Setup a notification buffer
64        let (sender, receiver) = mpsc::unbounded();
65        connection.inner.stream.notifications = Some(sender);
66
67        Ok(Self {
68            pool: pool.clone(),
69            connection: Some(connection),
70            buffer_rx: receiver,
71            buffer_tx: None,
72            channels: Vec::new(),
73            ignore_close_event: false,
74            eager_reconnect: true,
75        })
76    }
77
78    /// Set whether or not to ignore [`Pool::close_event()`]. Defaults to `false`.
79    ///
80    /// By default, when [`Pool::close()`] is called on the pool this listener is using
81    /// while [`Self::recv()`] or [`Self::try_recv()`] are waiting for a message, the wait is
82    /// cancelled and `Err(PoolClosed)` is returned.
83    ///
84    /// This is because `Pool::close()` will wait until _all_ connections are returned and closed,
85    /// including the one being used by this listener.
86    ///
87    /// Otherwise, `pool.close().await` would have to wait until `PgListener` encountered a
88    /// need to acquire a new connection (timeout, error, etc.) and dropped the one it was
89    /// currently holding, at which point `.recv()` or `.try_recv()` would return `Err(PoolClosed)`
90    /// on the attempt to acquire a new connection anyway.
91    ///
92    /// However, if you want `PgListener` to ignore the close event and continue waiting for a
93    /// message as long as it can, set this to `true`.
94    ///
95    /// Does nothing if this was constructed with [`PgListener::connect()`], as that creates an
96    /// internal pool just for the new instance of `PgListener` which cannot be closed manually.
97    pub fn ignore_pool_close_event(&mut self, val: bool) {
98        self.ignore_close_event = val;
99    }
100
101    /// Set whether a lost connection in `try_recv()` should be re-established before it returns
102    /// `Ok(None)`, or on the next call to `try_recv()`.
103    ///
104    /// By default, this is `true` and the connection is re-established before returning `Ok(None)`.
105    ///
106    /// If this is set to `false` then notifications will continue to be lost until the next call
107    /// to `try_recv()`. If your recovery logic uses a different database connection then
108    /// notifications that occur after it completes may be lost without any way to tell that they
109    /// have been.
110    pub fn eager_reconnect(&mut self, val: bool) {
111        self.eager_reconnect = val;
112    }
113
114    /// Starts listening for notifications on a channel.
115    /// The channel name is quoted here to ensure case sensitivity.
116    pub async fn listen(&mut self, channel: &str) -> Result<(), Error> {
117        self.connection()
118            .await?
119            .execute(AssertSqlSafe(format!(r#"LISTEN "{}""#, ident(channel))))
120            .await?;
121
122        self.channels.push(channel.to_owned());
123
124        Ok(())
125    }
126
127    /// Starts listening for notifications on all channels.
128    pub async fn listen_all(
129        &mut self,
130        channels: impl IntoIterator<Item = &str>,
131    ) -> Result<(), Error> {
132        let beg = self.channels.len();
133        self.channels.extend(channels.into_iter().map(|s| s.into()));
134
135        let query = build_listen_all_query(&self.channels[beg..]);
136        self.connection()
137            .await?
138            .execute(AssertSqlSafe(query))
139            .await?;
140
141        Ok(())
142    }
143
144    /// Stops listening for notifications on a channel.
145    /// The channel name is quoted here to ensure case sensitivity.
146    pub async fn unlisten(&mut self, channel: &str) -> Result<(), Error> {
147        // use RAW connection and do NOT re-connect automatically, since this is not required for
148        // UNLISTEN (we've disconnected anyways)
149        if let Some(connection) = self.connection.as_mut() {
150            connection
151                .execute(AssertSqlSafe(format!(r#"UNLISTEN "{}""#, ident(channel))))
152                .await?;
153        }
154
155        if let Some(pos) = self.channels.iter().position(|s| s == channel) {
156            self.channels.remove(pos);
157        }
158
159        Ok(())
160    }
161
162    /// Stops listening for notifications on all channels.
163    pub async fn unlisten_all(&mut self) -> Result<(), Error> {
164        // use RAW connection and do NOT re-connect automatically, since this is not required for
165        // UNLISTEN (we've disconnected anyways)
166        if let Some(connection) = self.connection.as_mut() {
167            connection.execute("UNLISTEN *").await?;
168        }
169
170        self.channels.clear();
171
172        Ok(())
173    }
174
175    #[inline]
176    async fn connect_if_needed(&mut self) -> Result<(), Error> {
177        if self.connection.is_none() {
178            let mut connection = self.pool.acquire().await?;
179            connection.inner.stream.notifications = self.buffer_tx.take();
180
181            connection
182                .execute(AssertSqlSafe(build_listen_all_query(&self.channels)))
183                .await?;
184
185            self.connection = Some(connection);
186        }
187
188        Ok(())
189    }
190
191    #[inline]
192    async fn connection(&mut self) -> Result<&mut PgConnection, Error> {
193        // Ensure we have an active connection to work with.
194        self.connect_if_needed().await?;
195
196        Ok(self.connection.as_mut().unwrap())
197    }
198
199    /// Receives the next notification available from any of the subscribed channels.
200    ///
201    /// If the connection to PostgreSQL is lost, it is automatically reconnected on the next
202    /// call to `recv()`, and should be entirely transparent (as long as it was just an
203    /// intermittent network failure or long-lived connection reaper).
204    ///
205    /// As notifications are transient, any received while the connection was lost, will not
206    /// be returned. If you'd prefer the reconnection to be explicit and have a chance to
207    /// do something before, please see [`try_recv`](Self::try_recv).
208    ///
209    /// # Example
210    ///
211    /// ```rust,no_run
212    /// # use sqlx::postgres::PgListener;
213    /// #
214    /// # sqlx::__rt::test_block_on(async move {
215    /// let mut listener = PgListener::connect("postgres:// ...").await?;
216    /// loop {
217    ///     // ask for next notification, re-connecting (transparently) if needed
218    ///     let notification = listener.recv().await?;
219    ///
220    ///     // handle notification, do something interesting
221    /// }
222    /// # Result::<(), sqlx::Error>::Ok(())
223    /// # }).unwrap();
224    /// ```
225    pub async fn recv(&mut self) -> Result<PgNotification, Error> {
226        loop {
227            if let Some(notification) = self.try_recv().await? {
228                return Ok(notification);
229            }
230        }
231    }
232
233    /// Receives the next notification available from any of the subscribed channels.
234    ///
235    /// If the connection to PostgreSQL is lost, `None` is returned, and the connection is
236    /// reconnected either immediately, or on the next call to `try_recv()`, depending on
237    /// the value of [`eager_reconnect`].
238    ///
239    /// # Example
240    ///
241    /// ```rust,no_run
242    /// # use sqlx::postgres::PgListener;
243    /// #
244    /// # sqlx::__rt::test_block_on(async move {
245    /// # let mut listener = PgListener::connect("postgres:// ...").await?;
246    /// loop {
247    ///     // start handling notifications, connecting if needed
248    ///     while let Some(notification) = listener.try_recv().await? {
249    ///         // handle notification
250    ///     }
251    ///
252    ///     // connection lost, do something interesting
253    /// }
254    /// # Result::<(), sqlx::Error>::Ok(())
255    /// # }).unwrap();
256    /// ```
257    ///
258    /// [`eager_reconnect`]: PgListener::eager_reconnect
259    pub async fn try_recv(&mut self) -> Result<Option<PgNotification>, Error> {
260        match self.recv_without_recovery().await {
261            Ok(notification) => Ok(Some(notification)),
262
263            // The connection is dead, ensure that it is dropped,
264            // update self state
265            Err(Error::Io(_)) => {
266                if let Some(mut conn) = self.connection.take() {
267                    self.buffer_tx = conn.inner.stream.notifications.take();
268                    // Close the connection in a background task, so we can continue.
269                    conn.close_on_drop();
270                }
271
272                if self.eager_reconnect {
273                    // If reconnecting fails due to an IO error - retry
274                    // if the pool is unable to get a new working connection
275                    // it will eventually error out with Error::PoolTimedOut and
276                    // end this loop
277                    loop {
278                        match self.connection().await {
279                            Ok(_) => break,
280                            Err(Error::Io(_)) => continue,
281                            Err(e) => return Err(e),
282                        }
283                    }
284                }
285
286                // lost connection
287                Ok(None)
288            }
289            Err(e) => Err(e),
290        }
291    }
292
293    async fn recv_without_recovery(&mut self) -> Result<PgNotification, Error> {
294        // Flush the buffer first, if anything
295        // This would only fill up if this listener is used as a connection
296        if let Some(notification) = self.next_buffered() {
297            return Ok(notification);
298        }
299
300        // Fetch our `CloseEvent` listener, if applicable.
301        let mut close_event = (!self.ignore_close_event).then(|| self.pool.close_event());
302
303        loop {
304            let next_message = self.connection().await?.inner.stream.recv_unchecked();
305
306            let res = if let Some(ref mut close_event) = close_event {
307                // cancels the wait and returns `Err(PoolClosed)` if the pool is closed
308                // before `next_message` returns, or if the pool was already closed
309                close_event.do_until(next_message).await?
310            } else {
311                next_message.await
312            };
313
314            let message = res?;
315
316            match message.format {
317                // We've received an async notification, return it.
318                BackendMessageFormat::NotificationResponse => {
319                    return Ok(PgNotification(message.decode()?));
320                }
321
322                // Mark the connection as ready for another query
323                BackendMessageFormat::ReadyForQuery => {
324                    self.connection().await?.inner.pending_ready_for_query_count -= 1;
325                }
326
327                // Ignore unexpected messages
328                _ => {}
329            }
330        }
331    }
332
333    /// Receives the next notification that already exists in the connection buffer, if any.
334    ///
335    /// This is similar to `try_recv`, except it will not wait if the connection has not yet received a notification.
336    ///
337    /// This is helpful if you want to retrieve all buffered notifications and process them in batches.
338    pub fn next_buffered(&mut self) -> Option<PgNotification> {
339        if let Ok(notification) = self.buffer_rx.try_recv() {
340            Some(PgNotification(notification))
341        } else {
342            None
343        }
344    }
345
346    /// Consume this listener, returning a `Stream` of notifications.
347    ///
348    /// The backing connection will be automatically reconnected should it be lost.
349    ///
350    /// This has the same potential drawbacks as [`recv`](PgListener::recv).
351    ///
352    pub fn into_stream(mut self) -> impl Stream<Item = Result<PgNotification, Error>> + Unpin {
353        Box::pin(try_stream! {
354            loop {
355                r#yield!(self.recv().await?);
356            }
357        })
358    }
359}
360
361impl Drop for PgListener {
362    fn drop(&mut self) {
363        if let Some(mut conn) = self.connection.take() {
364            let fut = async move {
365                let _ = conn.execute("UNLISTEN *").await;
366
367                // inline the drop handler from `PoolConnection` so it doesn't try to spawn another task
368                // otherwise, it may trigger a panic if this task is dropped because the runtime is going away:
369                // https://github.com/launchbadge/sqlx/issues/1389
370                conn.return_to_pool().await;
371            };
372
373            // Unregister any listeners before returning the connection to the pool.
374            crate::rt::spawn(fut.in_current_span());
375        }
376    }
377}
378
379impl<'c> Acquire<'c> for &'c mut PgListener {
380    type Database = Postgres;
381    type Connection = &'c mut PgConnection;
382
383    fn acquire(self) -> BoxFuture<'c, Result<Self::Connection, Error>> {
384        self.connection().boxed()
385    }
386
387    fn begin(self) -> BoxFuture<'c, Result<Transaction<'c, Self::Database>, Error>> {
388        self.connection().and_then(|c| c.begin()).boxed()
389    }
390}
391
392impl<'c> Executor<'c> for &'c mut PgListener {
393    type Database = Postgres;
394
395    fn fetch_many<'e, 'q, E>(
396        self,
397        query: E,
398    ) -> BoxStream<'e, Result<Either<PgQueryResult, PgRow>, Error>>
399    where
400        'c: 'e,
401        E: Execute<'q, Self::Database>,
402        'q: 'e,
403        E: 'q,
404    {
405        futures_util::stream::once(async move {
406            // need some basic type annotation to help the compiler a bit
407            let res: Result<_, Error> = Ok(self.connection().await?.fetch_many(query));
408            res
409        })
410        .try_flatten()
411        .boxed()
412    }
413
414    fn fetch_optional<'e, 'q, E>(self, query: E) -> BoxFuture<'e, Result<Option<PgRow>, Error>>
415    where
416        'c: 'e,
417        E: Execute<'q, Self::Database>,
418        'q: 'e,
419        E: 'q,
420    {
421        async move { self.connection().await?.fetch_optional(query).await }.boxed()
422    }
423
424    fn prepare_with<'e>(
425        self,
426        query: SqlStr,
427        parameters: &'e [PgTypeInfo],
428    ) -> BoxFuture<'e, Result<PgStatement, Error>>
429    where
430        'c: 'e,
431    {
432        async move {
433            self.connection()
434                .await?
435                .prepare_with(query, parameters)
436                .await
437        }
438        .boxed()
439    }
440
441    #[doc(hidden)]
442    #[cfg(feature = "offline")]
443    fn describe<'e>(
444        self,
445        query: SqlStr,
446    ) -> BoxFuture<'e, Result<crate::describe::Describe<Self::Database>, Error>>
447    where
448        'c: 'e,
449    {
450        async move { self.connection().await?.describe(query).await }.boxed()
451    }
452}
453
454impl PgNotification {
455    /// The process ID of the notifying backend process.
456    #[inline]
457    pub fn process_id(&self) -> u32 {
458        self.0.process_id
459    }
460
461    /// The channel that the notify has been raised on. This can be thought
462    /// of as the message topic.
463    #[inline]
464    pub fn channel(&self) -> &str {
465        from_utf8(&self.0.channel).unwrap()
466    }
467
468    /// The payload of the notification. An empty payload is received as an
469    /// empty string.
470    #[inline]
471    pub fn payload(&self) -> &str {
472        from_utf8(&self.0.payload).unwrap()
473    }
474}
475
476impl Debug for PgListener {
477    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
478        f.debug_struct("PgListener").finish()
479    }
480}
481
482impl Debug for PgNotification {
483    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
484        f.debug_struct("PgNotification")
485            .field("process_id", &self.process_id())
486            .field("channel", &self.channel())
487            .field("payload", &self.payload())
488            .finish()
489    }
490}
491
492fn ident(mut name: &str) -> String {
493    // If the input string contains a NUL byte, we should truncate the
494    // identifier.
495    if let Some(index) = name.find('\0') {
496        name = &name[..index];
497    }
498
499    // Any double quotes must be escaped
500    name.replace('"', "\"\"")
501}
502
503fn build_listen_all_query(channels: impl IntoIterator<Item = impl AsRef<str>>) -> String {
504    channels.into_iter().fold(String::new(), |mut acc, chan| {
505        acc.push_str(r#"LISTEN ""#);
506        acc.push_str(&ident(chan.as_ref()));
507        acc.push_str(r#"";"#);
508        acc
509    })
510}
511
512#[test]
513fn test_build_listen_all_query_with_single_channel() {
514    let output = build_listen_all_query(["test"]);
515    assert_eq!(output.as_str(), r#"LISTEN "test";"#);
516}
517
518#[test]
519fn test_build_listen_all_query_with_multiple_channels() {
520    let output = build_listen_all_query(["channel.0", "channel.1"]);
521    assert_eq!(output.as_str(), r#"LISTEN "channel.0";LISTEN "channel.1";"#);
522}