Thread

Re: pg_dump --no-comments confusion

Erik Wienhold <ewie@ewie.name> — 2024-11-04T16:24:34Z

On 2024-11-04 16:13 +0100, Matthias van de Meent wrote:
> On Mon, 4 Nov 2024 at 15:41, Bruce Momjian <bruce@momjian.us> wrote:
> >
> > Someone emailed me privately saying they were confused because they
> > thought pg_dump --no-comments would remove SQL comments, not the SQL
> > COMMENT commands.  Is this something worth clarifying in our docs?  I am
> > not even sure how I would express it.  It currently says:
> >
> >        --no-comments
> >            Do not dump comments.
> >
> > We could change it to:
> >
> >        --no-comments
> >            Do not dump SQL COMMENT commands
> 
> I think that'd be more confusing, as SQL comments are /* */. There is
> no SQL standard-prescribed COMMENT command (if our current docs are to
> be believed, I don't  have a recent version of ISO 9075 to verify that
> claim).

I think Bruce's suggestion is pretty clear that it does not mean line or
block comments, but rather the COMMENT command.  But I also think that
"SQL" in front of the command name is unnecessary because the man page
uses the "FOOBAR command" form throughout, e.g.:

    --inserts
        Dump data as INSERT commands [...]

Also, it doesn't really matter whether COMMENT is standard SQL.  I guess
the sole purpose of --no-comment is to make the dump more portable.  But
we don't mention that use case at all right now which would also apply
to --no-{publications,security-labels,subscriptions}.

> Maybe: "Do not dump database object comments",

I think that would be confusing because --verbose already reads "output
detailed object comments" which are in fact line comments.

-- 
Erik