第45章 サーバプログラミングインタフェース

目次

45.1. インタフェース関数
SPI_connect — SPIマネージャにプロシージャを接続する
SPI_finish — プロシージャをSPIマネージャから切断する
SPI_push — 再帰的にSPIを使用できるようにSPIスタックをプッシュする
SPI_pop — 再帰的なSPIの使用から復帰できるようにSPIスタックをポップする
SPI_execute — コマンドを実行する
SPI_exec — 読み書きコマンドを実行する
SPI_execute_with_args — 行外のパラメータを持つコマンドを実行する
SPI_prepare — 文を準備する。文の実行はまだ行わない
SPI_prepare_cursor — 文を準備する。まだ実行は行わない
SPI_prepare_params — 文を準備する。まだ実行は行わない
SPI_getargcountSPI_prepareにより準備した文に必要とされる引数の数を返す
SPI_getargtypeidSPI_prepareで準備された文で指定される引数のデータ型のOIDを返す
SPI_is_cursor_planSPI_prepareで準備された文がSPI_cursor_openで使用できる場合にtrueを返す
SPI_execute_planSPI_prepareで準備された文を実行する
SPI_execute_plan_with_paramlistSPI_prepareで準備された文を実行する
SPI_execp — 読み書きモードで文を実行する
SPI_cursor_openSPI_prepareで作成された文を使用したカーソルを設定する
SPI_cursor_open_with_args — 問い合わせとパラメータを使ってカーソルを設定する
SPI_cursor_open_with_paramlist — パラメータを使ってカーソルを設定する
SPI_cursor_find — 既存のカーソルを名前で検索する
SPI_cursor_fetch — カーソルから数行を取り出す
SPI_cursor_move — カーソルを移動する
SPI_scroll_cursor_fetch — カーソルから一部の行を取り出す
SPI_scroll_cursor_move — カーソルを移動する
SPI_cursor_close — カーソルを閉じる
SPI_keepplan — 準備済み文を保持する
SPI_saveplan — 準備済み文を保存する
45.2. インタフェースサポート関数
SPI_fname — 指定した列番号に対する列名を決定する
SPI_fnumber — 指定した列名から列番号を決定する
SPI_getvalue — 指定された列の文字列値を返す
SPI_getbinval — 指定した列のバイナリ値を返す
SPI_gettype — 指定された列のデータ型名を返す
SPI_gettypeid — 指定された列のデータ型のOIDを返す
SPI_getrelname — 指定されたリレーションの名前を返す
SPI_getnspname — 指定されたリレーションの名前空間を返す。
45.3. メモリ管理
SPI_palloc — 上位エクゼキュータコンテキスト内にメモリを割り当てる
SPI_repalloc — 上位エクゼキュータコンテキスト内にメモリを再割り当てる
SPI_pfree — 上位エクゼキュータコンテキスト内のメモリを解放する
SPI_copytuple — 上位エクゼキュータ内に行のコピーを作成する
SPI_returntuple — Datumとしてタプルを返す準備をする
SPI_modifytuple — 与えられた行の選択フィールドを置き換えた行を作成する
SPI_freetuple — 上位エクゼキュータコンテキスト内に割り当てられた行を解放する
SPI_freetuptableSPI_executeや類似の関数によって生成された行セットを解放する
SPI_freeplan — 以前に保存した準備済み文を解放する
45.4. データ変更の可視性
45.5. 例
<title>Server Programming Interface</title>

The <firstterm>Server Programming Interface</firstterm> (<acronym>SPI</acronym>) gives writers of user-defined <acronym>C</acronym> functions the ability to run <acronym>SQL</acronym> commands inside their functions. <acronym>SPI</acronym> is a set of interface functions to simplify access to the parser, planner, and executor. <acronym>SPI</acronym> also does some memory management. サーバプログラミングインタフェースSPI)は、ユーザ定義のC関数からSQL問い合わせを実行する機能をユーザに提供します。 SPIはパーサ、プランナ、エクゼキュータへのアクセスを単純化したインタフェース関数の集合です。 また、SPIは多少のメモリ管理を行います。

注記

The available procedural languages provide various means to execute SQL commands from procedures. Most of these facilities are based on SPI, so this documentation might be of use for users of those languages as well. 利用可能な手続き言語は、プロシージャからSQLコマンドを実行するための各種手段を提供します。 これらのほとんどは、SPIを基にしていますので、この文書はこれらの言語のユーザにとっても有用な場合があります。

To avoid misunderstanding we'll use the term <quote>function</quote> when we speak of <acronym>SPI</acronym> interface functions and <quote>procedure</quote> for a user-defined C-function that is using <acronym>SPI</acronym>. 誤解を防ぐために、これ以降、関数SPIインタフェース関数の意味で、プロシージャSPIを呼び出すユーザ定義のC関数の意味で使うことにします。

Note that if a command invoked via SPI fails, then control will not be returned to your procedure. Rather, the transaction or subtransaction in which your procedure executes will be rolled back. (This might seem surprising given that the SPI functions mostly have documented error-return conventions. Those conventions only apply for errors detected within the SPI functions themselves, however.) It is possible to recover control after an error by establishing your own subtransaction surrounding SPI calls that might fail. This is not currently documented because the mechanisms required are still in flux. コマンドがSPIの失敗を起こした場合、その制御はプロシージャには戻らないことに注意してください。 それどころか、プロシージャを実行していたトランザクションもしくは副トランザクションはロールバックされます (これはSPI関数のほとんどでエラーを返す規約があることから奇妙に思われるかもしれません。 しかし、こうした規約はSPI関数自身でエラーを検知した時にのみ適用されるものです)。 失敗する可能性があるSPI呼び出しを囲む副トランザクションを独自に用意することで、エラーの後の制御を戻すことができます。 要求される機構がまだ流動的であるため、これはまだ文書化されていません。

<acronym>SPI</acronym> functions return a nonnegative result on success (either via a returned integer value or in the global variable <varname>SPI_result</varname>, as described below). On error, a negative result or <symbol>NULL</symbol> will be returned. SPI関数は成功時に非負の結果を(戻り値、もしくは後述のSPI_resultグローバル変数の中に)返します。 エラー時、負の結果もしくはNULLを返します。

Source code files that use SPI must include the header file <filename>executor/spi.h</filename>. SPIを使用するソースコードファイルではexecutor/spi.hヘッダファイルをincludeしなければなりません。