Documenting inlining SQL functions

On Friday, July 18, 2025, Maciek Sakrejda <maciek(at)pganalyze(dot)com> wrote:

> +1, I think this is very nice to have. I knew about inlining, but not
> the details of the mechanism, so it's nice to see when I should expect
> it to happen.

+1 as well.

>
> I have some minor wording feedback:
>
> + And if an extension has hooked function entry/exit,
> + then inlining must be skipped.
>
> Maybe "And if any extension has hooked function entry/exit, then
> inlining will be skipped." for clarity?

Would like to avoid passive voice and not a huge fan of the location
either. I’d be inclined to add it as a note/caution at the end of the
sect2. Though I’m unsure exactly how these hooks work or what is
possible. I’m guessing something like:

Caution: PostgreSQL provides query-level hooks at function entry and exit
that extension code can tap into. When tapped, the planner will not inline
functions while planning queries.

> + It must return a type that matches the function declaration.
>
> I think this could also be clearer: maybe "It must return a type that
> matches the function declaration exactly (without an implicit cast)"?
> Maybe that's overkill, but when reading the original version, it
> wasn't clear to me why a function would return a type that does not
> match the declaration: wouldn't that be an error? Then I figured out
> you're probably talking about implicit casts.

Doesn’t this requirement preclude “record”, as well as polymorphic
functions?

As for the somewhat lengthy list itself:

If we reject “group by” then rejecting having and aggregate functions is
redundant. Maybe focus less on keywords and just say that concepts are not
allowed. Union/intersect/except already violate “select expression” but
could at least be summed up a SQL SET operators (with a link) if we want
some mention of the feature.

I would suggest two sub-parts for each of the restrictions/requirements:

A function, to qualify for inlining must be defined…e.g., non-strict
Additionally, in the query using the function, (these
limitations/requirements apply)…e.g., values for arguments cannot be
volatile functions

Might be good to put a leading paragraph declaring everything in common to
both (divided into definition and caller), then just note the differences
in the single/multi result specific paragraphs. Should be easier to inject
and recall that two long and only slightly different lists of rules.

+ The hypothetical inlined expression must be no more volatile than
> the original function
> + (so an <literal>IMMUTABLE</literal> function must inline to an
> <literal>IMMUTABLE</literal>
> + expression, and a <literal>STABLE</literal> function must inline to
> <literal>STABLE</literal> or <literal>IMMUTABLE</literal>).
>

> This makes sense, but I don't know how to reason about the volatility
> of an inlined expression. I don't think most users will be able to
> either. Is there a way to clarify that?
>

Kinda feel that such clarification, which is more general than just
inlining, should be explained elsewhere if needed (not sure where).

David J.