PgRelation

Namespace: Ankus

Assembly: Ankus.Runtime.dll

Holds a checked PostgreSQL relation cache reference with explicit native ownership and locking.

public sealed class PgRelation : IDisposable

Use on the owning backend thread and dispose before its PostgreSQL resource owner ends. PostgreSQL also reclaims references during statement, portal, or transaction cleanup; later checked access then fails. Metadata is read from the live relation. Copied names and tuple descriptors remain usable after disposal. Garbage collection never calls PostgreSQL. A relation may describe any pg_class object, including an index or sequence.

Inheritance: object

Implements: IDisposable

Methods

Clone()

Reopens the same OID with an independent AccessShare lock and cache reference.

public PgRelation Clone()

Returns: PgRelation

An independently disposable owner.

CountBufferHit()

Counts one buffer hit when relation statistics are enabled.

public void CountBufferHit()

CountBufferRead()

Counts one buffer read when relation statistics are enabled.

public void CountBufferRead()

CountHeapFetch()

Counts one fetched heap tuple when relation statistics are enabled.

public void CountHeapFetch()

CountHeapGetNext()

Counts one tuple returned by heap iteration when relation statistics are enabled.

public void CountHeapGetNext()

CountHeapScan()

Increments PostgreSQL’s heap scan counter when relation statistics are enabled.

public void CountHeapScan()

CountIndexScan()

Increments PostgreSQL’s index scan counter when relation statistics are enabled.

public void CountIndexScan()

CountIndexTuples(long)

Adds a signed count to PostgreSQL’s tuples-returned counter, preserving pgrx’s native counter semantics.

public void CountIndexTuples(long count)

Parameters:

count — long

The signed tuple count.

DangerousAdopt(void*)

Adopts one caller-owned Relation reference without incrementing it; disposal calls RelationClose without unlocking.

public static PgRelation? DangerousAdopt(void* address)

Parameters:

address — void*

A selected-version Relation pointer, or null.

Returns: PgRelation

The exclusive managed owner, or null for a null pointer.

The caller transfers exactly one close obligation registered with the current PostgreSQL resource owner. It must hold appropriate locks and must not independently close or adopt that same reference again. Failed adoption leaves the external close obligation with the caller.

DangerousBorrow(void*)

Borrows a caller-proven live Relation pointer without incrementing or closing its native reference.

public static PgRelation? DangerousBorrow(void* address)

Parameters:

address — void*

A selected-version Relation pointer, or null.

Returns: PgRelation

A checked view, or null for a null pointer.

The caller must preserve the external reference and required locks until disposal or ownership transfer. Its resource owner must be the current PostgreSQL owner. Checks cannot detect an earlier external close.

DangerousGetIndicesWithoutLock()

Opens every attached index without acquiring or releasing locks. The caller must already protect each index.

public IReadOnlyList<PgRelation> DangerousGetIndicesWithoutLock()

Returns: IReadOnlyList<PgRelation>

Independent cache-reference owners; dispose every element when finished.

DangerousGetPointer()

Returns a borrowed selected-version Relation pointer after validating this handle.

public void* DangerousGetPointer()

Returns: void*

The native pointer, valid only while this reference and its required locks remain live.

DangerousOpenHeap()

Opens the index’s owning heap without locking it. The caller must already hold the heap’s required lock.

public PgRelation? DangerousOpenHeap()

Returns: PgRelation

An independent owned heap reference, or null when this relation has no native index metadata.

DangerousOpenWithoutLock(string)

Resolves a name and opens without acquiring a lock. The caller must already protect the resolved relation.

public static PgRelation? DangerousOpenWithoutLock(string name)

Parameters:

name — string

The PostgreSQL relation name or numeric OID syntax.

Returns: PgRelation

An owned cache reference, or null when native to_regclass returns SQL NULL.

DangerousOpenWithoutLock(uint)

Opens without acquiring or later releasing a lock. The caller must already hold at least AccessShare.

public static PgRelation DangerousOpenWithoutLock(uint oid)

Parameters:

oid — uint

The relation OID protected by the caller’s lock.

Returns: PgRelation

An owned cache reference whose disposal only closes that reference.

DangerousTakeOwnership()

Transfers an external borrowed close obligation into an owned wrapper without incrementing the reference.

public PgRelation DangerousTakeOwnership()

Returns: PgRelation

This object when already owned, or a new owner that consumes the borrowed wrapper.

For a borrowed view, the caller must exclusively transfer the external close obligation and never close it again. This operation does not acquire or release an external lock. A failed transfer leaves the borrowed wrapper and external close obligation unchanged.

