pub struct PgListener { /* private fields */ }Expand description
A dedicated connection receiving PostgreSQL NOTIFY messages.
The connection is not taken from a pool. Dropping the listener closes it and stops its background tasks.
§Connect directly to PostgreSQL
A LISTEN subscription belongs to one server session, so the listener
must connect to PostgreSQL itself, not through a transaction-mode pooler
(such as PgBouncer with pool_mode = transaction) or a multiplexing
proxy such as Amazon RDS Proxy, which do not keep the client connection
tied to one server session: notifications would be lost or never
arrive. When the application’s pool goes through such a proxy, build the
listener from a PgConfig that points at the database server directly
rather than with from_pool, which copies the pool’s
host.
§Security
PostgreSQL has no privileges on channels: any role that can connect to
the database can NOTIFY on any channel, including the ones this
listener subscribes to. A notification proves nothing about who sent it
or whether its payload is true. Use it as a cue to re-read the
authoritative data, or verify an authenticated payload (such as an HMAC
over it with a key only legitimate senders hold) before acting on it.
Implementations§
Source§impl PgListener
impl PgListener
Sourcepub async fn connect(config: &PgConfig) -> PgResult<Self>
pub async fn connect(config: &PgConfig) -> PgResult<Self>
Connect with default PgListenerOptions.
Sourcepub async fn from_pool(pool: &PgPool) -> PgResult<Self>
pub async fn from_pool(pool: &PgPool) -> PgResult<Self>
Connect a dedicated listener using pool’s configuration (including
its TLS settings and host). The connection is not taken from the pool.
If the pool connects through a transaction-mode pooler or a proxy
such as Amazon RDS Proxy, use connect with a
config that points at PostgreSQL directly instead; see
Connect directly to PostgreSQL.
Sourcepub fn builder(config: &PgConfig) -> PgListenerBuilder
pub fn builder(config: &PgConfig) -> PgListenerBuilder
Start building a listener with custom PgListenerOptions.
Sourcepub async fn listen(&mut self, channel: &str) -> PgResult<()>
pub async fn listen(&mut self, channel: &str) -> PgResult<()>
Subscribe to channel.
The name is used verbatim (quoted as an identifier, case preserved), so
it matches pg_notify(channel, ..) / PgConnection::notify with the
same string. It must be non-empty, at most 63 bytes and free of NUL.
Subscribing to a channel twice is a no-op.
If the server does not answer within
ping_interval, this fails with a
timeout error and the listener treats the connection as lost.
After a connection loss, while the listener is backing off before its
next reconnect attempt, this (like unlisten and
unlisten_all) returns without waiting for the
server: the channel is recorded and subscribed when the connection is
re-established. (During the attempt itself it waits for the attempt to
finish.) If the server then rejects the channel name (for example one
its encoding cannot represent), the channel is dropped and reported as
PgListenerEvent::ChannelsDropped.
Sourcepub async fn listen_all<I, S>(&mut self, channels: I) -> PgResult<()>
pub async fn listen_all<I, S>(&mut self, channels: I) -> PgResult<()>
Subscribe to every channel in channels.
All names are validated before any is subscribed; on a server error the channels before the failing one stay subscribed.
Sourcepub async fn unlisten(&mut self, channel: &str) -> PgResult<()>
pub async fn unlisten(&mut self, channel: &str) -> PgResult<()>
Unsubscribe from channel. Unsubscribing from a channel that is not
subscribed is a no-op.
Sourcepub async fn unlisten_all(&mut self) -> PgResult<()>
pub async fn unlisten_all(&mut self) -> PgResult<()>
Unsubscribe from every channel (UNLISTEN *).
Sourcepub async fn recv(&mut self) -> PgResult<PgListenerEvent>
pub async fn recv(&mut self) -> PgResult<PgListenerEvent>
Wait for the next event.
Events keep their order relative to the notifications: a
PgListenerEvent::Disconnected, PgListenerEvent::Reconnected or
PgListenerEvent::Lagged is returned after the notifications that
were already queued when this first saw it, and before any queued
later. On an empty queue it is returned at once, also while this is
waiting. Each Disconnected comes before the Reconnected that ends
its outage, and a PgListenerEvent::ChannelsDropped right before
the Reconnected of the reconnect that dropped the channels; when
they are due together with a Lagged, they come first. Several
outages that happen before this sees the first reconnect are
reported as a single Disconnected and Reconnected (with every
channel dropped meanwhile), so the two always alternate.
Once the listener has stopped (the connection was lost with
PgListenerOptions::reconnect disabled, or reconnecting gave up)
and every queued event has been read, this returns the error that
ended it, and a generic “listener closed” error on later calls.
Cancel safe: if the future is dropped before completing, no event is lost.
Sourcepub fn into_stream(self) -> impl Stream<Item = PgResult<PgListenerEvent>> + Send
pub fn into_stream(self) -> impl Stream<Item = PgResult<PgListenerEvent>> + Send
Turn the listener into a stream of PgListener::recv results.
The stream ends after yielding the error that closed the listener.