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}