Struct pgx::PgTryBuilder

pub struct PgTryBuilder<'a, R, F>where
    F: FnOnce() -> R + UnwindSafe,{ /* private fields */ }

PgTryBuilder is a mechanism to mimic Postgres C macros PG_TRY and PG_CATCH.

A primary difference is that the PgTryBuilder::finally() block runs even if a catch handler rethrows (or throws a new) error.

Implementations

impl<'a, R, F> PgTryBuilder<'a, R, F>where
    F: FnOnce() -> R + UnwindSafe,

pub fn new(func: F) -> PgTryBuilder<'a, R, F>

Create a new [PgTryBuilder]. The func argument specifies the closure that is to run.

If it fails with either a Rust panic or a Postgres error, a registered catch handler for that specific error is run. Whether one exists or not, the finally block also runs at the end, for any necessary cleanup.

Example

let i = 41;
let mut finished = false;
let result = PgTryBuilder::new(|| {
    if i < 42 {
        ereport!(ERROR, PgSqlErrorCode::ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE, "number too small");
    }
    i
})
    .catch_when(PgSqlErrorCode::ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE, |cause| cause.rethrow())
    .finally(|| finished = true)
    .execute();

assert_eq!(finished, true);
assert_eq!(result, 42);

pub fn catch_when(
    self,
    error: PgSqlErrorCode,
    f: impl FnMut(CaughtError) -> R + UnwindSafe + RefUnwindSafe + 'a
) -> PgTryBuilder<'a, R, F>

Add a catch handler to run should a specific error occur during execution.

The argument to the catch handler closure is a CaughtError which can be rethrown via CaughtError::rethrow()

The return value must be of the same type as the main execution block, or the supplied error cause must be rethrown.

Safety

While this function isn’t itself unsafe, catching and then ignoring an important internal Postgres error may very well leave your database in an undesirable state. This is your responsibility.

pub fn catch_others(
    self,
    f: impl FnMut(CaughtError) -> R + UnwindSafe + RefUnwindSafe + 'a
) -> PgTryBuilder<'a, R, F>

Add a catch-all handler to catch a raised error that wasn’t explicitly caught via PgTryBuilder::catch_when.

The argument to the catch handler closure is a CaughtError which can be rethrown via CaughtError::rethrow().

The return value must be of the same type as the main execution block, or the supplied error cause must be rethrown.

Safety

While this function isn’t itself unsafe, catching and then ignoring an important internal Postgres error may very well leave your database in an undesirable state. This is your responsibility.

pub fn catch_rust_panic(
    self,
    f: impl FnMut(CaughtError) -> R + UnwindSafe + RefUnwindSafe + 'a
) -> PgTryBuilder<'a, R, F>

Add a handler to specifically respond to a Rust panic.

The catch handler’s closure argument is a [CaughtError::PostgresError {ereport, payload}] that you can inspect in whatever way makes sense.

The return value must be of the same type as the main execution block, or the supplied error cause must be rethrown.

pub fn finally(self, f: impl FnMut() + 'a) -> PgTryBuilder<'a, R, F>

The finally block, of which there can be only one. Successive calls to this function will replace the prior finally block.

The finally block closure is called after successful return from the main execution handler or a catch handler. The finally block does not return a value.

pub fn execute(self) -> R

Run the main execution block closure. Any error raised will be passed to a registered catch handler, and when finished, the finally block will be run.