Struct pgx::heap_tuple::PgHeapTuple
source · pub struct PgHeapTuple<'a, AllocatedBy: WhoAllocated> { /* private fields */ }
Expand description
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.
PgHeapTuple
s 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.
PgHeapTuple
s also describe composite types as defined by pgx::composite_type!()
.
Implementations§
source§impl<'a> PgHeapTuple<'a, AllocatedByPostgres>
impl<'a> PgHeapTuple<'a, AllocatedByPostgres>
sourcepub unsafe fn from_heap_tuple(
tupdesc: PgTupleDesc<'a>,
heap_tuple: HeapTuple
) -> Self
pub unsafe fn from_heap_tuple( tupdesc: PgTupleDesc<'a>, heap_tuple: HeapTuple ) -> Self
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.
sourcepub unsafe fn from_trigger_data(
trigger_data: &'a TriggerData,
which_tuple: TriggerTuple
) -> Option<PgHeapTuple<'a, AllocatedByPostgres>>
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.
sourcepub fn into_owned(self) -> PgHeapTuple<'a, AllocatedByRust>
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.
source§impl<'a> PgHeapTuple<'a, AllocatedByRust>
impl<'a> PgHeapTuple<'a, AllocatedByRust>
sourcepub fn new_composite_type(
type_name: &str
) -> Result<PgHeapTuple<'a, AllocatedByRust>, PgHeapTupleError>
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));
sourcepub fn from_datums<I: IntoIterator<Item = Option<Datum>>>(
tupdesc: PgTupleDesc<'a>,
datums: I
) -> Result<PgHeapTuple<'a, AllocatedByRust>, PgHeapTupleError>
pub fn from_datums<I: IntoIterator<Item = Option<Datum>>>( tupdesc: PgTupleDesc<'a>, datums: I ) -> Result<PgHeapTuple<'a, AllocatedByRust>, PgHeapTupleError>
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.
sourcepub unsafe fn from_composite_datum(composite: Datum) -> Self
pub unsafe fn from_composite_datum(composite: Datum) -> Self
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.
sourcepub fn set_by_name<T: IntoDatum>(
&mut self,
attname: &str,
value: T
) -> Result<(), TryFromDatumError>
pub fn set_by_name<T: IntoDatum>( &mut self, attname: &str, value: T ) -> Result<(), TryFromDatumError>
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
sourcepub fn set_by_index<T: IntoDatum>(
&mut self,
attno: NonZeroUsize,
value: T
) -> Result<(), TryFromDatumError>
pub fn set_by_index<T: IntoDatum>( &mut self, attno: NonZeroUsize, value: T ) -> Result<(), TryFromDatumError>
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
source§impl<'a, AllocatedBy: WhoAllocated> PgHeapTuple<'a, AllocatedBy>
impl<'a, AllocatedBy: WhoAllocated> PgHeapTuple<'a, AllocatedBy>
sourcepub fn into_composite_datum(self) -> Option<Datum>
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.
sourcepub fn into_trigger_datum(self) -> Option<Datum>
pub fn into_trigger_datum(self) -> Option<Datum>
Consume this PgHeapTuple
and return a Datum representation appropriate for returning from
a trigger function
sourcepub fn into_pg(self) -> *mut HeapTupleData
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.
sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the number of attributes in this PgHeapTuple
.
sourcepub fn attributes(
&'a self
) -> impl Iterator<Item = (NonZeroUsize, &'a FormData_pg_attribute)>
pub fn attributes( &'a self ) -> impl Iterator<Item = (NonZeroUsize, &'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)
.
sourcepub fn get_attribute_by_index(
&'a self,
index: NonZeroUsize
) -> Option<&'a FormData_pg_attribute>
pub fn get_attribute_by_index( &'a self, index: NonZeroUsize ) -> Option<&'a FormData_pg_attribute>
Get the attribute information for the specified attribute number.
Returns None
if the attribute number is out of bounds.
sourcepub fn get_attribute_by_name(
&'a self,
name: &str
) -> Option<(NonZeroUsize, &'a FormData_pg_attribute)>
pub fn get_attribute_by_name( &'a self, name: &str ) -> Option<(NonZeroUsize, &'a FormData_pg_attribute)>
Get the attribute information for the specified attribute, by name.
Returns None
if the attribute name is not found.
sourcepub fn get_by_name<T: FromDatum + IntoDatum + 'static>(
&self,
attname: &str
) -> Result<Option<T>, TryFromDatumError>
pub fn get_by_name<T: FromDatum + IntoDatum + 'static>( &self, attname: &str ) -> Result<Option<T>, TryFromDatumError>
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 thevalue
is not compatible with the attribute’s Postgres type
sourcepub fn get_by_index<T: FromDatum + IntoDatum + 'static>(
&self,
attno: NonZeroUsize
) -> Result<Option<T>, TryFromDatumError>
pub fn get_by_index<T: FromDatum + IntoDatum + 'static>( &self, attno: NonZeroUsize ) -> Result<Option<T>, TryFromDatumError>
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 thevalue
is not compatible with the attribute’s Postgres type
Trait Implementations§
source§impl<'a> FromDatum for PgHeapTuple<'a, AllocatedByRust>
impl<'a> FromDatum for PgHeapTuple<'a, AllocatedByRust>
source§unsafe fn from_polymorphic_datum(
composite: Datum,
is_null: bool,
_oid: Oid
) -> Option<Self>
unsafe fn from_polymorphic_datum( composite: Datum, is_null: bool, _oid: Oid ) -> Option<Self>
from_datum
for instantiating polymorphic types
which require preserving the dynamic type metadata. Read moresource§unsafe fn from_datum_in_memory_context(
memory_context: PgMemoryContexts,
composite: Datum,
is_null: bool,
_oid: Oid
) -> Option<Self>where
Self: Sized,
unsafe fn from_datum_in_memory_context( memory_context: PgMemoryContexts, composite: Datum, is_null: bool, _oid: Oid ) -> Option<Self>where Self: Sized,
FromDatum::from_datum(...)
from within that context. Read moresource§const GET_TYPOID: bool = false
const GET_TYPOID: bool = false
from_datum
?source§unsafe fn from_datum(datum: Datum, is_null: bool) -> Option<Self>where
Self: Sized,
unsafe fn from_datum(datum: Datum, is_null: bool) -> Option<Self>where Self: Sized,
source§unsafe fn try_from_datum(
datum: Datum,
is_null: bool,
type_oid: Oid
) -> Result<Option<Self>, TryFromDatumError>where
Self: Sized + IntoDatum,
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. Read moresource§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,
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,
try_from_datum
that switches to the given context to convert from Datumsource§impl<'a, AllocatedBy: WhoAllocated> IntoDatum for PgHeapTuple<'a, AllocatedBy>
impl<'a, AllocatedBy: WhoAllocated> IntoDatum for PgHeapTuple<'a, AllocatedBy>
source§impl SqlTranslatable for PgHeapTuple<'static, AllocatedByPostgres>
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
source§impl SqlTranslatable for PgHeapTuple<'static, AllocatedByRust>
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
Auto Trait Implementations§
impl<'a, AllocatedBy> RefUnwindSafe for PgHeapTuple<'a, AllocatedBy>where AllocatedBy: RefUnwindSafe,
impl<'a, AllocatedBy> !Send for PgHeapTuple<'a, AllocatedBy>
impl<'a, AllocatedBy> !Sync for PgHeapTuple<'a, AllocatedBy>
impl<'a, AllocatedBy> Unpin for PgHeapTuple<'a, AllocatedBy>where AllocatedBy: Unpin,
impl<'a, AllocatedBy> UnwindSafe for PgHeapTuple<'a, AllocatedBy>where AllocatedBy: UnwindSafe,
Blanket Implementations§
§impl<T> Conv for T
impl<T> Conv for T
§impl<T> FmtForward for T
impl<T> FmtForward for T
§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where Self: Binary,
self
to use its Binary
implementation when Debug
-formatted.§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where Self: Display,
self
to use its Display
implementation when
Debug
-formatted.§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where Self: LowerExp,
self
to use its LowerExp
implementation when
Debug
-formatted.§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where Self: LowerHex,
self
to use its LowerHex
implementation when
Debug
-formatted.§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where Self: Octal,
self
to use its Octal
implementation when Debug
-formatted.§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where Self: Pointer,
self
to use its Pointer
implementation when
Debug
-formatted.§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where Self: UpperExp,
self
to use its UpperExp
implementation when
Debug
-formatted.§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where Self: UpperHex,
self
to use its UpperHex
implementation when
Debug
-formatted.§fn fmt_list(self) -> FmtList<Self>where
&'a Self: for<'a> IntoIterator,
fn fmt_list(self) -> FmtList<Self>where &'a Self: for<'a> IntoIterator,
§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere T: ?Sized,
§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere Self: Sized,
§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere R: 'a,
self
and passes that borrow into the pipe function. Read more§fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere R: 'a,
self
and passes that borrow into the pipe function. Read more§fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> Rwhere
Self: Borrow<B>,
B: 'a + ?Sized,
R: 'a,
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> Rwhere Self: Borrow<B>, B: 'a + ?Sized, R: 'a,
§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> Rwhere
Self: BorrowMut<B>,
B: 'a + ?Sized,
R: 'a,
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> Rwhere Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,
§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> Rwhere
Self: AsRef<U>,
U: 'a + ?Sized,
R: 'a,
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> Rwhere Self: AsRef<U>, U: 'a + ?Sized, R: 'a,
self
, then passes self.as_ref()
into the pipe function.§fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> Rwhere
Self: AsMut<U>,
U: 'a + ?Sized,
R: 'a,
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> Rwhere Self: AsMut<U>, U: 'a + ?Sized, R: 'a,
self
, then passes self.as_mut()
into the pipe
function.§impl<T> Tap for T
impl<T> Tap for T
§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Selfwhere
Self: Borrow<B>,
B: ?Sized,
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Selfwhere Self: Borrow<B>, B: ?Sized,
Borrow<B>
of a value. Read more§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere
Self: BorrowMut<B>,
B: ?Sized,
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere Self: BorrowMut<B>, B: ?Sized,
BorrowMut<B>
of a value. Read more§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Selfwhere
Self: AsRef<R>,
R: ?Sized,
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Selfwhere Self: AsRef<R>, R: ?Sized,
AsRef<R>
view of a value. Read more§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere
Self: AsMut<R>,
R: ?Sized,
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere Self: AsMut<R>, R: ?Sized,
AsMut<R>
view of a value. Read more§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Selfwhere
Self: Deref<Target = T>,
T: ?Sized,
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Selfwhere Self: Deref<Target = T>, T: ?Sized,
Deref::Target
of a value. Read more§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Selfwhere
Self: DerefMut<Target = T> + Deref,
T: ?Sized,
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Selfwhere Self: DerefMut<Target = T> + Deref, T: ?Sized,
Deref::Target
of a value. Read more§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap()
only in debug builds, and is erased in release builds.§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut()
only in debug builds, and is erased in release
builds.§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Selfwhere
Self: Borrow<B>,
B: ?Sized,
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Selfwhere Self: Borrow<B>, B: ?Sized,
.tap_borrow()
only in debug builds, and is erased in release
builds.§fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere
Self: BorrowMut<B>,
B: ?Sized,
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Selfwhere Self: BorrowMut<B>, B: ?Sized,
.tap_borrow_mut()
only in debug builds, and is erased in release
builds.§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Selfwhere
Self: AsRef<R>,
R: ?Sized,
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Selfwhere Self: AsRef<R>, R: ?Sized,
.tap_ref()
only in debug builds, and is erased in release
builds.§fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere
Self: AsMut<R>,
R: ?Sized,
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Selfwhere Self: AsMut<R>, R: ?Sized,
.tap_ref_mut()
only in debug builds, and is erased in release
builds.