<!-- doc/src/sgml/tableam.sgml -->

<chapter id="tableam">
 <title>Table Access Method Interface Definition</title>

 <indexterm>
  <primary>Table Access Method</primary>
 </indexterm>
 <indexterm>
  <primary>tableam</primary>
  <secondary>Table Access Method</secondary>
 </indexterm>

 <para>
  This chapter explains the interface between the core
  <productname>PostgreSQL</productname> system and <firstterm>table access
  methods</firstterm>, which manage the storage for tables. The core system
  knows little 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>
  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 name and a
  <firstterm>handler function</firstterm> for the table 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.
 </para>

 <para>
  Here is how an extension SQL script file might create a table access
  method handler:
 </para>

<programlisting>
CREATE OR REPLACE FUNCTION my_tableam_handler(internal)
  RETURNS table_am_handler AS 'my_extension', 'my_tableam_handler'
  LANGUAGE C STRICT;

CREATE ACCESS METHOD myam TYPE TABLE HANDLER my_tableam_handler;
</programlisting>

 <para>
  The result of the function must be a pointer to a 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 return
  value needs to be of server lifetime, which is typically achieved by
  defining it as a <literal>static const</literal> variable in global scope.
 </para>

 <para>
  Here is how a source file with the table access method handler might
  look like:
 </para>

<programlisting><![CDATA[
#include "postgres.h"

#include "access/tableam.h"
#include "fmgr.h"

PG_MODULE_MAGIC;

static const TableAmRoutine my_tableam_methods = {
    .type = T_TableAmRoutine,

    /* Methods of TableAmRoutine omitted from example, add them here. */
};

PG_FUNCTION_INFO_V1(my_tableam_handler);

Datum
my_tableam_handler(PG_FUNCTION_ARGS)
{
    PG_RETURN_POINTER(&my_tableam_methods);
}
]]>
</programlisting>

 <para>
  The <structname>TableAmRoutine</structname> struct, also called the
  access method's <firstterm>API struct</firstterm>, defines the behavior of
  the access method using callbacks. These callbacks are pointers to plain