他のバージョンの文書10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

38.5. 基本的な文

本節および次節では、明示的にPL/pgSQLで解釈される、全ての種類の文について説明します。 これらの種類の文として認められないものは全て、SQLコマンドであると仮定され、項38.5.2および項38.5.3において記述したように、メインデータベースエンジンに送信され実行されます。

38.5.1. 代入

値をPL/pgSQL変数、もしくは行/レコードフィールドに代入する場合は以下のように記述します。

variable := expression;

上述した通り、このような文中にある式は、メインデータベースエンジンに送信されるSELECT SQLコマンドによって評価されます。 式は1つの値を生成しなければなりません。

式の結果データ型が変数のデータ型に一致しない場合、または、変数が(char(20)のように)特定の大きさ/精度を持つ場合、結果の値は PL/pgSQLインタプリタによって、結果の型の出力関数と変数の型の入力関数を使用して暗黙的に変換されます。 これにより、結果値の文字列形式を入力関数で受け付けることができない場合に、入力関数において実行時エラーが発生する可能性があることに注意してください。

例:

tax := subtotal * 0.06;
my_record.user_id := 20;

38.5.2. 結果を伴わないコマンドの実行

例えば、RETURNING句のないINSERTのように、行を返さない SQL のコマンドにおいて、単に記述することによってPL/pgSQL関数の内部でコマンドを実行できます。

コマンドのテキストに現れる全てのPL/pgSQL変数名も、パラメータのシンボルに置き換えられます。 その後、実行時のパラメータ値として、その時点の変数値が提供されます。 これは以前に述べた式に関する処理と同じです。 詳細は項38.10.1を見てください。 以下に例を示します。

DECLARE
    key TEXT;
    delta INTEGER;
BEGIN
    ...
    UPDATE mytab SET val = val + delta WHERE id = key;

コマンドのテキストは、SQL 主エンジンから下のように見えます。

    UPDATE mytab SET val = val + $1 WHERE id = $2;

通常このように考えることはありませんが、構文エラーメッセージの解析力が必要な時は、この解釈が有用となります。

注意

PL/pgSQLは、関数において宣言した変数と一致する全ての識別子への置換を行います。 したがって、関数内のコマンドで参照しなければならないテーブル名、列名または関数名と同じ名前を変数に使用するのは、不適切な考えです。 詳細は項38.10.1を見てください。

SQL コマンドがこのように実行されると、PL/pgSQLはコマンドを一度だけ計画し、データベース接続が切断されるまで、以後の実行で再利用します。 改善の詳細は項38.10.2を見てください。

式または問い合わせSELECTを評価して結果を破棄することが、役に立つ場合があります。 例えば、関数の呼び出しにおいて、副次的な成果を取得できるが、結果は無用である場合です。 このような時PL/pgSQLでは、PERFORM文を使用してください。

PERFORM query;

これはqueryを実行し、その結果を破棄します。 SQLのSELECT文と同じ方法でqueryを記述しますが、最初のキーワードSELECTPERFORMに置き換えてください。 結果を返さないコマンドと同様に、PL/pgSQL変数は問い合わせに置き換えられ、計画は同様にキャッシュされます。 また、特殊な変数であるFOUNDは問い合わせ結果が1行でも生成された場合は真に設定され、生成されない場合は偽に設定されます(項38.5.5を見てください)。

注意: 直接SELECTを記述すれば、この結果を得ることができると考えるかもしれませんが、現時点でこれを行う方法はPERFORMしかありません。 SELECTのように行を返すSQLコマンドは、エラーとして拒絶されます。 なお、INTO句を有する時は例外であり、次節で説明します。

以下に例を示します。

PERFORM create_mv('cs_session_page_requests_mv', my_query);

38.5.3. 1行の結果を返す問い合わせの実行

1行を返す(多分、複数列の)SQL コマンドの結果は、レコード変数、行型の変数、スカラ変数のリストに代入することができます。 これは、基本的なSQL コマンドを記述して、それにINTO句を追加することによって行われます。 以下に例を示します。

SELECT select_expressions INTO [STRICT] target FROM ...;
INSERT ... RETURNING expressions INTO [STRICT] target;
UPDATE ... RETURNING expressions INTO [STRICT] target;
DELETE ... RETURNING expressions INTO [STRICT] target;

