Struct pgrx::tupdesc::PgTupleDesc

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

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.

PGRX’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 unsafe fn from_pg_unchecked<'b>(ptr: TupleDesc) -> PgTupleDesc<'b>

Wrap a Postgres-provided pg_sys::TupleDescData.

The wrapped TupleDesc will not 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

pub unsafe 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

Safety

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

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

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

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

Examples

use pgrx::{pg_sys, PgTupleDesc};
let typid = example_pg_type_oid(42); // a valid pg_type Oid
let typmod = 0; // its 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 fn for_composite_type(name: &str) -> Option<PgTupleDesc<'a>>

Retrieve the tuple description of the shape of a defined composite type

use pgrx::{prelude::*, PgTupleDesc};

Spi::run("CREATE TYPE Dog AS (name text, age int);").unwrap();
let tuple_desc = PgTupleDesc::for_composite_type("Dog").unwrap();
let natts = tuple_desc.len();

unsafe {
    let mut is_null = (0..natts).map(|_| true).collect::<Vec<_>>();

    let heap_tuple_data =
        pg_sys::heap_form_tuple(tuple_desc.as_ptr(), std::ptr::null_mut(), is_null.as_mut_ptr());

    let heap_tuple = PgHeapTuple::from_heap_tuple(
        tuple_desc,
        heap_tuple_data,
    );
}

pub fn for_composite_type_by_oid(typoid: Oid) -> Option<PgTupleDesc<'a>>

Similar to PgTupleDesc::for_composite_type() but using the type’s pg_sys::Oid instead of its name.

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 iter(&self) -> TupleDescIterator<'_>

Iterate over our attributes

pub fn into_pg(self) -> *mut TupleDescData

Convert this PgTupleDesc into a pointer for passing into Postgres. You are responsible for releasing or freeing the returned pg_sys::TupleDescData pointer.

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> Clone for PgTupleDesc<'a>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

type Target = PgBox<TupleDescData, AllocatedByPostgres>

The resulting type after dereferencing.

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

Dereferences the value.

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

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?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.