Struct sqlx_postgres::PgListener
source · pub struct PgListener { /* private fields */ }
Expand description
A stream of asynchronous notifications from Postgres.
This listener will auto-reconnect. If the active connection being used ever dies, this listener will detect that event, create a new connection, will re-subscribe to all of the originally specified channels, and will resume operations as normal.
Implementations§
source§impl PgListener
impl PgListener
pub async fn connect(url: &str) -> Result<Self, Error>
pub async fn connect_with(pool: &Pool<Postgres>) -> Result<Self, Error>
sourcepub fn ignore_pool_close_event(&mut self, val: bool)
pub fn ignore_pool_close_event(&mut self, val: bool)
Set whether or not to ignore Pool::close_event()
. Defaults to false
.
By default, when Pool::close()
is called on the pool this listener is using
while Self::recv()
or Self::try_recv()
are waiting for a message, the wait is
cancelled and Err(PoolClosed)
is returned.
This is because Pool::close()
will wait until all connections are returned and closed,
including the one being used by this listener.
Otherwise, pool.close().await
would have to wait until PgListener
encountered a
need to acquire a new connection (timeout, error, etc.) and dropped the one it was
currently holding, at which point .recv()
or .try_recv()
would return Err(PoolClosed)
on the attempt to acquire a new connection anyway.
However, if you want PgListener
to ignore the close event and continue waiting for a
message as long as it can, set this to true
.
Does nothing if this was constructed with PgListener::connect()
, as that creates an
internal pool just for the new instance of PgListener
which cannot be closed manually.
sourcepub async fn listen(&mut self, channel: &str) -> Result<(), Error>
pub async fn listen(&mut self, channel: &str) -> Result<(), Error>
Starts listening for notifications on a channel. The channel name is quoted here to ensure case sensitivity.
sourcepub async fn listen_all(
&mut self,
channels: impl IntoIterator<Item = &str>
) -> Result<(), Error>
pub async fn listen_all( &mut self, channels: impl IntoIterator<Item = &str> ) -> Result<(), Error>
Starts listening for notifications on all channels.
sourcepub async fn unlisten(&mut self, channel: &str) -> Result<(), Error>
pub async fn unlisten(&mut self, channel: &str) -> Result<(), Error>
Stops listening for notifications on a channel. The channel name is quoted here to ensure case sensitivity.
sourcepub async fn unlisten_all(&mut self) -> Result<(), Error>
pub async fn unlisten_all(&mut self) -> Result<(), Error>
Stops listening for notifications on all channels.
sourcepub async fn recv(&mut self) -> Result<PgNotification, Error>
pub async fn recv(&mut self) -> Result<PgNotification, Error>
Receives the next notification available from any of the subscribed channels.
If the connection to PostgreSQL is lost, it is automatically reconnected on the next
call to recv()
, and should be entirely transparent (as long as it was just an
intermittent network failure or long-lived connection reaper).
As notifications are transient, any received while the connection was lost, will not
be returned. If you’d prefer the reconnection to be explicit and have a chance to
do something before, please see try_recv
.
§Example
loop {
// ask for next notification, re-connecting (transparently) if needed
let notification = listener.recv().await?;
// handle notification, do something interesting
}
sourcepub async fn try_recv(&mut self) -> Result<Option<PgNotification>, Error>
pub async fn try_recv(&mut self) -> Result<Option<PgNotification>, Error>
Receives the next notification available from any of the subscribed channels.
If the connection to PostgreSQL is lost, None
is returned, and the connection is
reconnected on the next call to try_recv()
.
§Example
loop {
// start handling notifications, connecting if needed
while let Some(notification) = listener.try_recv().await? {
// handle notification
}
// connection lost, do something interesting
}
sourcepub fn into_stream(
self
) -> impl Stream<Item = Result<PgNotification, Error>> + Unpin
pub fn into_stream( self ) -> impl Stream<Item = Result<PgNotification, Error>> + Unpin
Consume this listener, returning a Stream
of notifications.
The backing connection will be automatically reconnected should it be lost.
This has the same potential drawbacks as recv
.
Trait Implementations§
source§impl Debug for PgListener
impl Debug for PgListener
source§impl Drop for PgListener
impl Drop for PgListener
source§impl<'c> Executor<'c> for &'c mut PgListener
impl<'c> Executor<'c> for &'c mut PgListener
type Database = Postgres
source§fn fetch_many<'e, 'q: 'e, E>(
self,
query: E
) -> BoxStream<'e, Result<Either<PgQueryResult, PgRow>, Error>>
fn fetch_many<'e, 'q: 'e, E>( self, query: E ) -> BoxStream<'e, Result<Either<PgQueryResult, PgRow>, Error>>
source§fn fetch_optional<'e, 'q: 'e, E>(
self,
query: E
) -> BoxFuture<'e, Result<Option<PgRow>, Error>>
fn fetch_optional<'e, 'q: 'e, E>( self, query: E ) -> BoxFuture<'e, Result<Option<PgRow>, Error>>
source§fn prepare_with<'e, 'q: 'e>(
self,
query: &'q str,
parameters: &'e [PgTypeInfo]
) -> BoxFuture<'e, Result<PgStatement<'q>, Error>>where
'c: 'e,
fn prepare_with<'e, 'q: 'e>(
self,
query: &'q str,
parameters: &'e [PgTypeInfo]
) -> BoxFuture<'e, Result<PgStatement<'q>, Error>>where
'c: 'e,
source§fn execute<'e, 'q, E>(
self,
query: E
) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::QueryResult, Error>> + Send + 'e>>
fn execute<'e, 'q, E>( self, query: E ) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::QueryResult, Error>> + Send + 'e>>
source§fn execute_many<'e, 'q, E>(
self,
query: E
) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::QueryResult, Error>> + Send + 'e>>
fn execute_many<'e, 'q, E>( self, query: E ) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::QueryResult, Error>> + Send + 'e>>
source§fn fetch<'e, 'q, E>(
self,
query: E
) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::Row, Error>> + Send + 'e>>
fn fetch<'e, 'q, E>( self, query: E ) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::Row, Error>> + Send + 'e>>
source§fn fetch_all<'e, 'q, E>(
self,
query: E
) -> Pin<Box<dyn Future<Output = Result<Vec<<Self::Database as Database>::Row>, Error>> + Send + 'e>>
fn fetch_all<'e, 'q, E>( self, query: E ) -> Pin<Box<dyn Future<Output = Result<Vec<<Self::Database as Database>::Row>, Error>> + Send + 'e>>
Vec
.