Thread

Re: mention unused_oids script in pg_proc.dat

Florents Tselai <florents.tselai@gmail.com> — 2025-07-08T14:40:39Z

On Tue, Jul 1, 2025 at 12:25 PM Peter Eisentraut <peter@eisentraut.org>
wrote:

> On 24.05.25 12:34, Florents Tselai wrote:
> >
> >
> >> On 24 May 2025, at 12:24 PM, Álvaro Herrera <alvherre@kurilemu.de>
> wrote:
> >>
> >> On 2025-May-24, Florents Tselai wrote:
> >>
> >>> I aggree with having more READMEs around the src tree.
> >>> It’s true that a lot of doc content found in VII. Internals is
> dev-oriented,
> >>> but imho it should be closer to the src (and more succinct/less
> verbose too).
> >>
> >> Maybe these READMEs can simply contain little more than links to the
> >> built HTML docs, to avoid having multiple sources of info.
> >>
> >>> Looking at some of the text in 67.2.2. OID Assignment for example,
> >>> a few things look outdated wrt choosing OIDs.
> >>>
> >>> One can look through the history of similar commits to see what
> >>> needs to be changed; So it’s not THAT bad.
> >>
> >> Sure, outdated docs is something that happens.  Patches welcome.
> >>
> >
> > Something like this ?
>
>  > diff --git a/src/include/catalog/README b/src/include/catalog/README
>  > new file mode 100644
>  > index 00000000000..5bd81c6d86c
>  > --- /dev/null
>  > +++ b/src/include/catalog/README
>  > @@ -0,0 +1,11 @@
>  > +# Catalog
>  > +
>  > +For more details see https://www.postgresql.org/docs/current/bki.html
>
> I can see that having a README in src/include/catalog/ would be useful.
> That directory contains some "unusual" files, and some hints about them
> would be good.  Before commit 372728b0d49, we used to have a README in
> src/backend/catalog/README, but then this was moved to the SGML
> documentation.  Maybe you can read up there why this was chosen.  But I
> think src/include/catalog/ would be a better location in any case.
>

In practice people go to the git history to see the files touched by
similar commits,
and devise a to-do-list for their case.
so I think it helps them a lot to see some high-level READMEs waiting for
them there.

In this particular case, unused_oids isn't included in any commits so you
can't be aware of its existence even


> Maybe for now just a link like you show would be ok.  (But it should
> probably be s/current/devel/.)
>

Done


>
>  > +
>  > +Below are some checklists for common scenarios.
>  > +
>  > +## Adding a New Built-in SQL Command
>  > +
>  > +1. Implement the function in C and place it in the appropriate
> directory under `src` (typically in `src/utils/adt`)
>  > +2. Each function should have a unique integer OID. Run the script
> `src/include/catalog/unused_oids` to find available ranges.
>  > +3. Add the entry to `pg_proc.dat` following the surrounding
> conventions.
>
> Presumably, if you're developing this kind of thing, you are already
> reading some other part of the documentation, maybe xfunc.sgml?  Do we
> need to add more information there, or some links?
>

I agree. Added a link reference to that xfunc-c

Some basic stuff that was missing in xfunc, I've already added in 86e4efc .
For now I think it's good enough.