Dispose()

Releases this wrapper and its owned reference and lock. Borrowed wrappers do not close the external reference. Repeated disposal and disposal after native resource-owner cleanup are harmless on the owning backend thread.

public void Dispose()

GetIndices(PgLockMode)

Eagerly opens every attached index, closing previously opened references if any later open fails.

public IReadOnlyList<PgRelation> GetIndices(PgLockMode lockMode = PgLockMode.AccessShare)

Parameters:

lockMode — PgLockMode

The lock to acquire separately for each index.

Returns: IReadOnlyList<PgRelation>

A read-only list of independent owners; dispose every element when finished.

Open(string, PgLockMode)

Resolves a relation using native regclass syntax and search-path rules, then opens and locks it.

public static PgRelation Open(string name, PgLockMode lockMode = PgLockMode.AccessShare)

Parameters:

name — string

The PostgreSQL relation name or numeric OID syntax.

lockMode — PgLockMode

The required lock, defaulting to AccessShare.

Returns: PgRelation

An independently disposable reference. Missing names raise a PostgreSQL error.

Open(uint, PgLockMode)

Opens a relation by its exact OID and acquires the requested lock. Disposal releases this lock acquisition. Automatic resource cleanup follows PostgreSQL’s transaction lock rules.

public static PgRelation Open(uint oid, PgLockMode lockMode = PgLockMode.AccessShare)

Parameters:

oid — uint

The relation OID; nonexistent OIDs raise a PostgreSQL error.

lockMode — PgLockMode

The required lock, defaulting to AccessShare. None is not accepted.

Returns: PgRelation

An independently disposable relation reference.

ToDatum(PgMemoryContext)

Copies the relation OID into an explicitly context-bound regclass datum without transferring this reference.

public PgDatum ToDatum(PgMemoryContext context)

Parameters:

context — PgMemoryContext

The datum’s lifetime anchor.

Returns: PgDatum

A checked, nonnull regclass datum with the exact relation identity.

TryOpen(string, PgLockMode)

Resolves and opens a relation, returning null when native to_regclass returns SQL NULL.

public static PgRelation? TryOpen(string name, PgLockMode lockMode = PgLockMode.AccessShare)

Parameters:

name — string

The PostgreSQL relation name or numeric OID syntax.

lockMode — PgLockMode

The required lock, defaulting to AccessShare.

Returns: PgRelation

The owned reference or null. Lock, permission, and concurrent-deletion errors still propagate.

Properties

EstimatedTupleCount

Gets the native reltuples estimate, mapping exactly zero to null as pgrx does and preserving minus one.

public float? EstimatedTupleCount { get; }

Value: float?

IsCompositeType

Gets whether this describes a standalone composite type.

public bool IsCompositeType { get; }

Value: bool

IsForeignTable

Gets whether this is a foreign table.

public bool IsForeignTable { get; }

Value: bool

IsIndex

Gets whether this is an ordinary index. A partitioned index has kind I instead.

public bool IsIndex { get; }

Value: bool

IsMaterializedView

Gets whether this is a materialized view.

public bool IsMaterializedView { get; }

Value: bool

IsPartitionedTable

Gets whether this is a partitioned table.

public bool IsPartitionedTable { get; }

Value: bool

IsSequence

Gets whether this is a sequence.

public bool IsSequence { get; }

Value: bool

IsTable

Gets whether this is an ordinary table, including an ordinary table used as a partition.

public bool IsTable { get; }

Value: bool

IsToast

Gets whether this is a TOAST table.

public bool IsToast { get; }

Value: bool

IsView

Gets whether this is a view.

public bool IsView { get; }

Value: bool

Kind

Gets the exact PostgreSQL relkind character, including kinds without a convenience predicate.

public char Kind { get; }

Value: char

Name

Gets a copy of the relation’s current unqualified name.

public string Name { get; }

Value: string

NamespaceName

Gets a copy of the current namespace name.

public string NamespaceName { get; }

Value: string

NamespaceOid

Gets the current namespace OID.

public uint NamespaceOid { get; }

Value: uint

Oid

Gets the exact relation OID, distinct from its row type OID.

public uint Oid { get; }

Value: uint

TupleDescriptor

Gets an owned copy of the actual relation descriptor, including physical dropped slots and index columns. A descriptor without a native row type retains a zero type OID and cannot construct typed values.

public PgTupleDescriptor TupleDescriptor { get; }

Value: PgTupleDescriptor