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.haribabu@gmail.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