第63章 テーブルアクセスメソッドのインタフェース定義

<title>Table Access Method Interface Definition</title>

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. 本章は、PostgreSQLのコアシステムと、テーブルの格納を制御するテーブルアクセスメソッドとのインタフェースを説明します。 コアシステムはこのアクセスメソッドについて、ここで指定されたことのみを把握しています。これにより、追加コードを記述することで全く新しいアクセスメソッド種類を開発することができます。

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. 各テーブルアクセスメソッドはpg_amシステムカタログの行で記述されます。 pg_amのエントリではテーブルアクセスメソッドの名前とハンドラ関数を指定します。 これらのエントリはSQLコマンドCREATE ACCESS METHODDROP ACCESS METHODを使って、作成および削除することができます。

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. 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. 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 C functions and are not visible or callable at the SQL level. All the callbacks and their behavior is defined in the <structname>TableAmRoutine</structname> structure (with comments inside the struct defining the requirements for callbacks). Most callbacks have wrapper functions, which are documented from the point of view of a user (rather than an implementor) of the table access method. For details, please refer to the <ulink url="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/tableam.h;hb=HEAD"> <filename>src/include/access/tableam.h</filename></ulink> file. テーブルアクセスメソッドのハンドラ関数はinternal型の引数を一つ取り、table_am_handler疑似型を返すように宣言されなければなりません。 この引数はハンドラ関数がSQLコマンドから直接呼び出されるのを防ぐためだけのダミーの値です。 関数の結果はTableAmRoutine型の構造体のポインタでなければならず、そこにはテーブルアクセスメソッドを使用するためにコアコードが知る必要のあるすべてのことが含まれます。 サーバ生存期間の間、戻り値は必要で、通常これはグローバルスコープでstatic const変数として定義することで達成されます。 アクセスメソッドのAPI構造体とも呼ばれる、TableAmRoutine構造体はコールバックを使ってアクセスメソッドの振る舞いを定義します。 これらのコールバックは通常のC関数へのポインタで、SQLレベルでは見ることも呼び出すこともできません。 全てのコールバックとその振る舞いは、TableAmRoutine構造体(とコールバックの必要性を説明する構造体内のコメント)で定義されます。 たいていのコールバックはラッパー関数を持ちます。これらはテーブルアクセスメソッドの(開発者ではなく)使用者の立場でドキュメント記載されています。 詳細は、src/include/access/tableam.hファイルを参照してください。

To implement an access method, an implementor will typically need to implement an AM-specific type of tuple table slot (see <ulink url="https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/executor/tuptable.h;hb=HEAD"> <filename>src/include/executor/tuptable.h</filename></ulink>), which allows code outside the access method to hold references to tuples of the AM, and to access the columns of the tuple. アクセスメソッドを実装するには開発者は通常、タプルテーブルスロットのAM固有の型を実装する必要があります(src/include/executor/tuptable.hを参照してください)。 これはアクセスメソッド外のコードが、AMのタプルへの参照を保持できるようにして、そのタプルの列にアクセスできるようにするものです。

Currently, the way an AM actually stores data is fairly unconstrained. For example, it's possible, but not required, to use postgres' shared buffer cache. In case it is used, it likely makes sense to use <productname>PostgreSQL</productname>'s standard page layout as described in <xref linkend="storage-page-layout"/>. 今のところAMが実際にデータを格納する方法は全く制限されていません。 例えば、postgresの共有バッファキャッシュを使うことも、必須ではありませんが、可能です。 使う場合、おそらく73.6に記述されたPostgreSQLの標準ページレイアウトを使うには有意義でしょう。

One fairly large constraint of the table access method API is that, currently, if the AM wants to support modifications and/or indexes, it is necessary for each tuple to have a tuple identifier (<acronym>TID</acronym>) consisting of a block number and an item number (see also <xref linkend="storage-page-layout"/>). It is not strictly necessary that the sub-parts of <acronym>TIDs</acronym> have the same meaning they e.g., have for <literal>heap</literal>, but if bitmap scan support is desired (it is optional), the block number needs to provide locality. 現在のテーブルアクセスメソッドAPIのそれなりに大きい制約は、AMが更新および/またはインデックスに対応したい場合、各タプルがブロック番号とアイテム番号から成るタプル識別子(TID)を持つ必要があることです(73.6も参照してください)。 TIDsの下位要素が、例えばheapに対して持つのと同じ意味を持つことは、厳密には必要ありません。しかし、ビットマップスキャン対応(これは任意です)を望むなら、ブロック番号は局所性を備える必要があります。

For crash safety, an AM can use postgres' <link linkend="wal"><acronym>WAL</acronym></link>, or a custom implementation. If <acronym>WAL</acronym> is chosen, either <link linkend="generic-wal">Generic WAL Records</link> can be used, or a <link linkend="custom-rmgr">Custom WAL Resource Manager</link> can be implemented. クラッシュ安全性のために、AMはpostgresのWAL、あるいは、カスタム実装を使うことができます。 WALを選んだ場合、汎用WALレコードを利用するか、カスタムWALリソースマネージャを実装することができます。

To implement transactional support in a manner that allows different table access methods be accessed within a single transaction, it likely is necessary to closely integrate with the machinery in <filename>src/backend/access/transam/xlog.c</filename>. 異なるテーブルアクセスメソッドが単一トランザクション内でアクセスできるという類のトランザクション対応を実装するには、おそらくsrc/backend/access/transam/xlog.cの仕組みと注意深く統合することが必要でしょう。

Any developer of a new <literal>table access method</literal> can refer to the existing <literal>heap</literal> implementation present in <filename>src/backend/access/heap/heapam_handler.c</filename> for details of its implementation. テーブルアクセスメソッドの開発者は、実装の詳細について、src/backend/access/heap/heapam_handler.cにある既存のheapの実装を参照できます。