# How pgrust Implements Table Partitioning: PostgreSQL Architecture Ported to Rust

> Explore how pgrust implements table partitioning using a Rust architecture. Learn about its layered approach to DDL parsing caching metadata and optimizing queries with runtime constraint validation.

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

---

**pgrust reimplements PostgreSQL's native table partitioning through a layered Rust architecture that parses DDL commands, caches partition metadata via runtime seams, and optimizes queries using partition-aware planner structures, all while validating hash constraints at runtime with a pure-Rust `satisfies_hash_partition` function.**

The pgrust project reproduces PostgreSQL’s core engine—including its sophisticated table partitioning system—entirely in Rust. By carving the C implementation into distinct crates for parsing, catalog caching, and query planning, the codebase demonstrates how pgrust implements table partitioning while maintaining binary compatibility with PostgreSQL’s system catalogs. This analysis explores the specific source files, function implementations, and runtime mechanisms that enable hash, range, and list partitioning strategies.

## Parsing Partition DDL Commands

Partitioning support begins in the SQL parser, where `CREATE TABLE ... PARTITION BY` and `ATTACH PARTITION` statements are transformed into internal representation nodes.

In [`crates/backend/parser/parse_utilcmd/src/partition.rs`](https://github.com/malisper/pgrust/blob/main/crates/backend/parser/parse_utilcmd/src/partition.rs), the entry points `transformPartitionCmd` and `transformPartitionBound` handle this transformation. When processing a partition command, `transformPartitionCmd` dispatches based on the parent relation's `relkind` (e.g., `RELKIND_PARTITIONED_TABLE` or `RELKIND_PARTITIONED_INDEX`). If the statement includes a `FOR VALUES` clause, the code invokes `transformPartitionBound` to construct a `PartitionBoundSpec` node, storing the result in `CreateStmtContext.partbound` for downstream processing.

## Catalog and Cache Access via relcache Seams

Once parsed, partition metadata must be retrieved from PostgreSQL's system catalogs. pgrust exposes this functionality through runtime-registered function pointers called *seams*, defined in [`crates/backend/utils/cache/relcache/src/relcache_seams.rs`](https://github.com/malisper/pgrust/blob/main/crates/backend/utils/cache/relcache/src/relcache_seams.rs).

Key seam functions include:

- **`RelationGetPartitionKey`** – Retrieves the `PartitionKeyData` struct for a relation, containing the partitioning strategy (Hash, Range, or List), column OIDs, operator families, collations, and support functions (`partsupfunc`).
- **`RelationGetPartitionQual`** – Returns the partition qualification expressions used for runtime constraint checking.

The `PartitionKeyData` structure mirrors PostgreSQL's C definition, enabling the planner to understand which columns define the partition key and which hash or comparison functions to apply. An additional in-memory cache in [`crates/backend/utils/cache/partcache/src/lib.rs`](https://github.com/malisper/pgrust/blob/main/crates/backend/utils/cache/partcache/src/lib.rs) manages these descriptors to avoid repeated catalog lookups during query planning.

## Planner Integration: Partition Schemes and Pruning

During query optimization, pgrust populates internal planner structures that enable partition pruning and partition-wise joins. The orchestration occurs in [`crates/backend/optimizer/plan/planner/src/partition_info.rs`](https://github.com/malisper/pgrust/blob/main/crates/backend/optimizer/plan/planner/src/partition_info.rs) through the function `set_relation_partition_info`.

This function executes several critical steps:

1. Opens the parent relation using `relation_open` with an access-share lock.
2. Fetches the `PartitionKeyData` and the partition directory (metadata for all child partitions).
3. Constructs a `PartitionScheme` via `find_partition_scheme`, encapsulating the strategy, column types, and support functions.
4. Populates the `RelOptInfo` structure with `part_scheme`, `boundinfo`, `partexprs`, and `partition_qual` via calls to `set_baserel_partition_key_exprs` and `set_baserel_partition_constraint`.

The resulting `PartitionScheme` enables the planner to eliminate irrelevant partitions when `enable_partition_pruning` is active, and to generate partition-wise joins or aggregates when enabled through configuration variables.

## Runtime Hash Partition Validation

For hash-partitioned tables, PostgreSQL defines a hidden CHECK constraint that verifies rows match their partition's hash modulus and remainder. pgrust implements this logic in pure Rust within [`crates/backend/partitioning/partbounds/src/satisfies_hash_partition.rs`](https://github.com/malisper/pgrust/blob/main/crates/backend/partitioning/partbounds/src/satisfies_hash_partition.rs).

The `body` function (implementing `satisfies_hash_partition`) performs the following operations:

- Validates three fixed arguments: parent OID, modulus, and remainder.
- Opens the parent relation and confirms the partitioning strategy is Hash.
- Hashes supplied column values using the strategy-specific support function (`partsupfunc`), combining results with `hash_combine64`.
- Returns `true` only if `row_hash % modulus == remainder`.

Registered as a non-strict builtin (`strict: false`), this function explicitly handles NULL inputs by returning `false`, ensuring rows with NULL partition keys are rejected.

## Configuring Partition Behavior with GUC Variables

Partitioning behavior is controlled through Grand Unified Configuration (GUC) variables defined in [`crates/backend/utils/misc/guc_tables/src/vars.rs`](https://github.com/malisper/pgrust/blob/main/crates/backend/utils/misc/guc_tables/src/vars.rs). These settings allow administrators to enable or disable specific optimizations:

- **`enable_partition_pruning`** – Allows the planner to skip partitions that cannot satisfy query predicates.
- **`enable_partitionwise_join`** – Permits joins between partitioned tables to be executed partition-by-partition.
- **`enable_partitionwise_aggregate`** – Enables aggregation to be performed per partition before final combination.

## Practical Example: Creating and Querying Partitioned Tables

The following example demonstrates how pgrust handles the complete lifecycle of a hash-partitioned table:

```rust
// Create a hash-partitioned table
let sql = r#"
    CREATE TABLE orders (
        order_id   bigint,
        cust_id    bigint,
        order_ts   timestamp
    ) PARTITION BY HASH (cust_id);
"#;
pg_client.execute(sql, &[])?;

// Attach a specific partition remainder
let sql = r#"
    CREATE TABLE orders_0 PARTITION OF orders
        FOR VALUES WITH (MODULUS 4, REMAINDER 0);
"#;
pg_client.execute(sql, &[])?;

// Insert a row - executor calls satisfies_hash_partition internally
pg_client.execute(
    "INSERT INTO orders (order_id, cust_id, order_ts) VALUES (1, 42, now())",
    &[],
)?;

// Enable partition pruning for optimal planning
pg_client.execute("SET enable_partition_pruning TO on;", &[])?;

```

When the insert executes, pgrust evaluates `rel->partition_qual`, invoking `satisfies_hash_partition` to verify that the row's `cust_id` hashes to remainder 0 before routing the tuple to the `orders_0` partition.

## Summary

- **pgrust implements table partitioning** through a three-layer architecture spanning DDL parsing, catalog caching, and planner optimization.
- **Parser functions** `transformPartitionCmd` and `transformPartitionBound` in [`crates/backend/parser/parse_utilcmd/src/partition.rs`](https://github.com/malisper/pgrust/blob/main/crates/backend/parser/parse_utilcmd/src/partition.rs) convert SQL statements into internal `PartitionBoundSpec` nodes.
- **Runtime seams** like `RelationGetPartitionKey` in [`relcache_seams.rs`](https://github.com/malisper/pgrust/blob/main/relcache_seams.rs) bridge Rust code with PostgreSQL catalog structures.
- **Planner functions** in [`partition_info.rs`](https://github.com/malisper/pgrust/blob/main/partition_info.rs) construct `PartitionScheme` and `RelOptInfo` metadata to enable pruning and partition-wise operations.
- **Hash validation** occurs through the Rust-native `satisfies_hash_partition` function in [`satisfies_hash_partition.rs`](https://github.com/malisper/pgrust/blob/main/satisfies_hash_partition.rs), ensuring rows match their designated partitions' constraints.

## Frequently Asked Questions

### How does pgrust handle different partitioning strategies?

pgrust supports Hash, Range, and List partitioning strategies as defined in the `PartitionKeyData` structure. The strategy type determines which support functions are loaded from `pg_partitioned_table` and how bound specifications are interpreted during planning and execution.

### What role do "seams" play in pgrust's partitioning implementation?

Seams are runtime-registered function pointers that allow pgrust's Rust code to interoperate with PostgreSQL's C-based catalog access methods. Functions like `RelationGetPartitionKey` and `RelationGetPartitionQual` in [`relcache_seams.rs`](https://github.com/malisper/pgrust/blob/main/relcache_seams.rs) provide safe Rust wrappers around catalog lookups, enabling the planner to retrieve partition metadata without direct C struct manipulation.

### How is partition pruning implemented in the pgrust planner?

During the planning phase, `set_relation_partition_info` populates `RelOptInfo` with partition constraints. When `enable_partition_pruning` is active (controlled via GUC variables in [`vars.rs`](https://github.com/malisper/pgrust/blob/main/vars.rs)), the optimizer eliminates child partitions whose bounds cannot satisfy the query's `WHERE` clause predicates, reducing I/O for partitioned table scans.

### Where does pgrust validate that rows belong to their hash partitions?

Runtime validation occurs in [`crates/backend/partitioning/partbounds/src/satisfies_hash_partition.rs`](https://github.com/malisper/pgrust/blob/main/crates/backend/partitioning/partbounds/src/satisfies_hash_partition.rs). When tuples are inserted, the executor evaluates the `partition_qual` check constraint, which invokes the `satisfies_hash_partition` function to compute the hash of partition key columns and verify the result matches the partition's defined modulus and remainder.