バージョンごとのドキュメント一覧

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

<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. 《機械翻訳》テーブルアクセスメソッドハンドラ関数は、タイプ内部の単一の引数を受け入れ、結果に対して擬似タイプtable_am_handlerを宣言する必要があります。 引数は、ハンドラ関数がSQLコマンドから直接呼び出されないようにするためだけに使用されるダミー値です。

Here is how an extension SQL script file might create a table access method handler: 《機械翻訳》次に、extension SQLスクリプトファイルがメソッドハンドラテーブル・アクセスを作成する方法を示します。

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;

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. 《機械翻訳》関数の結果は、タイプ構造体TableAmRoutineへのポインタである必要があります。 これは、テーブルアクセスメソッドをmakeが使用するためにコアコードニーズが知っているすべてのものを包含します。 戻り値のニーズはサーバの寿命になります。 これは通常、グローバルスコープでstatic const変数として定義することで実現されます。

Here is how a source file with the table access method handler might look like: 《機械翻訳》テーブルアクセスメソッドハンドラのあるソースファイルは次のようになります。

#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);
}

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. 《機械翻訳》TableAmRoutine構造体はアクセス・メソッドのAPI構造体とも呼ばれ、コールバックを使用してアクセス・メソッドの動作を定義します。 これらのコールバックはプレーンC関数へのポインタであり、可視ではなく、SQLレベルで呼び出せるものでもありません。 すべてのコールバックとその動作はTableAmRoutine構造体で定義されます(コールバックの要件を定義するコメントが構造体内部にあります)。 ほとんどのコールバックにはラッパー関数があり、テーブルアクセスメソッドのユーザ(実装者ではなく)のビューポイントからドキュメント化されています。 詳細はsrc/include/access/tableam.hファイルを参照してください。

To implement an access method, an implementor will typically need to implement an <acronym>AM</acronym>-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の共有バッファキャッシュを使うことも、必須ではありませんが、可能です。 使う場合、おそらく66.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)を持つ必要があることです(66.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の実装を参照できます。