public inbox for [email protected]  

help / color / mirror / Atom feed

From: Tom Lane <[email protected]>
To: Chao Li <[email protected]>
Cc: Peter Eisentraut <[email protected]>
Cc: Postgres hackers <[email protected]>
Subject: Re: tablecmds: clarify recurse vs recusing
Date: Tue, 20 Jan 2026 15:07:32 -0500
Message-ID: <[email protected]> (raw)
In-Reply-To: <CAEoWx2=QnOBUCuTg4rt7n0FjyvhBfztWMffSdObGCbGrz2tg6w@mail.gmail.com>
References: <CAEoWx2n9E6_zxPbqwMpaPuC1C_p4b3y635SjiDuCPSVm8GBjsA@mail.gmail.com>
	<[email protected]>
	<[email protected]>
	<CAEoWx2=QnOBUCuTg4rt7n0FjyvhBfztWMffSdObGCbGrz2tg6w@mail.gmail.com>

Chao Li <[email protected]> writes:
> Enhancing the header comments also helps here.
> PSA v2:

I had something more like the attached in mind.  I'm not generally
a fan of documenting only some of the arguments of a function, so
I don't care for the way you handled the issue for other functions
in tablecmds.c either.  We can either assume that people read
ATPrepCmd's comment and can extrapolate to the other functions,
or we can do something similar to this for all of them.

I do agree with your 0002, but I see no point in pushing that
separately.

			regards, tom lane



Attachments:

  [text/x-diff] v3-document-ATPrepCmd-arguments.patch (1.4K, ../[email protected]/2-v3-document-ATPrepCmd-arguments.patch)
  download | inline diff:
diff --git a/src/backend/commands/tablecmds.c b/src/backend/commands/tablecmds.c
index f976c0e5c7e..fcdb81dd4ea 100644
--- a/src/backend/commands/tablecmds.c
+++ b/src/backend/commands/tablecmds.c
@@ -4901,8 +4901,22 @@ ATController(AlterTableStmt *parsetree,
  * Traffic cop for ALTER TABLE Phase 1 operations, including simple
  * recursion and permission checks.
  *
- * Caller must have acquired appropriate lock type on relation already.
+ * *wqueue: resulting AlteredTableInfo structs are added to this list
+ * rel: the relation we are currently considering
+ * cmd: the ALTER TABLE subcommand we are currently considering
+ * recurse: true to recurse to child tables of rel (including partitions)
+ * recursing: true if already recursing (rel is a descendant of original table)
+ * lockmode: lock level held on rel, and to be acquired on children
+ * context: context passed down from ProcessUtility, or NULL if none
+ *
+ * At top level, recurse is true unless the command specified ONLY.
+ * Internally, it can be true if we are descending the inheritance tree
+ * on-the-fly, or false if we already expanded the tree at an outer level
+ * (see ATSimpleRecursion).
+ *
+ * Caller must have acquired lockmode on rel already.
  * This lock should be held until commit.
+ * If we recurse, the same lockmode will be acquired on child tables.
  */
 static void
 ATPrepCmd(List **wqueue, Relation rel, AlterTableCmd *cmd,

view thread (4+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected], [email protected]
  Subject: Re: tablecmds: clarify recurse vs recusing
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox