Struct sqlx::postgres::PgListener

pub struct PgListener { /* fields omitted */ }

This is supported on crate feature postgres only.

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

impl PgListener

pub async fn connect(uri: &'_ str) -> Result<PgListener, Error>

This is supported on crate feature postgres only.

pub async fn connect_with(pool: &'_ Pool<Postgres>) -> Result<PgListener, Error>

This is supported on crate feature postgres only.

pub async fn listen(&'_ mut self, channel: &'_ str) -> Result<(), Error>

This is supported on crate feature postgres only.

Starts listening for notifications on a channel. The channel name is quoted here to ensure case sensitivity.

pub async fn listen_all<'_>(
    &'_ mut self,
    channels: impl IntoIterator<Item = &'_ str>
) -> Result<(), Error>

This is supported on crate feature postgres only.

Starts listening for notifications on all channels.

pub async fn unlisten(&'_ mut self, channel: &'_ str) -> Result<(), Error>

This is supported on crate feature postgres only.

Stops listening for notifications on a channel. The channel name is quoted here to ensure case sensitivity.

pub async fn unlisten_all(&'_ mut self) -> Result<(), Error>

This is supported on crate feature postgres only.

Stops listening for notifications on all channels.

pub async fn recv(&'_ mut self) -> Result<PgNotification, Error>

This is supported on crate feature postgres only.

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
}

pub async fn try_recv(&'_ mut self) -> Result<Option<PgNotification>, Error>

This is supported on crate feature postgres only.

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
}

pub fn into_stream(
    self
) -> impl Unpin + Stream<Item = Result<PgNotification, Error>>

This is supported on crate feature postgres only.

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

impl Debug for PgListener

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'c> Executor<'c> for &'c mut PgListener

type Database = Postgres

fn fetch_many<'e, 'q, E>(
    self,
    query: E
) -> Pin<Box<dyn Stream<Item = Result<Either<PgDone, PgRow>, Error>> + 'e + Send>> where
    'q: 'e,
    'c: 'e,
    E: 'q + Execute<'q, <&'c mut PgListener as Executor<'c>>::Database>, 

Execute multiple queries and return the generated results as a stream from each query, in a stream.

fn fetch_optional<'e, 'q, E>(
    self,
    query: E
) -> Pin<Box<dyn Future<Output = Result<Option<PgRow>, Error>> + 'e + Send>> where
    'q: 'e,
    'c: 'e,
    E: 'q + Execute<'q, <&'c mut PgListener as Executor<'c>>::Database>, 

Execute the query and returns at most one row.

fn prepare_with<'e, 'q>(
    self,
    query: &'q str,
    parameters: &'e [PgTypeInfo]
) -> Pin<Box<dyn Future<Output = Result<PgStatement<'q>, Error>> + 'e + Send>> where
    'q: 'e,
    'c: 'e, 

Prepare the SQL query, with parameter type information, to inspect the type information about its parameters and results.

fn execute<'e, 'q, E>(
    self,
    query: E
) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Done, Error>> + 'e + Send>> where
    'q: 'e,
    'c: 'e,
    E: 'q + Execute<'q, Self::Database>, 

Execute the query and return the total number of rows affected.

fn execute_many<'e, 'q, E>(
    self,
    query: E
) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::Done, Error>> + 'e + Send>> where
    'q: 'e,
    'c: 'e,
    E: 'q + Execute<'q, Self::Database>, 

Execute multiple queries and return the rows affected from each query, in a stream.

fn fetch<'e, 'q, E>(
    self,
    query: E
) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::Row, Error>> + 'e + Send>> where
    'q: 'e,
    'c: 'e,
    E: 'q + Execute<'q, Self::Database>, 

Execute the query and return the generated results as a stream.

fn fetch_all<'e, 'q, E>(
    self,
    query: E
) -> Pin<Box<dyn Future<Output = Result<Vec<<Self::Database as Database>::Row>, Error>> + 'e + Send>> where
    'q: 'e,
    'c: 'e,
    E: 'q + Execute<'q, Self::Database>, 

Execute the query and return all the generated results, collected into a Vec.

fn fetch_one<'e, 'q, E>(
    self,
    query: E
) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Row, Error>> + 'e + Send>> where
    'q: 'e,
    'c: 'e,
    E: 'q + Execute<'q, Self::Database>, 

Execute the query and returns exactly one row.

fn prepare<'e, 'q>(
    self,
    query: &'q str
) -> Pin<Box<dyn Future<Output = Result<<Self::Database as HasStatement<'q>>::Statement, Error>> + 'e + Send>> where
    'q: 'e,
    'c: 'e, 

Prepare the SQL query to inspect the type information of its parameters and results.