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

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

目次

47.1. インタフェース関数
SPI_connect — SPIマネージャにC関数を接続する
SPI_finish — C関数をSPIマネージャから切断する
SPI_execute — コマンドを実行する
SPI_exec — 読み書きコマンドを実行する
SPI_execute_extended — 行外のパラメータを持つコマンドを実行する
SPI_execute_with_args — 行外のパラメータを持つコマンドを実行する
SPI_prepare — 文を準備する。文の実行はまだ行わない
SPI_prepare_cursor — 文を準備する。まだ実行は行わない
SPI_prepare_extended — 文を準備する。文の実行はまだ行わない
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_extendedSPI_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_parse_open — 問い合わせ文字列とパラメータを使ってカーソルを設定する
SPI_cursor_find — 既存のカーソルを名前で検索する
SPI_cursor_fetch — カーソルから数行を取り出す
SPI_cursor_move — カーソルを移動する
SPI_scroll_cursor_fetch — カーソルから一部の行を取り出す
SPI_scroll_cursor_move — カーソルを移動する
SPI_cursor_close — カーソルを閉じる
SPI_keepplan — 準備済み文を保持する
SPI_saveplan — 準備済み文を保存する
SPI_register_relation — 短命の名前付きリレーションをSPIの問い合わせから名前で参照可能にする
SPI_unregister_relation — 短命の名前付きリレーションをSPIのレジストリから削除する
SPI_register_trigger_data — 短命のトリガーデータをSPIの問い合わせから利用可能にする
47.2. インタフェースサポート関数
SPI_fname — 指定した列番号に対する列名を決定する
SPI_fnumber — 指定した列名から列番号を決定する
SPI_getvalue — 指定された列の文字列値を返す
SPI_getbinval — 指定した列のバイナリ値を返す
SPI_gettype — 指定された列のデータ型名を返す
SPI_gettypeid — 指定された列のデータ型のOIDを返す
SPI_getrelname — 指定されたリレーションの名前を返す
SPI_getnspname — 指定されたリレーションの名前空間を返す
SPI_result_code_string — 文字列でエラーコードを返します
47.3. メモリ管理
SPI_palloc — 上位エグゼキュータコンテキスト内にメモリを割り当てる
SPI_repalloc — 上位エグゼキュータコンテキスト内にメモリを再割り当てる
SPI_pfree — 上位エグゼキュータコンテキスト内のメモリを解放する
SPI_copytuple — 上位エグゼキュータ内に行のコピーを作成する
SPI_returntuple — Datumとしてタプルを返す準備をする
SPI_modifytuple — 与えられた行の選択フィールドを置き換えた行を作成する
SPI_freetuple — 上位エグゼキュータコンテキスト内に割り当てられた行を解放する
SPI_freetuptableSPI_executeや類似の関数によって生成された行セットを解放する
SPI_freeplan — 以前に保存した準備済み文を解放する
47.4. トランザクション制御
SPI_commit — 現在のトランザクションをコミットします。
SPI_rollback — 現在のトランザクションを中断します。
SPI_start_transaction — 廃れた関数
47.5. データ変更の可視性
47.6. 例
<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 or procedures. <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 functions. Most of these facilities are based on SPI, so this documentation might be of use for users of those languages as well. 利用可能な手続き言語は、関数からSQLコマンドを実行するための各種手段を提供します。 これらのほとんどは、SPIを基にしていますので、この文書はこれらの言語のユーザにとっても有用な場合があります。

Note that if a command invoked via SPI fails, then control will not be returned to your C function. Rather, the transaction or subtransaction in which your C function 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. コマンドがSPIの失敗を起こした場合、その制御はC関数には戻らないことに注意してください。 それどころか、プロシージャを実行していたトランザクションもしくは副トランザクションはロールバックされます (これは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しなければなりません。