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>
 
   <table>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index a03ea1427b..7e37042a55 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -89,6 +89,7 @@
 <!ENTITY gin        SYSTEM "gin.sgml">
 <!ENTITY brin       SYSTEM "brin.sgml">
 <!ENTITY planstats    SYSTEM "planstats.sgml">
+<!ENTITY tableam    SYSTEM "tableam.sgml">
 <!ENTITY indexam    SYSTEM "indexam.sgml">
 <!ENTITY nls        SYSTEM "nls.sgml">
 <!ENTITY plhandler  SYSTEM "plhandler.sgml">
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 96d196d229..3e115f1c76 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -250,6 +250,7 @@
   &tablesample-method;
   &custom-scan;
   &geqo;
+  &tableam;
   &indexam;
   &generic-wal;
   &btree;
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>
+  
+  <para>
+   Each table access method is described by a row in the
+   <link linkend="catalog-pg-am"><structname>pg_am</structname></link> system
+   catalog. The <structname>pg_am</structname> entry specifies a <firstterm>type</firstterm>
+   of the access method and a <firstterm>handler function</firstterm> for the
+   access method. These entries can be created and deleted using the <xref linkend="sql-create-access-method"/>
+   and <xref linkend="sql-drop-access-method"/> SQL commands.
+  </para>
+
+  <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. 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>
+
+  <para>
+   Any new <literal>TABLE</literal> access method developers can refer the exisitng
+   <literal>HEAP</literal> implementation present in the <filename>src/backend/heap/heapam_handler.c</filename>
+   for more details of how it is implemented for HEAP access method.
+  </para>
+
+</chapter>
-- 
2.20.1.windows.1