Re: Pluggable Storage - Andres's take

Hi,

On 2019-04-02 17:11:07 +1100, Haribabu Kommi wrote:
> From a72cfcd523887f1220473231d7982928acc23684 Mon Sep 17 00:00:00 2001
> From: Hari Babu <kommi(dot)haribabu(at)gmail(dot)com>
> Date: Tue, 2 Apr 2019 15:41:17 +1100
> Subject: [PATCH 1/2] tableam : doc update of table access methods
>
> Providing basic explanation of table access methods
> including their structure details and reference heap
> implementation files.
> ---
> doc/src/sgml/catalogs.sgml | 5 ++--
> doc/src/sgml/filelist.sgml | 1 +
> doc/src/sgml/postgres.sgml | 1 +
> doc/src/sgml/tableam.sgml | 56 ++++++++++++++++++++++++++++++++++++++
> 4 files changed, 61 insertions(+), 2 deletions(-)
> create mode 100644 doc/src/sgml/tableam.sgml
>
> diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
> index f4aabf5dc7..200708e121 100644
> --- a/doc/src/sgml/catalogs.sgml
> +++ b/doc/src/sgml/catalogs.sgml
> @@ -587,8 +587,9 @@
> The catalog <structname>pg_am</structname> stores information about
> relation access methods. There is one row for each access method supported
> by the system.
> - Currently, only indexes have access methods. The requirements for index
> - access methods are discussed in detail in <xref linkend="indexam"/>.
> + Currently, only table and indexes have access methods. The requirements for table
> + access methods are discussed in detail in <xref linkend="tableam"/> and the
> + requirements for index access methods are discussed in detail in <xref linkend="indexam"/>.
> </para>

I also adapted pg_am.amtype.

> diff --git a/doc/src/sgml/tableam.sgml b/doc/src/sgml/tableam.sgml
> new file mode 100644
> index 0000000000..9eca52ee70
> --- /dev/null
> +++ b/doc/src/sgml/tableam.sgml
> @@ -0,0 +1,56 @@
> +<!-- doc/src/sgml/tableam.sgml -->
> +
> +<chapter id="tableam">
> + <title>Table Access Method Interface Definition</title>
> +
> + <para>
> + This chapter defines the interface between the core <productname>PostgreSQL</productname>
> + system and <firstterm>access methods</firstterm>, which manage <literal>TABLE</literal>
> + types. The core system knows nothing about these access methods beyond
> + what is specified here, so it is possible to develop entirely new access
> + method types by writing add-on code.
> + </para>
> +
> + <para>
> + All Tables in <productname>PostgreSQL</productname> system are the primary
> + data store. Each table is stored as its own physical <firstterm>relation</firstterm>
> + and so is described by an entry in the <structname>pg_class</structname>
> + catalog. A table's content is entirely controlled by its access method.
> + (All the access methods furthermore use the standard page layout described
> + in <xref linkend="storage-page-layout"/>.)
> + </para>

I don't think there's actually any sort of dependency on the page
layout. It's entirely conceivable to write an AM that doesn't use
postgres' shared buffers.

> + <para>
> + A table access method handler function must be declared to accept a single
> + argument of type <type>internal</type> and to return the pseudo-type
> + <type>table_am_handler</type>. The argument is a dummy value that simply
> + serves to prevent handler functions from being called directly from SQL commands.

> + The result of the function must be a palloc'd struct of type <structname>TableAmRoutine</structname>,
> + which contains everything that the core code needs to know to make use of
> + the table access method.

That's not been correct for a while...

> The <structname>TableAmRoutine</structname> struct,
> + also called the access method's <firstterm>API struct</firstterm>, includes
> + fields specifying assorted fixed properties of the access method, such as
> + whether it can support bitmap scans. More importantly, it contains pointers
> + to support functions for the access method, which do all of the real work to
> + access tables. These support functions are plain C functions and are not
> + visible or callable at the SQL level. The support functions are described
> + in <structname>TableAmRoutine</structname> structure. For more details, please
> + refer the file <filename>src/include/access/tableam.h</filename>.
> + </para>

This seems to not have been adapted after copying it from indexam?

I'm still working on this (in particular I think storage.sgml and
probably some other places needs updates to make clear they apply to
heap not generally; I think there needs to be some references to generic
WAL records in tableam.sgml, ...), but I got to run a few errands.

One thing I want to call out is that I made the reference to
src/include/access/tableam.h a link to gitweb. I think that makes it
much more useful to the casual reader. But it also means that, baring
some infrastructure / procedure we don't have, the link will just
continue to point to master. I'm not particularly concerned about that,
but it seems worth pointing out, given that we've only a single link to
gitweb in the sgml docs so far.

Greetings,

Andres Freund