doc/src/sgml/tableam.sgml

   1 <!-- doc/src/sgml/tableam.sgml -->
   2
   3 <chapter id="tableam">
   4  <title>Table Access Method Interface Definition</title>
   5
   6  <indexterm>
   7   <primary>Table Access Method</primary>
   8  </indexterm>
   9  <indexterm>
  10   <primary>tableam</primary>
  11   <secondary>Table Access Method</secondary>
  12  </indexterm>
  13
  14  <para>
  15   This chapter explains the interface between the core
  16   <productname>PostgreSQL</productname> system and <firstterm>table access
  17   methods</firstterm>, which manage the storage for tables. The core system
  18   knows little about these access methods beyond what is specified here, so
  19   it is possible to develop entirely new access method types by writing
  20   add-on code.
  21  </para>
  22
  23  <para>
  24   Each table access method is described by a row in the <link
  25   linkend="catalog-pg-am"><structname>pg_am</structname></link> system
  26   catalog. The <structname>pg_am</structname> entry specifies a name and a
  27   <firstterm>handler function</firstterm> for the table access method.  These
  28   entries can be created and deleted using the <xref
  29   linkend="sql-create-access-method"/> and <xref
  30   linkend="sql-drop-access-method"/> SQL commands.
  31  </para>
  32
  33  <para>
  34   A table access method handler function must be declared to accept a single
  35   argument of type <type>internal</type> and to return the pseudo-type
  36   <type>table_am_handler</type>.  The argument is a dummy value that simply
  37   serves to prevent handler functions from being called directly from SQL commands.
  38  </para>
  39
  40  <para>
  41   Here is how an extension SQL script file might create a table access
  42   method handler:
  43  </para>
  44
  45 <programlisting>
  46 CREATE OR REPLACE FUNCTION my_tableam_handler(internal)
  47   RETURNS table_am_handler AS 'my_extension', 'my_tableam_handler'
  48   LANGUAGE C STRICT;
  49
  50 CREATE ACCESS METHOD myam TYPE TABLE HANDLER my_tableam_handler;
  51 </programlisting>
  52
  53  <para>
  54   The result of the function must be a pointer to a struct of type
  55   <structname>TableAmRoutine</structname>, which contains everything that the
  56   core code needs to know to make use of the table access method. The return
  57   value needs to be of server lifetime, which is typically achieved by
  58   defining it as a <literal>static const</literal> variable in global scope.
  59  </para>
  60
  61  <para>
  62   Here is how a source file with the table access method handler might
  63   look like:
  64  </para>
  65
  66 <programlisting><![CDATA[
  67 #include "postgres.h"
  68
  69 #include "access/tableam.h"
  70 #include "fmgr.h"
  71
  72 PG_MODULE_MAGIC;
  73
  74 static const TableAmRoutine my_tableam_methods = {
  75     .type = T_TableAmRoutine,
  76
  77     /* Methods of TableAmRoutine omitted from example, add them here. */
  78 };
  79
  80 PG_FUNCTION_INFO_V1(my_tableam_handler);
  81
  82 Datum
  83 my_tableam_handler(PG_FUNCTION_ARGS)
  84 {
  85     PG_RETURN_POINTER(&my_tableam_methods);
  86 }
  87 ]]>
  88 </programlisting>
  89
  90  <para>
  91   The <structname>TableAmRoutine</structname> struct, also called the
  92   access method's <firstterm>API struct</firstterm>, defines the behavior of
  93   the access method using callbacks. These callbacks are pointers to plain C
  94   functions and are not visible or callable at the SQL level. All the
  95   callbacks and their behavior is defined in the
  96   <structname>TableAmRoutine</structname> structure (with comments inside the
  97   struct defining the requirements for callbacks). Most callbacks have
  98   wrapper functions, which are documented from the point of view of a user
  99   (rather than an implementor) of the table access method.  For details,
 100   please refer to the <ulink url="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/tableam.h;hb=HEAD">
 101   <filename>src/include/access/tableam.h</filename></ulink> file.
 102  </para>
 103
 104  <para>
 105   To implement an access method, an implementor will typically need to
 106   implement an <acronym>AM</acronym>-specific type of tuple table slot (see
 107   <ulink url="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/executor/tuptable.h;hb=HEAD">
 108    <filename>src/include/executor/tuptable.h</filename></ulink>), which allows
 109    code outside the access method to hold references to tuples of the AM, and
 110    to access the columns of the tuple.
 111  </para>
 112
 113  <para>
 114   Currently, the way an AM actually stores data is fairly unconstrained. For
 115   example, it's possible, but not required, to use postgres' shared buffer
 116   cache.  In case it is used, it likely makes sense to use
 117   <productname>PostgreSQL</productname>'s standard page layout as described in
 118   <xref linkend="storage-page-layout"/>.
 119  </para>
 120
 121  <para>
 122   One fairly large constraint of the table access method API is that,
 123   currently, if the AM wants to support modifications and/or indexes, it is
 124   necessary for each tuple to have a tuple identifier (<acronym>TID</acronym>)
 125   consisting of a block number and an item number (see also <xref
 126   linkend="storage-page-layout"/>).  It is not strictly necessary that the
 127   sub-parts of <acronym>TIDs</acronym> have the same meaning they e.g., have
 128   for <literal>heap</literal>, but if bitmap scan support is desired (it is
 129   optional), the block number needs to provide locality.
 130  </para>
 131
 132  <para>
 133   For crash safety, an AM can use postgres' <link
 134   linkend="wal"><acronym>WAL</acronym></link>, or a custom implementation.
 135   If <acronym>WAL</acronym> is chosen, either <link
 136   linkend="generic-wal">Generic WAL Records</link> can be used,
 137   or a <link linkend="custom-rmgr">Custom WAL Resource Manager</link> can be
 138   implemented.
 139  </para>
 140
 141  <para>
 142   To implement transactional support in a manner that allows different table
 143   access methods be accessed within a single transaction, it likely is
 144   necessary to closely integrate with the machinery in
 145   <filename>src/backend/access/transam/xlog.c</filename>.
 146  </para>
 147
 148  <para>
 149   Any developer of a new <literal>table access method</literal> can refer to
 150   the existing <literal>heap</literal> implementation present in
 151   <filename>src/backend/access/heap/heapam_handler.c</filename> for details of
 152   its implementation.
 153  </para>
 154
 155 </chapter>