Struct pgx::tupdesc::PgTupleDesc

pub struct PgTupleDesc<'a> { /* fields omitted */ }

This struct is passed around within the backend to describe the structure of tuples. For tuples coming from on-disk relations, the information is collected from the pg_attribute, pg_attrdef, and pg_constraint catalogs. Transient row types (such as the result of a join query) have anonymous TupleDesc structs that generally omit any constraint info; therefore the structure is designed to let the constraints be omitted efficiently.

Note that only user attributes, not system attributes, are mentioned in TupleDesc; with the exception that tdhasoid indicates if OID is present.

If the tupdesc is known to correspond to a named rowtype (such as a table's rowtype) then tdtypeid identifies that type and tdtypmod is -1. Otherwise tdtypeid is RECORDOID, and tdtypmod can be either -1 for a fully anonymous row type, or a value >= 0 to allow the rowtype to be looked up in the typcache.c type cache.

Note that tdtypeid is never the OID of a domain over composite, even if we are dealing with values that are known (at some higher level) to be of a domain-over-composite type. This is because tdtypeid/tdtypmod need to match up with the type labeling of composite Datums, and those are never explicitly marked as being of a domain type, either.

Tuple descriptors that live in caches (relcache or typcache, at present) are reference-counted: they can be deleted when their reference count goes to zero. Tuple descriptors created by the executor need no reference counting, however: they are simply created in the appropriate memory context and go away when the context is freed. We set the tdrefcount field of such a descriptor to -1, while reference-counted descriptors always have tdrefcount >= 0.

PGX's safe wrapper takes care of properly freeing or decrementing reference counts

Implementations

impl<'a> PgTupleDesc<'a>

pub unsafe fn from_pg<'b>(ptr: TupleDesc) -> PgTupleDesc<'b>

Wrap a Postgres-provided pg_sys::TupleDescData. It is assumed the provided TupleDesc is reference counted by Postgres.

The wrapped TupleDesc will have its reference count decremented when this PgTupleDesc instance is dropped.

Safety

This method is unsafe as we cannot validate that the provided pg_sys::TupleDesc is valid or requires reference counting.

pub fn from_pg_copy<'b>(ptr: TupleDesc) -> PgTupleDesc<'b>

Wrap a copy of a pg_sys::TupleDesc. This form is not reference counted and the copy is allocated in the CurrentMemoryContext

When this instance is dropped, the copied TupleDesc is pfree()'d

pub unsafe fn from_pg_is_copy<'b>(ptr: TupleDesc) -> PgTupleDesc<'b>

Similar to ::from_pg_copy(), but assumes the provided TupleDesc is already a copy.

When this instance is dropped, the TupleDesc is pfree()'d

Examples

use pgx::{pg_sys, PgTupleDesc};
let typid = 42 as pg_sys::Oid;  // a valid pg_type "oid" value
let typmod = 0; // it's corresponding typemod value
let tupdesc = unsafe { PgTupleDesc::from_pg_is_copy(pg_sys::lookup_rowtype_tupdesc_copy(typid, typmod)) };

// assert the tuple descriptor has 12 attributes
assert_eq!(tupdesc.len(), 12);

// the wrapped tupdesc pointer is pfree'd
drop(tupdesc)

Safety

This method is unsafe as we cannot validate that the provided pg_sys::TupleDesc is valid or is actually a copy that requires a pfree() on Drop.

pub fn from_relation(parent: &PgRelation) -> PgTupleDesc<'_>

wrap the pg_sys::TupleDesc contained by the specified PgRelation

pub unsafe fn from_composite(composite: Datum) -> Self

create a PgTupleDesc from a composite pg_sys::Datum, also tracking the backing HeapTupleData so its attribute values can get retrieved via the get_attr() function.

Safety

This function is unsafe as it cannot guarantee that the provided pg_sys::Datum actually points to a composite type

pub fn parent(&self) -> Option<&PgRelation>

From which relation was this TupleDesc created, if any?

pub fn oid(&self) -> Oid

What is the pg_type oid of this TupleDesc?

pub fn typmod(&self) -> i32

What is the typemod of this TupleDesc?

pub fn len(&self) -> usize

How many attributes do we have?

pub fn is_empty(&self) -> bool

Do we have attributes?

pub fn get(&self, i: usize) -> Option<&FormData_pg_attribute>

Get a numbered attribute. Attribute numbers are zero-based

pub fn get_attr<T: FromDatum>(&self, attno: usize) -> Option<T>

Get a typed attribute Datum from the backing composite data.

This is only possible for PgTupleDesc created with from_composite().

The attno argument is zero-based

pub fn iter(&self) -> TupleDescIterator<'_>

Iterate over our attributes

Methods from Deref<Target = PgBox<TupleDescData>>

pub fn is_null(&self) -> bool

Are we boxing a NULL?

pub fn as_ptr(&self) -> *mut T

Return the boxed pointer, so that it can be passed back into a Postgres function

Trait Implementations

impl<'a> Deref for PgTupleDesc<'a>

type Target = PgBox<TupleDescData>

The resulting type after dereferencing.

pub fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a> Drop for PgTupleDesc<'a>

pub fn drop(&mut self)

Executes the destructor for this type.

impl<'a> IntoIterator for PgTupleDesc<'a>

type Item = FormData_pg_attribute

The type of the elements being iterated over.

type IntoIter = TupleDescDataIntoIterator<'a>

Which kind of iterator are we turning this into?

pub fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.