Struct PgRelation

pub struct PgRelation { /* private fields */ }

Implementations

impl PgRelation

pub unsafe fn from_pg(ptr: Relation) -> Self

Wrap a Postgres-provided pg_sys::Relation.

It is assumed that Postgres will later RelationClose() the provided relation pointer. As such, it is not closed when this instance is dropped

Safety

This method is unsafe as we cannot ensure that this relation will later be closed by Postgres

pub unsafe fn from_pg_owned(ptr: Relation) -> Self

Wrap a Postgres-provided pg_sys::Relation.

The provided Relation will be closed via pg_sys::RelationClose when this instance is dropped

pub unsafe fn open(oid: Oid) -> Self

Given a relation oid, use pg_sys::RelationIdGetRelation() to open the relation

If the specified relation oid was recently deleted, this function will panic.

Additionally, the relation is closed via pg_sys::RelationClose() when this instance is dropped.

Safety

The caller should already have at least AccessShareLock on the relation ID, else there are nasty race conditions.

As such, this function is unsafe as we cannot guarantee that this requirement is true.

pub unsafe fn with_lock(oid: Oid, lockmode: LOCKMODE) -> Self

relation_open - open any relation by relation OID

If lockmode is not “NoLock”, the specified kind of lock is obtained on the relation.

An error is raised if the relation does not exist.

Safety

Using an inappropriate lockmode, such as using NoLock on a relation that has not been previously locked, may result in undefined behavior.

NB: a “relation” is anything with a pg_class entry. The caller is expected to check whether the relkind is something it can handle.

The opened relation is automatically closed via pg_sys::relation_close() when this instance is dropped

pub unsafe fn open_with_name(relname: &str) -> Result<Self, &'static str>

Given a relation name, use pg_sys::to_regclass to look up its oid, and then pg_sys::RelationIdGetRelation() to open the relation.

If the specified relation name is not found, we return an Err(&str).

If the specified relation was recently deleted, this function will panic.

Additionally, the relation is closed via pg_sys::RelationClose() when this instance is dropped.

Safety

The caller should already have at least AccessShareLock on the relation ID, else there are nasty race conditions.

As such, this function is unsafe as we cannot guarantee that this requirement is true.

pub fn open_with_name_and_share_lock( relname: &str, ) -> Result<Self, &'static str>

Given a relation name, use pg_sys::to_regclass to look up its oid, and then open it with an AccessShareLock

If the specified relation name is not found, we return an Err(&str).

If the specified relation was recently deleted, this function will panic.

Additionally, the relation is closed via pg_sys::RelationClose() when this instance is dropped.

pub fn name(&self) -> &str

RelationGetRelationName Returns the rel’s name.

Note that the name is only unique within the containing namespace.

pub fn oid(&self) -> Oid

RelationGetRelid Returns the OID of the relation

pub fn namespace_oid(&self) -> Oid

RelationGetNamespace Returns the rel’s namespace OID.

pub fn namespace(&self) -> &str

What is the name of the namespace in which this relation is located?

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

If this PgRelation represents an index, return the PgRelation for the heap relation to which it is attached

pub fn indices(&self, lockmode: LOCKMODE) -> impl Iterator<Item = PgRelation>

Return an iterator of indices, as PgRelations, attached to this relation

pub fn tuple_desc(&self) -> PgTupleDesc<'_>

Returned a wrapped PgTupleDesc

The returned PgTupleDesc is tied to the lifetime of this PgRelation instance.

use pgx::{PgRelation, pg_sys};
let oid = example_pg_class_oid(42); // a valid pg_class "oid" value
let relation = unsafe { PgRelation::from_pg(pg_sys::RelationIdGetRelation(oid) ) };
let tupdesc = relation.tuple_desc();

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

pub fn reltuples(&self) -> Option<f32>

Number of tuples in this relation (not always up-to-date)

pub fn is_table(&self) -> bool

pub fn is_matview(&self) -> bool

pub fn is_index(&self) -> bool

pub fn is_view(&self) -> bool

pub fn is_sequence(&self) -> bool

pub fn is_composite_type(&self) -> bool

pub fn is_foreign_table(&self) -> bool

pub fn is_partitioned_table(&self) -> bool

pub fn is_toast_value(&self) -> bool

pub fn to_owned(self) -> Self

ensures that the returned PgRelation is closed by Rust when it is dropped

Methods from Deref<Target = PgBox<RelationData>>

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 Clone for PgRelation

fn clone(&self) -> Self

Same as calling PgRelation::with_lock(AccessShareLock) on the underlying relation id

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

Performs copy-assignment from source.

impl Deref for PgRelation

type Target = PgBox<RelationData>

The resulting type after dereferencing.

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

Dereferences the value.

impl Drop for PgRelation

fn drop(&mut self)

Executes the destructor for this type.

impl FromDatum for PgRelation

unsafe fn from_polymorphic_datum( datum: Datum, is_null: bool, _typoid: Oid, ) -> Option<PgRelation>

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

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 from_datum_in_memory_context( memory_context: PgMemoryContexts, datum: Datum, is_null: bool, typoid: Oid, ) -> Option<Self>

where Self: Sized,

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

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 IntoDatum for PgRelation

fn into_datum(self) -> Option<Datum>

fn type_oid() -> Oid

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

fn array_type_oid() -> Oid

fn is_compatible_with(other: Oid) -> bool

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

impl SqlTranslatable for PgRelation

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