Struct PgHeapTuple

pub struct PgHeapTuple<'a, AllocatedBy>
where
    AllocatedBy: WhoAllocated,
{ /* private fields */ }

A PgHeapTuple is a lightweight wrapper around Postgres’ pg_sys::HeapTuple object and a PgTupleDesc.

In order to access the attributes within a pg_sys::HeapTuple, the PgTupleDesc is required to describe its structure.

PgHeapTuples can be created from existing (Postgres-provided) pg_sys::HeapTuple pointers, from pg_sys::TriggerData pointers, from a composite datum, or created from scratch using raw Datums.

A PgHeapTuple can either be considered to be allocated by Postgres or by the Rust runtime. If allocated by Postgres, it is not mutable until PgHeapTuple::into_owned is called.

PgHeapTuples also describe composite types as defined by pgrx::composite_type!().

Implementations

impl<'a> PgHeapTuple<'a, AllocatedByPostgres>

pub unsafe fn from_heap_tuple( tupdesc: PgTupleDesc<'a>, heap_tuple: *mut HeapTupleData, ) -> PgHeapTuple<'a, AllocatedByPostgres>

Creates a new PgHeapTuple from a PgTupleDesc and a pg_sys::HeapTuple pointer. The returned PgHeapTuple will be considered by have been allocated by Postgres and is not mutable until PgHeapTuple::into_owned is called.

Safety

This function is unsafe as we cannot guarantee that the pg_sys::HeapTuple pointer is valid, nor can we guaratee that the provided PgTupleDesc properly describes the structure of the heap tuple.

pub unsafe fn from_trigger_data( trigger_data: &'a TriggerData, which_tuple: TriggerTuple, ) -> Option<PgHeapTuple<'a, AllocatedByPostgres>>

Creates a new PgHeapTuple identified by the which_tuple trigger tuple. The returned PgHeapTuple will be considered by have been allocated by Postgres and is not mutable until PgHeapTuple::into_owned is called.

pgrx also invents the concept of a “current” ([TriggerTuple::Current]) tuple, which is either the new row being inserted or the row being updated (not the new version) or deleted.

Asking for a TriggerTuple that isn’t compatible with how the trigger was fired causes this function to return None. Specifically this means None is always returned for statement-level triggers.

Safety

This function is unsafe as we cannot guarantee that any pointers in the trigger_data argument are valid or that it’s being used in the context of a firing trigger, which necessitates Postgres internal state be correct for executing a trigger.

pub fn into_owned(self) -> PgHeapTuple<'a, AllocatedByRust>

Consumes a [PgHeapTuple] considered to be allocated by Postgres and transforms it into one that is considered allocated by Rust. This is accomplished by copying the underlying pg_sys::HeapTupleData.

impl<'a> PgHeapTuple<'a, AllocatedByRust>

pub fn new_composite_type( type_name: &str, ) -> Result<PgHeapTuple<'a, AllocatedByRust>, PgHeapTupleError>

Create a new heap tuple in the shape of a defined composite type

use pgrx::prelude::*;

Spi::run("CREATE TYPE dog AS (name text, age int);");
let mut heap_tuple = PgHeapTuple::new_composite_type("dog").unwrap();

assert_eq!(heap_tuple.get_by_name::<String>("name").unwrap(), None);
assert_eq!(heap_tuple.get_by_name::<i32>("age").unwrap(), None);

heap_tuple
    .set_by_name("name", "Brandy".to_string())
    .unwrap();
heap_tuple.set_by_name("age", 42).unwrap();

assert_eq!(
    heap_tuple.get_by_name("name").unwrap(),
    Some("Brandy".to_string())
);
assert_eq!(heap_tuple.get_by_name("age").unwrap(), Some(42i32));

pub fn new_composite_type_by_oid( typoid: Oid, ) -> Result<PgHeapTuple<'a, AllocatedByRust>, PgHeapTupleError>

pub unsafe fn from_datums<I>( tupdesc: PgTupleDesc<'a>, datums: I, ) -> Result<PgHeapTuple<'a, AllocatedByRust>, PgHeapTupleError>

where I: IntoIterator<Item = Option<Datum>>,

Create a new PgHeapTuple from a PgTupleDesc from an iterator of Datums.

Errors

• PgHeapTupleError::IncorrectAttributeCount if the number of items in the iterator does not match the number of attributes in the PgTupleDesc.

Safety

This function is unsafe as we cannot guarantee the provided pg_sys::Datums are valid as the specified PgTupleDesc might expect

pub unsafe fn from_composite_datum( composite: Datum, ) -> PgHeapTuple<'a, AllocatedByRust>

Creates a new PgHeapTuple from an opaque Datum that should be a “composite” type.

The Datum should be a pointer to a pg_sys::HeapTupleHeader. Typically, this will be used in situations when working with SQL ROW(...) constructors, or a composite SQL type such as

CREATE TYPE my_composite AS (name text, age i32);

Safety

This function is unsafe as we cannot guarantee that the provided Datum is a valid pg_sys::HeapTupleHeader pointer.

pub fn set_by_name<T>( &mut self, attname: &str, value: T, ) -> Result<(), TryFromDatumError>

where T: IntoDatum,

Given the name for an attribute in this PgHeapTuple, change its value.

Attribute names are case sensitive.

Errors

• return TryFromDatumError::NoSuchAttributeName if the attribute does not exist
• return TryFromDatumError::IncompatibleTypes if the Rust type of the value is not compatible with the attribute’s Postgres type

pub fn set_by_index<T>( &mut self, attno: NonZero<usize>, value: T, ) -> Result<(), TryFromDatumError>

where T: IntoDatum,

Given the index for an attribute in this PgHeapTuple, change its value.

Attribute numbers start at 1, not 0.

Errors

• return TryFromDatumError::NoSuchAttributeNumber if the attribute does not exist
• return TryFromDatumError::IncompatibleTypes if the Rust type of the value is not compatible with the attribute’s Postgres type

impl<'a, AllocatedBy> PgHeapTuple<'a, AllocatedBy>

where AllocatedBy: WhoAllocated,

pub fn into_composite_datum(self) -> Option<Datum>

Consume this PgHeapTuple and return a composite Datum representation, containing the tuple data and the corresponding tuple descriptor information.

pub fn into_trigger_datum(self) -> Option<Datum>

Consume this PgHeapTuple and return a Datum representation appropriate for returning from a trigger function

pub fn into_pg(self) -> *mut HeapTupleData

Consumes this PgHeapTuple, returning a pointer to a pg_sys::HeapTupleData that can be passed to a Postgres FFI function. It’ll be freed whenever Postgres frees the MemoryContext in which it was allocated.

pub fn len(&self) -> usize

Returns the number of attributes in this PgHeapTuple.

pub fn attributes( &'a self, ) -> impl Iterator<Item = (NonZero<usize>, &'a FormData_pg_attribute)>

Returns an iterator over the attributes in this PgHeapTuple.

The return value is (attribute_number: NonZeroUsize, attribute_info: &pg_sys::FormData_pg_attribute).

pub fn get_attribute_by_index( &'a self, index: NonZero<usize>, ) -> Option<&'a FormData_pg_attribute>

Get the attribute information for the specified attribute number.

Returns None if the attribute number is out of bounds.

pub fn get_attribute_by_name( &'a self, name: &str, ) -> Option<(NonZero<usize>, &'a FormData_pg_attribute)>

Get the attribute information for the specified attribute, by name.

Returns None if the attribute name is not found.

pub fn get_by_name<T>( &self, attname: &str, ) -> Result<Option<T>, TryFromDatumError>

where T: FromDatum + IntoDatum + 'static,

Retrieve the value of the specified attribute, by name.

Attribute names are case-insensitive.

Errors

• return TryFromDatumError::NoSuchAttributeName if the attribute does not exist
• return TryFromDatumError::IncompatibleTypes if the Rust type of the value is not compatible with the attribute’s Postgres type

pub fn get_by_index<T>( &self, attno: NonZero<usize>, ) -> Result<Option<T>, TryFromDatumError>

where T: FromDatum + IntoDatum + 'static,

Retrieve the value of the specified attribute, by index.

Attribute numbers start at 1, not 0.

Errors

• return TryFromDatumError::NoSuchAttributeNumber if the attribute does not exist
• return TryFromDatumError::IncompatibleTypes if the Rust type of the value is not compatible with the attribute’s Postgres type

Trait Implementations

impl<'a> FromDatum for PgHeapTuple<'a, AllocatedByRust>

unsafe fn from_polymorphic_datum( composite: Datum, is_null: bool, _oid: Oid, ) -> Option<PgHeapTuple<'a, AllocatedByRust>>

Like from_datum for instantiating polymorphic types which require preserving the dynamic type metadata.

unsafe fn from_datum_in_memory_context( memory_context: PgMemoryContexts, composite: Datum, is_null: bool, _oid: Oid, ) -> Option<PgHeapTuple<'a, AllocatedByRust>>

where PgHeapTuple<'a, AllocatedByRust>: Sized,

Default implementation switched to the specified memory context and then simply calls FromDatum::from_datum(...) from within that context.

const GET_TYPOID: bool = false

Should a type OID be fetched when calling from_datum?

unsafe fn from_datum(datum: Datum, is_null: bool) -> Option<Self>

where Self: Sized,

Safety

unsafe fn try_from_datum( datum: Datum, is_null: bool, type_oid: Oid, ) -> Result<Option<Self>, TryFromDatumError>

where Self: Sized + IntoDatum,

try_from_datum is a convenience wrapper around FromDatum::from_datum that returns a a Result around an Option, as a Datum can be null. It’s intended to be used in situations where the caller needs to know whether the type conversion succeeded or failed.

unsafe fn try_from_datum_in_memory_context( memory_context: PgMemoryContexts, datum: Datum, is_null: bool, type_oid: Oid, ) -> Result<Option<Self>, TryFromDatumError>

where Self: Sized + IntoDatum,

A version of try_from_datum that switches to the given context to convert from Datum

impl<'a, AllocatedBy> IntoDatum for PgHeapTuple<'a, AllocatedBy>

where AllocatedBy: WhoAllocated,

fn into_datum(self) -> Option<Datum>

fn type_oid() -> Oid

fn composite_type_oid(&self) -> Option<Oid>

fn is_compatible_with(other: Oid) -> bool

Is a Datum of this type compatible with another Postgres type?

fn array_type_oid() -> Oid

impl SqlTranslatable for PgHeapTuple<'static, AllocatedByPostgres>

fn argument_sql() -> Result<SqlMapping, ArgumentError>

fn return_sql() -> Result<Returns, ReturnsError>

fn type_name() -> &'static str

fn variadic() -> bool

fn optional() -> bool

fn entity() -> FunctionMetadataTypeEntity

impl SqlTranslatable for PgHeapTuple<'static, AllocatedByRust>

fn argument_sql() -> Result<SqlMapping, ArgumentError>

fn return_sql() -> Result<Returns, ReturnsError>

fn type_name() -> &'static str

fn variadic() -> bool

fn optional() -> bool

fn entity() -> FunctionMetadataTypeEntity