pub struct PgAdvisoryLockGuard<'lock, C: AsMut<PgConnection>> { /* private fields */ }
Expand description

A wrapper for PgConnection (or a similar type) that represents a held Postgres advisory lock.

Can be acquired by PgAdvisoryLock::acquire() or PgAdvisoryLock::try_acquire(). Released on-drop or via Self::release_now().

§Note: Release-on-drop is not immediate!

On drop, this guard queues a pg_advisory_unlock() call on the connection which will be flushed to the server the next time it is used, or when it is returned to a PgPool in the case of PoolConnection<Postgres>.

This means the lock is not actually released as soon as the guard is dropped. To ensure the lock is eagerly released, you can call .release_now().await.

Implementations§

source§

impl<'lock, C: AsMut<PgConnection>> PgAdvisoryLockGuard<'lock, C>

source

pub async fn release_now(self) -> Result<C>

Immediately release the held advisory lock instead of when the connection is next used.

An error should only be returned if there is something wrong with the connection, in which case the lock will be automatically released by the connection closing anyway.

If pg_advisory_unlock() returns false, a warning will be logged, both by SQLx as well as the Postgres server. This would only happen if the lock was released without using this guard, or the connection was swapped using std::mem::replace().

source

pub fn leak(self) -> C

Cancel the release of the advisory lock, keeping it held until the connection is closed.

To manually release the lock later, see PgAdvisoryLock::force_release().

Methods from Deref<Target = PgConnection>§

source

pub fn server_version_num(&self) -> Option<u32>

the version number of the server in libpq format

source

pub async fn copy_in_raw( &mut self, statement: &str ) -> Result<PgCopyIn<&mut Self>>

Issue a COPY FROM STDIN statement and transition the connection to streaming data to Postgres. This is a more efficient way to import data into Postgres as compared to INSERT but requires one of a few specific data formats (text/CSV/binary).

If statement is anything other than a COPY ... FROM STDIN ... command, an error is returned.

Command examples and accepted formats for COPY data are shown here: https://www.postgresql.org/docs/current/sql-copy.html

§Note

PgCopyIn::finish or PgCopyIn::abort must be called when finished or the connection will return an error the next time it is used.

source

pub async fn copy_out_raw<'c>( &'c mut self, statement: &str ) -> Result<BoxStream<'c, Result<Bytes>>>

Issue a COPY TO STDOUT statement and transition the connection to streaming data from Postgres. This is a more efficient way to export data from Postgres but arrives in chunks of one of a few data formats (text/CSV/binary).

If statement is anything other than a COPY ... TO STDOUT ... command, an error is returned.

Note that once this process has begun, unless you read the stream to completion, it can only be canceled in two ways:

  1. by closing the connection, or:
  2. by using another connection to kill the server process that is sending the data as shown in this StackOverflow answer.

If you don’t read the stream to completion, the next time the connection is used it will need to read and discard all the remaining queued data, which could take some time.

Command examples and accepted formats for COPY data are shown here: https://www.postgresql.org/docs/current/sql-copy.html

Trait Implementations§

source§

impl<'lock, C: AsMut<PgConnection>> AsMut<PgConnection> for PgAdvisoryLockGuard<'lock, C>

Mutable access to the underlying connection is provided so it can still be used like normal, even allowing locks to be taken recursively.

However, replacing the connection with a different one using, e.g. std::mem::replace() is a logic error and will cause a warning to be logged by the PostgreSQL server when this guard attempts to release the lock.

source§

fn as_mut(&mut self) -> &mut PgConnection

Converts this type into a mutable reference of the (usually inferred) input type.
source§

impl<'lock, C: AsMut<PgConnection> + AsRef<PgConnection>> AsRef<PgConnection> for PgAdvisoryLockGuard<'lock, C>

source§

fn as_ref(&self) -> &PgConnection

Converts this type into a shared reference of the (usually inferred) input type.
source§

impl<'lock, C: AsMut<PgConnection> + AsRef<PgConnection>> Deref for PgAdvisoryLockGuard<'lock, C>

§

type Target = PgConnection

The resulting type after dereferencing.
source§

fn deref(&self) -> &Self::Target

Dereferences the value.
source§

impl<'lock, C: AsMut<PgConnection> + AsRef<PgConnection>> DerefMut for PgAdvisoryLockGuard<'lock, C>

Mutable access to the underlying connection is provided so it can still be used like normal, even allowing locks to be taken recursively.

However, replacing the connection with a different one using, e.g. std::mem::replace() is a logic error and will cause a warning to be logged by the PostgreSQL server when this guard attempts to release the lock.

source§

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.
source§

impl<'lock, C: AsMut<PgConnection>> Drop for PgAdvisoryLockGuard<'lock, C>

Queues a pg_advisory_unlock() call on the wrapped connection which will be flushed to the server the next time it is used, or when it is returned to PgPool in the case of PoolConnection<Postgres>.

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

impl<'lock, C> Freeze for PgAdvisoryLockGuard<'lock, C>
where C: Freeze,

§

impl<'lock, C> RefUnwindSafe for PgAdvisoryLockGuard<'lock, C>
where C: RefUnwindSafe,

§

impl<'lock, C> Send for PgAdvisoryLockGuard<'lock, C>
where C: Send,

§

impl<'lock, C> Sync for PgAdvisoryLockGuard<'lock, C>
where C: Sync,

§

impl<'lock, C> Unpin for PgAdvisoryLockGuard<'lock, C>
where C: Unpin,

§

impl<'lock, C> UnwindSafe for PgAdvisoryLockGuard<'lock, C>
where C: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more