How pgrust Implements Table Partitioning: PostgreSQL Architecture Ported to Rust

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, 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.

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 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 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.

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. 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:

// 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 convert SQL statements into internal PartitionBoundSpec nodes.
• Runtime seams like RelationGetPartitionKey in relcache_seams.rs bridge Rust code with PostgreSQL catalog structures.
• Planner functions in 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, 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 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), 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}