ここで、targetはレコード変数、行変数、あるいは、単純な変数とレコード/行変数のフィールドをカンマで区切ったリストです。 PL/pgSQL変数は置換されて残りの問い合わせとなり、行を返さないコマンドにおいて述べたように計画がキャッシュされます。 このように作動するのは、RETURNINGを伴ったINSERT/UPDATE/DELETESELECTおよび行セットの結果を返すユーティリティコマンド(例えば、EXPLAIN)です。 INTO句以外では、SQL コマンドはPL/pgSQLの外部に記述したものと同じです。

ティップ: 通常のPostgreSQLSELECT INTO文では、INTOの対象は新しく作成されるテーブルです。 しかし、INTOを伴ったSELECTでは、この解釈が通常と大きく異なることに注意してください。 PL/pgSQL 関数内部でSELECTの結果からテーブルを作成したい場合は、CREATE TABLE ... AS SELECT構文を使用してください。

行または変数リストが対象に使用された場合、列数とデータ型において問い合わせの結果と対象の構造が正確に一致しなければなりません。 さもないと、実行時エラーが発生します。 レコード変数が対象の場合は、問い合わせ結果の列の行型に自分自身を自動的に設定します。

INTO句以外は、このSELECT文は通常のSELECT SQLコマンドと同一であり、SELECTの全ての機能を使用することができます。

INTO句はSQLコマンドのほとんど任意の場所に記述することができます。 習慣的には、SELECT文においてはselect_expressionsの直前または直後に、他のコマンドにおいては文の終わりに記述されます。 将来PL/pgSQLのパーサが厳格になる場合に備えて、この習慣に従うことを推奨します。

INTO句においてSTRICTが指定されない場合、targetは問い合わせが返す最初の行となり、行を返さない時はNULLとなります。 ("最初の行"とはORDER BYを使用しないと定義できないことに注意してください。) 2行目以降の行の結果は、全て破棄されます。 特殊なFOUND変数を調べて、行が返されたかどうかを知ることができます。 (項38.5.5を参照してください) 以下に例を示します。

SELECT * INTO myrec FROM emp WHERE empname = myname;
IF NOT FOUND THEN
    RAISE EXCEPTION 'employee % not found', myname;
END IF;

STRICTオプションが指定された場合、問い合わせは正確に 1行を返さなければなりません。 さもないと、行がない時はNO_DATA_FOUND、2行以上が返った時はTOO_MANY_ROWSの実行時エラーが生じます。 エラーを捕捉したい時は、例外ブロックを使用できます。 以下に例を示します。

BEGIN
    SELECT * INTO STRICT myrec FROM emp WHERE empname = myname;
    EXCEPTION
        WHEN NO_DATA_FOUND THEN
            RAISE EXCEPTION 'employee % not found', myname;
        WHEN TOO_MANY_ROWS THEN
            RAISE EXCEPTION 'employee % not unique', myname;
END;

STRICTを指定したコマンドが成功すると、FOUND変数は常に真に設定されます。

STRICTが指定されない場合でも、RETURNINGを伴ったINSERT/UPDATE/DELETEが2行以上を返した時は、エラーとなります。 なぜなら、どの1行を返すか決定するORDER BYのようなオプションが存在しないからです。

注意: STRICTオプションは、OracleのPL/SQLのSELECT INTOおよび関連した文に対応します。

SQLの問い合わせが返す複数行の結果を処理したい場合は、項38.6.4を参照してください。

38.5.4. 動的コマンドの実行

PL/pgSQL関数の内部で、動的コマンド、つまり実行する度に別のテーブルや別のデータ型を使用するコマンドがほしいということがよくあるでしょう。 PL/pgSQLが通常行うコマンドの計画のキャッシュは(項38.10.2で述べたように)このような状況では動作しません。 この種の問題を扱うために、以下のEXECUTE文が用意されています。

EXECUTE command-string [ INTO [STRICT] target ] [ USING expression [, ...] ];

ここで、command-stringは実行されるコマンドを含む(text型の)文字列に従った評価式です。オプションのtargetはレコード変数、行変数、あるいは、単純な変数とレコード/行変数のフィールドをカンマで区切ったリストで、その中にコマンドの結果が格納されます。オプションのUSING評価式はそのコマンドに挿入される値を与えます。

PL/pgSQL変数は、この演算用のコマンド文字列へ置換されません。 どの変数の値も、コマンド文字列を作成する時に埋め込まなければならないか、以下に記述されるパラメータを使用します。

