Allow Table AMs to Define Their Own Reloptions

Core Problem

PostgreSQL's Table Access Method (TAM) API, introduced in PostgreSQL 12, allows custom storage engines to be plugged in as alternatives to the built-in heap. However, the reloptions infrastructure—the mechanism by which users pass storage-level configuration parameters via WITH (...) clauses—remains hardcoded to heap's options (fillfactor, toast_tuple_target, autovacuum_* parameters, etc.).

This creates a fundamental architectural inconsistency: Index Access Methods have long been able to define their own custom reloptions (via amoptions), but Table Access Methods cannot. Any non-heap TAM is forced to either:

1. Silently accept heap-specific options that are meaningless to it (e.g., fillfactor for a columnar store), or
2. Have no mechanism to expose its own storage-tuning parameters to users.

This gap limits the utility of the TAM API as an extensibility point. Real-world table AMs (like columnar stores, in-memory engines, or append-optimized storage) need their own configuration knobs—compression algorithms, segment sizes, block layouts, etc.—that have no analog in heap.

Proposed Solutions

Julien Tachoires' Patch (v1-v3, March–May 2025)

The primary proposal adds a new TAM routine called relation_options to the TableAmRoutine struct. This callback allows each table AM to provide its own reloptions parser/validator, analogous to how amOptions works for index AMs.

Key design decisions:

1. Breaking change for non-heap TAMs: Once applied, non-heap table AMs no longer inherit heap's reloptions by default. If a custom TAM wants fillfactor or similar settings, it must explicitly define them. This is a clean architectural separation—each AM owns its option namespace entirely.

2. DDL integration with three syntax paths:

   • CREATE TABLE ... USING am WITH (options) — standard creation
   • ALTER TABLE ... SET (options) — modification
   • ALTER TABLE ... SET ACCESS METHOD am OPTIONS (options) — AM migration with option remapping

3. Option lifecycle during AM migration: When switching a table from one AM to another, options from the old AM can be explicitly DROPped (if unsupported by the new AM) or SET to new values. This addresses a real operational concern: what happens to AM-specific metadata when you change storage engines.

4. Test infrastructure: A dummy_table_am test module (modeled on the existing dummy_index_am) provides both regression testing and a reference implementation for TAM authors.

Andrew Dunstan's Fresh Attempt (June 2026)

After the thread went dormant for over a year, Andrew Dunstan posted a new implementation that he developed independently (with AI assistance). He explicitly positions it as being "in line with what we do for Index AMs" and claims it addresses previous objections raised in earlier attempts.

Prior Art and Related Efforts

This problem has been attacked multiple times:

• Jeff Davis' approach (referenced as [1]): An earlier attempt at TAM-specific reloptions.
• SadhuPrasad's patch (referenced as [2]): The direct predecessor to Julien's work.
• Wu Hao's patch (referenced as [3]): Another attempt from the HashData team.
• Nikolay's generic options extension patch (Yura Sokolov's reference): A more general-purpose approach to extending the options infrastructure everywhere, not just for TAMs. This represents a philosophical divergence—targeted TAM-specific solution vs. a generic options framework.

Key Architectural Tensions

Targeted vs. Generic Approach

Yura Sokolov advocates for reviewing Nikolay's more general options-extension patch, arguing that "adding generic way to options extension is better way than targeting specific options." The tension is classic in PostgreSQL development:

• Targeted approach (Julien's): Solves the immediate TAM problem cleanly, mirrors existing index AM pattern, lower risk of unintended consequences.
• Generic approach (Nikolay's): Could solve options extensibility for TAMs, FDWs, and other subsystems simultaneously, but with greater complexity and review burden.

Backward Compatibility for Existing Non-Heap TAMs

Julien's patch deliberately breaks the status quo where non-heap TAMs silently accept heap options. This is architecturally correct (a columnar store shouldn't pretend it has a fillfactor), but it means any existing third-party TAM extensions would need to be updated. The migration path—explicitly re-defining needed options—is clean but represents a compatibility cliff.

Symmetry with Index AM API

The strongest argument for this feature is API symmetry. Index AMs define amOptions to parse their reloptions; the analogous capability for Table AMs is simply missing. Andrew Dunstan's late entry explicitly invokes this parallel, suggesting the community has consensus on the goal but not yet on the implementation.

Status and Outlook

The thread shows a pattern common to features that cross multiple subsystems: multiple independent attempts, no clear champion driving it to commit, and eventual dormancy. The rebases in March and May 2025 show Julien maintaining the patch, but the lack of substantive review from committers is notable. Andrew Dunstan's June 2026 revival (Dunstan being a committer) may provide the momentum needed, though his implementation appears to be a separate effort rather than a continuation of Julien's work.