# How the Catalog System Functions in the pgrust Project: A Technical Deep Dive

> Explore the pgrust catalog system's Rust implementation of PostgreSQL's system-catalog. Learn about OID lookups, MVCC snapshot management, and runtime catalog-driven dispatch.

- Repository: [Michael Malis/pgrust](https://github.com/malisper/pgrust)
- Tags: deep-dive
- Published: 2026-07-13

---

**The pgrust catalog system implements PostgreSQL's system-catalog layer in pure Rust, providing OID lookups, MVCC snapshot management, and runtime catalog-driven dispatch through the `types_catalog` and `snapmgr` crates.**

The pgrust project reimplements PostgreSQL's architecture in Rust, including its essential catalog system that serves as the single source of truth for database metadata. This system manages built-in objects like tables, types, and functions while enabling runtime lookup of relation metadata and OID resolution without relying on hard-coded identifiers.

## Core Catalog Definitions in types_catalog

The foundation of the catalog system resides in the **`_support/types/types_catalog`** crate, which defines Rust modules that mirror PostgreSQL's header files (`catalog/*.h`). In [`crates/_support/types/types_catalog/src/lib.rs`](https://github.com/malisper/pgrust/blob/main/crates/_support/types/types_catalog/src/lib.rs), the crate re-exports a module for each catalog relation:

```rust
// crates/_support/types/types_catalog/src/lib.rs
pub mod catalog;
pub mod catalog_dependency;
pub mod pg_attrdef;
pub mod pg_attribute;
pub mod pg_cast;
pub mod pg_class;
pub mod pg_constraint;
pub mod pg_conversion;
pub mod pg_enum;
pub mod pg_extension;
pub mod pg_proc;
pub mod pg_type;
// ...

```

Each sub-module contains Rust structs that correspond to rows in PostgreSQL catalog tables (e.g., `pg_class`, `pg_type`, `pg_proc`). These definitions follow the same field ordering and types as the original C structs, ensuring binary-compatible access when the runtime reads a catalog snapshot.

## OID Constants and Base Vocabulary in types_core

The **`_support/types/types_core`** crate builds on the catalog vocabulary to provide higher-level constants and utilities. Located in [`crates/_support/types/types_core/src/lib.rs`](https://github.com/malisper/pgrust/blob/main/crates/_support/types/types_core/src/lib.rs), this crate centralizes OID values and command-tag enums that the rest of the codebase imports:

```rust
// crates/_support/types/types_core/src/lib.rs
pub mod catalog;          // re-exports everything from `types_catalog`
pub mod cmdtag;
pub mod fmgr;
pub mod primitive;
pub mod xact;
// ...
pub use catalog::*;
pub use fmgr::*;

```

By centralizing constants like `TYPTYPE_PSEUDO`, `F_OIDEQ`, and `BTREE_AM_OID`, the core crate allows other modules to reference catalog objects without magic numbers. This pattern appears throughout the PL/pgSQL compiler in [`crates/pl/plpgsql/src/comp/src/lib.rs`](https://github.com/malisper/pgrust/blob/main/crates/pl/plpgsql/src/comp/src/lib.rs), which uses these constants during compilation.

## Runtime Catalog Snapshots via snapmgr

Runtime code accesses catalog data through *catalog snapshots*—MVCC-consistent views of the system catalogs produced by backend utilities. The snapshot logic lives in **`backend/utils/time/snapmgr`**:

```rust
// backend/utils/time/snapmgr/src/lib.rs
pub fn get_catalog_snapshot(relid: Oid) -> Result<Snapshot, Error> { … }
pub fn get_non_historic_catalog_snapshot(relid: Oid) -> Result<Snapshot, Error> { … }
pub fn invalidate_catalog_snapshot() { … }

```

These functions support relation caches, syscache lookups, and the PL/pgSQL compiler by fetching the latest catalog state and invalidating stale snapshots when catalog-changing commands execute.

## Catalog-Driven Dispatch for Extensions

Extension modules in pgrust do not embed hard-coded OIDs. Instead, they obtain identifiers from the catalog at runtime through a generic dispatch mechanism. This pattern appears across `contrib/*` crates such as `pg_trgm`, where GiST and GIN op-class implementations read their support functions from the catalog:

```rust
// Example from pg_trgm/src/lib.rs
/// Reached through pgrust's GENERIC, catalog-driven GiST opclass dispatch

```

The dispatch mechanism reads the catalog entry for an op-class, extracts its support functions, and wires them into the Rust implementation. This approach eliminates magic numbers and ensures compatibility with PostgreSQL's catalog structure.

## Heap Access and Catalog Drivers

Heap access code in `backend/access/heap/heapam` uses a dedicated **`catalog_drivers`** module to translate catalog rows into low-level storage parameters. In [`crates/backend/access/heap/heapam/src/lib.rs`](https://github.com/malisper/pgrust/blob/main/crates/backend/access/heap/heapam/src/lib.rs), these drivers read the catalog snapshot to obtain column definitions, type OIDs, and storage options required for heap operations:

```rust
// backend/access/heap/heapam/src/lib.rs
pub mod catalog_drivers;

```

This integration ensures that tuple descriptors and storage parameters remain synchronized with the system catalog state.

## Practical Code Examples

### Looking Up a Type OID

To retrieve the OID of the built-in `text` type from the catalog constants:

```rust
use types_core::catalog::pg_type;

/// Get the OID of the built-in `text` type from the catalog.
fn text_oid() -> Oid {
    // `pg_type` exposes constants generated from the catalog.
    pg_type::TEXT_TYPE_OID
}

```

*Relevant source:* [`crates/_support/types/types_catalog/src/pg_type.rs`](https://github.com/malisper/pgrust/blob/main/crates/_support/types/types_catalog/src/pg_type.rs)

### Fetching a Catalog Snapshot

To retrieve the current MVCC snapshot for a given relation OID:

```rust
use backend::utils::time::snapmgr;

/// Retrieve the current MVCC snapshot for a given relation OID.
fn current_snapshot(relid: Oid) -> Result<Snapshot, Error> {
    snapmgr::get_catalog_snapshot(relid)
}

```

*Relevant source:* [`crates/backend/utils/time/snapmgr/src/lib.rs`](https://github.com/malisper/pgrust/blob/main/crates/backend/utils/time/snapmgr/src/lib.rs)

### Using Catalog-Driven GiST Op-Classes

To build a GiST op-class instance that reads its support functions from the catalog:

```rust
use contrib::pg_trgm::TrgmGist;

/// Build a GiST op-class instance that reads its support functions from the catalog.
let gist = TrgmGist::new_from_catalog();

```

*Relevant source:* [`crates/contrib/pg_trgm/src/gist.rs`](https://github.com/malisper/pgrust/blob/main/crates/contrib/pg_trgm/src/gist.rs)

## Summary

- The **catalog system** resides primarily in `types_catalog` and `types_core` crates, which define binary-compatible structs and OID constants mirroring PostgreSQL's system catalogs.
- **Runtime access** uses MVCC snapshots via functions in `snapmgr`, providing consistent views of catalog data for relation caches and compilers.
- **Extension modules** leverage catalog-driven dispatch rather than hard-coded OIDs, enabling generic GiST/GIN op-class implementations in crates like `pg_trgm`.
- **Heap access layers** translate catalog metadata into storage parameters using the `catalog_drivers` module in `heapam`.

## Frequently Asked Questions

### What is the primary crate for catalog definitions in pgrust?

The **`_support/types/types_catalog`** crate serves as the primary source for catalog definitions. It contains Rust modules like `pg_type`, `pg_class`, and `pg_proc` that structurally mirror PostgreSQL's catalog tables, ensuring binary-compatible access to system catalog data.

### How does pgrust handle runtime catalog lookups?

Runtime code uses the **`snapmgr`** crate to obtain MVCC-consistent catalog snapshots. Functions like `get_catalog_snapshot()` and `invalidate_catalog_snapshot()` manage these views, allowing subsystems to query current metadata while maintaining consistency with concurrent catalog updates.

### Why does pgrust avoid hard-coded OIDs in extension modules?

Extension modules use **catalog-driven dispatch** to obtain OIDs and support function pointers at runtime. This approach eliminates magic numbers, reduces maintenance burden when OIDs change, and ensures that op-class implementations in crates like `pg_trgm` remain compatible with the underlying PostgreSQL catalog structure.

### What role does the catalog_drivers module play in heap access?

The **`catalog_drivers`** module in `backend/access/heap/heapam` translates catalog rows into heap access parameters. It reads column definitions, type OIDs, and storage options from the catalog snapshot to configure tuple descriptors and storage handlers for heap operations.