Subject: tablecmds: clarify recurse vs recusing

From: Chao Li <[email-masked]>
Date: Mon, 19 Jan 2026 15:14:48 +0800

Hi Hacker,

Many ALTER TABLE-related functions take two boolean parameters, "recurse"
and "recursing", whose names are easy to confuse. For example:
```
/*
* ALTER TABLE ALTER COLUMN DROP IDENTITY
*
* Return the address of the affected column.
*/
static ObjectAddress
ATExecDropIdentity(Relation rel, const char *colName, bool missing_ok,
LOCKMODE lockmode,
                   bool recurse, bool recursing)
```

The "recurse" parameter actually indicates whether ONLY was *not* specified
in the ALTER TABLE command. It’s supposed to affect both inherited tables
and partitioned tables.

In contrast, "recursing" is an internal indicator that only affects
inherited tables.

To reduce this confusion, I’m proposing to rename "recurse" to "no_only",
which more directly reflects its meaning.

In this patch set:

* 0001 - only renames “recurse” to “no_only” together with minimum comment
updates.
* 0002 - performs a small mechanical refactoring, replacing “if (no_only)
cmd->no_only = true” to “cmd->no_only = no_only”.

Related patches are [1], [2] and [3]:

[1]
https://postgr.es/m/[email-masked]
[2]
https://postgr.es/m/CAEoWx2=[email-masked]
[3]
https://postgr.es/m/CAEoWx2=SLga-xH09Cq_PAvsHhQHrBK+V0vF821JKgzS=[email-masked]

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/

---

From: Peter Eisentraut <[email-masked]>
Date: Mon, 19 Jan 2026 16:50:01 +0100

On 19.01.26 08:14, Chao Li wrote:
> Many ALTER TABLE-related functions take two boolean parameters, 
> "recurse" and "recursing", whose names are easy to confuse.

I'm not bothered by this.

> To reduce this confusion, I’m proposing to rename "recurse" to 
> "no_only", which more directly reflects its meaning.

This seems worse.  Especially since no_only is almost a double negative.

---

From: Tom Lane <[email-masked]>
Date: Mon, 19 Jan 2026 11:14:40 -0500

> This seems worse.  Especially since no_only is almost a double negative.

Yeah, I don't find this change an improvement either.  I think the
actual problem here is lack of documentation: unlike many other
places, there is next to zero commentary in tablecmds.c about what
all the function parameters are.  It would probably help to define
these, along the lines of

 *  recurse: true if we should recurse to children of this table
 *  recursing: true if we are already recursing from some parent table

If we fleshed out the header comment for ATPrepCmd and maybe a few
other key functions along these lines, that would make the logic
a good deal more intelligible, I think.

			regards, tom lane

---

From: Chao Li <[email-masked]>
Date: Tue, 20 Jan 2026 11:45:50 +0800

On Jan 20, 2026, at 00:14, Tom Lane <[email-masked]> wrote:

regards, tom lane

Enhancing the header comments also helps here.

PSA v2:

0001 - Adds detailed descriptions in the header comments of ATController()
and ATPrepCmd(). For the other 16 functions that take both “recurse” and
“recursing”, I only added brief references to those header comments.

0002 - While working on 0001, I noticed that the header comment of
addFkConstraint() explains all parameters except “is_internal”. I added a
line for “is_internal”, so that the comment fully reflects the function
signature. This change is really trivial and can be squashed into 0001 if
preferred.

Best regards,