| 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> |