Struct sqlx_core::postgres::PgAdvisoryLockGuard

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

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

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

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().

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>

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

the version number of the server in libpq format

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.

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

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.

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

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

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

fn as_ref(&self) -> &PgConnection

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

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

type Target = PgConnection

The resulting type after dereferencing.

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

Dereferences the value.

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.

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

Mutably dereferences the value.

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>.

fn drop(&mut self)

Executes the destructor for this type.