また、EXECUTEに対して実行されるコマンドの計画をキャッシュすることはありません。 代わりに、コマンドは文が実行される時に準備されます。 したがって、異なるテーブルと列に対する操作を実行できるように、コマンド文字列を関数内部で動的に作成することができます。

INTO句は、行を返すSQLコマンドの結果を代入するべき場所を指定します。 行または変数リストが用いられる時、それは問い合わせの結果の構造と正確に一致しなければなりません。 (レコード変数が使用される時、それは自分自身を結果の構造と自動的に一致させます)。 複数の行が返された時、最初の行だけがINTO変数に代入されます。 1行も返されない時、NULL がINTO変数に代入されます。 INTO句が指定されない時、問い合わせの結果は捨てられます。

STRICTオプションが指定された時、問い合わせの結果が正確に1行の場合を除き、エラーとなります。

コマンド文字列はパラメータ値を使用可能で、それらは$1$2、等のようなコマンドの中で参照されます。 これらの標識記号はUSINGで与えられる値を参照します。この方式はデータの値をテキストとしてコマンド文字列の中に挿入する際、多くの場合望ましいものです。それは値をテキストに、そしてその逆を行う場合の実行時負荷を回避するとともに、括弧で括るとか、エスケープをする必要がないため、SQLインジェクション攻撃に対してより襲われにくくなります。例をあげます。

EXECUTE 'SELECT count(*) FROM mytable WHERE inserted_by = $1 AND inserted <= $2'
   INTO c
   USING checked_user, checked_date;

パラメータ標識文字はデータ値のみ使用可能です。もし動的に決定されるテーブルや列名を使用したい場合、テキストでコマンド文字列にそれらを挿入する必要があります。例えば、先行する問い合わせが、ある動的に選択されたテーブルに対して処理される必要がある時は、次のようにします。

EXECUTE 'SELECT count(*) FROM '
    || tabname::regclass
    || ' WHERE inserted_by = $1 AND inserted <= $2'
   INTO c
   USING checked_user, checked_date;

最初の例のように、単純な定数コマンドとUSINGパラメータを使ったEXECUTEは、コマンドを直接PL/pgSQLで書いて、PL/pgSQL変数を自動的に置換したものと機能的に同じです。 重要な差異として、EXECUTEが現在のパラメータ値に特定なプランを生成し、そのそれぞれを実行するにあたって、再プランを行うことです。一方、PL/pgSQLは通常一般的プランを作成し、再使用に備えキャッシュします。最適プランがパラメータ値に大きく依存する場合、EXECUTEは大幅に高速化されますが、プランがパラメータ値に繊細に反応しない場合、再プランは無駄です。

SELECT INTOEXECUTEでは現在サポートされません。 代わりに、SELECTコマンドの実行においてINTOを記述し、EXECUTEの一部としてください。

注意: PL/pgSQL EXECUTE文はPostgreSQLサーバでサポートされているEXECUTESQL文とは関連がありません。 サーバのEXECUTE文はPL/pgSQL関数内で使用することはできません(使用する必要もありません)。

例 38-1. 動的問い合わせの中の値の引用

動的コマンドを実行する時、PL/pgSQLでは単一引用符をエスケープしなければなりません。 推奨されるのは、関数本体における固定のテキストをドル引用符で囲む方法です (ドル引用符を用いない旧式のコードを保有している場合は、項38.11.1の概要を参照することが、理解しやすいコードへの変換作業の手助けになります)。

作成した問い合わせに挿入すべき動的な値は、それ自身の内部に引用符を含む可能性があるため、注意深い処理が必要です。 以下に例を示します(ここでは関数にドル引用符を用いる方法を使用すると仮定しているので、引用符を二重化する必要はありません)。

EXECUTE 'UPDATE tbl SET '
        || quote_ident(colname)
        || ' = '
        || quote_literal(newvalue)
        || ' WHERE key = '
        || quote_literal(keyvalue);

この例は、quote_identquote_literal関数の使用方法を示しています。安全のため、列またはテーブル識別子を含む評価式は動的問い合わせに挿入する前にquote_identを介して渡されなくてはなりません。組み立てられたコマンドの中のリテラル文字列であるべき値を含む評価式は、quote_literalを介して渡されなければなりません。これらの関数は、適切にエスケープされたいかなる埋め込み文字を持っている、二重引用符または単一引用符で囲まれた入力テキストを返すのに、適切な手順を踏みます。

