Re: Add minimal C example and SQL registration example for custom table access methods.

From: Phil Eaton <phil(at)eatonphil(dot)com>
To: Robert Haas <robertmhaas(at)gmail(dot)com>
Cc: fabriziomello(at)gmail(dot)com, Roberto Mello <roberto(dot)mello(at)gmail(dot)com>, pgsql-hackers(at)lists(dot)postgresql(dot)org
Subject: Re: Add minimal C example and SQL registration example for custom table access methods.
Date: 2024-05-03 17:35:31
Message-ID: CAByiw+o9uKi=qAuZ=4TtqRqGO8-OLMRS9fVx-UwZPEdT8SshFA@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs pgsql-hackers

Thanks Robert for mentioning this! I indeed did not notice the switch.

> Nitpicking a little: your patch appears to change more lines than it does, because it added line breaks earlier in the lines. I would generally avoid that unless there's good reason to do so.

Thanks! I'm not sure why that happened since I normally run
fill-region in emacs and when I re-ran it now, it looked as it used
to. I've fixed it up in this patch.

> Perhaps you could provide a "see <xyz>" to point the reader finding your example where he could find these non-optional methods he must provide?

Since the responses were positive, I've taken the liberty to extend
the sample code by simply including all the stub methods and the full
struct. Marking which methods are optional and not.

If that looks like too much, I can revert back. Perhaps only
mentioning the struct like we do for the index AM here:
https://www.postgresql.org/docs/current/index-api.html. However, as a
reader, I feel like the full stubs are a bit more useful.

Happy for feedback. Updated patch is attached.

Cheers,
Phil

On Fri, Mar 22, 2024 at 1:40 PM Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>
> On Fri, Jan 26, 2024 at 3:03 PM Fabrízio de Royes Mello
> <fabriziomello(at)gmail(dot)com> wrote:
> > On Wed, Nov 15, 2023 at 8:29 PM Roberto Mello <roberto(dot)mello(at)gmail(dot)com> wrote:
> > > Suggestion:
> > >
> > > In the C example you added you mention in the comment:
> > >
> > > + /* Methods from TableAmRoutine omitted from example, but all
> > > + non-optional ones must be provided here. */
> > >
> > > Perhaps you could provide a "see <xyz>" to point the reader finding your example where he could find these non-optional methods he must provide?
> > >
> > > Nitpicking a little: your patch appears to change more lines than it does, because it added line breaks earlier in the lines. I would generally avoid that unless there's good reason to do so.
> >
> > Hey folks,
> >
> > There is a previous patch [1] around the same topic. What about joining efforts on pointing these documentation changes to the proposed test module?
> >
> > [1] https://commitfest.postgresql.org/46/4588/
>
> Looking over this thread, I see that it was moved from pgsql-docs to
> pgsql-hackers while at the same time dropping the original poster from
> the Cc list. That seems rather unfortunate. I suspect there's a pretty
> good chance that Phil Eaton hasn't seen any of the replies other than
> the first one from Paul Jungwirth, which is also the only one that
> didn't ask for anything to be changed.
>
> Re-adding Phil. Phil, you should have a look over
> https://www.postgresql.org/message-id/flat/CAByiw%2Br%2BCS-ojBDP7Dm%3D9YeOLkZTXVnBmOe_ajK%3Den8C_zB3_g%40mail.gmail.com
> and respond to the various emails and probably update the patch
> somehow. Note that feature freeze is in 2 weeks, so if we can't reach
> agreement on what is to be done here soon, this will have to wait for
> the next cycle, or later.
>
> --
> Robert Haas
> EDB: http://www.enterprisedb.com

Attachment Content-Type Size
v2-0001-Add-boilerplate-C-code-and-SQL-registration-examp.patch application/octet-stream 14.5 KB

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Dan Wainwright 2024-05-04 17:12:47 RETURNING order guarantees documentation
Previous Message PG Doc comments form 2024-05-03 16:20:51 Missing examples for hash partitioning

Browse pgsql-hackers by date

  From Date Subject
Next Message Tom Lane 2024-05-03 18:12:32 First-draft release notes for back branches are done
Previous Message Nathan Bossart 2024-05-03 17:13:48 add --no-sync to pg_upgrade's calls to pg_dump and pg_dumpall