Struct Datum

pub struct Datum<'src>(/* private fields */);

How Postgres represents datatypes

The “no-frills” version is pg_sys::Datum, which is abstractly a union of “pointer to void” with other scalar types that can be packed within a pointer’s bytes. In practical use, a “raw” Datum can prove to have the same risks as a pointer: code may try to use it without knowing whether its pointee has been deallocated. To lift a Datum into a Rust type requires making implicit lifetimes into explicit bounds.

Merely having a lifetime does not make Datum<'src> “safe” to use. To abstractly represent a full PostgreSQL value needs at least the tuple (Datum, bool, pg_sys::Oid): a tagged union. Datum<'src> itself is effectively a dynamically-typed union without a type tag. It exists not to make code manipulating it safe, but to make it possible to write unsafe code correctly, passing Datums to and from Postgres without having to wonder if the implied &'src T would actually refer to deallocated data.

Designing safe abstractions

A function must only be declared safe if all inputs cannot cause undefined behavior. Transmuting a raw pg_sys::Datum into &'a T grants a potentially-unbounded lifetime, breaking the rule borrows must not outlive the borrowed. Avoiding such transmutations infects even simple generic functions with soundness obligations. Using only &'a pg_sys::Datum lasts only until one must pass by-value, which is the entire point of the original type as Postgres defined it, but can still be preferable.

Datum<'src> makes it theoretically possible to write functions with a signature like

use pgrx::datum::Datum;
fn construct_type_from_datum<'src, T>(
    datum: Datum<'src>,
    func: impl FnOnce(Datum<'src>) -> InCx<'src, T>
) -> InCx<'src, T> {
   func(datum)
}

However, it is possible for T<'src> to be insufficient to represent the real lifetime of the abstract Postgres type’s allocations. Often a Datum must be “detoasted”, which may reallocate. This may demand two constraints on the return type to represent both possible lifetimes, like:

use pgrx::datum::Datum;
use pgrx::memcx::MemCx;
fn detoast_type_from_datum<'old, 'new, T>(
    datum: Datum<'old>,
    memcx: MemCx<'new>,
) -> Detoasted<'new, InCx<'old, T>> {
   todo!()
}

In actual practice, these can be unified into a single lifetime: the lower bound of both. This is both good and bad: types can use fewer lifetime annotations, even after detoasting. However, in general, because lifetime unification can be done implicitly by the compiler, it is often important to name each and every single lifetime involved in functions that perform these tasks.

Implementations

impl<'src> Datum<'src>

pub fn sans_lifetime(self) -> Datum

Strip a Datum of its lifetime for FFI purposes.

pub fn null() -> Datum<'src>

Construct a Datum containing only a null pointer.

pub unsafe fn borrow_as<T: BorrowDatum>(&self) -> Option<&T>

Reborrow the Datum as T

If the type is PassBy::Ref, this may be None.