begriffs open source - ai-pg/blob - full-docs/src/sgml/html/tableam.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 62. Table Access Method Interface Definition</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="geqo-biblio.html" title="61.4. Further Reading" /><link rel="next" href="indexam.html" title="Chapter 63. Index Access Method Interface Definition" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">Chapter 62. Table Access Method Interface Definition</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="geqo-biblio.html" title="61.4. Further Reading">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="indexam.html" title="Chapter 63. Index Access Method Interface Definition">Next</a></td></tr></table><hr /></div><div class="chapter" id="TABLEAM"><div class="titlepage"><div><div><h2 class="title">Chapter 62. Table Access Method Interface Definition</h2></div></div></div><a id="id-1.10.14.2" class="indexterm"></a><a id="id-1.10.14.3" class="indexterm"></a><p>
   3   This chapter explains the interface between the core
   4   <span class="productname">PostgreSQL</span> system and <em class="firstterm">table access
   5   methods</em>, which manage the storage for tables. The core system
   6   knows little about these access methods beyond what is specified here, so
   7   it is possible to develop entirely new access method types by writing
   8   add-on code.
   9  </p><p>
  10   Each table access method is described by a row in the <a class="link" href="catalog-pg-am.html" title="52.3. pg_am"><code class="structname">pg_am</code></a> system
  11   catalog. The <code class="structname">pg_am</code> entry specifies a name and a
  12   <em class="firstterm">handler function</em> for the table access method.  These
  13   entries can be created and deleted using the <a class="xref" href="sql-create-access-method.html" title="CREATE ACCESS METHOD"><span class="refentrytitle">CREATE ACCESS METHOD</span></a> and <a class="xref" href="sql-drop-access-method.html" title="DROP ACCESS METHOD"><span class="refentrytitle">DROP ACCESS METHOD</span></a> SQL commands.
  14  </p><p>
  15   A table access method handler function must be declared to accept a single
  16   argument of type <code class="type">internal</code> and to return the pseudo-type
  17   <code class="type">table_am_handler</code>.  The argument is a dummy value that simply
  18   serves to prevent handler functions from being called directly from SQL commands.
  19  </p><p>
  20   Here is how an extension SQL script file might create a table access
  21   method handler:
  22  </p><pre class="programlisting">
  23 CREATE OR REPLACE FUNCTION my_tableam_handler(internal)
  24   RETURNS table_am_handler AS 'my_extension', 'my_tableam_handler'
  25   LANGUAGE C STRICT;
  26
  27 CREATE ACCESS METHOD myam TYPE TABLE HANDLER my_tableam_handler;
  28 </pre><p>
  29   The result of the function must be a pointer to a struct of type
  30   <code class="structname">TableAmRoutine</code>, which contains everything that the
  31   core code needs to know to make use of the table access method. The return
  32   value needs to be of server lifetime, which is typically achieved by
  33   defining it as a <code class="literal">static const</code> variable in global scope.
  34  </p><p>
  35   Here is how a source file with the table access method handler might
  36   look like:
  37  </p><pre class="programlisting">
  38 #include "postgres.h"
  39
  40 #include "access/tableam.h"
  41 #include "fmgr.h"
  42
  43 PG_MODULE_MAGIC;
  44
  45 static const TableAmRoutine my_tableam_methods = {
  46     .type = T_TableAmRoutine,
  47
  48     /* Methods of TableAmRoutine omitted from example, add them here. */
  49 };
  50
  51 PG_FUNCTION_INFO_V1(my_tableam_handler);
  52
  53 Datum
  54 my_tableam_handler(PG_FUNCTION_ARGS)
  55 {
  56     PG_RETURN_POINTER(&amp;my_tableam_methods);
  57 }
  58
  59 </pre><p>
  60   The <code class="structname">TableAmRoutine</code> struct, also called the
  61   access method's <em class="firstterm">API struct</em>, defines the behavior of
  62   the access method using callbacks. These callbacks are pointers to plain C
  63   functions and are not visible or callable at the SQL level. All the
  64   callbacks and their behavior is defined in the
  65   <code class="structname">TableAmRoutine</code> structure (with comments inside the
  66   struct defining the requirements for callbacks). Most callbacks have
  67   wrapper functions, which are documented from the point of view of a user
  68   (rather than an implementor) of the table access method.  For details,
  69   please refer to the <a class="ulink" href="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/tableam.h;hb=HEAD" target="_top">
  70   <code class="filename">src/include/access/tableam.h</code></a> file.
  71  </p><p>
  72   To implement an access method, an implementor will typically need to
  73   implement an <acronym class="acronym">AM</acronym>-specific type of tuple table slot (see
  74   <a class="ulink" href="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/executor/tuptable.h;hb=HEAD" target="_top">
  75    <code class="filename">src/include/executor/tuptable.h</code></a>), which allows
  76    code outside the access method to hold references to tuples of the AM, and
  77    to access the columns of the tuple.
  78  </p><p>
  79   Currently, the way an AM actually stores data is fairly unconstrained. For
  80   example, it's possible, but not required, to use postgres' shared buffer
  81   cache.  In case it is used, it likely makes sense to use
  82   <span class="productname">PostgreSQL</span>'s standard page layout as described in
  83   <a class="xref" href="storage-page-layout.html" title="66.6. Database Page Layout">Section 66.6</a>.
  84  </p><p>
  85   One fairly large constraint of the table access method API is that,
  86   currently, if the AM wants to support modifications and/or indexes, it is
  87   necessary for each tuple to have a tuple identifier (<acronym class="acronym">TID</acronym>)
  88   consisting of a block number and an item number (see also <a class="xref" href="storage-page-layout.html" title="66.6. Database Page Layout">Section 66.6</a>).  It is not strictly necessary that the
  89   sub-parts of <acronym class="acronym">TIDs</acronym> have the same meaning they e.g., have
  90   for <code class="literal">heap</code>, but if bitmap scan support is desired (it is
  91   optional), the block number needs to provide locality.
  92  </p><p>
  93   For crash safety, an AM can use postgres' <a class="link" href="wal.html" title="Chapter 28. Reliability and the Write-Ahead Log"><acronym class="acronym">WAL</acronym></a>, or a custom implementation.
  94   If <acronym class="acronym">WAL</acronym> is chosen, either <a class="link" href="generic-wal.html" title="64.1. Generic WAL Records">Generic WAL Records</a> can be used,
  95   or a <a class="link" href="custom-rmgr.html" title="64.2. Custom WAL Resource Managers">Custom WAL Resource Manager</a> can be
  96   implemented.
  97  </p><p>
  98   To implement transactional support in a manner that allows different table
  99   access methods be accessed within a single transaction, it likely is
 100   necessary to closely integrate with the machinery in
 101   <code class="filename">src/backend/access/transam/xlog.c</code>.
 102  </p><p>
 103   Any developer of a new <code class="literal">table access method</code> can refer to
 104   the existing <code class="literal">heap</code> implementation present in
 105   <code class="filename">src/backend/access/heap/heapam_handler.c</code> for details of
 106   its implementation.
 107  </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="geqo-biblio.html" title="61.4. Further Reading">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="indexam.html" title="Chapter 63. Index Access Method Interface Definition">Next</a></td></tr><tr><td width="40%" align="left" valign="top">61.4. Further Reading </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 63. Index Access Method Interface Definition</td></tr></table></div></body></html>