quote_literalSTRICTラベル付けされているため、null引数付きで呼ばれた場合、常にnullを返します。上記の例で、newvalue、またはkeyvalueがnullの場合、動的問合せ文字列全体はnullとなり、EXECUTEからのエラーを導きます。quote_nullable関数の使用によりこの問題を回避することができます。その動作は、null引数付きで呼ばれた場合にquote_literalでは文字列NULLを返すことを除いて同一です。例を示します。

EXECUTE 'UPDATE tbl SET '
        || quote_ident(colname)
        || ' = '
        || quote_nullable(newvalue)
        || ' WHERE key = '
        || quote_nullable(keyvalue);

nullの可能性のある値を処理するのであれば、通常quote_literalの代わりにquote_nullableを使用してください。

いつものように、問い合わせの中のnull値は意図しない結果を確実にもたらさないよう配慮をしなければなりません。例えば次のようなWHERE句の結果はどうなるのでしょう。

     'WHERE key = ' || quote_nullable(keyvalue)

これはkeyvalueがnullである限り成功しません。その理由は、null被演算子を伴った等価演算子 = の使用による結果は常にnullとなるからです。nullを通常のキーの値と同じように動作させたい場合、上記を、以下のように再記述する必要があります。

     'WHERE key IS NOT DISTINCT FROM ' || quote_nullable(keyvalue)

(現時点では、IS NOT DISTINCT FROM=よりもより効率性が少なく扱われますので、必要に迫られた場合以外は行わないようにしてください。nullとIS DISTINCTについての更なる情報は項9.2を参照してください。

ドル引用符の用法は一定のテキストを囲む時だけ有用だということに注意してください。 この例を次のように記述するのは非常に悪い着想です。

EXECUTE 'UPDATE tbl SET '
        || quote_ident(colname)
        || ' = $$'
        || newvalue
        || '$$ WHERE key = '
        || quote_literal(keyvalue);

なぜなら、newvalueの内容がたまたま$$を含む時は、途中で次の処理へ移ってしまうからです。 同様の不測事態は、ドル引用符の他の区切り文字を選んだ時も起こります。 したがって、テキストの内容が既知でない時は、安全のために、適切なものとしてquote_literalquote_nullable、またはquote_ident関数を使用しなければなりません

動的問い合わせとEXECUTEの長大な例は例38-7で見ることができます。 それは新しい関数を定義するためにCREATE FUNCTIONコマンドを用いて実行するものです。

38.5.5. 結果ステータスの取得

コマンドの効果を判断するには、いくつか方法があります。 最初の方法は、以下のような形式のGET DIAGNOSTICSを使用する方法です。

GET DIAGNOSTICS variable = item [ , ... ];

このコマンドによって、システムステータスインジケータを取り出すことができます。 各itemは、指定された変数に割り当てられた状態値を識別するためのキーワードです(これは受け取るために正しいデータ型でなければなりません)。 現在使用可能なステータス項目は、最後にSQLエンジンに送信されたSQLコマンドによって処理された行数を示すROW_COUNT、および、最も最近のSQLコマンドによって挿入された最後の行のOIDであるRESULT_OIDです。RESULT_OIDはOID を保有するテーブルへのINSERTコマンドの後でのみ有意であることに注意してください。

以下に例を示します。

GET DIAGNOSTICS integer_var = ROW_COUNT;

2番目のコマンドの効果を判断する方法は、FOUNDというboolean型の特殊な変数をチェックすることです。 PL/pgSQLの各関数内で使用される際、FOUNDは最初は偽に設定されています。 以下のように、それぞれの文の種類によって設定が変更されます。

FOUNDは各々のPL/pgSQL関数内部のローカル変数です。 FOUNDに対して行われた全ての変更は、現在の関数にのみ影響します。

38.5.6. まったく何もしない

何もしないプレースホルダ文が有用になることがあります。 例えば、IF/THEN/ELSE文の一部が空文であることを明示したい時です。 このような目的には、NULL文を使用します。

NULL;

例えば、次の2つのコードは同等です。

    BEGIN
        y := x / 0;
    EXCEPTION
        WHEN division_by_zero THEN
            NULL;  -- 誤りを無視する
    END;

    BEGIN
        y := x / 0;
    EXCEPTION
        WHEN division_by_zero THEN  -- 誤りを無視する
    END;

どちらが望ましいと思うかは、好みの問題です。

注意: OracleのPL/SQLでは、無記述の文は許されないのでNULL文が必須となります。 それに反して PL/pgSQLでは、無記述の文が許可されています。