Document reopen of output file via SIGHUP in pg_recvlogical
Hi, pg_recvlogical continuously writes to the file specified with the --file option, which means the output file can grow indefinitely. To manage file size, some users may want to rotate the output periodically. While reviewing the source code to find the way to rotate the file, I noticed that pg_recvlogical reopens the output file when it receives a SIGHUP signal. This makes file rotation possible: we can rename the current output file and then send a SIGHUP to pg_recvlogical, which will close the renamed file and open a new one with the same original name. This is a useful feature, but it's currently undocumented. So I'd like to apply the attached patch that adds this information to the documentation. Thought? Regards, -- Fujii Masao NTT DATA Japan Corporation From 3d0b0df5d21b570bbda75353c9ba230d0907e253 Mon Sep 17 00:00:00 2001 From: Fujii Masao Date: Thu, 10 Jul 2025 16:25:12 +0900 Subject: [PATCH v1] doc: Document reopen of output file via SIGHUP in pg_recvlogical. When pg_recvlogical receives a SIGHUP signal, it closes the current output file and reopens a new one. This is useful since it allows us to rotate the output file by renaming the current file and sending a SIGHUP. This behavior was previously undocumented. This commit adds the missing documentation. --- doc/src/sgml/ref/pg_recvlogical.sgml | 10 ++ 1 file changed, 10 insertions(+) diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml index f68182266a9..3c667141495 100644 --- a/doc/src/sgml/ref/pg_recvlogical.sgml +++ b/doc/src/sgml/ref/pg_recvlogical.sgml @@ -53,6 +53,16 @@ PostgreSQL documentation (ControlC) or SIGTERM signal. + + + When pg_recvlogical receives + a SIGHUP signal, it closes the current output file + and opens a new one using the filename given with + the --file option. This allows us to rotate + the output file by first renaming the current file and then sending + a SIGHUP signal to + pg_recvlogical. + -- 2.49.0
Re: Outdated typedefs in documentation
On Wed, Jul 9, 2025 at 5:46 PM Artem Fadeev wrote: > I have noticed a slight mismatch between typedefs in docs and header > files. Your code is producing obvious false-positives by finding documentation examples and stating the obvious fact that such examples do not exist in the code base (since they are examples). The better algorithm is to first identify structs in the code that should be documented. Then for each one search the docs and report whether it is "present and matching", "present and not matching", or "not present". Ideally ignoring comments since only the names/types and positions matter. i.e., canonicalize the things being compared first. From that listing you can then produce a patch to update the ones that aren't "present and matching". It seems mostly wasted effort to identify documented structs that are not in the code - at least in an automated fashion. Documenting one and then removing it outright - in way that someone might leave the documentation for it behind - seems unlikely. But I'm guessing and maybe you will find more than expected once you manually audit the results of such a scan and produce a final clean report and, ideally, patch. David J.
Re: Missing File weather.txt
> On 5 Jul 2025, at 19:29, Tom Lane wrote: > > Fujii Masao writes: >> On 2020/01/28 19:18, Daniel Gustafsson wrote: >>> This is only mentioned as an example of another input method, with a link to >>> the COPY page for more information. That being said, it's a good thing for >>> a >>> tutorial to be self-contained, and going from a basic tutorial to the COPY >>> reference page is a fairly large step. I propose that we add a small >>> example >>> on what weather.txt could look like as per the attached diff. > >> Sorry for reviving this old thread, but I wanted to follow up since >> the same issue was reported again in [1], and the proposed patch >> basically looks good to me. > > +1 > >> In the tutorial, three rows are inserted using INSERT, so shouldn't >> the sample input for COPY include all three, like this? > > Agreed, the example file should match what the tutorial expects to be > in the table. I'd include text along the lines of "The data inserted > above could also be inserted from a file containing:". The attached v2 adds the missing line, and tweaks the text added to document the file. Since there have been reports I propose backpatching this all the way down to 13 while at it. -- Daniel Gustafsson v2-0001-doc-Add-example-file-for-COPY.patch Description: Binary data
Re: Outdated typedefs in documentation
> On 10 Jul 2025, at 02:45, Artem Fadeev wrote: > Attached diff file shows other mismatches I could find. There are some > comments that could be updated. Other differences are caused by indentation > variations and false positives. The attached diff is not useable for knowing what you propose to change, it's a mish-mash of incorrect proposal and unexplained comment removals against a file not present in our tree. Please make an actual patch against the docs you propose to change for us to have something to consider. -- Daniel Gustafsson
Re: Outdated typedefs in documentation
"David G. Johnston" writes: > It seems mostly wasted effort to identify documented structs that are not > in the code - at least in an automated fashion. Documenting one and then > removing it outright - in way that someone might leave the documentation > for it behind - seems unlikely. I'm dubious about that too. We should only put a real struct into the documentation if it's part of a stable API for extensions to use. Removing such a thing altogether would need to clear a very high bar. But this script is also finding example structs that are not expected to match anything in the code. I'm more prepared to believe that there might be places where a struct's documentation is out of sync with the code (e.g, missing fields). And indeed Artem's script seems to have found some. Those things should be fixed. A lot of this, though, looks to be complaints because the comments in the code don't exactly match the comments in the documentation. I'm not clear whether "they should match exactly" is a useful goal. The two cases are oriented towards different audiences. regards, tom lane
Re: Missing File weather.txt
On 2025/07/11 7:22, Daniel Gustafsson wrote:
On 5 Jul 2025, at 19:29, Tom Lane wrote:
Fujii Masao writes:
On 2020/01/28 19:18, Daniel Gustafsson wrote:
This is only mentioned as an example of another input method, with a link to
the COPY page for more information. That being said, it's a good thing for a
tutorial to be self-contained, and going from a basic tutorial to the COPY
reference page is a fairly large step. I propose that we add a small example
on what weather.txt could look like as per the attached diff.
Sorry for reviving this old thread, but I wanted to follow up since
the same issue was reported again in [1], and the proposed patch
basically looks good to me.
+1
In the tutorial, three rows are inserted using INSERT, so shouldn't
the sample input for COPY include all three, like this?
Agreed, the example file should match what the tutorial expects to be
in the table. I'd include text along the lines of "The data inserted
above could also be inserted from a file containing:".
The attached v2 adds the missing line, and tweaks the text added to document
the file.
Thanks for updating the patch! LGTM.
Just one small comment:
+Hayward37540.01994-11-29
This row is inserted using the following INSERT statement:
INSERT INTO weather (date, city, temp_hi, temp_lo)
VALUES ('1994-11-29', 'Hayward', 54, 37);
Since the prcp column isn't specified, its value is NULL. So shouldn't
the fourth field in the data line above be \N instead of 0.0?
Since there have been reports I propose backpatching this all the
way down to 13 while at it.
+1
Regards,
--
Fujii Masao
NTT DATA Japan Corporation
