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

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

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