begriffs open source - ai-pg/blob - full-docs/txt/tableam.txt

   1
   2 Chapter 62. Table Access Method Interface Definition
   3
   4    This chapter explains the interface between the core PostgreSQL system
   5    and table access methods, which manage the storage for tables. The core
   6    system knows little about these access methods beyond what is specified
   7    here, so it is possible to develop entirely new access method types by
   8    writing add-on code.
   9
  10    Each table access method is described by a row in the pg_am system
  11    catalog. The pg_am entry specifies a name and a handler function for
  12    the table access method. These entries can be created and deleted using
  13    the CREATE ACCESS METHOD and DROP ACCESS METHOD SQL commands.
  14
  15    A table access method handler function must be declared to accept a
  16    single argument of type internal and to return the pseudo-type
  17    table_am_handler. The argument is a dummy value that simply serves to
  18    prevent handler functions from being called directly from SQL commands.
  19
  20    Here is how an extension SQL script file might create a table access
  21    method handler:
  22 CREATE OR REPLACE FUNCTION my_tableam_handler(internal)
  23   RETURNS table_am_handler AS 'my_extension', 'my_tableam_handler'
  24   LANGUAGE C STRICT;
  25
  26 CREATE ACCESS METHOD myam TYPE TABLE HANDLER my_tableam_handler;
  27
  28    The result of the function must be a pointer to a struct of type
  29    TableAmRoutine, which contains everything that the core code needs to
  30    know to make use of the table access method. The return value needs to
  31    be of server lifetime, which is typically achieved by defining it as a
  32    static const variable in global scope.
  33
  34    Here is how a source file with the table access method handler might
  35    look like:
  36 #include "postgres.h"
  37
  38 #include "access/tableam.h"
  39 #include "fmgr.h"
  40
  41 PG_MODULE_MAGIC;
  42
  43 static const TableAmRoutine my_tableam_methods = {
  44     .type = T_TableAmRoutine,
  45
  46     /* Methods of TableAmRoutine omitted from example, add them here. */
  47 };
  48
  49 PG_FUNCTION_INFO_V1(my_tableam_handler);
  50
  51 Datum
  52 my_tableam_handler(PG_FUNCTION_ARGS)
  53 {
  54     PG_RETURN_POINTER(&my_tableam_methods);
  55 }
  56
  57
  58    The TableAmRoutine struct, also called the access method's API struct,
  59    defines the behavior of the access method using callbacks. These
  60    callbacks are pointers to plain C functions and are not visible or
  61    callable at the SQL level. All the callbacks and their behavior is
  62    defined in the TableAmRoutine structure (with comments inside the
  63    struct defining the requirements for callbacks). Most callbacks have
  64    wrapper functions, which are documented from the point of view of a
  65    user (rather than an implementor) of the table access method. For
  66    details, please refer to the src/include/access/tableam.h file.
  67
  68    To implement an access method, an implementor will typically need to
  69    implement an AM-specific type of tuple table slot (see
  70    src/include/executor/tuptable.h), which allows code outside the access
  71    method to hold references to tuples of the AM, and to access the
  72    columns of the tuple.
  73
  74    Currently, the way an AM actually stores data is fairly unconstrained.
  75    For example, it's possible, but not required, to use postgres' shared
  76    buffer cache. In case it is used, it likely makes sense to use
  77    PostgreSQL's standard page layout as described in Section 66.6.
  78
  79    One fairly large constraint of the table access method API is that,
  80    currently, if the AM wants to support modifications and/or indexes, it
  81    is necessary for each tuple to have a tuple identifier (TID) consisting
  82    of a block number and an item number (see also Section 66.6). It is not
  83    strictly necessary that the sub-parts of TIDs have the same meaning
  84    they e.g., have for heap, but if bitmap scan support is desired (it is
  85    optional), the block number needs to provide locality.
  86
  87    For crash safety, an AM can use postgres' WAL, or a custom
  88    implementation. If WAL is chosen, either Generic WAL Records can be
  89    used, or a Custom WAL Resource Manager can be implemented.
  90
  91    To implement transactional support in a manner that allows different
  92    table access methods be accessed within a single transaction, it likely
  93    is necessary to closely integrate with the machinery in
  94    src/backend/access/transam/xlog.c.
  95
  96    Any developer of a new table access method can refer to the existing
  97    heap implementation present in src/backend/access/heap/heapam_handler.c
  98    for details of its implementation.