Struct PGRobustClient

pub struct PGRobustClient<TLS>
where
    TLS: MakeTlsConnect<Socket>,
{ /* private fields */ }

Implementations

impl<TLS> PGRobustClient<TLS>

where TLS: MakeTlsConnect<Socket> + Clone, <TLS as MakeTlsConnect<Socket>>::Stream: Send + Sync + 'static,

pub async fn spawn( database_url: impl AsRef<str>, make_tls: TLS, callback: impl Fn(PGMessage) + Send + Sync + 'static, ) -> PGResult<Self>

Given a connect factory and a callback, returns a new PGRobustClient.

The callback will be called whenever a new NOTIFY/RAISE message is received. Furthermore, it is also called with a PGMessage::Timeout, when a query times out, [PGMessage::Disconnected] if the internal state of the client is not as expected (Poisoned lock, dropped connections, etc.) or PGMessage::Reconnect whenever a new reconnect attempt is made.

pub fn with_default_timeout(self, timeout: Duration) -> Self

Sets the default timeout for all queries. Defaults to 1 hour.

This function consumes and returns self and is therefor usually used just after PGRobustClient::spawn.

pub fn with_max_reconnect_attempts(self, max_attempts: u32) -> Self

Sets the maximum number of reconnect attempts before giving up. Defaults to u32::MAX.

This function consumes and returns self and is therefor usually used just after PGRobustClient::spawn.

pub async fn cancel_query(&mut self) -> PGResult<()>

Cancels any in-progress query.

This is the only function that does not take a timeout nor does it attempt to reconnect if the connection is lost. It will simply return the original error.

pub fn capture_and_clear_log(&mut self) -> Vec<PGMessage>

Returns the log messages captured since the last call to this function. It also clears the log.

pub async fn with_captured_log<F, T>( &mut self, f: F, ) -> PGResult<(T, Vec<PGMessage>)>

where F: AsyncFn(&mut Self) -> PGResult<T>,

Given an async closure taking the postgres client, returns the result of said closure along with the accumulated log since the beginning of the closure.

If you use query pipelining then collect the logs for all queries in the pipeline. Otherwise, the logs might not be what you expect.

pub async fn reconnect(&mut self) -> PGResult<()>

Attempts to reconnect after a connection loss.

Reconnection applies an exponention backoff with jitter in order to avoid thundering herd effect. If the maximum number of attempts is reached then an error is returned.

If an error unrelated to establishing a new connection is returned when trying to connect then that error is returned.

pub async fn wrap_reconnect<T>( &mut self, max_dur: Option<Duration>, factory: impl AsyncFn(&mut PGClient) -> Result<T, Error>, ) -> PGResult<T>

pub async fn subscribe_notify( &mut self, channels: &[impl AsRef<str> + Send + Sync + 'static], timeout: Option<Duration>, ) -> PGResult<()>

pub async fn unsubscribe_notify( &mut self, channels: &[impl AsRef<str> + Send + Sync + 'static], timeout: Option<Duration>, ) -> PGResult<()>

pub async fn unsubscribe_notify_all( &mut self, timeout: Option<Duration>, ) -> PGResult<()>

Unsubscribes from all channels.

pub async fn execute_raw<P, I, T>( &mut self, statement: &T, params: I, timeout: Option<Duration>, ) -> PGResult<u64>

where T: ?Sized + ToStatement + Sync + Send, P: BorrowToSql + Clone + Send + Sync, I: IntoIterator<Item = P> + Sync + Send, I::IntoIter: ExactSizeIterator,

Like [Client::execute_raw].

pub async fn query<T>( &mut self, query: &T, params: &[&(dyn ToSql + Sync)], timeout: Option<Duration>, ) -> PGResult<Vec<Row>>

where T: ?Sized + ToStatement + Sync + Send,

Like [Client::query].

pub async fn query_one<T>( &mut self, statement: &T, params: &[&(dyn ToSql + Sync)], timeout: Option<Duration>, ) -> PGResult<Row>

where T: ?Sized + ToStatement + Sync + Send,

Like [Client::query_one].

pub async fn query_opt<T>( &mut self, statement: &T, params: &[&(dyn ToSql + Sync)], timeout: Option<Duration>, ) -> PGResult<Option<Row>>

where T: ?Sized + ToStatement + Sync + Send,

Like [Client::query_opt].

pub async fn query_raw<T, P, I>( &mut self, statement: &T, params: I, timeout: Option<Duration>, ) -> PGResult<RowStream>

where T: ?Sized + ToStatement + Sync + Send, P: BorrowToSql + Clone + Send + Sync, I: IntoIterator<Item = P> + Sync + Send, I::IntoIter: ExactSizeIterator,

Like [Client::query_raw].

pub async fn query_typed( &mut self, statement: &str, params: &[(&(dyn ToSql + Sync), Type)], timeout: Option<Duration>, ) -> PGResult<Vec<Row>>

Like [Client::query_typed]

pub async fn query_typed_raw<P, I>( &mut self, statement: &str, params: I, timeout: Option<Duration>, ) -> PGResult<RowStream>

where P: BorrowToSql + Clone + Send + Sync, I: IntoIterator<Item = (P, Type)> + Sync + Send,

Like [Client::query_typed_raw]

pub async fn prepare( &mut self, query: &str, timeout: Option<Duration>, ) -> PGResult<Statement>

Like [Client::prepare].

pub async fn prepare_typed( &mut self, query: &str, parameter_types: &[Type], timeout: Option<Duration>, ) -> PGResult<Statement>

Like [Client::prepare_typed].

pub async fn transaction<F>( &mut self, timeout: Option<Duration>, f: F, ) -> PGResult<()>

where for<'a> F: AsyncFn(&'a mut Transaction<'_>) -> Result<(), Error>,

Similar but not quite the same as [Client::transaction].

Executes the closure as a single transaction. Commit is automatically called after the closure. If any connection issues occur during the transaction then the transaction is rolled back (on drop) and retried a new with the new connection subject to the maximum number of reconnect attempts.

pub async fn batch_execute( &mut self, query: &str, timeout: Option<Duration>, ) -> PGResult<()>

Like [Client::batch_execute].

pub async fn simple_query( &mut self, query: &str, timeout: Option<Duration>, ) -> PGResult<Vec<SimpleQueryMessage>>

Like [Client::simple_query].

pub fn client(&self) -> &PGClient

Returns a reference to the underlying [Client].